luv_finder.catalogue

Module Attributes

DETECTION_RULE

How the likelihood ratio and the fidelity combine into detected: "and" (both) or "or" (either).

RELIABILITY

Default reliability tests: the S/N floor of the groups, the likelihood ratio k, the fidelity and the rule.

NOISE_FLOOR

Lowest S/N of the noise peaks the noise model is fitted to (the data's groups start at floor).

MIN_NOISE

Fewest noise peaks above NOISE_FLOOR to fit the model to; fewer, and nothing is detected.

EXPONENT_PRIOR

Width of the Gaussian prior on the exponent m, about the field's dimension minus one.

UNITS

Units of the catalogue() columns.

SEARCH_META

meta of catalogue() that belongs to one search, kept per part by merge_catalogues().

Functions

bright(cat, floor)

The detections whose sidelobes reach floor: S/N at least the brightest's times the response's highest sidelobe, none if the brightest's own sidelobes stay below floor.

catalogue(result[, ref, floor, k, ...])

Catalogue the line candidates of a search: one row per group of the data, by S/N descending.

continuum_catalogue(windows[, ref])

Catalogue the continuum sources of a search's continuum per window (SearchResult.continuum).

duplicates(cat, beam[, by])

Id of a brighter group of the same line in another unit (another by), else 0, for every row of cat.

fidelity(snr_data, snr_noise, noise, floor)

Fidelity 1 - N_noise / N_data per S/N bin from floor, N_noise from the noise model noise.

groups(snr, result, nc[, floor])

Group the local maxima of snr into candidates, one per source, brightest first.

jackknife_spread(result)

Robust spread of the jackknife S/N per template, (n_template,): 1 under H0.

likelihood(snr_data, noise)

N_data(>= gamma) / N_noise(>= gamma) at every data S/N (Vio & Andreani 2021); noise(u) the expected noise peaks at or above u (noise_above()), infinite where it is zero.

merge_catalogues(cats[, reliability, beam])

One catalogue of several searches (e.g. one per spectral window), its reliability over their whole volume.

noise_above(u, n, m[, floor])

Expected noise peaks at or above u of a kernel with n noise peaks above floor.

passes(ratio, fid, k, fidelity_min)

Which groups pass the likelihood ratio and which the fidelity (NaN passes neither).

peak_exponent(snr_noise, dim[, floor])

Exponent m of the noise peak counts N(>= u) ~ u^m exp(-u^2 / 2) above floor, by unbinned MAP.

response_correlation(result[, max_lag, ...])

Measure the correlation function of the response under the null on the search's jackknife.

Classes

Group(i, j, t, k, snr, n_peaks)

Local maxima of the S/N merged into one candidate (see groups()).

ResponseCorrelation(spatial, lags_ra, ...)

Correlation function of the matched-filter response under the null (see response_correlation()).

luv_finder.catalogue.DETECTION_RULE = 'and'

How the likelihood ratio and the fidelity combine into detected: “and” (both) or “or” (either).

luv_finder.catalogue.EXPONENT_PRIOR = 1.0

Width of the Gaussian prior on the exponent m, about the field’s dimension minus one.

class luv_finder.catalogue.Group(i: int, j: int, t: int, k: int, snr: float, n_peaks: int)[source]

Local maxima of the S/N merged into one candidate (see groups()).

luv_finder.catalogue.MIN_NOISE = 10

Fewest noise peaks above NOISE_FLOOR to fit the model to; fewer, and nothing is detected.

luv_finder.catalogue.NOISE_FLOOR = 2.5

Lowest S/N of the noise peaks the noise model is fitted to (the data’s groups start at floor).

luv_finder.catalogue.RELIABILITY = {'fidelity_min': 0.6, 'floor': 4.0, 'k': 3.0, 'rule': 'and'}

Default reliability tests: the S/N floor of the groups, the likelihood ratio k, the fidelity and the rule.

class luv_finder.catalogue.ResponseCorrelation(spatial: ndarray, lags_ra: ndarray, lags_dec: ndarray, spectral: ndarray, templates: ndarray, hwhm_major: ndarray, hwhm_minor: ndarray, pa: ndarray, spectral_hwhm: ndarray, spectral_hwhm_kms: ndarray, sidelobe: ndarray)[source]

Correlation function of the matched-filter response under the null (see response_correlation()).

luv_finder.catalogue.SEARCH_META = ('jackknife_spread', 'hwhm_major', 'hwhm_minor', 'pa', 'spectral_hwhm', 'sidelobe')

meta of catalogue() that belongs to one search, kept per part by merge_catalogues().

luv_finder.catalogue.UNITS = {'bmaj': 'arcsec', 'bmin': 'arcsec', 'ddec': 'arcsec', 'dec': 'deg', 'dra': 'arcsec', 'error': 'Jy', 'flux': 'Jy', 'freq_ghz': 'GHz', 'line_flux': 'Jy km/s', 'line_flux_error': 'Jy km/s', 'pa': 'deg', 'ra': 'deg', 'width': 'km/s'}

Units of the catalogue() columns.

luv_finder.catalogue.bright(cat: Table, floor: float) → ndarray[source]

The detections whose sidelobes reach floor: S/N at least the brightest’s times the response’s highest sidelobe, none if the brightest’s own sidelobes stay below floor. They are subtracted in rounds.

luv_finder.catalogue.catalogue(result: SearchResult, ref=None, floor: float = 4.0, k: float = 3.0, fidelity_min: float = 0.6, rule: str = 'and', band: tuple[float, float] | None = None) → Table[source]

Catalogue the line candidates of a search: one row per group of the data, by S/N descending.

The noise correlation of result is measured, and the data, the jackknife and the negated data are grouped (groups()) on the filter’s S/N (see the module docstring), the data from floor, the jackknife and the negated data from NOISE_FLOOR. Each data group gets the likelihood ratio and the fidelity against the noise peak counts modelled on the jackknife’s groups of its own kernel (peak_exponent(), likelihood(), fidelity()). It is detected if Lambda >= k and its fidelity is at least fidelity_min (rule="and", the default), or either (rule="or"); without a noise model (fewer than MIN_NOISE noise peaks) nothing is. Nothing is clipped: the candidates are cat[cat["detected"]].

Parameters:
resultSearchResult

PB-corrected (and, for a mosaic, combined) search with its jackknife.

ref(RA, Dec) in rad, optional

The sky frame’s reference (ref); adds ra and dec.

floorfloat

Lowest S/N of a local maximum, and the lower edge of the fidelity bins.

kfloat

Likelihood-ratio threshold.

fidelity_minfloat

Fidelity threshold.

rule{“or”, “and”}

How the two tests combine into detected.

band(low, high) Hz, optional

Keep only the groups (of the data, the jackknife and the negated data) that peak in low <= nu < high: the chunk’s own part of a spectrum searched in overlapping chunks.

Returns:
astropy.table.Table

Columns id, dra, ddec (arcsec), ra, dec (deg, with ref), freq_ghz, the template’s bmin, bmaj, pa and width, the snr, flux and error (Jy) and line_flux, line_flux_error (Jy km/s) at the brightest maximum, coverage, n_peaks, likelihood, fidelity and detected. meta holds the jackknife_spread, the noise correlation’s hwhm_major, hwhm_minor, pa, spectral_hwhm and sidelobe, the thresholds, the noise model (noise_floor, noise_exponent, kernels), the lowest data S/N with Lambda >= k (snr_likelihood) and with a fidelity of at least fidelity_min (snr_fidelity), NaN if none, the S/N of every group of the data, the jackknife and the negated data (snr_data, snr_jackknife, snr_negative) and the binned fidelity (fidelity_bins), all as lists and floats.

Raises:
ValueError

If result has no jackknife.

luv_finder.catalogue.continuum_catalogue(windows: SearchResult, ref=None, **reliability) → Table[source]

Catalogue the continuum sources of a search’s continuum per window (SearchResult.continuum).

Grouped and tested as catalogue() on the windows combined (continuum(), freq_ghz their mean frequency), each source has its in-band spectrum, the flux density and error of every window at its position and template (meta["spectra"]), and the spectral index alpha (S ~ nu^alpha) fitted to it, linearised about freq_ghz.

luv_finder.catalogue.duplicates(cat: Table, beam: dict, by: str = 'unit') → ndarray[source]

Id of a brighter group of the same line in another unit (another by), else 0, for every row of cat.

Two groups are one line when they are within beam[unit] (arcsec) of each other and their templates overlap, |dv| <= (FWHM_a + FWHM_b) / 2: a line wider than the gap it straddles between two windows is found once in each, its halves far apart in frequency. cat is sorted by S/N.

luv_finder.catalogue.fidelity(snr_data, snr_noise, noise, floor: float, step: float = 0.25) → tuple[ndarray, dict][source]

Fidelity 1 - N_noise / N_data per S/N bin from floor, N_noise from the noise model noise.

Every data group gets its bin’s fidelity. The bins hold the counts of the data and of the noise groups snr_noise, their binned fidelity with its error (for the eye) and the model fidelity.

luv_finder.catalogue.groups(snr: ndarray, result: SearchResult, nc: ResponseCorrelation, floor: float = 4.0) → list[Group][source]

Group the local maxima of snr into candidates, one per source, brightest first.

luv_finder.catalogue.jackknife_spread(result: SearchResult) → ndarray[source]

Robust spread of the jackknife S/N per template, (n_template,): 1 under H0.

luv_finder.catalogue.likelihood(snr_data, noise) → ndarray[source]

N_data(>= gamma) / N_noise(>= gamma) at every data S/N (Vio & Andreani 2021); noise(u) the expected noise peaks at or above u (noise_above()), infinite where it is zero.

luv_finder.catalogue.merge_catalogues(cats: Sequence[Table], reliability: dict | None = None, beam: dict | None = None) → Table[source]

One catalogue of several searches (e.g. one per spectral window), its reliability over their whole volume.

reliability (floor, k, fidelity_min, rule) overrides the searches’ own, so the tests can change without a new search. With beam (arcsec per unit), a line found by two searches (duplicates()) counts once: the fainter group gets duplicate_of and is not detected.

luv_finder.catalogue.noise_above(u, n: int, m: float, floor: float = 2.5) → ndarray[source]

Expected noise peaks at or above u of a kernel with n noise peaks above floor.

luv_finder.catalogue.passes(ratio, fid, k: float, fidelity_min: float) → tuple[ndarray, ndarray][source]

Which groups pass the likelihood ratio and which the fidelity (NaN passes neither).

luv_finder.catalogue.peak_exponent(snr_noise, dim: int, floor: float = 2.5) → float[source]

Exponent m of the noise peak counts N(>= u) ~ u^m exp(-u^2 / 2) above floor, by unbinned MAP.

The expected number of peaks of a smooth Gaussian field of dimension dim above u (its Euler characteristic, Vio & Andreani 2021) is a polynomial in u times exp(-u^2 / 2), of degree dim - 1: the prior’s centre, EXPONENT_PRIOR wide, so a few noise peaks (a continuum) cannot drive m far off and many (a line search) set it. NaN, with a warning, below MIN_NOISE peaks.

luv_finder.catalogue.response_correlation(result: SearchResult, max_lag: float = 30.0, max_lag_chan: int | None = None) → ResponseCorrelation[source]

Measure the correlation function of the response under the null on the search’s jackknife.