Skip to content

cross_correlate_rv

Measure radial velocity by cross-correlation against a template spectrum.
Category Radial velocity
Backend scipy - implemented here on top of scipy primitives
Version 3.0.0
Reads ctx.spectrum (a Spectrum1D)
Writes metrics.radial_velocity_kms, metrics.radial_velocity_error_kms, metrics.peak_strength, metrics.ccf_peak, metrics.tonry_davis_r, metrics.ccf_fwhm_kms, metrics.n_grid_used, metrics.velocity_step_kms, extras.ccf, extras.template_id, extras.template_source

Template comes from template_path (FITS), template_key (a Spectrum1D under ctx.extras), ctx.extras['template_spectrum'] or ctx.spectra[0] — first match wins. By default the brick subtracts a running-median continuum from both observed and template (continuum_subtract=True) — the Tonry-Davis CCF only behaves correctly on continuum-normalised inputs ; with raw flux the SED slope dominates the correlation and biases the RV toward zero. Disable with continuum_subtract=False when the caller has already normalised the spectrum. The RV error is the Tonry-Davis 1979 formula ; it underestimates the true error for asymmetric CCFs (multi-component blended templates) — for a physics-grounded floor see rv_precision_bouchy (Bouchy, Pepe & Queloz 2001). v3.0.0: n_grid defaults to None — the log-λ grid follows the finest native Δlnλ of the two spectra over the overlap (capped at 2^18 samples). The former default of 4096 samples (41 km/s per sample on 4000-7000 Å) under-sampled finely sampled spectra and the parabolic refinement did not recover the loss : on a 30 000-px synthetic (σ_line 0.15 Å, S/N 100) an injected +10 km/s came back as +0.9 km/s with n_grid=4096 and as +9.97 km/s on the native grid ; pass n_grid=4096 explicitly to reproduce the pre-3.0.0 numbers. σ_v is a lower bound at coarse grids because it ignores the interpolation error. Masked samples (Spectrum1D.mask) of either spectrum are skipped like NaN when resampling (v3.0.0). Descending wavelength axes are sorted before resampling. DEPRECATED: the ctx.spectra[0] template fallback violates the 'second spectrum in ctx.extras' convention and will be removed in a future major release — it is flagged in the message, in extras['template_source'] and via a DeprecationWarning.

Parameters

Parameter Default Required Description
template_path None - Path / URL of a template FITS spectrum to load.
template_key None - Key in ctx.extras where a Spectrum1D template is stored.
n_grid None - Number of log-wavelength samples on which to interpolate. null/None (default since v3.0.0) derives it from the finest native Δlnλ of the two spectra inside the overlap (capped at 2^18) ; 4096 reproduces the pre-3.0.0 grid (41 km/s per sample on 4000-7000 Å, under-sampled for most spectra).
vmin_kms -800.0 - Lower bound of the velocity search range (km/s).
vmax_kms 800.0 - Upper bound of the velocity search range (km/s).
continuum_subtract True - If True (default), subtract a running-median continuum from both observed and template before correlation — the Tonry-Davis 1979 prerequisite. Disable only when the spectra are already continuum-normalised.
continuum_window 101 - Running-median window (samples on the log-λ grid) for the continuum estimator. Must be odd ≥ 3; the brick rounds up if even. Ignored when continuum_subtract is False.

Use it

from spectro_kernel import run_algorithm

output = run_algorithm("cross_correlate_rv", ctx, {
    "template_path": None,
    "template_key": None,
    "n_grid": None,
    "vmin_kms": -800.0,
    "vmax_kms": 800.0,
    "continuum_subtract": True,
    "continuum_window": 101
})

spectro run cross_correlate_rv --input spectrum.fits \
  --param template_path=none \
  --param template_key=none \
  --param n_grid=none \
  --param vmin_kms=-800.0 \
  --param vmax_kms=800.0 \
  --param continuum_subtract=true \
  --param continuum_window=101

{
  "tool": "cross_correlate_rv",
  "arguments": {
    "session_id": "<session_id>",
    "params": {
      "template_path": null,
      "template_key": null,
      "n_grid": null,
      "vmin_kms": -800.0,
      "vmax_kms": 800.0,
      "continuum_subtract": true,
      "continuum_window": 101
    }
  }
}

Every algorithm is an MCP tool of the same name; describe_algorithm returns this page's metadata as JSON.

References

  • Tonry & Davis 1979, AJ 84, 1511 — fundamental CCF method for RV; r-value, σ_v = 3·w/(8·(1+r)) error formula (§III), and the requirement of continuum-normalised inputs (§II).
  • Bouchy, Pepe & Queloz 2001, A&A 374, 733 — photon-limited RV precision (see also: rv_precision_bouchy).
  • scipy.signal.correlate — cross-correlation engine.
  • scipy.ndimage.median_filter — running-median continuum.