luv_finder.matchedfilter

Grid-search matched filter for spectral lines in the UV plane, in JAX (float64).

Per window and trial source shape, luv_finder.kernel collapses the visibilities, weighted by the source’s own visibility amplitude, onto every trial position: the dirty spectrum d = sig / W with variance 1 / W. At every position and channel the model is d = A g + P c, the Gaussian line template g on a polynomial continuum P c in the channel index. With c free, A is the fit of the template projected off the polynomials, h = g - P (P^T W P)^-1 P^T W g: A = h^T W d / h^T W h. A polynomial cannot mimic a narrow Gaussian, so no line-free channels are needed; the line loses only the polynomial-like part of g. The error of A includes the channel correlation measured on the jackknife, so the S/N has unit variance under the null.

Module Attributes

GRID_DEFAULTS

The value of a search axis a grid leaves out: the phase centre, a point source, a 100 km/s line.

MASK_SNR

A line whose response peaks at MASK_SNR or more at a position is left out of the continuum fit there, within MASK_FWHM template FWHM of its peak, so it does not bend the continuum of the others.

MASK_FWHM

A line whose response peaks at MASK_SNR or more at a position is left out of the continuum fit there, within MASK_FWHM template FWHM of its peak, so it does not bend the continuum of the others.

CONTINUUM_MASK_FWHM

Template FWHM a line masks from the continuum of its position (_continuum()): a Gaussian line keeps 1.8% of its flux beyond 1 FWHM, 0.9 sigma of a S/N 100 line's continuum, and 1e-6 beyond 2.

MASK_PEAKS

The brightest peaks per position that may mask (a position rarely holds more lines at MASK_SNR).

SPECTRAL_ARRAYS

Arrays of a block's positions x templates x centres that _spectral() holds at once (measured on ASPECS 3 mm, 2026-10-22): it sizes the position blocks, so a window's spectral fit stays within BLOCK_BYTES.

POINT

FWHM of a grid's default source shape, a point to the filter, in units of the resolution (a sigma of 1/10).

WIDTHS

Template FWHMs (km/s) a grid searches unless it names its own.

Functions

build_grid(data, cfg)

Grid ranges from YAML, positions in the dataset's sky frame (arcsec from the reference).

combine_pointings(results[, span, own])

Combine the PB-corrected searches of a mosaic's pointings on the union of their grids, one at a time.

continuum(windows[, freq])

A continuum per window (SearchResult.continuum) as one: the windows combined by inverse variance, a single "channel" at freq Hz, by default their mean frequency weighted alike; its jackknife alike.

continuum_response(data, grid_cfg[, ...])

The continuum per window of in-memory data (a model's visibilities, say) on the search's grid: every field PB-corrected and combined as search_pointings() does, over every channel.

grid_axis(cfg, key, default)

One search axis of a grid YAML: a value, a list, or {start, stop, step}; default if absent.

pb_corrected(result, data[, pb_limit])

The search of one pointing corrected for its primary beam (a copy; result is left as it is).

search_pointings(path[, grid_cfg, ...])

Search every field (or fields) of a measurement set or NPZ, PB-corrected, and combine them on one sky grid as they come; subtract takes each field's data to what is searched (a model's residual).

window_groups(freqs[, widest])

Windows ({key: freq}) joined where they overlap or their gap is narrower than widest km/s.

Classes

MatchedFilter(data, grid[, continuum_order, ...])

S/N of one field over the grid axes (GRID_KEYS: a value or a list each, else GRID_DEFAULTS, e.g. from build_grid()); channel_noise: "measure", None or {spw: ChannelNoise}.

SearchResult(axes, freqs, snr, error, coverage)

Matched-filter search of one pointing or of a mosaic.

luv_finder.matchedfilter.CONTINUUM_MASK_FWHM = 2.0

Template FWHM a line masks from the continuum of its position (_continuum()): a Gaussian line keeps 1.8% of its flux beyond 1 FWHM, 0.9 sigma of a S/N 100 line’s continuum, and 1e-6 beyond 2.

luv_finder.matchedfilter.GRID_DEFAULTS = {'bmaj': 0.0, 'bmin': 0.0, 'ddec': 0.0, 'dra': 0.0, 'pa': 0.0, 'width': 100.0}

The value of a search axis a grid leaves out: the phase centre, a point source, a 100 km/s line.

luv_finder.matchedfilter.MASK_FWHM = 1.0

A line whose response peaks at MASK_SNR or more at a position is left out of the continuum fit there, within MASK_FWHM template FWHM of its peak, so it does not bend the continuum of the others.

luv_finder.matchedfilter.MASK_PEAKS = 4

The brightest peaks per position that may mask (a position rarely holds more lines at MASK_SNR).

luv_finder.matchedfilter.MASK_SNR = 5.0

A line whose response peaks at MASK_SNR or more at a position is left out of the continuum fit there, within MASK_FWHM template FWHM of its peak, so it does not bend the continuum of the others.

class luv_finder.matchedfilter.MatchedFilter(data: DataHandler, grid: dict, continuum_order: int | None = 1, channel_noise: str | dict | None = 'measure', band: tuple[float, float] | None = None, core: tuple[float, float] | None = None, lines: bool = True)[source]

S/N of one field over the grid axes (GRID_KEYS: a value or a list each, else GRID_DEFAULTS, e.g. from build_grid()); channel_noise: “measure”, None or {spw: ChannelNoise}.

band (Hz, low and high) keeps the trial centres there, a chunk of a long spectrum: every window is still fitted over all its centres, so its continuum and its masks are those of the whole spectrum. core (Hz) the windows whose continuum this search gives, those centred in it (None: every window), so the chunks of a spectrum give each window’s continuum once. Without lines only the continuum is computed, over every channel (a model’s response, say).

run(jackknife: bool = False, cores: int | None = None) → None[source]

Fill result and, with jackknife, result.jackknife on the same grid, on cores cores.

luv_finder.matchedfilter.POINT = 0.23550000000000001

FWHM of a grid’s default source shape, a point to the filter, in units of the resolution (a sigma of 1/10).

luv_finder.matchedfilter.SPECTRAL_ARRAYS = 4

Arrays of a block’s positions x templates x centres that _spectral() holds at once (measured on ASPECS 3 mm, 2026-10-22): it sizes the position blocks, so a window’s spectral fit stays within BLOCK_BYTES.

class luv_finder.matchedfilter.SearchResult(axes: dict, freqs: ndarray, snr: ndarray, error: ndarray, coverage: ndarray, jackknife: SearchResult | None = None, continuum: SearchResult | None = None)[source]

Matched-filter search of one pointing or of a mosaic.

continuum: SearchResult | None = None

The flat-spectrum continuum per window, a search with one “channel” per window (continuum()).

property flux: ndarray

Peak flux density, Jy: snr * error.

property response: ndarray

S/N as (n_grid, n_chan), one row per grid_params entry.

luv_finder.matchedfilter.WIDTHS = (50.0, 100.0, 300.0, 500.0)

Template FWHMs (km/s) a grid searches unless it names its own.

luv_finder.matchedfilter.build_grid(data: DataHandler, cfg: dict | None) → dict[source]

Grid ranges from YAML, positions in the dataset’s sky frame (arcsec from the reference).

luv_finder.matchedfilter.combine_pointings(results: Iterable[SearchResult], span: tuple | None = None, own: bool = False) → SearchResult[source]

Combine the PB-corrected searches of a mosaic’s pointings on the union of their grids, one at a time.

span (dra, ddec), the union’s axes if known, is allocated with the first pointing, so the sums never grow (and are never copied) as the pointings come; own results are spent on their sums.

luv_finder.matchedfilter.continuum(windows: SearchResult, freq: float | None = None) → SearchResult[source]

A continuum per window (SearchResult.continuum) as one: the windows combined by inverse variance, a single “channel” at freq Hz, by default their mean frequency weighted alike; its jackknife alike.

luv_finder.matchedfilter.continuum_response(data: DataHandler, grid_cfg: dict | None, pb_limit: float = 0.2, cores: int | None = None) → SearchResult[source]

The continuum per window of in-memory data (a model’s visibilities, say) on the search’s grid: every field PB-corrected and combined as search_pointings() does, over every channel.

luv_finder.matchedfilter.grid_axis(cfg: dict | None, key: str, default) → ndarray[source]

One search axis of a grid YAML: a value, a list, or {start, stop, step}; default if absent.

luv_finder.matchedfilter.pb_corrected(result: SearchResult, data: DataHandler, pb_limit: float = 0.2) → SearchResult[source]

The search of one pointing corrected for its primary beam (a copy; result is left as it is).

luv_finder.matchedfilter.search_pointings(path: str, grid_cfg: dict | None = None, jackknife: bool = True, cores: int | None = None, pb_limit: float = 0.2, fields: list[int] | None = None, subtract: Callable[[DataHandler], DataHandler] | None = None, **filter_kwargs) → SearchResult[source]

Search every field (or fields) of a measurement set or NPZ, PB-corrected, and combine them on one sky grid as they come; subtract takes each field’s data to what is searched (a model’s residual).

luv_finder.matchedfilter.window_groups(freqs: dict, widest: float = 500.0) → list[list][source]

Windows ({key: freq}) joined where they overlap or their gap is narrower than widest km/s.

A line no wider than the widest template is then searched and fitted in every window that holds it. The groups, each a sorted list of keys, come in frequency order.