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

"""Sub-pixel CCF peak location on a coarse velocity grid (seeding / scout only).

These helpers locate a raw CCF extremum for Gaussian-fit *seeds* and auto-center
scouts. They are **not** used as the pipeline final RV estimator (that is the
Gaussian centroid from :func:`~hispecdrp.primitives.utils.ccf.ccf_fitting.calc_ccf_metrics`
/ :func:`~hispecdrp.primitives.utils.ccf.ccf_utils.fit_ccf_rv`).
"""

from __future__ import annotations

import math

import numpy as np
from scipy.interpolate import CubicSpline
from scipy.optimize import minimize_scalar

__all__ = [
    "_ccf_raw_grid_subpixel_peak_nearest_disc_max_m_s",
]


def _collapse_duplicate_velocity_samples_m_s(
    vm: np.ndarray,
    y: np.ndarray,
) -> tuple[np.ndarray, np.ndarray]:
    """Sort by velocity and average CCF values at duplicate ``vm`` knots."""
    vm = np.asarray(vm, dtype=np.float64).ravel()
    y = np.asarray(y, dtype=np.float64).ravel()
    if vm.size == 0 or vm.size != y.size:
        return np.array([], dtype=np.float64), np.array([], dtype=np.float64)
    o = np.argsort(vm)
    vm = vm[o]
    y = y[o]
    if vm.size < 2:
        return vm, y
    if np.all(np.diff(vm) > 0):
        return vm, y
    vm_u, inv = np.unique(vm, return_inverse=True)
    cnt = np.bincount(inv)
    y_u = np.bincount(inv, weights=y) / np.maximum(cnt.astype(np.float64), 1.0)
    return vm_u, y_u


def _subpixel_peak_cubic_spline_m_s(vm_w: np.ndarray, z_w: np.ndarray) -> tuple[float | None, str | None]:
    """Location of the maximum via cubic spline + bounded optimization on velocity."""
    vw = np.asarray(vm_w, dtype=np.float64).ravel()
    zw = np.asarray(z_w, dtype=np.float64).ravel()
    if vw.size < 3 or zw.size != vw.size:
        return None, "insufficient points"
    if not np.all(np.isfinite(vw)) or not np.all(np.isfinite(zw)):
        return None, "non-finite window data"
    if np.any(np.diff(vw) <= 0):
        return None, "velocity not strictly increasing"
    lo, hi = float(vw[0]), float(vw[-1])
    if not (math.isfinite(lo) and math.isfinite(hi)) or hi <= lo:
        return None, "invalid velocity bounds"

    try:
        cs = CubicSpline(vw, zw)

        def negc(x: float) -> float:
            v = float(cs(x))
            return -v if math.isfinite(v) else 1e300

        res = minimize_scalar(
            negc,
            bounds=(lo, hi),
            method="bounded",
            options={"xatol": 1e-12, "maxiter": 200},
        )
        if not res.success or not math.isfinite(res.x):
            return None, "cubic optimize failed"
        vtx = float(res.x)
        if not math.isfinite(vtx) or vtx < lo - 1.0 or vtx > hi + 1.0:
            return None, "bad vertex"
        return vtx, None
    except Exception:
        return None, "cubic spline failed"


def _ccf_raw_grid_subpixel_peak_m_s(
    vm: np.ndarray,
    y: np.ndarray,
    *,
    use_maximum: bool = True,
) -> float:
    """
    Sub-pixel location of a raw CCF extremum on the velocity grid.

    Prefer a cubic-spline extremum; fall back to the discrete argmax/argmin bin.
    """
    vm = np.asarray(vm, dtype=np.float64).ravel()
    y = np.asarray(y, dtype=np.float64).ravel()
    if vm.size < 3 or y.size != vm.size:
        return float("nan")
    ok = np.isfinite(vm) & np.isfinite(y)
    if int(np.count_nonzero(ok)) < 3:
        return float("nan")
    vm = vm[ok]
    y = y[ok]
    vm, y = _collapse_duplicate_velocity_samples_m_s(vm, y)
    if vm.size < 3:
        return float("nan")
    if np.any(np.diff(vm) <= 0):
        return float("nan")
    y_eff = np.asarray(y, dtype=np.float64).ravel()
    if not use_maximum:
        y_eff = -y_eff
    v_c, _err = _subpixel_peak_cubic_spline_m_s(vm, y_eff)
    if v_c is not None and math.isfinite(float(v_c)):
        return float(v_c)
    return float(vm[int(np.nanargmax(y_eff))])


[docs] def _ccf_raw_grid_subpixel_peak_nearest_disc_max_m_s(vm: np.ndarray, y: np.ndarray) -> float: """ Sub-pixel raw CCF location using the better of the global-maximum and minimum branches, chosen by proximity to the discrete velocity at ``argmax(y)``. """ a = _ccf_raw_grid_subpixel_peak_m_s(vm, y, use_maximum=True) b = _ccf_raw_grid_subpixel_peak_m_s(vm, y, use_maximum=False) imx = int(np.nanargmax(y)) if not (0 <= imx < int(vm.size)): return float(a if math.isfinite(a) else b) v_disc = float(vm[imx]) if not math.isfinite(v_disc): return float(a if math.isfinite(a) else b) if not math.isfinite(a): return float(b) if not math.isfinite(b): return float(a) return float(a) if abs(float(a) - v_disc) <= abs(float(b) - v_disc) else float(b)