Skip to content

temporal_variance_spectrum

Temporal variance spectrum (Fullerton, Gies & Bolton 1996) of N ≥ 3 line profiles.
Category Time series
Backend scipy - implemented here on top of scipy primitives
Version 2.0.0
Reads ctx.spectra (a list of Spectrum1D)
Writes extras.tvs, metrics.tvs_n_epochs, metrics.tvs_n_pixels, metrics.tvs_sigma_0, metrics.tvs_threshold_sqrt, metrics.tvs_max_sqrt, metrics.tvs_n_significant_pixels, metrics.tvs_variable_lo_aa, metrics.tvs_variable_hi_aa

Implements the noise-weighted TVS of Fullerton et al. (1996, §3). The per-epoch continuum noise σ_ic is the median of Spectrum1D.uncertainty inside the continuum window when present, else the DER_SNR estimate on the epoch's own (native, not resampled) samples in that window (the whole overlap when continuum_lo/continuum_hi are null — fine as long as lines cover less than half of the pixels; DER_SNR is a median statistic). The weights w_i = (σ_0/σ_ic)² are normalised to Σ w_i = N through σ_0 = [(1/N) Σ σ_ic⁻²]^(−1/2), so the mean profile S̄j = (1/N) Σ w_i S_ij is the inverse-variance weighted mean. Under the null hypothesis (N−1)(TVS)_j/σ_0² follows χ² with N−1 degrees of freedom, hence the threshold (TVS)^1/2 > σ_0 [χ²(N−1)(p)/(N−1)]^1/2 with p = 1 − confidence; at the default 99 % about 1 % of non-variable pixels exceed it by chance. (TVS)^1/2 is reported in continuum units (multiply by 100 for the paper's percent-of-continuum presentation). Caveats: the pixel-dependent Poisson term α_ij = S_ij^1/2 of the paper's fully general form is not applied (uniform noise across the profile, i.e. photon noise inside deep lines is treated as equal to the continuum noise, which is conservative for absorption lines); resampling onto a common grid correlates adjacent pixels, so for a strict test feed epochs already on one wavelength grid (they are then used as-is); wavelength-shifted epochs (RV, barycentric) must be aligned beforehand or the shift itself shows up as variability. tvs_variable_lo_aa / tvs_variable_hi_aa are a reporting convenience (the bounds of the longest run of at least min_run_pixels contiguous significant pixels), not part of the paper's formalism; they are only written when such a run exists. v2.0.0: masked samples (Spectrum1D.mask) are ignored, per epoch — a common-grid pixel that any epoch lacks (masked or non-finite, including the resampled pixels that would draw on one) gets no TVS (null in extras.tvs, never significant) instead of failing the run ; the per-epoch noise skips them too ; extras.tvs.n_excluded_pixels counts them and at least 5 usable pixels are required.

Parameters

Parameter Default Required Description
continuum_lo None - Lower edge (wavelength units) of the line-free window used for the per-epoch noise σ_ic; null = whole overlap.
continuum_hi None - Upper edge of the continuum window; null = whole overlap.
confidence 0.99 - Confidence level of the χ²_(N−1) variability threshold (paper: 0.99).
min_run_pixels 3 - Minimum number of contiguous significant pixels for a run to be reported as tvs_variable_lo_aa / tvs_variable_hi_aa.

Use it

from spectro_kernel import run_algorithm

output = run_algorithm("temporal_variance_spectrum", ctx, {
    "continuum_lo": None,
    "continuum_hi": None,
    "confidence": 0.99,
    "min_run_pixels": 3
})

The CLI loads a single 1-D spectrum with --input; this algorithm needs ctx.spectra (a list of Spectrum1D). Run it from Python or as a step of a pipeline preset.

{
  "tool": "temporal_variance_spectrum",
  "arguments": {
    "session_id": "<session_id>",
    "params": {
      "continuum_lo": null,
      "continuum_hi": null,
      "confidence": 0.99,
      "min_run_pixels": 3
    }
  }
}

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

References

  • Fullerton, Gies & Bolton 1996, ApJS 103, 475 — §3, the temporal variance spectrum: (TVS)j = 1/(N−1) Σ_i w_i (S_ij − S̄_j)² with w_i = (σ_0/σ_ic)², σ_0 = [(1/N) Σ_i σ_ic⁻²]^(−1/2) so that Σ w_i = N, S̄_j = (1/N) Σ_i w_i S_ij, and the significance test (N−1)(TVS)_j/σ_0² ~ χ²(N−1) under the null hypothesis.
  • Stoehr et al. 2008, ASP Conf. Ser. 394, 505 — DER_SNR, the recipe used for σ_ic when a spectrum carries no uncertainty array.
  • box_least_squares - Box least squares transit search (Kovács, Zucker & Mazeh 2002) via astropy.
  • lomb_scargle - Compute a Lomb-Scargle periodogram and report the dominant period.
  • phase_dispersion_minimization - Stellingwerf (1978) phase dispersion minimization: Θ = s²/σ² over a period grid.
  • phase_fold - Phase-fold a light curve on a known period.