Catalogue and line fit ====================== Catalogue --------- :func:`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 (:func:`~luv_finder.data.channel_noise`), so it has unit variance under H0 (:func:`~luv_finder.catalogue.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)`` (:func:`~luv_finder.catalogue.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``. .. code-block:: python 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 (:doc:`../quickstart`) does this per unit and merges the units with :func:`~luv_finder.catalogue.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 (:func:`~luv_finder.catalogue.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. :func:`~luv_finder.catalogue.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. :func:`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. .. code-block:: python 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; :func:`~luv_finder.imaging.line_maps` makes their moment-0 maps. Diagnostic figures ------------------ :mod:`luv_finder.plotting` holds every figure; each returns its figure and writes it to ``plots_dir`` when one is given. :func:`~luv_finder.plotting.reliability_check` shows the counts, the likelihood ratio and the fidelity; :func:`~luv_finder.plotting.response_shape_check` the response correlation against real lines; :func:`~luv_finder.plotting.line_spectra_check` and :func:`~luv_finder.plotting.line_maps_check` the fitted lines. ``pytest --plots`` writes the test figures to ``plots/`` with an ``index.html`` contact sheet.