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:

  1. 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);

  2. 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;

  3. 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;

  4. every data group gets the likelihood ratio N_data(>= S/N) / N_jackknife(>= S/N) (van Marrewijk et al. 2025, required >= 3) and the fidelity 1 - N_jackknife / N_data per S/N bin (González-López et al. 2019, required >= 0.6). N_jackknife is 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 exponent m per search, with a prior of width 1 about the field’s dimension minus one, and n_k per template, since narrow templates make more trials. Fewer than 10 noise peaks detect nothing. detected needs both tests (rule="and", the default) or either ("or"); the defaults are catalogue.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.