streamobs.match_filter module

streamobs.match_filter.build_filter_splines(iso_color: ndarray, iso_mag: ndarray, *, mu: float = 0.0, mag_is_absolute: bool = True, abs_mag_min: float | None = 2.9, app_mag_max: float | None = None, color_min: float = -0.5, color_max: float = 1.5, dmu: float = 0.5, C: tuple | list = (0.05, 0.05), E: tuple | list = (2.0, 2.0), err: Callable[[ndarray], ndarray] | None = None) → Tuple[Callable, Callable]

Build matched-filter boundary splines from precomputed isochrone arrays.

Constructs two interpolating functions — spline_near (blue/near edge) and spline_far (red/far edge) — that give the color boundaries of the matched-filter region as a function of apparent magnitude.

The splines are built from the isochrone locus after applying magnitude cuts and color clipping, so they remain bounded even where the raw exponential error model would diverge.

Parameters:

• iso_color (array_like) – Isochrone color array (e.g. g−r) for the locus.

• iso_mag (array_like) – Isochrone magnitude array. Interpreted as absolute magnitude when mag_is_absolute=True, apparent magnitude otherwise.

• mu (float, optional) – Distance modulus (used only when mag_is_absolute=True).

• mag_is_absolute (bool, optional) – Whether iso_mag is in absolute magnitudes.

• abs_mag_min (float or None, optional) – Bright absolute-magnitude cut applied before spline fitting.

• app_mag_max (float or None, optional) – Faint apparent-magnitude cut applied before spline fitting.

• color_min (float, optional) – Hard clip bounds applied to the near/far color envelopes before spline fitting. These prevent runaway exponential values from entering the polygon.

• color_max (float, optional) – Hard clip bounds applied to the near/far color envelopes before spline fitting. These prevent runaway exponential values from entering the polygon.

• dmu (float, optional) – Half-width of the distance-modulus spread used to shift magnitudes for the near/far error evaluation.

• C (tuple/list [near, far], optional) – Additive color padding on the near (blue) and far (red) sides.

• E (tuple/list [near, far], optional) – Multiplicative error scaling for near and far sides.

• err (callable or None, optional) – Function err(apparent_mag) -> mag_error. When None the default exponential model is used.

Returns:

spline_near, spline_far – Functions mapping apparent magnitude → color boundary. They return nan outside the valid magnitude range so that callers can detect out-of-bounds regions without needing explicit range checks.

Return type:

callable

streamobs.match_filter.build_match_filter(distance_modulus, age=13.0, metallicity=0.0002, distance_modulus_spread=0.5, color_spread=[0.05, 0.05], error_multiplier=[2.0, 2.0], rgb_clip_mag=0.2, color_cut=True, red_cap_mode='error_shrunk', verbose=False, error_kwargs={}, survey='lsst', isochrone_model='Marigo2017', band_1='g', band_2='r')

Build an isochrone matched-filter polygon in color-magnitude space.

Creates a closed polygon that encompasses the expected locus of stars at a given distance, accounting for photometric errors and distance spread.

Implementation note: polygon edges are constructed via spline interpolation of the isochrone locus rather than raw concatenation of error-broadened arrays. This keeps all polygon vertices strictly bounded (within the color_min/color_max clip derived from the survey), preventing the exponential error model from producing degenerate colors at the faint end (the old approach produced blue-edge colors of ~ -113 at distance_modulus ≈ 16.8 with default LSST parameters).

Parameters:

• distance_modulus (float) – Distance modulus (m − M) of the stellar population in magnitudes.

• age (float, optional) – Isochrone age in Gigayears (Gyr).

• metallicity (float, optional) – Isochrone metallicity as mass fraction Z.

• distance_modulus_spread (float, optional) – Half-width of the distance modulus range to consider [mag].

• color_spread (list of float, optional) – Additive color padding as [blue_side, red_side] in magnitudes.

• error_multiplier (list of float, optional) – Multiplicative scaling for photometric errors as [blue_side, red_side].

• rgb_clip_mag (float or None, optional) – If provided, clips the Red Giant Branch at this magnitude offset from the Main Sequence Turn-Off (MSTO).

• color_cut (bool, optional) – If True, the red spline edge is additionally capped so the filter does not extend to very red stars (see red_cap_mode).

• red_cap_mode ({'error_shrunk', 'constant'}, optional) –

  How the red-edge cap behaves when color_cut=True:

  • 'error_shrunk' (default): cap at (color_max - 0.25) - error(mag_far), so the cap moves blueward with the photometric error and the filter narrows (eventually closes) at the faint end — the historical pre-spline behaviour, now applied to the spline-sampled edges. The far edge is floored at the near edge so the polygon stays simple instead of self-crossing.

  • 'constant': cap at color_max - 0.25 at all magnitudes.

• verbose (bool, optional) – Print diagnostic information.

• error_kwargs (dict, optional) – Extra keyword arguments forwarded to error_model().

• survey (str, optional) – Survey name passed to the ugali isochrone factory. Also controls per-survey color clip limits and absolute-magnitude cuts.

• isochrone_model (str, optional) – Ugali isochrone model name (e.g. 'Marigo2017').

• band_1 (str, optional) – Bands defining the CMD: color = band_1 − band_2, magnitude = band_1. Defaults ('g', 'r') preserve the historical LSST behaviour. For Roman pass e.g. band_1='F106', band_2='F158'. Roman isochrone magnitudes are returned by ugali in Vega and are converted to AB here (via the ROMAN_VEGA_TO_AB table that the injection path uses), so the filter selects on the same photometric system as the injected catalogs.

• band_2 (str, optional) – Bands defining the CMD: color = band_1 − band_2, magnitude = band_1. Defaults ('g', 'r') preserve the historical LSST behaviour. For Roman pass e.g. band_1='F106', band_2='F158'. Roman isochrone magnitudes are returned by ugali in Vega and are converted to AB here (via the ROMAN_VEGA_TO_AB table that the injection path uses), so the filter selects on the same photometric system as the injected catalogs.

Returns:

polygon_vertices – Vertices of the closed polygon as (color, magnitude) pairs. Column 0: color (band_1 − band_2) Column 1: apparent band_1 magnitude Suitable for use with matplotlib.path.Path.contains_points().

Return type:

ndarray, shape (N, 2)

Notes

• Uses Marigo2017 isochrone models from the ugali package by default.

• The Vega→AB conversion for Roman bands is applied before any spline fitting, so the polygon is in the same photometric system as the data.

streamobs.match_filter.error_model(magnitude, baseline_error=0.004775486092612673, exp_pivot=28.421419633248796, exp_scale=1.0011829218659076, verbose=False)

Compute the median photometric error as a function of magnitude.

Uses an exponential error model calibrated for typical survey data.

Parameters:

• magnitude (float or array-like) – Apparent magnitude(s) for which to compute the error.

• baseline_error (float, optional) – Constant floor of the error curve.

• exp_pivot (float, optional) – Pivot magnitude of the exponential growth.

• exp_scale (float, optional) – Scale length of the exponential.

• verbose (bool, optional) – Print parameter values.

Returns:

error – Photometric error(s) corresponding to the input magnitude(s).

Return type:

float or array-like

streamobs.match_filter.is_in_match_filter(mag_1, mag_2, polygon_vertices=None, match_filter_params=None, verbose=False)

Select objects inside the matched-filter polygon.

mag_1/mag_2 are the same two bands the polygon was built with (color = mag_1 − mag_2, magnitude axis = mag_1) — 'g'/'r' for LSST, e.g. 'F106'/'F158' for Roman.

Parameters:

• mag_1 (array_like) – Apparent magnitude in band_1.

• mag_2 (array_like) – Apparent magnitude in band_2.

• polygon_vertices (ndarray, shape (N, 2) or None, optional) – Pre-built polygon from build_match_filter(). If None, match_filter_params must be given.

• match_filter_params (dict or None, optional) – Keyword arguments forwarded to build_match_filter() to build the polygon on the fly.

• verbose (bool, optional) – Print selection statistics.

Returns:

selection_mask – True for objects inside the polygon.

Return type:

ndarray of bool