Source code for hispecdrp.primitives.stellar_rv.rv_combine_utils

"""Helpers for combining per-chunk RV estimates into aggregates."""

from __future__ import annotations

import math

import numpy as np
from astropy.stats import mad_std

# Reject coarse-grid CCF alias peaks before aggregation (typical stellar |v| < few × 10 km/s).
DEFAULT_CHUNK_RV_MAX_ABS_M_S = 120_000.0
# When ``ccf_input_velocity`` is set, keep chunks within this half-width of the prior (m/s).
DEFAULT_CHUNK_RV_PRIOR_HALF_WIDTH_M_S = 10_000.0

__all__ = [
    "DEFAULT_CHUNK_RV_MAX_ABS_M_S",
    "DEFAULT_CHUNK_RV_PRIOR_HALF_WIDTH_M_S",
    "combine_rvs_median_mad",
    "weighted_mean_rv",
    "combine_rv_estimates_median_mad_weighted",
    "combine_stellar_rv_chunk_estimates",
]


[docs] def combine_rvs_median_mad( rvs: np.ndarray, rv_errs: np.ndarray, outlier_sigma: float = 4.0, *, center_m_s: float | None = None, ) -> tuple[np.ndarray, float, float]: """ Error-aware robust outlier mask on per-chunk RVs. Chunks with finite ``rvs`` and positive ``rv_errs`` set the rejection center (sample median, or ``center_m_s`` when finite) and the ensemble MAD. A chunk is kept when ``|RV − center| <= outlier_sigma * max(MAD, σ_i)`` so points that agree within the MAD are never rejected, while points that are both outside the MAD envelope and inconsistent with their own formal ``σ_i`` are rejected. Invalid chunks are marked not inlier. """ valid = np.isfinite(rvs) & np.isfinite(rv_errs) & (rv_errs > 0) if not np.any(valid): return np.zeros_like(rvs, dtype=bool), np.nan, np.nan rv_valid = rvs[valid] if center_m_s is not None and math.isfinite(float(center_m_s)): median_rv = float(center_m_s) else: median_rv = float(np.nanmedian(rv_valid)) mad_rv = mad_std(rv_valid, ignore_nan=True) if mad_rv <= 0: mad_rv = np.nanstd(rv_valid) if not np.isfinite(mad_rv) or mad_rv <= 0: mad_rv = 1.0 # Per-chunk threshold: MAD floor keeps mutually consistent points; larger # formal σ widens the gate so noisy chunks are not rejected on scatter alone. thresh = float(outlier_sigma) * np.maximum(float(mad_rv), np.asarray(rv_errs, dtype=np.float64)) inlier = valid & (np.abs(rvs - median_rv) <= thresh) return inlier, float(median_rv), float(mad_rv)
[docs] def weighted_mean_rv( rvs: np.ndarray, rv_errs: np.ndarray, inlier: np.ndarray, ) -> tuple[float, float]: """Inverse-variance weighted mean RV and error on the mean.""" use = inlier & np.isfinite(rvs) & np.isfinite(rv_errs) & (rv_errs > 0) if not np.any(use): return np.nan, np.nan w = 1.0 / (np.asarray(rv_errs, dtype=np.float64) ** 2) w = np.where(use, w, 0.0) if np.sum(w) <= 0: return np.nan, np.nan rv_mean = np.average(rvs, weights=w) var_mean = 1.0 / np.sum(w) rv_std = np.sqrt(var_mean) return float(rv_mean), float(rv_std)
# Formal per-chunk CCF σ is typically ~3–4× too small vs order-to-order scatter # on e2e simulations (Fisher / Gaussian cov ignores mask systematics). Inflate # before IVW *weighting* so the weighted mean is not dominated by underdispersed # chunks. The reported aggregate σ is max(uninflated IVW SE, MAD/√N), which # converges to MAD/√N as per-chunk σ → 0. DEFAULT_CHUNK_RV_ERR_INFLATION = 3.5
[docs] def combine_rv_estimates_median_mad_weighted( rvs: np.ndarray, rv_errs: np.ndarray, outlier_sigma: float = 4.0, *, center_m_s: float | None = None, rv_err_inflation: float = DEFAULT_CHUNK_RV_ERR_INFLATION, ) -> tuple[float, float, np.ndarray, float, float]: """ Error-aware robust rejection, inverse-variance mean, and IVW uncertainty. Outlier rejection uses the **uninflated** per-chunk ``rv_errs`` with :func:`combine_rvs_median_mad` (``|Δ| <= outlier_sigma * max(MAD, σ_i)``). Per-chunk ``rv_errs`` are scaled by ``rv_err_inflation`` only for IVW *weights* (default 3.5) so the mean is not dominated by underdispersed formal σ. The reported ``rv_std`` is :math:`\\max(\\sigma_{\\mathrm{IVW}},\\,\\mathrm{MAD}/\\sqrt{N})` of the inliers: photon-weighted IVW when it is honest, and the empirical line scatter when formal σ are optimistic or systematics dominate. As per-chunk σ → 0 (infinite S/N), this converges to ``MAD/√N``. If the median formal σ is >10⁶× the inlier MAD (broken Hessian), IVW is discarded and ``MAD/√N`` is reported. Inflated IVW SE and empirical ``MAD/√N`` are returned as ``rv_std_internal`` and ``scatter_se`` for diagnostics. """ rvs = np.asarray(rvs, dtype=np.float64).ravel() rv_errs = np.asarray(rv_errs, dtype=np.float64).ravel() if rvs.size != rv_errs.size: raise ValueError("combine_rv_estimates_median_mad_weighted: rvs and rv_errs length mismatch") infl = float(rv_err_inflation) if rv_err_inflation is not None else 1.0 if not math.isfinite(infl) or infl <= 0: infl = 1.0 rv_errs_w = rv_errs * infl # Rejection uses formal (uninflated) σ so large-error chunks can survive a # MAD cut when still consistent with their error bars. inlier, _, _ = combine_rvs_median_mad( rvs, rv_errs, outlier_sigma, center_m_s=center_m_s ) rv_mean, rv_std_internal = weighted_mean_rv(rvs, rv_errs_w, inlier) _, rv_std_uninfl = weighted_mean_rv(rvs, rv_errs, inlier) n_in = int(np.sum(inlier)) scatter_se = float("nan") if n_in > 1: rv_in = rvs[inlier] mad_disp = float(mad_std(rv_in, ignore_nan=True)) if math.isfinite(mad_disp) and mad_disp > 0: scatter_se = mad_disp / math.sqrt(float(n_in)) if math.isfinite(rv_std_uninfl) and rv_std_uninfl > 0: rv_std = float(rv_std_uninfl) elif math.isfinite(rv_std_internal) and rv_std_internal > 0: rv_std = float(rv_std_internal) else: rv_std = scatter_se if math.isfinite(scatter_se) and scatter_se > 0.0: if math.isfinite(rv_std) and rv_std > 0.0: rv_std = max(float(rv_std), float(scatter_se)) else: rv_std = float(scatter_se) # Exploded formal σ (ill-conditioned Hessian at infinite S/N) make IVW # >> MAD. That is not a photon error; quote the empirical floor. if n_in >= 3: med_err = float(np.median(rv_errs[inlier])) mad_disp = scatter_se * math.sqrt(float(n_in)) if ( math.isfinite(med_err) and math.isfinite(mad_disp) and mad_disp > 0.0 and med_err > 1.0e6 * mad_disp ): rv_std = float(scatter_se) # Prefer the inlier median when formal-IVW and median disagree — common when # a few chunks still have underestimated σ after inflation. Keep IVW σ. if n_in >= 3 and math.isfinite(rv_mean): med = float(np.median(rvs[inlier])) mad_disp = float(mad_std(rvs[inlier], ignore_nan=True)) if ( math.isfinite(med) and math.isfinite(mad_disp) and mad_disp > 0 and abs(rv_mean - med) > 1.0 * mad_disp ): rv_mean = med return float(rv_mean), float(rv_std), inlier, float(rv_std_internal), float(scatter_se)
[docs] def combine_stellar_rv_chunk_estimates( rvs: np.ndarray, rv_errs: np.ndarray, outlier_sigma: float = 4.0, *, chunk_rv_max_abs_m_s: float = DEFAULT_CHUNK_RV_MAX_ABS_M_S, chunk_rv_prior_m_s: float | None = None, chunk_rv_prior_half_width_m_s: float | None = None, median_fallback_sigma: float = 3.0, ) -> tuple[float, float, np.ndarray, float, float]: """ Aggregate per-chunk RVs for :class:`~hispecdrp.primitives.stellar_rv.stellar_rv_primitive.StellarRVPrimitive`. Applies a **sanity gate**, error-aware MAD rejection (``|Δ| <= outlier_sigma * max(MAD, σ_i)``), and inverse-variance weighting (:func:`combine_rv_estimates_median_mad_weighted`). The reported aggregate ``rv_std`` is :math:`\\max(\\sigma_{\\mathrm{IVW}},\\,\\mathrm{MAD}/\\sqrt{N})` of the inliers. When ``chunk_rv_prior_m_s`` is finite, the gate keeps ``|RV − prior| <= half_width`` (default ``DEFAULT_CHUNK_RV_PRIOR_HALF_WIDTH_M_S``) and MAD rejection is anchored to the prior. Otherwise the gate uses ``|RV| <= chunk_rv_max_abs_m_s`` and the sample median anchors MAD rejection. When the weighted mean disagrees with the inlier median by more than ``median_fallback_sigma × MAD``, the median is used for the aggregate RV (guards against alias peaks with underestimated formal errors on coarse CCF grids); the reported uncertainty remains the IVW SE. """ rvs = np.asarray(rvs, dtype=np.float64).ravel() rv_errs = np.asarray(rv_errs, dtype=np.float64).ravel() if rvs.size != rv_errs.size: raise ValueError("combine_stellar_rv_chunk_estimates: rvs and rv_errs length mismatch") finite = np.isfinite(rvs) & np.isfinite(rv_errs) & (rv_errs > 0) use_prior_gate = chunk_rv_prior_m_s is not None and math.isfinite(float(chunk_rv_prior_m_s)) mad_center: float | None = None if use_prior_gate: prior = float(chunk_rv_prior_m_s) half_w = chunk_rv_prior_half_width_m_s if half_w is None or not math.isfinite(float(half_w)) or float(half_w) <= 0: half_w = DEFAULT_CHUNK_RV_PRIOR_HALF_WIDTH_M_S else: half_w = float(half_w) sane = finite & (np.abs(rvs - prior) <= half_w) mad_center = prior else: sane = finite & (np.abs(rvs) <= float(chunk_rv_max_abs_m_s)) if not np.any(sane): return np.nan, np.nan, np.zeros_like(rvs, dtype=bool), np.nan, np.nan rv_errs_gated = np.asarray(rv_errs, dtype=np.float64).copy() rv_errs_gated[~sane] = np.nan rv_mean, rv_std, inlier, std_iv, scatter_se = combine_rv_estimates_median_mad_weighted( rvs, rv_errs_gated, outlier_sigma, center_m_s=mad_center, ) inlier = inlier & sane use = inlier & sane if not np.any(use): med = float(np.median(rvs[sane])) _, rv_std_sane = weighted_mean_rv(rvs, rv_errs, sane) if not (math.isfinite(rv_std_sane) and rv_std_sane > 0): mad = float(mad_std(rvs[sane], ignore_nan=True)) n_s = int(np.sum(sane)) rv_std_sane = mad / math.sqrt(float(n_s)) if n_s > 1 and mad > 0 else max(mad, 1.0) return med, float(rv_std_sane), sane, np.nan, float(rv_std_sane) med = float(np.median(rvs[use])) mad = float(mad_std(rvs[use], ignore_nan=True)) if not math.isfinite(mad) or mad <= 0: mad = float(np.nanstd(rvs[use])) if np.sum(use) > 1 else 1.0 if ( math.isfinite(rv_mean) and math.isfinite(med) and math.isfinite(mad) and mad > 0 and abs(rv_mean - med) > float(median_fallback_sigma) * mad ): rv_mean = med elif use_prior_gate and math.isfinite(med): # Prior-gated pools are small and formal chunk errors often hit the bisector # floor; the weighted mean is biased by ~km/s outliers still inside the gate. rv_mean = med return float(rv_mean), float(rv_std), inlier, float(std_iv), float(scatter_se)