from dataclasses import dataclass
import math
import numpy as np
from hispecdrp.primitives.line_fitting.fit_lines import SIGMA_TO_FWHM, fit_line_gauss
from .ccf_bisector import (
CCFBisectorConfig,
calc_bisector_inverse_slope,
fit_ccf_rv_bisector,
)
from .ccf_common import effective_ccf_v_step_for_fit
__all__ = ["CCFMetrics", "calc_ccf_metrics"]
[docs]
@dataclass
class CCFMetrics:
"""
Results of a CCF Gaussian fit plus bisector analysis.
``rv`` / ``rv_err`` come from the Gaussian line fit (peak location, width, and
amplitude) and are the pipeline chunk / aggregate RV. ``bis_rv`` / ``bis_rv_err``
are the **absolute** bisector radial velocity from NEID-style weighted percentile
cuts (diagnostic only). ``bis`` / ``bis_err`` are the Queloz et al. (2001)
bisector-inverse-slope (``v_shallow - v_core``) and its uncertainty.
``bis_shallow`` / ``bis_core`` (and ``bisector`` / ``bis_levels``) come from the
same Queloz construction.
"""
contrast: float
contrast_err: float
rv: float
rv_err: float
fwhm: float
fwhm_err: float
offset: float
offset_err: float
bis_rv: float | None
bis_rv_err: float | None
bis: float | None = None
bis_err: float | None = None
bis_shallow: float | None = None
bis_shallow_err: float | None = None
bis_core: float | None = None
bis_core_err: float | None = None
bis_levels: np.ndarray | None = None
bisector: np.ndarray | None = None
bis_quant_shallow: tuple[float, float] | None = None
bis_quant_core: tuple[float, float] | None = None
# NEID-style ``fit_ccf_rv_bisector`` diagnostics (cuts, ``bis_m_s``, …) when available.
bisector_diagnostics: dict | None = None
@property
def sigma(self) -> float:
return self.fwhm / SIGMA_TO_FWHM
@property
def sigma_err(self) -> float:
return self.fwhm_err / SIGMA_TO_FWHM
@property
def popt(self) -> np.ndarray:
return np.array([self.contrast, self.rv, self.fwhm, self.offset])
@property
def perr(self) -> np.ndarray:
return np.array([self.contrast_err, self.rv_err, self.fwhm_err, self.offset_err])
[docs]
def to_row(self) -> dict:
return {
"contrast": self.contrast,
"contrast_err": self.contrast_err,
"rv": self.rv,
"rv_err": self.rv_err,
"fwhm": self.fwhm,
"fwhm_err": self.fwhm_err,
"offset": self.offset,
"offset_err": self.offset_err,
"bis_rv": self.bis_rv,
"bis_rv_err": self.bis_rv_err,
"bis": self.bis,
"bis_err": self.bis_err,
}
def _calc_rverr_from_ccf(
vel_grid: np.ndarray,
ccf: np.ndarray,
ccf_err: np.ndarray | None = None,
rv0: float | None = None,
fwhm: float | None = None,
fwhm_factor: float = 0.85,
pix_size: float | None = None,
) -> float:
"""
Estimate the 1-sigma uncertainty on a CCF-derived radial velocity
from the Fisher information:
sigma_v^-2 = sum_i ( dCCF/dv |_i )^2 / sigma_eff_i^2
where sigma_eff_i is the per-point CCF error, inflated to account
for the correlation between adjacent CCF velocity bins introduced
by top-hat binning of detector pixels onto an oversampled velocity
grid:
sigma_eff_i = ccf_err_i * sqrt(nsp)
nsp = tophat_width / grid_spacing
Parameters
----------
vel_grid : ndarray
1-D float ndarray: velocity grid (m/s) on which the CCF was
evaluated, i.e. the centers of the top-hat bins. Must already be
a 1-D numpy array (no list/Series coercion or flattening is
performed).
ccf : ndarray
1-D float ndarray, same shape as `vel_grid`: CCF values at each
point in `vel_grid`. Used to compute the local derivative
dCCF/dv; also used as a noise proxy (sqrt(ccf)) if `ccf_err` is
not provided.
rv0 : float, optional
Center velocity (m/s) of the window, typically the fitted RV.
If None, estimated as the first moment (intensity-weighted
centroid) of the inverted CCF: weight_i = max(ccf) - ccf_i.
fwhm : float, optional
Width (m/s) of the window around rv0 to use for the fit.
Typically the fitted CCF FWHM. If None, estimated from the
second moment (intensity-weighted variance) of the inverted
CCF, converted to FWHM assuming a Gaussian-like core:
fwhm = 2*sqrt(2*ln2) * sqrt(variance).
fwhm_factor : float, default 0.85
Factor multiplied by the FWHM to define the window around rv0 to use for the fit.
Example: fwhm_factor=0.85 uses a window of +/- 0.85*FWHM around rv0.
ccf_err : ndarray, optional
1-D float ndarray, same shape as `ccf`: 1-sigma uncertainty on
each CCF value. Assumed diagonal prior to the nsp inflation (no
covariance matrix available). If None, falls back to a
photon/Poisson noise proxy: sqrt(ccf).
pix_size : float | None
Size of a pixel in the velocity grid (m/s) to account for oversampling the CCF.
If None, no oversampling correction is applied (nsp=1).
Returns
-------
float
Estimated 1-sigma RV uncertainty in m/s. Returns 0.0 if the
inputs don't support a calculation (too few points, bad window,
non-positive errors, non-positive tophat_width, etc.).
"""
# Ensure correct shapes
if vel_grid.shape != ccf.shape:
raise ValueError("vel_grid and ccf must have the same shape")
# Check that CCF and errors are positive and finite and have enough points for a fit
if ccf_err is None:
if np.any(ccf < 0):
return 0.0
ccf_err = np.sqrt(np.maximum(ccf, 1e-30))
elif ccf_err.shape != ccf.shape:
raise ValueError("ccf_err must have the same shape as ccf")
# Mask out any non-finite or non-positive points in ccf and ccf_err
good = np.isfinite(vel_grid) & np.isfinite(ccf) & np.isfinite(ccf_err)
vel_grid, ccf, ccf_err = vel_grid[good], ccf[good], ccf_err[good]
# Can't fit with fewer than 3 points in the window
if vel_grid.size < 3:
return 0.0
# Compute zeroth and first moments if not provided
if rv0 is None or fwhm is None:
weight = np.maximum(np.max(ccf) - ccf, 0.0)
weight_sum = np.sum(weight)
if weight_sum <= 0 or not np.isfinite(weight_sum):
return 0.0
if rv0 is None:
rv0 = float(np.sum(weight * vel_grid) / weight_sum)
if fwhm is None:
variance = float(np.sum(weight * (vel_grid - rv0) ** 2) / weight_sum)
if variance <= 0 or not np.isfinite(variance):
return 0.0
fwhm = float(2.0 * np.sqrt(2.0 * np.log(2.0)) * np.sqrt(variance))
# FWHM must be positive
if fwhm <= 0:
return np.nan
# Correction factor for oversampling
delta_vel = vel_grid[1] - vel_grid[0]
if pix_size is not None and np.isfinite(float(pix_size)) and float(pix_size) > 0.0:
nsp = max(float(pix_size) / delta_vel, 1.0)
else:
nsp = 1.0
# Restrict to the window around rv0
fwhm_factor_half = fwhm_factor / 2.0
in_window = (vel_grid >= rv0 - fwhm * fwhm_factor_half) & (vel_grid <= rv0 + fwhm * fwhm_factor_half)
vel_window = vel_grid[in_window]
ccf_window = ccf[in_window]
ccf_err_window = ccf_err[in_window]
# Check again that we have enough valid points
if vel_window.size < 3:
return np.nan
if np.any(ccf_err_window <= 0) or np.any(~np.isfinite(ccf_err_window)):
return np.nan
# Inflate errors
effective_err = ccf_err_window * np.sqrt(nsp)
# dCCF/dv via finite differences
gradient = np.gradient(ccf_window, vel_window)
# FISHER info
fisher_info = np.sum((gradient / effective_err) ** 2)
if fisher_info <= 0 or not np.isfinite(fisher_info):
return np.nan
# Compute RV uncertainty from Fisher information
rv_err = 1.0 / np.sqrt(fisher_info)
return rv_err
[docs]
def calc_ccf_metrics(
vel_grid: np.ndarray,
ccf: np.ndarray,
ccf_err: np.ndarray | None = None,
pix_size: float | None = None,
absorption: bool = False,
calc_bis: bool = True,
n_levels_bis: int = 100,
bis_quant_shallow: tuple[float, float] | None = (0.10, 0.40),
bis_quant_core: tuple[float, float] | None = (0.55, 0.90),
override_rv_err_fisher: bool = True,
mu_guess: float | None = None,
) -> CCFMetrics:
"""
Fit a Gaussian to a CCF and (by default) run full bisector analysis.
Always computes the Gaussian peak (``rv``, ``fwhm``, ``contrast``, ``offset``) so
the CCF width and amplitude are available; ``rv`` / ``rv_err`` are the pipeline
chunk RV. When ``calc_bis`` is True, also:
1. Queloz BIS construction → ``bis`` / ``bis_err`` (slope ``v_shallow - v_core``),
plus ``bis_shallow`` / ``bis_core`` / ``bisector`` / ``bis_levels``.
2. NEID-style weighted-percentile bisector RV → ``bis_rv`` / ``bis_rv_err``
(absolute bisector RV diagnostic; not used as the pipeline final RV).
Parameters
----------
vel_grid : ndarray
Array of velocity trial values for the CCF.
ccf : ndarray
Array of CCF values corresponding to `vel_grid`.
ccf_err : ndarray, optional
Array of 1-sigma uncertainties on the CCF values.
absorption : bool, optional
Whether to fit an absorption line (True) or emission line (False). Default False.
pix_size : float, optional
Size of a pixel in the velocity grid (m/s) to account for oversampling the CCF.
calc_bis : bool, optional
Whether to run Queloz BIS diagnostics and the absolute bisector RV refine.
Default True.
n_levels_bis : int, optional
Number of levels to use for the Queloz bisector curve. Default 100.
bis_quant_shallow : tuple[float, float], optional
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).
bis_quant_core : tuple[float, float], optional
Lower/upper depth fractions (0-1, measured from the continuum) bounding
the core (near-core) region used for ``v_core``.
Defaults to (0.55, 0.90).
override_rv_err_fisher : bool, optional
Whether to override the RV error from the Gaussian fit with the Fisher
information estimate. Default True.
mu_guess : float or None, optional
Velocity seed (m/s) for the Gaussian fit. When omitted, uses the discrete
argmax/argmin of ``ccf``. Pass the scout / prominence center on multi-line
mask CCFs so a secondary extremum in a wide window does not steal the seed.
Returns
-------
result : CCFMetrics
Fully populated Gaussian + bisector metrics when ``calc_bis`` is True.
"""
# Index of the peak (emission line) or trough (absorption line) in the CCF
if mu_guess is not None and math.isfinite(float(mu_guess)):
mu_guess_v = float(mu_guess)
else:
idx_mu = np.argmax(ccf) if not absorption else np.argmin(ccf)
mu_guess_v = float(vel_grid[idx_mu])
# Default CCF error (use |ccf|: stored mask CCFs are often entirely negative)
if ccf_err is None:
ccf_err = np.sqrt(np.maximum(np.abs(ccf), 1e-30))
# Oversample correction (naive)
if pix_size is not None:
delta_vel = vel_grid[1] - vel_grid[0]
nsp = max(pix_size / delta_vel, 1.0)
ccf_err_eff = ccf_err * np.sqrt(nsp)
else:
ccf_err_eff = ccf_err
# Fit CCF with gaussian
fit_result = fit_line_gauss(
vel_grid,
ccf,
ccf_err_eff,
mu_guess=mu_guess_v,
background_poly_deg=0,
absorption=absorption,
)
# Override the RV error
if override_rv_err_fisher:
rv_err = _calc_rverr_from_ccf(
vel_grid,
ccf,
ccf_err,
rv0=fit_result.mu,
fwhm=fit_result.fwhm,
pix_size=pix_size,
)
else:
rv_err = fit_result.mu_err
bis_rv = None
bis_rv_err = None
bis = None
bis_err = None
bis_shallow = None
bis_shallow_err = None
bis_core = None
bis_core_err = None
bis_levels = None
bisector = None
bisector_diagnostics = None
if calc_bis:
# Queloz BIS: first return is the *slope* (v_shallow - v_core), not absolute RV.
(
_bis_slope,
_bis_slope_err,
bis_shallow,
bis_shallow_err,
bis_core,
bis_core_err,
bis_levels,
bisector,
) = calc_bisector_inverse_slope(
vel_grid,
ccf,
ccf_err_eff,
n_levels=n_levels_bis,
quant_shallow=bis_quant_shallow,
quant_core=bis_quant_core,
)
if math.isfinite(float(_bis_slope)):
bis = float(_bis_slope)
if math.isfinite(float(_bis_slope_err)):
bis_err = float(_bis_slope_err)
# Absolute bisector RV (refined peak). Prefer the caller ``mu_guess`` when the
# Gaussian center has wandered far: on broad, shallow mask CCFs an emission
# Gaussian with a flat continuum often drifts by several km/s, and seeding
# the bisector there reintroduces injected→recovered tilt.
v_step = (
float(pix_size)
if pix_size is not None and math.isfinite(float(pix_size)) and float(pix_size) > 0.0
else float(effective_ccf_v_step_for_fit(vel_grid))
)
bis_seed = float(fit_result.mu)
if (
mu_guess is not None
and math.isfinite(float(mu_guess))
and math.isfinite(bis_seed)
and abs(bis_seed - mu_guess_v) > 2000.0
):
bis_seed = mu_guess_v
rv_b, err_b, bisector_diagnostics = fit_ccf_rv_bisector(
vel_grid,
ccf,
v_step,
ccf_err=ccf_err_eff,
return_diagnostics=True,
gaussian_seed_mean_m_s=bis_seed,
)
if not isinstance(bisector_diagnostics, dict):
bisector_diagnostics = None
if math.isfinite(float(rv_b)):
bis_rv = float(rv_b)
cut_err = (
float(err_b)
if err_b is not None and math.isfinite(float(err_b)) and float(err_b) > 0.0
else float("nan")
)
fisher_err = (
float(rv_err)
if rv_err is not None and math.isfinite(float(rv_err)) and float(rv_err) > 0.0
else float("nan")
)
# Cut-weighted formal σ (numerator) can sit near ~0.3 Δv on coarse grids;
# Fisher on the same CCF can be optimistic when ``ccf_err`` is tiny. The
# geometric mean tracks injected→recovered scatter (~m/s) better than
# either extreme alone.
if math.isfinite(cut_err) and math.isfinite(fisher_err):
bis_rv_err = float(math.sqrt(cut_err * fisher_err))
elif math.isfinite(cut_err):
bis_rv_err = cut_err
elif math.isfinite(fisher_err):
bis_rv_err = fisher_err
# Re-apply the bisector velocity-grid floor after combining with Fisher:
# geomean can undershoot that floor and break residual ≤ 3×RV_ERR coverage.
vstep_floor_frac = float(CCFBisectorConfig().rv_err_min_vstep_fraction)
if (
bis_rv_err is not None
and math.isfinite(float(bis_rv_err))
and vstep_floor_frac > 0.0
and math.isfinite(v_step)
and float(v_step) > 0.0
):
bis_rv_err = max(float(bis_rv_err), vstep_floor_frac * float(v_step))
elif (
bisector is not None
and np.size(bisector) > 0
and np.any(np.isfinite(bisector))
):
# Fallback: mean Queloz bisector midpoint curve (absolute velocities).
bis_rv = float(np.nanmean(np.asarray(bisector, dtype=np.float64)))
elif (
bis_shallow is not None
and bis_core is not None
and math.isfinite(float(bis_shallow))
and math.isfinite(float(bis_core))
):
bis_rv = 0.5 * (float(bis_shallow) + float(bis_core))
if (
bis is None
and isinstance(bisector_diagnostics, dict)
and bisector_diagnostics.get("bis_m_s") is not None
and math.isfinite(float(bisector_diagnostics["bis_m_s"]))
):
bis = float(bisector_diagnostics["bis_m_s"])
be = bisector_diagnostics.get("bis_err_m_s")
if be is not None and math.isfinite(float(be)):
bis_err = float(be)
return CCFMetrics(
contrast=fit_result.amplitude,
contrast_err=fit_result.amplitude_err,
rv=fit_result.mu,
rv_err=rv_err,
fwhm=fit_result.fwhm,
fwhm_err=fit_result.fwhm_err,
offset=fit_result.background_coeffs[0],
offset_err=fit_result.background_coeffs_err[0],
bis_rv=bis_rv,
bis_rv_err=bis_rv_err,
bis=bis,
bis_err=bis_err,
bis_shallow=bis_shallow,
bis_shallow_err=bis_shallow_err,
bis_core=bis_core,
bis_core_err=bis_core_err,
bis_levels=bis_levels,
bisector=bisector,
bis_quant_shallow=bis_quant_shallow,
bis_quant_core=bis_quant_core,
bisector_diagnostics=bisector_diagnostics,
)