hispecdrp.primitives.utils.ccf.ccf_bisector

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

Functions

_calc_bis(vel_grid, ccf, ccf_err[, ...])

Bisector Inverse Slope (BIS) of a CCF, after Queloz et al. (2001).

_ccf_bisector_cut_m_s(v_m_s, y_peak_up, ...)

Bisector midpoint at one depth percentile.

_ccf_bisector_discretization_sigma_m_s(...)

Sub-grid 1σ uncertainty (m/s) for a linearly interpolated wing crossing.

_ccf_bisector_wing_crossing_m_s(v_m_s, ...)

Velocity (m/s) and bracket index where y_peak_up crosses target.

_ccf_bisector_wing_velocity_m_s(v_m_s, ...)

Velocity (m/s) where y_peak_up crosses target on the left or right wing of i_peak.

_ccf_bisector_wing_velocity_uncertainty_m_s(...)

Approximate 1σ uncertainty (m/s) on a bisector wing crossing.

_find_ccf_level(vel_grid, ccf, ccf_err, ...)

Find where one flank crosses level, walking outward from the extremum.

_interp_x_at_y(x0, y0, x1, y1, y)

Linear interpolation: return x where a segment (x0,y0)-(x1,y1) hits y.

_refine_ccf_rv_bisector_after_gaussian_fit(...)

Bisector RV after fit_ccf_rv() (NEID-style weighted percentile cuts).

calc_bisector_inverse_slope(vel_grid, ccf[, ...])

Bisector Inverse Slope (BIS) of a CCF, after Queloz et al. (2001).

fit_ccf_rv_bisector(v_grid_m_s, ccf, ...[, ...])

Radial velocity (m/s) from a traditional CCF bisector analysis.

Classes

CCFBisectorConfig([rv_percentile_lo, ...])

Tunables for fit_ccf_rv_bisector() (traditional CCF bisector RV).

class CCFBisectorConfig(rv_percentile_lo=10.0, rv_percentile_hi=90.0, rv_n_percentile_cuts=31, rv_percentile_step=5.0, bis_top_lo=60.0, bis_top_hi=90.0, bis_bottom_lo=10.0, bis_bottom_hi=40.0, core_weight_sigma_percentile=25.0, rv_err_core_percentile=50.0, rv_err_bootstrap_samples=0, rv_err_bootstrap_seed=None, min_cuts=5, min_peak_contrast_sigma=5.0, rv_err_min_vstep_fraction=0.15)[source]

Bases: object

Tunables for 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 \((v_\mathrm{left}+v_\mathrm{right})/2\) at multiple depth percentiles: with per-cut midpoint uncertainties \(e_i\) and weights \(w_i\),

\[\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 \(e_i\) comes from CCF-error propagation when informative, otherwise from the smooth-profile discretization estimate.

bis_bottom_hi = 40.0

Bottom section high for BIS.

bis_bottom_lo = 10.0

Bottom section low for BIS, NEID default 10–40%.

bis_top_hi = 90.0

Top section high for BIS.

bis_top_lo = 60.0

Top section low for bisector inverse slope (BIS), NEID default 60–90%.

core_weight_sigma_percentile = 25.0

Gaussian performance weight on percentile cuts (core emphasis).

min_cuts = 5

Minimum successful bisector cuts required for a valid RV.

min_peak_contrast_sigma = 5.0

Minimum peak amplitude (above baseline) in units of robust wing noise.

rv_err_bootstrap_samples = 0
rv_err_bootstrap_seed = None
rv_err_core_percentile = 50.0

Representative “core” cut percentile for diagnostics / preview labeling.

rv_err_min_vstep_fraction = 0.15

Floor rv_err to this fraction of the minimum positive velocity spacing.

rv_n_percentile_cuts = 31

Fixed number of evenly spaced percentile cuts (overrides rv_percentile_step when >= 2).

rv_percentile_hi = 90.0

Percentile range high (0–100) for bisector midpoints in the RV estimate.

rv_percentile_lo = 10.0

Percentile range low (0–100) for bisector midpoints in the RV estimate.

rv_percentile_step = 5.0

Step between percentile cuts when rv_n_percentile_cuts < 2.

_refine_ccf_rv_bisector_after_gaussian_fit(v_grid_m_s, ccf, vstep, *, ccf_err=None, config=None, gaussian_seed_mean_m_s=None)[source]

Bisector RV after 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.

calc_bisector_inverse_slope(vel_grid, ccf, ccf_err=None, n_levels=100, quant_shallow=(0.1, 0.4), quant_core=(0.6, 0.9))[source]

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 (ndarray) – Velocity grid (ascending) and CCF values.

  • 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.

fit_ccf_rv_bisector(v_grid_m_s, ccf, v_step_m_s, *, ccf_err=None, config=None, return_diagnostics=False, gaussian_seed_mean_m_s=None)[source]

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 (\(\sum_i w_i e_i\,/\,\sum_i w_i\)), not an independent-cut \(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 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.