Catalogue and line fit¶
Catalogue¶
luv_finder.catalogue.catalogue() turns a search with its jackknife (one pointing
or the combined mosaic, on a uniform position lattice) into an astropy table of line
candidates. The jackknife, which has the data’s noise and no sky, is the reference
throughout:
the S/N is the filter’s, normalised by its exact variance under the correlation between channels measured on the jackknife per spectral window (
channel_noise()), so it has unit variance under H0 (jackknife_spread()checks it);the correlation function of the jackknife response is measured; it is also the expected shape of a matched line’s response (Vio & Andreani 2021), so its half-power ellipsoid in position and frequency is what one source occupies;
local maxima of the best-template S/N above 4 are merged, brightest first, within that ellipsoid, for the data, the jackknife and (as a diagnostic) the negated data;
every data group gets the likelihood ratio
N_data(>= S/N) / N_jackknife(>= S/N)(van Marrewijk et al. 2025, required >= 3) and the fidelity1 - N_jackknife / N_dataper S/N bin (González-López et al. 2019, required >= 0.6).N_jackknifeis a model of the jackknife’s peak counts,N(>= u) = n_k (u/2.5)^m exp(-(u^2 - 2.5^2)/2)(peak_exponent()): one exponentmper search, with a prior of width 1 about the field’s dimension minus one, andn_kper template, since narrow templates make more trials. Fewer than 10 noise peaks detect nothing.detectedneeds both tests (rule="and", the default) or either ("or"); the defaults arecatalogue.RELIABILITY.
from luv_finder.catalogue import catalogue
cat = catalogue(result, ref=data.metadata.ref)
lines = cat[cat["detected"]]
cat.write("lines.ecsv", format="ascii.ecsv")
A run (Quickstart) does this per unit and merges the units with
merge_catalogues(), which recomputes the reliability over
the whole volume and counts a line found by two units once (duplicate_of). The
template’s bmaj, bmin and width columns are FWHM.
A line whose sidelobes reach the floor (bright()) is fitted,
subtracted from the visibilities and the unit searched again, up to five rounds; the
catalogue’s round column says when (0: never subtracted).
Continuum sources¶
The filter fits a continuum at every position with that position’s lines masked, so
the search also yields a continuum per window at no extra cost.
continuum_catalogue() catalogues it with the same tests (a
peak exponent about 1), and a run writes continuum.ecsv: each source fitted in the
visibilities as a Gaussian with a flux density per window, its in-band spectrum and
spectral index alpha, bright ones subtracted in rounds like the lines.
Fitting the detected lines¶
Detection stays a grid search. luv_finder.fit.fit_lines() then refines every
detected line by least squares in the visibilities: an elliptical Gaussian source
(position and sky covariance) whose spectrum is a Gaussian line on a polynomial continuum,
times each pointing’s primary beam at the source, jointly in every pointing whose primary
beam covers the line (PB >= 0.2) and every spectral window within one FWHM of it, each
window with its own continuum.
from luv_finder.fit import fit_lines
fitted = fit_lines("mosaic.npz", cat) # or the search's DataHandler
fitted.write("lines.ecsv", format="ascii.ecsv", overwrite=True)
luv-run run.yaml fit fits a run’s detections and near misses. The fitted columns
(fit_dra, fit_ddec, fit_ra, fit_dec; fit_bmaj, fit_bmin as FWHM
and fit_pa; fit_freq_ghz, fit_width as FWHM in km/s, fit_peak,
fit_line_flux and fit_continuum at the line centre, each with an _error) are
intrinsic, PB-corrected values. An unresolved axis lands on zero size, with a NaN error.
Errors are formal, corrected for the channel correlation. meta["spectra"] keeps every
fitted line’s spectrum and best fit; line_maps() makes their
moment-0 maps.
Diagnostic figures¶
luv_finder.plotting holds every figure; each returns its figure and writes it
to plots_dir when one is given. reliability_check() shows the counts, the
likelihood ratio and the fidelity; response_shape_check() the
response correlation against real lines; line_spectra_check()
and line_maps_check() the fitted lines. pytest --plots
writes the test figures to plots/ with an index.html contact sheet.