hispecdrp.primitives.stellar_rv.rv_combine_utils

Helpers for combining per-chunk RV estimates into aggregates.

Functions

combine_rv_estimates_median_mad_weighted(...)

Error-aware robust rejection, inverse-variance mean, and IVW uncertainty.

combine_rvs_median_mad(rvs, rv_errs[, ...])

Error-aware robust outlier mask on per-chunk RVs.

combine_stellar_rv_chunk_estimates(rvs, rv_errs)

Aggregate per-chunk RVs for StellarRVPrimitive.

weighted_mean_rv(rvs, rv_errs, inlier)

Inverse-variance weighted mean RV and error on the mean.

combine_rv_estimates_median_mad_weighted(rvs, rv_errs, outlier_sigma=4.0, *, center_m_s=None, rv_err_inflation=3.5)[source]

Error-aware robust rejection, inverse-variance mean, and IVW uncertainty.

Outlier rejection uses the uninflated per-chunk rv_errs with 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 \(\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.

combine_rvs_median_mad(rvs, rv_errs, outlier_sigma=4.0, *, center_m_s=None)[source]

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.

combine_stellar_rv_chunk_estimates(rvs, rv_errs, outlier_sigma=4.0, *, chunk_rv_max_abs_m_s=120000.0, chunk_rv_prior_m_s=None, chunk_rv_prior_half_width_m_s=None, median_fallback_sigma=3.0)[source]

Aggregate per-chunk RVs for StellarRVPrimitive.

Applies a sanity gate, error-aware MAD rejection (|Δ| <= outlier_sigma * max(MAD, σ_i)), and inverse-variance weighting (combine_rv_estimates_median_mad_weighted()). The reported aggregate rv_std is \(\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.

weighted_mean_rv(rvs, rv_errs, inlier)[source]

Inverse-variance weighted mean RV and error on the mean.