Contrast limits: Ruffio and Absil
Install: the "As a pipeline" section needs the
pipelineextra:pip install "virgil-astro[pipeline]".
You have a non-detection, or you have subtracted a well-measured companion and want to know whether anything else is in the data. What could you have detected?
This tutorial applies the two methods common in interferometry to a non-detection: the Bayesian Ruffio method and the frequentist Absil method. Detection limits says which to use.
First, the imports.
Imports and setup
import shutil
import jax
import jax.numpy as jnp
import numpy as onp
import jax.scipy as jsp
import matplotlib.pyplot as plt
from virgil.coverage import nrm_oidata
from virgil.grid_fit import laplace_flux_uncertainty_grid, optimized_flux_grid
from virgil.limits import absil_limits, flux_to_delta_mag, ruffio_upperlimit
from virgil.models import BinaryModelCartesian
from virgil.plotting import plot_contrast_curve, plot_grid_map, set_style
set_style() # the figure style used throughout the docs
shutil.rmtree("limits_run", ignore_errors=True) # the pipeline section writes here
Simulate Data
We generate pure-noise data with the Fourier sampling of the JWST AMI mask: nrm_oidata gives the 21 squared visibilities and 35 closure phases of its seven holes at 4.8 microns, with zero data and chosen errors, and with_model fills them from a model plus noise. The model is a lone star, a binary with no flux in the companion.
oidata_sim = nrm_oidata(
wavelength_m=4.817e-6, sigma_v2=3.3e-4, sigma_cp_deg=0.016
).with_model(
BinaryModelCartesian(dra=0.0, ddec=0.0, flux=0.0), key=jax.random.PRNGKey(7)
)
print(oidata_sim.vis.size, "squared visibilities and", oidata_sim.phi.size, "closure phases")
21 squared visibilities and 35 closure phases
Declare a search grid
Next, declare the search grid. It sets the flux level in each pixel about which we expand the posterior or build confidence intervals.
samples = {
"dra": jnp.linspace(-250.0, 250.0, 61),
"ddec": jnp.linspace(-250.0, 250.0, 61),
"flux": 10 ** jnp.linspace(-5.0, -1.5, 50),
}
# Best-fit companion/primary flux at every (dra, ddec).
opt_flux = optimized_flux_grid(BinaryModelCartesian, oidata_sim, samples)
RuntimeWarning: optimized_flux_grid(): the optimizer did not converge at 160 of 3721 grid positions; values there may be inaccurate.
optimized_flux_grid warns where its optimizer did not converge (here at a few per cent of the grid points), because the best-fit flux, and so the limit, may be inaccurate there; the warning is the function telling you where.
Ruffio limits
The Ruffio limit is a Bayesian upper limit on a companion's flux at each position, conditioned on the astrometry being right and a source being there; Ruffio et al. 2018, defined in Detection limits.
sigma_flux = laplace_flux_uncertainty_grid(
BinaryModelCartesian, oidata_sim, samples, flux=opt_flux
)
# Ruffio method at the 2σ-equivalent percentile
perc = jsp.stats.norm.cdf(2.0)
ruffio_map = ruffio_upperlimit(opt_flux, sigma_flux, perc)
plot_grid_map(
ruffio_map, samples, kind="limit", units="delta_mag", percentile=perc
);

Absil limits
The Absil limit is the faintest companion that a \(\chi^2\) test would have detected at n-σ; Absil et al. 2011, defined in Detection limits.
# Absil method at 2σ
absil_map = absil_limits(
BinaryModelCartesian, oidata_sim, samples, sigma=2.0, flux_bounds=(1e-8, 1.0)
)
plot_grid_map(absil_map, samples, kind="limit", units="delta_mag", sigma=2.0);
RuntimeWarning: absil_limits(): 1 limits fell outside flux_bounds=(1e-08, 1.0) and were clipped to the nearer bound; pass wider flux_bounds, or None, to search further.

Contrast curves
absil_limits warns that one limit fell outside flux_bounds and was clipped to the nearer bound; it is a single pixel of the map. Plotted as contrast curves on one axis, the two methods give similar but not identical limits.
The limits are companion/primary flux ratios; units="delta_mag" (the default for curves) or units="contrast" converts for display (units).
Contrast limits say which companions a non-detection rules out at each position. To calibrate a detection threshold against simulated noise, including the look-elsewhere effect of a grid search, and to measure completeness at a fixed false-alarm probability, see Detection ROC curves.
# Overplot Ruffio and Absil radial contrast curves on one axis
fig, ax = plt.subplots(figsize=(8, 4))
plot_contrast_curve(ruffio_map, samples, label="Ruffio (2σ-equivalent)", ax=ax)
plot_contrast_curve(absil_map, samples, label="Absil 2σ", ax=ax)
ax.set_title("Radial contrast limits: Ruffio vs Absil");

As a pipeline
The search grid, Ruffio limits and contrast curve are the search and limits stages of BinaryPipeline, so running it through="limits" stops before the fit and sampler, which a non-detection does not need. The cell below uses the same \(\pm 250\) mas grid of 61 points per axis, the same flux axis and \(\sigma = 2\). The pipeline blanks grid points inside the resolution limit, where separation and flux are degenerate, so compare its limit map with the hand-computed Ruffio map where both are defined; limit_method="absil" gives the Absil map instead. The contrast curve is one of the pipeline's plots. A non-detection is the expected outcome here, so the detection check warns that no companion exceeds 3σ; the convergence and stage_warnings warnings count grid positions where the flux refinement did not converge, as in the warning above; res.describe() prints the full report.
from IPython.display import Image, display
from virgil.pipeline import BinaryPipeline
res = BinaryPipeline(
oidata_sim,
BinaryModelCartesian(dra=0.0, ddec=0.0, flux=1e-3),
output="limits_run",
sigma=2.0,
max_sep_mas=250.0,
grid_step_mas=8.34, # 61 points from -250 to 250 mas
flux_range=[1e-5, 10**-1.5],
n_flux=50,
).run(through="limits")
s = res.summary
print(f"chi2/N of the star alone: {s['chi2']['null_reduced']:.2f}; "
f"best grid point {s['search']['local_nsigma']:.1f} sigma (local)")
print(f"deepest 2-sigma limit: {s['limits']['deepest_delta_mag']:.1f} mag")
print({c.name: c.status for c in res.checks if c.status != "pass"})
display(Image(filename=str(res.path / "plots" / "limits_contrast_curve.png")))
chi2/N of the star alone: 1.05; best grid point 1.9 sigma (local)
deepest 2-sigma limit: 10.7 mag
{'detection': 'warn', 'convergence': 'warn', 'stage_warnings': 'warn'}
