Skip to content

phase_dispersion_minimization

Stellingwerf (1978) phase dispersion minimization: Θ = s²/σ² over a period grid.
Category Time series
Backend numpy - implemented here on top of numpy primitives
Version 1.0.0
Reads -
Writes light_curves.input, periodograms.<output_key>, metrics.pdm_best_period_days, metrics.pdm_theta_min

The light curve is folded on every trial period of a grid uniform in frequency between 1/period_max and 1/period_min (phase zero at the first observation). Phases are split into n_bins equal bins, repeated n_covers times with a phase offset of 1/(n_bins·n_covers) between sequences — Stellingwerf's (N_b, N_c) structure; (10, 3) and (5, 2) are the usual choices. Θ = s²/σ² compares the pooled within-bin variance to the total variance: ≈ 1 when the fold is wrong, ≪ 1 at the true period. Point uncertainties are not used (the 1978 statistic is unweighted). Regime: period_max should stay well below the time baseline (Θ is meaningless beyond one cycle) and period_min above twice the typical cadence; at least 2·n_bins points are required. Integer multiples of the true period also produce low Θ (a fold on 2P is still coherent) — inspect the Θ curve, and prefer the shortest period among near-equal minima. No significance level is attached because Stellingwerf's F-test is known to be incorrect (Schwarzenberg-Czerny 1997). Metric names assume times in days.

Parameters

Parameter Default Required Description
time None - List of observation times; omit to use a light curve from the context.
flux None - List of flux values, paired with 'time'.
uncertainty None - Optional list of per-point flux uncertainties.
light_curve_key None - Key in ctx.light_curves to use when time/flux are omitted.
period_min None - Shortest trial period (time units of the curve); null = twice the median cadence.
period_max None - Longest trial period; null = half the time baseline.
n_periods 2000 - Number of trial periods, spaced uniformly in frequency.
n_bins 10 - N_b — number of phase bins per sequence (Stellingwerf 1978).
n_covers 3 - N_c — number of offset bin sequences ('covers'); 1 = plain non-overlapping bins.
output_key 'pdm' - Key under which the Θ curve is stored in ctx.periodograms.

Use it

from spectro_kernel import run_algorithm

output = run_algorithm("phase_dispersion_minimization", ctx, {
    "time": None,
    "flux": None,
    "uncertainty": None,
    "light_curve_key": None,
    "period_min": None,
    "period_max": None,
    "n_periods": 2000,
    "n_bins": 10,
    "n_covers": 3,
    "output_key": "pdm"
})

spectro run phase_dispersion_minimization --input spectrum.fits \
  --param time=none \
  --param flux=none \
  --param uncertainty=none \
  --param light_curve_key=none \
  --param period_min=none \
  --param period_max=none \
  --param n_periods=2000 \
  --param n_bins=10 \
  --param n_covers=3 \
  --param output_key=pdm

{
  "tool": "phase_dispersion_minimization",
  "arguments": {
    "session_id": "<session_id>",
    "params": {
      "time": null,
      "flux": null,
      "uncertainty": null,
      "light_curve_key": null,
      "period_min": null,
      "period_max": null,
      "n_periods": 2000,
      "n_bins": 10,
      "n_covers": 3,
      "output_key": "pdm"
    }
  }
}

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

References

  • Stellingwerf 1978, ApJ 224, 953 — the PDM statistic Θ = s²/σ² with σ² = Σ(x−x̄)²/(N−1) and s² = Σ_j (n_j−1) s_j² / (Σ_j n_j − M) over M overlapping phase samples (N_b bins × N_c covers); Θ ≈ 1 for a wrong period, minimum at the true one.
  • Schwarzenberg-Czerny 1997, ApJ 489, 941 — the PDM statistic follows a (incomplete) beta distribution, not the F distribution of the 1978 paper; hence no false-alarm probability is reported here.
  • 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_fold - Phase-fold a light curve on a known period.
  • temporal_variance_spectrum - Temporal variance spectrum (Fullerton, Gies & Bolton 1996) of N ≥ 3 line profiles.