`virgil.limits`

Contrast limits, significance, and conversions between flux ratios (companion/primary), contrasts (primary/companion) and magnitudes. A companion 100 times fainter than the primary has flux 0.01, contrast 100 and Δmag 5.

Contrast limits, significance, and flux/contrast/Δmag conversions.

Fluxes are companion/primary; contrast is primary/companion and Δmag = 2.5 log10(contrast). See detection limits for the methods and which to use.

ruffio_upperlimit: Bayesian upper limits.
absil_limits: frequentist chi-squared limits.
injection_limits: limits by companion injection.
radial_profile: azimuthal statistics of a limit map.

`flux_to_contrast(flux)`

Contrast (primary/companion) of a companion/primary flux ratio.

float(flux_to_contrast(0.01)) 100.0

`contrast_to_flux(contrast)`

Companion/primary flux ratio of a contrast (primary/companion).

`flux_to_delta_mag(flux)`

Magnitude difference 2.5 log10(primary/companion) of a flux ratio.

float(flux_to_delta_mag(0.01)) 5.0

`delta_mag_to_flux(delta_mag)`

Companion/primary flux ratio of a magnitude difference.

`ruffio_upperlimit(mean, sigma, percentile)`

Percentile of a flux posterior truncated to non-negative values.

The posterior is the Laplace Gaussian N(mean, sigma) truncated to flux >= 0; percentile = norm.cdf(2) gives a 2σ-equivalent upper limit. See detection limits.

Source: Ruffio et al. (2018), references.

Parameters:

Name	Type	Description	Default
`mean`	`float or array - like`	Unconstrained best-fit flux (may be negative), e.g. from `optimized_flux_grid`.	required
`sigma`	`float or array - like`	Laplace uncertainty of the flux, e.g. from `laplace_flux_uncertainty_grid`.	required
`percentile`	`float or array - like`	Quantile(s) of the truncated posterior, between 0 and 1.	required

Returns:

Type	Description
`array - like`	Non-negative flux, of shape `broadcast(mean, sigma).shape + percentile.shape`.

`absil_limits(model, data, grid, sigma, *, flux_param=None, flux_bounds=(1e-06, 1.0), batch_size=None)`

Flux above which a companion is ruled out at sigma significance.

At each grid position, the flux at which the model fits worse than the no-companion model by a chi-squared ratio of significance sigma (see nsigma); the degrees of freedom are the data points, with fitted parameters not subtracted. See detection limits.

Source: Absil et al. (2011), references.

Parameters:

Name	Type	Description	Default
`model`	`SourceModel or class`	As for `likelihood_grid`; the no-companion model sets every parameter in `grid` to zero.	required
`data`	`OIData`	Data to fit.	required
`grid`	`dict[str, array - like]`	Grid axes (e.g. `dra`/`ddec` in mas). The flux axis matters only with `flux_bounds=None`, where its smallest positive value starts the search.	required
`sigma`	`float`	Exclusion significance in Gaussian-equivalent σ, above that of a ratio of 1 (about 0.67) and below the float ceiling (12.9 in float32, 37 in float64).	required
`flux_param`	`str`	Key of `grid` holding the flux (default: the key ending in `flux`).	`None`
`flux_bounds`	`tuple[float, float] or None`	Search range, searched upward from its lower end; limits outside it are clipped with a `RuntimeWarning`. `None` searches without bounds (e.g. for `System` weights above 1).	`(1e-06, 1.0)`
`batch_size`	`int`	Grid points evaluated at once.	`None`

Returns:

Type	Description
`array - like`	Flux limit (companion/primary), one axis per coordinate key; convert with `flux_to_contrast` or `flux_to_delta_mag`.

`injection_limits(model, data, grid, sigma, *, flux_param=None, flux_bounds=(1e-06, 1.0), batch_size=None)`

Flux at which an injected companion would be detected at sigma.

A companion of flux f is added to every observable and the no-companion model is fitted to the result; the limit is where it fits worse than the companion model by a chi-squared ratio of significance sigma. Compare absil_limits; the search and the differences from CANDID are in detection limits.

Source: Gallenne et al. (2015), references.

Parameters:

Name	Type	Description	Default
`model`		As for `absil_limits`.	required
`data`		As for `absil_limits`.	required
`grid`		As for `absil_limits`.	required
`flux_param`		As for `absil_limits`.	required
`flux_bounds`		As for `absil_limits`.	required
`batch_size`		As for `absil_limits`.	required
`sigma`	`float`	Detection significance, with the same bounds as for `absil_limits`.	required

Returns:

Type	Description
`array - like`	Flux limit (companion/primary), one axis per coordinate key.

Examples:

>>> import jax.numpy as np
>>> from virgil import PointSource, System, UniformDisk, injection_limits
>>> template = System(star=UniformDisk(0.8), comp=PointSource(0.01))
>>> grid = {
...     "comp.dra": np.linspace(-10, 10, 21),
...     "comp.ddec": np.linspace(-10, 10, 21),
...     "comp.flux": np.array([0.01]),
... }
>>> limits = injection_limits(template, data, grid, 3.0)

`chi2ppf(p, df)`

Percentile function (inverse CDF) of the chi-squared distribution.

Accurate to about 1e-14 relative in float64 for p in [1e-10, 1 - 1e-10]; differentiable and jit-able. p is clipped to [eps, 1 - eps]; for small tail probabilities use nsigma. See detection limits.

Parameters:

Name	Type	Description	Default
`p`	`array - like`	Percentile and degrees of freedom.	required
`df`	`array - like`	Percentile and degrees of freedom.	required

Returns:

Type	Description
`array - like`	The chi-squared value at the percentile.

`nsigma(chi2r_test, chi2r_true, ndof)`

Gaussian-equivalent significance of a reduced-chi-squared ratio.

ndof * chi2r_test / chi2r_true is compared with a chi-squared distribution of ndof degrees of freedom. Accurate far beyond 8σ; it saturates near 13σ in float32 and 37σ in float64. See detection limits.

Source: Absil et al. (2011), references.

Parameters:

Name	Type	Description	Default
`chi2r_test`	`float`	Reduced chi-squared of the test and true models.	required
`chi2r_true`	`float`	Reduced chi-squared of the test and true models.	required
`ndof`	`int`	Degrees of freedom.	required

Returns:

Type	Description
`float`	Detection significance in Gaussian sigma.

`radial_profile(values, dra, ddec, center=(0.0, 0.0), r_max=None, bins=20)`

Azimuthal statistics of a map in bins of separation.

Parameters:

Name	Type	Description	Default
`values`	`array - like`	Map of shape `(len(dra), len(ddec))` (axis 0 is `dra`), e.g. flux limits.	required
`dra`	`array - like`	Grid axes in mas.	required
`ddec`	`array - like`	Grid axes in mas.	required
`center`	`tuple[float, float]`	Centre `(dra, ddec)` of the annuli in mas.	`(0.0, 0.0)`
`r_max`	`float`	Outer radius in mas (default: the largest separation on the grid).	`None`
`bins`	`int`	Number of annuli.	`20`

Returns:

Type	Description
`dict`	`r` (annulus centres, mas), `mean`, `std`, `median`, `q16`, `q84` and `count`. Non-finite values are ignored; empty annuli are NaN.