Skip to content

virgil.pipeline

The classes and functions of the pipelines. For what a pipeline does, the run folder, the checks and the stability policy, see Pipelines and their stability.

Bases: _Pipeline

Search for a companion, set contrast limits, fit and sample a binary.

Stages: load → overview → search → limits → fit → posterior → quicklook.

  • load applies wavel_range and error_floor and writes the data that are fitted to data/processed.oifits.
  • overview plots the data and their uv coverage.
  • search runs detection_statistics (Δχ², log Bayes factor, best SNR) on a point-companion grid (dra, ddec in mas, log-spaced flux), with maps of Δχ², best flux and SNR, and the significance at the peak (local_nsigma) before and after a look-elsewhere correction for the number of resolution elements searched.
  • limits runs absil_limits at sigma and its radial_profile.
  • fit runs fit on the model template from the best grid point.
  • posterior samples numpyro_model with NUTS from the fit.
  • quicklook writes and executes quicklook.ipynb.

The fit is on the quoted errors unless error_scale="fit", and χ²/N is always reported on the quoted errors. Priors are group-invariant: uniform in position (dra, ddec or sep), uniform in position angle (an AngleVector, with no wrap at 0°/360°) and log-uniform in flux over flux_range.

Parameters:

Name Type Description Default
data OIData

The data.

 required
model BinaryModelAngular or BinaryModelCartesian

Model template; its class sets the fitted parameters (sep, pa, flux or dra, ddec, flux). Default BinaryModelAngular. The search and limits always use a point companion in Cartesian offsets.

 None
output str or PathLike

Run folder (default "run").

 'run'
**settings

Overrides of the defaults (see BinaryPipeline.defaults()):

  • sigma (3.0): significance of the contrast limits.
  • detection_sigma (3.0): threshold of the detection check, on the look-elsewhere-corrected significance.
  • max_sep_mas (None): half-width of the search grid; by default fov_fraction × λ_max/B_min.
  • fov_fraction (1.0): see max_sep_mas.
  • grid_step_mas (None): grid spacing; by default λ_min/(4 B_max), coarsened so that no axis exceeds max_grid points.
  • max_grid (101): most points per position axis.
  • flux_range ([1e-5, 0.5]): flux axis of the grid and bounds of the log-uniform flux prior (companion/primary).
  • n_flux (40): points on the flux axis.
  • wavel_range (None): [min, max] wavelengths to keep (m).
  • error_floor (None): absolute error floors by observable, e.g. {"vis": 0.01, "phi": 0.005} (phases in radians), as OIData.with_error_floor.
  • error_scale ("quoted"): "fit" also fits log-uniform error scales vis_scale and phi_scale on [0.1, 10].
  • num_warmup, num_samples, num_chains (1000, 1000, 4), chain_method ("vectorized") and seed (0): NUTS.
  • batch_size (None): grid batch size.
  • limit_bins (20): annuli of the contrast curve.
  • quicklook_execute (True): execute the quicklook notebook.
 {}

Examples:

>>> import virgil as vg
>>> from virgil.pipeline import BinaryPipeline, load
>>> res = BinaryPipeline(vg.OIData("hd1234.oifits"), output="runs/hd1234").run()
>>> res.summary["companion"]["sep_mas"]

NAME = 'binary' class-attribute instance-attribute

STABILITY = 'stable' class-attribute instance-attribute

STAGES = ('load', 'overview', 'search', 'limits', 'fit', 'posterior', 'quicklook') class-attribute instance-attribute

__init__(data, model=None, *, output='run', **settings)

Bases: _Pipeline

Measure a star's angular diameter, with and without limb darkening.

Stages: load → overview → fit → posterior → quicklook.

  • load applies wavel_range and error_floor and writes the data that are fitted to data/processed.oifits.
  • overview plots the data and their uv coverage.
  • fit scans the uniform-disk diameter (a uniform disk's closure phases flip at every null, so its χ² is not smooth and a scan is the reliable fit), then fits each other model with fit from the scanned diameter. With the default model it compares the limb-darkened and uniform fits by their Δχ² on the quoted errors against a BIC penalty.
  • posterior samples every fitted model with NUTS (numpyro_model).
  • quicklook writes and executes quicklook.ipynb: the main result is V² against spatial frequency with the model curves.

The fit is on the quoted errors unless error_scale="fit", and χ²/N is always reported on the quoted errors. Priors are group-invariant: log-uniform in the diameter over diam_range_mas and uniform on [0, 1] in Kipping's limb-darkening coefficients q1, q2, which cover exactly the physical quadratic laws.

res.model() is the preferred model (the limb-darkened one only if its Δχ² exceeds the BIC penalty of its two extra parameters); res.model("uniform") and res.model("limb_darkened") give each.

Parameters:

Name Type Description Default
data OIData

The data.

 required
model str or SourceModel

What to fit. A short name, "uniform" (a UniformDisk) or "limb_darkened" (a QuadraticLimbDarkenedDisk in Kipping's q1, q2), fits that model alone. An instance of one of those classes fits that model, with its q1 and q2 as starting values. By default both are fitted and compared.

 None
output str or PathLike

Run folder (default "run").

 'run'
**settings

Overrides of the defaults (see StarPipeline.defaults()):

  • diam_range_mas (None): [min, max] of the log-uniform diameter prior; by default from 0.1 λ_min/B_max (well inside the unresolved regime) to 4 λ_max/B_min (beyond the first null on every baseline).
  • n_scan (2000): points of the log-spaced diameter scan; a second scan of 201 points over ±1% then refines it.
  • max_lobes (5): the most diameter lobes (separate minima of the scan) fitted for each model. The best lobe gives the fit and bounds the posterior's diameter prior; the table of lobes is in summary["fit"]["models"][name]["lobes"].
  • wavel_range (None): [min, max] wavelengths to keep (m).
  • error_floor (None): absolute error floors by observable, e.g. {"vis": 0.01, "phi": 0.005}, as OIData.with_error_floor.
  • error_scale ("quoted"): "fit" also fits log-uniform error scales vis_scale and phi_scale on [0.1, 10].
  • num_warmup, num_samples, num_chains (1000, 1000, 4), chain_method ("vectorized") and seed (0): NUTS.
  • batch_size (None): scan batch size.
  • quicklook_execute (True): execute the quicklook notebook.
 {}

Examples:

>>> import virgil as vg
>>> from virgil.pipeline import StarPipeline
>>> res = StarPipeline(vg.OIData("star.oifits"), output="runs/star").run()
>>> res.summary["star"]["diam_mas"]

NAME = 'star' class-attribute instance-attribute

STABILITY = 'stable' class-attribute instance-attribute

STAGES = ('load', 'overview', 'fit', 'posterior', 'quicklook') class-attribute instance-attribute

names = names instance-attribute

__init__(data, model=None, *, output='run', **settings)

Reload a pipeline run from its folder, without recomputing anything.

Parameters:

Name Type Description Default
path str or PathLike

The run folder (the pipeline's output).

 required

Returns:

Type Description
Result

The outputs of a pipeline run, reloaded from its folder.

Nothing is recomputed: every accessor reads the files the run wrote, and returns plain numbers, numpy arrays or real virgil objects that can be refined by hand.

Attributes:

Name Type Description
path Path

The run folder.
run dict

The contents of run.json: schema, status, resolved config, inputs, provenance and per-stage timings.
summary dict

The contents of summary.json: key numbers by stage, and the checks as dicts.

path = Path(path) instance-attribute

run = read_json(run_file) instance-attribute

summary = read_json(summary_file) if summary_file.exists() else {} instance-attribute

status property

Run status: "running", "partial", "complete" or "failed".

checks property

The quality checks, as a list of Check.

plots property

Paths of the plots the run wrote, sorted by name.

__init__(path)

__repr__()

describe()

The key numbers of the summary as short text, one per line.

data()

The data actually fitted, as an OIData, from data/processed.oifits.

model(name=None)

A fitted model, a real virgil object with its values set.

Parameters:

Name Type Description Default
name str

For a run that fitted several models (StarPipeline), the model to rebuild; by default the preferred one, "best".

 None

model_values(name=None)

The fitted parameter values, as path → numpy array (see model).

samples(group_by_chain=True, name=None)

Posterior samples by site, shaped (chain, draw) (or flat).

name selects one of several fitted models, as in model.

sample_stats(name=None)

NUTS diagnostics per transition, shaped (chain, draw).

grid()

Grid results: "axes" (usable as grid=) plus one map per name.

fit_result(name=None)

The MAP fit as a virgil FitResult, e.g. to continue with fit.

name selects one of several fitted models, as in model.

One quality check of a pipeline run.

Attributes:

Name Type Description
name str

Stable identifier, e.g. "chi2_companion".
status {'pass', 'warn', 'fail'}

Outcome.
value (float, list or None)

The quantity tested.
threshold (float, list or None)

The threshold it was compared with.
message str

One templated sentence saying what the outcome means.

name instance-attribute

status instance-attribute

value instance-attribute

threshold instance-attribute

message instance-attribute

__post_init__()

to_dict()

The check as a JSON-ready dict.

from_dict(record) classmethod

Rebuild a check from :meth:to_dict.

__init__(name, status, value, threshold, message)

Bases: ValueError

Resuming a run whose stored configuration differs from this one.