Source code for hispecdrp.primitives.utils.ccf.ccf_bisector

"""CCF bisector utilities: Queloz BIS (Numba) and NEID-style weighted percentile RV."""

from __future__ import annotations

import math
from dataclasses import dataclass, replace

import numpy as np
from astropy.stats import mad_std
from numba import njit
from scipy.interpolate import CubicSpline

from .ccf_common import (
    _ccf_background_sigma_clipped_median,
    _ccf_background_sigma_clipped_median_dv_weighted,
    _ccf_rv_err_numeric_floor,
    effective_ccf_v_step_for_fit,
)

__all__ = [
    "CCFBisectorConfig",
    "calc_bisector_inverse_slope",
    "fit_ccf_rv_bisector",
    "_refine_ccf_rv_bisector_after_gaussian_fit",
]

@njit(cache=True, nogil=True)
def _interp_x_at_y(x0: float, y0: float, x1: float, y1: float, y: float) -> float:
    """Linear interpolation: return x where a segment (x0,y0)-(x1,y1) hits y."""
    dy = y1 - y0
    if dy == 0.0:
        return 0.5 * (x0 + x1)
    t = (y - y0) / dy
    return x0 + t * (x1 - x0)


@njit(cache=True, nogil=True)
def _find_ccf_level(
    vel_grid: np.ndarray,
    ccf: np.ndarray,
    ccf_err: np.ndarray,
    i_ext: int,
    level: float,
    direction: int,
) -> tuple[float, float, float, bool]:
    """
    Find where one flank crosses `level`, walking outward from the extremum.

    direction = -1 walks toward index 0 (blue flank); +1 toward n-1 (red flank).
    Returns (v_cross, flux_err_at_cross, dv_dflux, found). A single pass yields
    everything the caller needs, so no bracket is searched more than once.

    Parameters
    ----------
    vel_grid : np.ndarray
        Velocity grid (m/s).
    ccf : np.ndarray
        CCF values on vel_grid.
    ccf_err : np.ndarray
        1-sigma uncertainties on ccf (same shape).
    i_ext : int
        Index of the extremum (minimum for absorption dip, maximum for emission peak).
    level : float
        CCF value at which to find the flank crossing.
    direction : int
        -1 to walk left, +1 to walk right.
    """
    n = len(vel_grid)
    if direction == -1:
        i = i_ext
        while i > 0:
            a = ccf[i]
            b = ccf[i - 1]
            if (a - level) * (b - level) <= 0.0 and a != b:
                v_cross = _interp_x_at_y(vel_grid[i], a, vel_grid[i - 1], b, level)
                tt = (level - a) / (b - a)
                e_cross = ccf_err[i] * (1.0 - tt) + ccf_err[i - 1] * tt
                slope = (vel_grid[i - 1] - vel_grid[i]) / (b - a)
                return v_cross, e_cross, slope, True
            i -= 1
    elif direction == 1:
        i = i_ext
        while i < n - 1:
            a = ccf[i]
            b = ccf[i + 1]
            if (a - level) * (b - level) <= 0.0 and a != b:
                v_cross = _interp_x_at_y(vel_grid[i], a, vel_grid[i + 1], b, level)
                tt = (level - a) / (b - a)
                e_cross = ccf_err[i] * (1.0 - tt) + ccf_err[i + 1] * tt
                slope = (vel_grid[i + 1] - vel_grid[i]) / (b - a)
                return v_cross, e_cross, slope, True
            i += 1
    return np.nan, 0.0, 0.0, False


@njit(cache=True, nogil=True)
def _calc_bis(
    vel_grid: np.ndarray,
    ccf: np.ndarray,
    ccf_err: np.ndarray,
    n_levels: int = 100,
    shallow_lo: float = 0.10,
    shallow_hi: float = 0.40,
    core_lo: float = 0.55,
    core_hi: float = 0.90,
    pix_size: float | None = None
):
    """Bisector Inverse Slope (BIS) of a CCF, after Queloz et al. (2001).

    The bisector is the locus of midpoints of horizontal (constant-CCF-value)
    slices through the profile: at each flux level the velocities of the blue
    and red flanks are found and averaged. The BIS is then

        BIS = v_shallow - v_core

    where ``v_shallow`` is the mean bisector velocity over the shallow
    (near-continuum) depth region and ``v_core`` the mean over the core
    (near-core) region.

    Depth fractions are measured from the continuum toward the extremum, so the
    region definitions are orientation-invariant: a fraction of 0 is the
    continuum and a fraction of 1 is the core, whether the feature is an
    absorption dip or an emission peak. The Queloz et al. (2001) definition uses
    shallow = 10%-40% and core = 55%-90%, which are the defaults here.

    The CCF may be either an absorption-like dip or an emission-like peak; the
    orientation is detected automatically from whether the extremum lies below
    or above the wing (continuum) level.

    Parameters
    ----------
    vel_grid : ndarray
        Velocities (m/s), strictly ascending.
    ccf : ndarray
        CCF values on ``vel_grid``.
    ccf_err : ndarray
        1-sigma uncertainties on ``ccf`` (same shape). Used only to propagate
        the velocity uncertainties; pass an array of ones if you only want the
        velocity values.
    n_levels : int
        Number of evenly spaced depth levels at which the bisector is sampled
        across the full 0-1 depth range. Levels falling inside the shallow/core
        windows are the ones actually averaged into ``v_shallow``/``v_core``.
    shallow_lo, shallow_hi : float
        Lower/upper depth fractions (0-1, measured from the continuum) bounding
        the shallow (near-continuum) region used for ``v_shallow``. Defaults
        0.10, 0.40 (Queloz 2001).
    core_lo, core_hi : float
        Lower/upper depth fractions bounding the core (near-core) region used
        for ``v_core``. Defaults 0.55, 0.90 (Queloz 2001).

    Returns
    -------
    bis : float
        The bisector inverse slope (``v_shallow - v_core``), in the same
        velocity units as ``vel_grid``. NaN if the bisector cannot be measured
        (e.g. flat/degenerate profile, a non-interior extremum, or no levels
        bracketed inside the shallow/core windows).
    bis_err : float
        Propagated 1-sigma uncertainty on ``bis``: the quadrature sum of
        ``shallow_err`` and ``core_err``. NaN if ``bis`` is NaN.
    v_shallow : float
        Mean bisector velocity over the shallow (near-continuum) region. NaN if
        the fit failed before this could be computed.
    shallow_err : float
        1-sigma uncertainty on ``v_shallow``: the mean per-level bisector
        uncertainty in the shallow window divided by sqrt(N_shallow). NaN on
        failure.
    v_core : float
        Mean bisector velocity over the core (near-core) region. NaN on failure.
    core_err : float
        1-sigma uncertainty on ``v_core``: the mean per-level bisector
        uncertainty in the core window divided by sqrt(N_core). NaN on failure.
    levels : ndarray
        Depth fractions (0-1, measured from the continuum toward the extremum)
        at which the bisector was successfully measured. Levels where either
        flank could not be bracketed are omitted (no NaN padding), so this is
        generally shorter than ``n_levels - 1``. Empty if the profile was
        degenerate before sampling began.
    bis_curve : ndarray
        Bisector velocity at each level in ``levels``; paired element-for-
        element with it. Same length as ``levels``.

    Notes
    -----
    All returns have fixed arity (8 values) regardless of success or failure;
    failure paths fill the scalars with NaN and return whatever portion of
    ``levels``/``bis_curve`` had been collected (possibly empty).
    """
    n = vel_grid.shape[0]
    if n < 4:
        return np.nan, np.nan, np.nan, np.nan, np.nan, np.nan, np.empty(0, dtype=np.float64), np.empty(0, dtype=np.float64)

    i_ext = 0
    cmin = ccf[0]
    cmax = ccf[0]
    i_min = 0
    i_max = 0
    for i in range(n):
        v = ccf[i]
        if v < cmin:
            cmin = v
            i_min = i
        if v > cmax:
            cmax = v
            i_max = i

    cont = 0.5 * (ccf[0] + ccf[n - 1])

    if (cont - cmin) >= (cmax - cont):
        is_dip = True
        i_ext = i_min
        extreme = cmin
    else:
        is_dip = False
        i_ext = i_max
        extreme = cmax

    full_depth = cont - extreme if is_dip else extreme - cont
    if not (full_depth > 0.0):
        return np.nan, np.nan, np.nan, np.nan, np.nan, np.nan, np.empty(0, dtype=np.float64), np.empty(0, dtype=np.float64)

    if i_ext <= 0 or i_ext >= n - 1:
        return np.nan, np.nan, np.nan, np.nan, np.nan, np.nan, np.empty(0, dtype=np.float64), np.empty(0, dtype=np.float64)

    shallow_sum = 0.0
    shallow_var = 0.0
    shallow_cnt = 0
    core_sum = 0.0
    core_var = 0.0
    core_cnt = 0

    curve_buf = np.empty(n_levels, dtype=np.float64)
    level_buf = np.empty(n_levels, dtype=np.float64)
    n_curve = 0

    for j in range(1, n_levels):
        f = j / n_levels

        if is_dip:
            level = cont - f * full_depth
        else:
            level = cont + f * full_depth

        vb, eb, sb, found_b = _find_ccf_level(
            vel_grid, ccf, ccf_err, i_ext, level, -1,
        )
        vr, er, sr, found_r = _find_ccf_level(
            vel_grid, ccf, ccf_err, i_ext, level, 1,
        )

        if not (found_b and found_r):
            continue

        v_bis = 0.5 * (vb + vr)

        curve_buf[n_curve] = v_bis
        level_buf[n_curve] = f
        n_curve += 1

        ev_b = abs(sb) * eb
        ev_r = abs(sr) * er
        v_bis_err = 0.5 * np.sqrt(ev_b * ev_b + ev_r * ev_r)

        if (f >= shallow_lo) and (f <= shallow_hi):
            shallow_sum += v_bis
            shallow_var += v_bis_err * v_bis_err
            shallow_cnt += 1
        if (f >= core_lo) and (f <= core_hi):
            core_sum += v_bis
            core_var += v_bis_err * v_bis_err
            core_cnt += 1

    bis_curve = curve_buf[:n_curve].copy()
    levels = level_buf[:n_curve].copy()

    if shallow_cnt == 0 or core_cnt == 0:
        return np.nan, np.nan, np.nan, np.nan, np.nan, np.nan, levels, bis_curve

    v_shallow = shallow_sum / shallow_cnt
    v_core = core_sum / core_cnt
    bis = v_shallow - v_core

    shallow_err = np.sqrt(shallow_var / shallow_cnt) / np.sqrt(shallow_cnt)
    core_err = np.sqrt(core_var / core_cnt) / np.sqrt(core_cnt)
    bis_err = np.sqrt(shallow_err * shallow_err + core_err * core_err)

    if pix_size is not None:
        shallow_err = max(shallow_err, pix_size / np.sqrt(shallow_cnt))
        core_err = max(core_err, pix_size / np.sqrt(core_cnt))
    else:
        shallow_err = max(shallow_err, np.sqrt(shallow_var) / shallow_cnt)
        core_err = max(core_err, np.sqrt(core_var) / core_cnt)
    bis_err = max(bis_err, np.sqrt(shallow_err * shallow_err + core_err * core_err))

    return bis, bis_err, v_shallow, shallow_err, v_core, core_err, levels, bis_curve


[docs] def calc_bisector_inverse_slope( vel_grid: np.ndarray, ccf: np.ndarray, ccf_err: np.ndarray | None = None, n_levels: int = 100, quant_shallow : tuple[float, float] = (0.10, 0.40), quant_core : tuple[float, float] = (0.6, 0.90) ): """ Bisector Inverse Slope (BIS) of a CCF, after Queloz et al. (2001). Thin wrapper over the njit core (``_calc_bis``). ``ccf_err`` is optional: it is used only to propagate the velocity uncertainties, never the velocity values themselves. When ``ccf_err`` is None the bisector velocities are computed normally and all three error outputs (``bis_err``, ``shallow_err``, ``core_err``) are returned as NaN, since there is no uncertainty information to propagate. See ``_calc_bis`` for the full parameter and algorithm description. In brief, the bisector midpoints are averaged over two depth-fraction windows measured from the continuum toward the extremum (orientation-invariant for both absorption dips and emission peaks): BIS = v_shallow - v_core with ``shallow`` near the continuum and ``core`` near the core. Parameters ---------- vel_grid, ccf : ndarray Velocity grid (ascending) and CCF values. ccf_err : ndarray | None 1-sigma uncertainties on ``ccf``. Optional; if None, the error outputs are NaN. n_levels : int Number of evenly spaced depth levels sampled across the 0-1 range. quant_shallow : tuple[float, float] | None Lower/upper depth fractions (0-1, measured from the continuum) bounding the shallow (near-continuum) region used for ``v_shallow``. Defaults to (0.10, 0.40). quant_core : tuple[float, float] Lower/upper depth fractions (0-1, measured from the continuum) bounding the core (near-core) region used for ``v_core``. Defaults to (0.6, 0.90). Returns ------- bis : float The bisector inverse slope (``v_shallow - v_core``). NaN if not measurable. bis_err : float Propagated 1-sigma uncertainty on ``bis`` (quadrature sum of ``shallow_err`` and ``core_err``). NaN if not measurable or if ``ccf_err`` was None. v_shallow : float Mean bisector velocity over the shallow (near-continuum) region. shallow_err : float 1-sigma uncertainty on ``v_shallow``. NaN if not measurable or if ``ccf_err`` was None. v_core : float Mean bisector velocity over the core (near-core) region. core_err : float 1-sigma uncertainty on ``v_core``. NaN if not measurable or if ``ccf_err`` was None. levels, bis_curve : ndarray Depth fractions and bisector velocities at each successfully bracketed level, sampled across the full 0-1 depth range. Paired element-for- element. """ if ccf_err is None: (bis, _, v_shallow, _, v_core, _, levels, bis_curve) = _calc_bis( vel_grid, ccf, np.ones_like(ccf), n_levels, quant_shallow[0], quant_shallow[1], quant_core[0], quant_core[1] ) return (bis, np.nan, v_shallow, np.nan, v_core, np.nan, levels, bis_curve) return _calc_bis( vel_grid, ccf, ccf_err, n_levels, quant_shallow[0], quant_shallow[1], quant_core[0], quant_core[1] )
# --------------------------------------------------------------------------- # NEID-style weighted-percentile bisector RV (pipeline / fit_ccf_rv_bisector) # ---------------------------------------------------------------------------
[docs] @dataclass class CCFBisectorConfig: """ Tunables for :func:`fit_ccf_rv_bisector` (traditional CCF bisector RV). Follows the NEID-DRP bisector construction (percentile cuts through the CCF in velocity space; see NEID algorithms § CCF Bisector Calculation). Radial velocity **and** its uncertainty are a **weighted mean** of bisector midpoints :math:`(v_\\mathrm{left}+v_\\mathrm{right})/2` at multiple depth percentiles: with per-cut midpoint uncertainties :math:`e_i` and weights :math:`w_i`, .. math:: \\hat{v} = \\frac{\\sum_i w_i v_i}{\\sum_i w_i},\\qquad \\sigma_{\\hat{v}} = \\frac{\\sum_i w_i e_i}{\\sum_i w_i}. (The uncertainty is the weighted average of the cut uncertainties, not an independent-measurement reduction of those errors.) Cut weights are the core performance weight only; per-cut :math:`e_i` comes from CCF-error propagation when informative, otherwise from the smooth-profile discretization estimate. """ #: Percentile range low (0–100) for bisector midpoints in the RV estimate. rv_percentile_lo: float = 10.0 #: Percentile range high (0–100) for bisector midpoints in the RV estimate. rv_percentile_hi: float = 90.0 #: Fixed number of evenly spaced percentile cuts (overrides ``rv_percentile_step`` when ``>= 2``). rv_n_percentile_cuts: int = 31 #: Step between percentile cuts when ``rv_n_percentile_cuts < 2``. rv_percentile_step: float = 5.0 #: Top section low for bisector inverse slope (BIS), NEID default 60–90%. bis_top_lo: float = 60.0 #: Top section high for BIS. bis_top_hi: float = 90.0 #: Bottom section low for BIS, NEID default 10–40%. bis_bottom_lo: float = 10.0 #: Bottom section high for BIS. bis_bottom_hi: float = 40.0 #: Gaussian performance weight on percentile cuts (core emphasis). core_weight_sigma_percentile: float = 25.0 #: Representative “core” cut percentile for diagnostics / preview labeling. rv_err_core_percentile: float = 50.0 rv_err_bootstrap_samples: int = 0 rv_err_bootstrap_seed: int | None = None #: Minimum successful bisector cuts required for a valid RV. min_cuts: int = 5 #: Minimum peak amplitude (above baseline) in units of robust wing noise. min_peak_contrast_sigma: float = 5.0 #: Floor ``rv_err`` to this fraction of the minimum positive velocity spacing. rv_err_min_vstep_fraction: float = 0.15
def _ccf_bisector_wing_crossing_m_s( v_m_s: np.ndarray, y_peak_up: np.ndarray, i_peak: int, target: float, side: str, ) -> tuple[float, int]: """ Velocity (m/s) and bracket index where ``y_peak_up`` crosses ``target``. Returns ``(v_cross, i_lo)`` with the crossing lying between ``v_m_s[i_lo]`` and ``v_m_s[i_lo + 1]``. """ n = len(v_m_s) if side == "left": for i in range(i_peak - 1, -1, -1): y0, y1 = float(y_peak_up[i]), float(y_peak_up[i + 1]) if (y0 - target) * (y1 - target) <= 0.0 and y1 != y0: frac = (target - y0) / (y1 - y0) return float(v_m_s[i] + frac * (v_m_s[i + 1] - v_m_s[i])), int(i) return float("nan"), -1 if side == "right": for i in range(i_peak, n - 1): y0, y1 = float(y_peak_up[i]), float(y_peak_up[i + 1]) if (y0 - target) * (y1 - target) <= 0.0 and y1 != y0: frac = (target - y0) / (y1 - y0) return float(v_m_s[i] + frac * (v_m_s[i + 1] - v_m_s[i])), int(i) return float("nan"), -1 raise ValueError(f"side must be 'left' or 'right', got {side!r}") def _ccf_bisector_wing_velocity_m_s( v_m_s: np.ndarray, y_peak_up: np.ndarray, i_peak: int, target: float, side: str, ) -> float: """ Velocity (m/s) where ``y_peak_up`` crosses ``target`` on the left or right wing of ``i_peak``. Uses linear interpolation between bracketing samples. ``y_peak_up`` must be peak-up (non-negative at the extremum). """ v_cross, _ = _ccf_bisector_wing_crossing_m_s(v_m_s, y_peak_up, i_peak, target, side) return v_cross def _ccf_bisector_discretization_sigma_m_s( v_m_s: np.ndarray, y_peak_up: np.ndarray, i_lo: int, ) -> float: """ Sub-grid 1σ uncertainty (m/s) for a linearly interpolated wing crossing. For a smooth CCF sampled on a uniform grid, interpolation error scales as :math:`\\mathcal{O}(\\Delta v^2)` (not :math:`\\mathcal{O}(\\Delta v)`). """ n = len(v_m_s) i_lo = int(i_lo) if i_lo < 0 or i_lo >= n - 1: return float("nan") dv = float(v_m_s[i_lo + 1] - v_m_s[i_lo]) if dv <= 0.0: return float("nan") dy_dv = float(y_peak_up[i_lo + 1] - y_peak_up[i_lo]) / dv if abs(dy_dv) <= 1e-30: return float("nan") if 0 < i_lo < n - 2: d2y_dv2 = float(y_peak_up[i_lo + 1] - 2.0 * y_peak_up[i_lo] + y_peak_up[i_lo - 1]) / (dv * dv) elif i_lo == 0: d2y_dv2 = float(y_peak_up[i_lo + 2] - 2.0 * y_peak_up[i_lo + 1] + y_peak_up[i_lo]) / (dv * dv) else: d2y_dv2 = float(y_peak_up[i_lo + 1] - 2.0 * y_peak_up[i_lo] + y_peak_up[i_lo - 1]) / (dv * dv) return float(abs(dv * dv * d2y_dv2 / (2.0 * dy_dv))) def _ccf_bisector_wing_velocity_uncertainty_m_s( v_m_s: np.ndarray, y_peak_up: np.ndarray, i_lo: int, target: float, *, y_err: np.ndarray | None = None, v_step_m_s: float, ) -> float: """ Approximate 1σ uncertainty (m/s) on a bisector wing crossing. With per-bin ``y_err``, propagates noise through the linear interpolation that locates the crossing when that formal σ is below the uniform-in-bracket prior (:math:`\\Delta v/\\sqrt{12}`). When formal noise saturates that prior, returns the :math:`\\mathcal{O}(\\Delta v^2)` discretization estimate for a smooth CCF instead of locking σ to ~0.3 grid steps. Without meaningful ``y_err``, uses discretization only. """ n = len(v_m_s) i_lo = int(i_lo) if i_lo < 0 or i_lo >= n - 1: return float(max(v_step_m_s, _ccf_rv_err_numeric_floor(v_step_m_s))) y0 = float(y_peak_up[i_lo]) y1 = float(y_peak_up[i_lo + 1]) v0 = float(v_m_s[i_lo]) v1 = float(v_m_s[i_lo + 1]) dy = y1 - y0 dv = v1 - v0 if abs(dy) <= 0.0: return float(max(v_step_m_s, _ccf_rv_err_numeric_floor(v_step_m_s))) use_noise = False s0 = s1 = 0.0 if y_err is not None and len(y_err) == n: s0 = float(y_err[i_lo]) if np.isfinite(y_err[i_lo]) else 0.0 s1 = float(y_err[i_lo + 1]) if np.isfinite(y_err[i_lo + 1]) else 0.0 use_noise = (s0 > 0.0) or (s1 > 0.0) # Guard against tiny bracket gradients on noisy samples (would inflate σ_v). local_span = max(abs(dv), float(v_step_m_s)) grad_floor = max(abs(y1 - y0) / local_span, 1e-30) if use_noise and abs(dy) < 0.02 * grad_floor * local_span: dy = math.copysign(0.02 * grad_floor * local_span, dy if dy != 0.0 else 1.0) sig_disc = _ccf_bisector_discretization_sigma_m_s(v_m_s, y_peak_up, i_lo) if use_noise: # v* = v0 + (target - y0) * (v1 - v0) / (y1 - y0) dv_dy0 = -(v1 - v0) / dy dv_dy1 = (target - y0) * (v1 - v0) / (dy * dy) sig_noise = math.sqrt((dv_dy0 * s0) ** 2 + (dv_dy1 * s1) ** 2) # Uniform-in-bracket prior σ = Δv/√12. When formal noise sits at or above # that ceiling, bin spacing — not CCF S/N — dominates the linear # interpolator; use the smooth-profile O(Δv²) discretization estimate so a # coarse velocity grid is not stuck near ~0.3 Δv per wing. bracket_prior = abs(dv) / math.sqrt(12.0) if ( math.isfinite(bracket_prior) and bracket_prior > 0.0 and math.isfinite(sig_noise) and sig_noise >= 0.95 * bracket_prior and math.isfinite(sig_disc) and sig_disc > 0.0 ): sig_v = float(sig_disc) else: sig_v = float(sig_noise) else: sig_v = float(sig_disc) if math.isfinite(sig_disc) and sig_disc > 0.0 else 0.0 if not math.isfinite(sig_v) or sig_v <= 0.0: sig_v = float(max(v_step_m_s, _ccf_rv_err_numeric_floor(v_step_m_s))) return float(sig_v) def _ccf_bisector_cut_m_s( v_m_s: np.ndarray, y_peak_up: np.ndarray, i_peak: int, depth_frac: float, peak_amp: float, *, y_err: np.ndarray | None = None, v_step_m_s: float, ) -> tuple[float, float, float, float, float] | None: """ Bisector midpoint at one depth percentile. Returns ``(v_mid, v_mid_err, v_left, v_right, percentile)`` or ``None`` if the cut does not bracket both wings. """ if not (0.0 < depth_frac < 1.0) or peak_amp <= 0.0: return None target = depth_frac * peak_amp v_left, i_left = _ccf_bisector_wing_crossing_m_s(v_m_s, y_peak_up, i_peak, target, "left") v_right, i_right = _ccf_bisector_wing_crossing_m_s(v_m_s, y_peak_up, i_peak, target, "right") if not (math.isfinite(v_left) and math.isfinite(v_right)): return None sig_l = _ccf_bisector_wing_velocity_uncertainty_m_s( v_m_s, y_peak_up, i_left, target, y_err=y_err, v_step_m_s=v_step_m_s ) sig_r = _ccf_bisector_wing_velocity_uncertainty_m_s( v_m_s, y_peak_up, i_right, target, y_err=y_err, v_step_m_s=v_step_m_s ) v_mid = 0.5 * (v_left + v_right) v_mid_err = math.sqrt(0.25 * (sig_l * sig_l + sig_r * sig_r)) return v_mid, v_mid_err, v_left, v_right, depth_frac * 100.0
[docs] def fit_ccf_rv_bisector( v_grid_m_s: np.ndarray, ccf: np.ndarray, v_step_m_s: float, *, ccf_err: np.ndarray | None = None, config: CCFBisectorConfig | None = None, return_diagnostics: bool = False, gaussian_seed_mean_m_s: float | None = None, ) -> ( tuple[float, float] | tuple[float, float, dict] ): """ Radial velocity (m/s) from a traditional CCF bisector analysis. At each depth percentile between baseline and peak, finds the left and right wing velocities where the CCF crosses that flux level and takes their midpoint. The RV estimate **and** its uncertainty are a performance-weighted mean of midpoints over ``config.rv_percentile_lo`` … ``config.rv_percentile_hi``, with Gaussian weight emphasizing the CCF core (50% depth). The reported σ is the weighted average of per-cut midpoint uncertainties (:math:`\\sum_i w_i e_i\\,/\\,\\sum_i w_i`), not an independent-cut :math:`1/\\sqrt{N}` reduction. Also computes bisector inverse slope (BIS) following NEID-DRP: average midpoints in the top (60–90%) minus bottom (10–40%) sections, with the same weighted-mean uncertainty on each section. Parameters ---------- v_grid_m_s : np.ndarray Velocity samples (m/s), need not be uniform. ccf : np.ndarray CCF values on the same grid. v_step_m_s : float Effective finest velocity spacing (m/s) for uncertainty floors; use :func:`effective_ccf_v_step_for_fit` on ``v_grid_m_s``. ccf_err : np.ndarray or None, optional Per-sample CCF uncertainty for wing-crossing error propagation. config : CCFBisectorConfig or None, optional Bisector percentile ranges and weighting. return_diagnostics : bool, optional If True, return ``(rv, rv_err, diag)`` with per-cut midpoints, BIS, etc. gaussian_seed_mean_m_s : float or None, optional When set (typically the Gaussian CCF fit center), the bisector peak index is the sample nearest this velocity (with a small local refine). Do **not** re-search ``argmax(|CCF − baseline|)`` over a multi-km/s window: a global contrast search can lock onto a window edge when the core has near-zero contrast relative to an unweighted continuum. Returns ------- rv_m_s, rv_err_m_s : float Weighted bisector RV and combined uncertainty (m/s). diag : dict, optional Present when ``return_diagnostics=True``. """ cfg = config or CCFBisectorConfig() vg = np.asarray(v_grid_m_s, dtype=np.float64).ravel() y0 = np.asarray(ccf, dtype=np.float64).ravel() ok = np.isfinite(vg) & np.isfinite(y0) if int(np.sum(ok)) < 5: out = (float("nan"), float("nan"), {"ok": False, "message": "insufficient finite samples"}) return out if return_diagnostics else (out[0], out[1]) order = np.argsort(vg[ok]) v_m_s = vg[ok][order] y = y0[ok][order] y_err: np.ndarray | None = None has_ccf_err = False if ccf_err is not None: ye = np.asarray(ccf_err, dtype=np.float64).ravel() if ye.size == y0.size: y_err = ye[ok][order] has_ccf_err = bool(np.any(np.isfinite(y_err) & (y_err > 0.0))) baseline = _ccf_background_sigma_clipped_median_dv_weighted(v_m_s, y) if not math.isfinite(baseline): baseline = _ccf_background_sigma_clipped_median(y) if not math.isfinite(baseline): baseline = float(np.nanmedian(y)) y_rel = y - baseline n = int(v_m_s.size) v_step = float(v_step_m_s) if math.isfinite(v_step_m_s) and v_step_m_s > 0 else effective_ccf_v_step_for_fit(v_m_s) if ( gaussian_seed_mean_m_s is not None and math.isfinite(float(gaussian_seed_mean_m_s)) and n >= 3 ): # Lock the bisector peak to the Gaussian / scout seed. A wide unweighted # |y_rel| search can lock onto the window edge when the core has near-zero # contrast. v_seed = float(gaussian_seed_mean_m_s) i_peak = int(np.argmin(np.abs(v_m_s - v_seed))) i_peak = int(min(max(i_peak, 1), n - 2)) # Optional micro-refine within ±2 steps of the seed (not a wide half-window # that reintroduces edge locking). refine_half = max(2.0 * float(v_step), 100.0) idx = np.arange(n, dtype=np.int64) local = ( (v_m_s >= v_seed - refine_half) & (v_m_s <= v_seed + refine_half) & (idx > 0) & (idx < n - 1) ) if np.any(local): loc = np.where(local)[0] i_local = int(loc[int(np.nanargmax(np.abs(y_rel[local])))]) # Accept refine only if it stays near the seed (reject wing-edge spikes). if abs(float(v_m_s[i_local]) - v_seed) <= refine_half: i_peak = i_local else: i_peak = int(np.nanargmax(np.abs(y_rel))) # Wing walks need an interior peak; fall back to nearest interior sample. if i_peak <= 0 or i_peak >= n - 1: if n >= 3: interior = np.abs(y_rel[1 : n - 1]) if np.any(np.isfinite(interior)): i_peak = int(np.nanargmax(interior)) + 1 else: i_peak = n // 2 else: out = (float("nan"), float("nan"), {"ok": False, "message": "peak at array edge"}) return out if return_diagnostics else (out[0], out[1]) peak_amp = float(abs(y_rel[i_peak])) # Prefer a wing continuum when the window is wide enough so a global # (even Δv-weighted) median does not sit near the peak. wing_min = max(20.0 * float(v_step), 2000.0) wing = np.abs(v_m_s - float(v_m_s[i_peak])) >= wing_min if int(np.count_nonzero(wing)) >= 5: baseline_w = _ccf_background_sigma_clipped_median_dv_weighted(v_m_s[wing], y[wing]) if math.isfinite(baseline_w): amp_w = float(abs(float(y[i_peak]) - float(baseline_w))) if amp_w > peak_amp or peak_amp <= 0.0 or not math.isfinite(peak_amp): baseline = float(baseline_w) y_rel = y - baseline peak_amp = amp_w if peak_amp <= 0.0 or not math.isfinite(peak_amp): out = (float("nan"), float("nan"), {"ok": False, "message": "zero peak amplitude"}) return out if return_diagnostics else (out[0], out[1]) sign = 1.0 if y_rel[i_peak] >= 0.0 else -1.0 y_peak_up = sign * y_rel p_lo = float(cfg.rv_percentile_lo) p_hi = float(cfg.rv_percentile_hi) if p_hi <= p_lo: out = (float("nan"), float("nan"), {"ok": False, "message": "invalid percentile grid"}) return out if return_diagnostics else (out[0], out[1]) n_fixed = int(cfg.rv_n_percentile_cuts) if n_fixed >= 2: percentiles = np.linspace(p_lo, p_hi, n_fixed, dtype=np.float64) else: p_step = float(cfg.rv_percentile_step) if p_step <= 0.0: out = (float("nan"), float("nan"), {"ok": False, "message": "invalid percentile grid"}) return out if return_diagnostics else (out[0], out[1]) percentiles = np.arange(p_lo, p_hi + 0.5 * p_step, p_step, dtype=np.float64) cuts: list[dict] = [] for pct in percentiles: depth = float(pct) / 100.0 row = _ccf_bisector_cut_m_s( v_m_s, y_peak_up, i_peak, depth, peak_amp, y_err=y_err, v_step_m_s=v_step, ) if row is None: continue v_mid, v_mid_err, v_left, v_right, pct_out = row core_sig = float(cfg.core_weight_sigma_percentile) if core_sig <= 0.0: w_perf = 1.0 else: w_perf = math.exp(-0.5 * ((pct_out - 50.0) / core_sig) ** 2) # Performance weight only. Inverse-variance cut weights are inappropriate # for strongly correlated percentile cuts and become unstable when a cut's # formal e_i collapses to the discretization floor. w_cut = w_perf target = float(depth * peak_amp) cuts.append( { "percentile": float(pct_out), "v_mid_m_s": float(v_mid), "v_mid_err_m_s": float(v_mid_err), "v_left_m_s": float(v_left), "v_right_m_s": float(v_right), "weight": float(w_cut), "target_flux": target, # Absolute CCF value of the horizontal cut (for previews). "ccf_level": float(baseline + sign * target), } ) if len(cuts) < int(cfg.min_cuts): out = ( float("nan"), float("nan"), {"ok": False, "message": f"too few bisector cuts ({len(cuts)})", "cuts": cuts}, ) return out if return_diagnostics else (out[0], out[1]) w_arr = np.array([c["weight"] for c in cuts], dtype=np.float64) v_arr = np.array([c["v_mid_m_s"] for c in cuts], dtype=np.float64) w_sum = float(np.sum(w_arr)) if w_sum <= 0.0 or not math.isfinite(w_sum): out = (float("nan"), float("nan"), {"ok": False, "message": "invalid weights", "cuts": cuts}) return out if return_diagnostics else (out[0], out[1]) rv = float(np.sum(w_arr * v_arr) / w_sum) e_arr = np.array([c["v_mid_err_m_s"] for c in cuts], dtype=np.float64) # Weighted mean of per-cut midpoint uncertainties. Cuts share one CCF, so do # **not** apply an independent-measurement :math:`1/\\sqrt{N}` reduction # (:math:`\\sqrt{\\sum (w e)^2}/\\sum w`); that understates σ by ~√N_eff. rv_err = float(np.sum(w_arr * e_arr) / w_sum) core_pct = float(cfg.rv_err_core_percentile) core_cut = min(cuts, key=lambda c: abs(c["percentile"] - core_pct)) cut_spread = float( math.sqrt(max(float(np.average((v_arr - rv) ** 2, weights=w_arr / w_sum)), 0.0)) ) d_pos = np.diff(v_m_s) d_pos = d_pos[np.isfinite(d_pos) & (d_pos > 0)] d_min = float(np.min(d_pos)) if d_pos.size > 0 else float(v_step) vstep_floor_frac = float(cfg.rv_err_min_vstep_fraction) if vstep_floor_frac > 0.0 and math.isfinite(d_min) and d_min > 0.0: rv_err = max(rv_err, vstep_floor_frac * d_min) wing_noise = float(mad_std(y_rel, ignore_nan=True)) if not math.isfinite(wing_noise) or wing_noise <= 0.0: wing_noise = float(np.nanstd(y_rel)) if y.size > 1 else peak_amp # Relative noise floor: an absolute 1e-30 destroys contrast when the CCF is an # unnormalized covariance of ~1e-17 fluxes (peak ~1e-34), then weak-peak # scaling inflates ``rv_err`` by many orders of magnitude. wing_floor = max(abs(float(peak_amp)) * 1e-30, float(np.finfo(np.float64).tiny)) peak_contrast_sigma = float(peak_amp / max(wing_noise, wing_floor)) min_contrast = float(cfg.min_peak_contrast_sigma) if min_contrast > 0.0 and peak_contrast_sigma < min_contrast: # Scale formal σ (do not floor to a multiple of the velocity grid step). rv_err *= float(min_contrast / max(peak_contrast_sigma, 1e-300)) rv_err = max(rv_err, _ccf_rv_err_numeric_floor(v_step)) boot_sig = float("nan") if has_ccf_err and int(cfg.rv_err_bootstrap_samples) > 0: y_model = CubicSpline(v_m_s, y, extrapolate=False)(v_m_s) rng = np.random.default_rng(cfg.rv_err_bootstrap_seed) boot_cfg = replace(cfg, rv_err_bootstrap_samples=0) ye_draw = np.where(np.isfinite(y_err), y_err, 0.0) boot_rvs: list[float] = [] for _ in range(int(cfg.rv_err_bootstrap_samples)): y_boot = y_model + rng.normal(0.0, ye_draw) rv_b, _ = fit_ccf_rv_bisector( v_m_s, y_boot, v_step, ccf_err=y_err, config=boot_cfg, ) if math.isfinite(rv_b): boot_rvs.append(float(rv_b)) if len(boot_rvs) >= 2: boot_sig = float(np.std(boot_rvs, ddof=1)) rv_err = max(rv_err, boot_sig) def _section_mean(lo: float, hi: float) -> tuple[float, float]: sel = [c for c in cuts if lo <= c["percentile"] <= hi] if not sel: return float("nan"), float("nan") ww = np.array([c["weight"] for c in sel], dtype=np.float64) vv = np.array([c["v_mid_m_s"] for c in sel], dtype=np.float64) ee = np.array([c["v_mid_err_m_s"] for c in sel], dtype=np.float64) wsum = float(np.sum(ww)) if wsum <= 0.0: return float("nan"), float("nan") mean_v = float(np.sum(ww * vv) / wsum) mean_e = float(np.sum(ww * ee) / wsum) return mean_v, mean_e v_top, e_top = _section_mean(cfg.bis_top_lo, cfg.bis_top_hi) v_bot, e_bot = _section_mean(cfg.bis_bottom_lo, cfg.bis_bottom_hi) bis = float(v_top - v_bot) if math.isfinite(v_top) and math.isfinite(v_bot) else float("nan") bis_err = float( math.sqrt(e_top * e_top + e_bot * e_bot) ) if math.isfinite(e_top) and math.isfinite(e_bot) else float("nan") diag = { "ok": True, "rv_m_s": rv, "rv_err_m_s": rv_err, "rv_err_core_percentile": core_pct, "rv_err_core_cut_percentile": float(core_cut["percentile"]), "rv_err_core_cut_m_s": float(core_cut["v_mid_err_m_s"]), "rv_err_bootstrap_sigma_m_s": boot_sig, "used_rv_err_bootstrap": math.isfinite(boot_sig) and boot_sig > 0.0, "baseline": float(baseline), "peak_amplitude": float(peak_amp), "v_peak_m_s": float(v_m_s[i_peak]), "n_cuts": len(cuts), "cuts": cuts, "bis_m_s": bis, "bis_err_m_s": bis_err, "bis_top_mean_m_s": v_top, "bis_bottom_mean_m_s": v_bot, "method": "ccf_bisector_weighted_percentile", "cut_midpoint_spread_m_s": cut_spread, "wing_noise_mad": wing_noise, "peak_contrast_sigma": peak_contrast_sigma, } if return_diagnostics: return rv, rv_err, diag return rv, rv_err
[docs] def _refine_ccf_rv_bisector_after_gaussian_fit( v_grid_m_s: np.ndarray, ccf: np.ndarray, vstep: float, *, ccf_err: np.ndarray | None = None, config: CCFBisectorConfig | None = None, gaussian_seed_mean_m_s: float | None = None, ) -> tuple[float | None, float | None, dict | None]: """ Bisector RV after :func:`fit_ccf_rv` (NEID-style weighted percentile cuts). Pass ``gaussian_seed_mean_m_s`` (Gaussian CCF center) so the bisector peak is taken near that velocity rather than a global ``argmax`` that can lock onto a window edge. Returns ``(None, None, diag)`` when bisector fitting fails; ``diag`` may still carry ``ok=False`` and cut metadata for previews. """ v_step_eff = ( float(vstep) if math.isfinite(vstep) and vstep > 0 else effective_ccf_v_step_for_fit(v_grid_m_s) ) rv_b, err_b, diag = fit_ccf_rv_bisector( v_grid_m_s, ccf, v_step_eff, ccf_err=ccf_err, config=config, return_diagnostics=True, gaussian_seed_mean_m_s=gaussian_seed_mean_m_s, ) if not isinstance(diag, dict) or not diag.get("ok") or not math.isfinite(float(rv_b)): return None, None, diag if isinstance(diag, dict) else None err_out: float | None = None if err_b is not None and math.isfinite(float(err_b)) and float(err_b) > 0.0: err_out = float(err_b) return float(rv_b), err_out, diag