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 2.1.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). The default n_grid=4096 under-samples finely sampled spectra (41 km/s per sample on 4000-7000 Å) and the parabolic refinement does not fully recover the loss ; pass n_grid=None (v2.1.0) to derive the grid from the finest native Δlnλ of the two spectra (capped at 2^18). σ_v is a lower bound at coarse grids because it ignores the interpolation error. 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 4096 - Number of log-wavelength samples on which to interpolate (default 4096). null/None derives it from the finest native Δlnλ of the two spectra inside the overlap (capped at 2^18).
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": 4096,
    "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=4096 \
  --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": 4096,
      "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.