Skip to content

box_least_squares

Box least squares transit search (Kovács, Zucker & Mazeh 2002) via astropy.
Category Time series
Backend astropy - wraps the domain-standard astropy implementation
Version 1.0.0
Reads -
Writes light_curves.input, periodograms.<output_key>, extras.bls_model, metrics.bls_best_period_days, metrics.bls_depth, metrics.bls_depth_err, metrics.bls_duration_hours, metrics.bls_transit_time, metrics.bls_snr

Wraps astropy.timeseries.BoxLeastSquares. Durations are tried in turn at every period (pass the list expected for the target ; the reported depth is diluted when the true duration is shorter than the best box). The period grid is astropy's autoperiod grid (uniform in frequency with spacing min(duration)/baseline², bounds period_min / period_max defaulting to 2·max(duration) and baseline/3) unless n_periods is given, in which case n_periods frequencies are spaced uniformly between 1/period_max and 1/period_min. objective='likelihood' maximises the log-likelihood of the box model (astropy default) ; 'snr' maximises depth/depth_err. Point uncertainties are used as inverse-variance weights when the light curve carries them ; otherwise every point gets the same σ = 1.4826 × MAD(flux − median), the robust point-to-point scatter, so that depth_err and bls_snr are on the data's noise scale (astropy alone would assume σ = 1 and report a meaningless SNR ; the uniform weight leaves the period ranking identical to the unweighted fit). Regime : times in days (metric names say so), a detrended/normalised flux, at least ~2 transits inside the baseline ; period_min must exceed the longest duration. bls_snr is astropy's depth_snr = depth/depth_err at the best period — compare with the ≈ 6 detection level of Kovács et al. ; no false-alarm probability is computed.

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 in days; null = 2 × longest duration.
period_max None - Longest trial period in days; null = baseline / 3.
duration_hours [1.0, 2.0, 4.0] - Transit duration(s) to try, in hours (single value or list).
n_periods None - Number of trial periods, uniform in frequency; null = astropy's autoperiod grid.
objective 'likelihood' - Quantity maximised over phase/depth/duration: one of ['likelihood', 'snr'].
output_key 'bls' - Key under which the power spectrum is stored in ctx.periodograms.

Use it

from spectro_kernel import run_algorithm

output = run_algorithm("box_least_squares", ctx, {
    "time": None,
    "flux": None,
    "uncertainty": None,
    "light_curve_key": None,
    "period_min": None,
    "period_max": None,
    "duration_hours": [
        1.0,
        2.0,
        4.0
    ],
    "n_periods": None,
    "objective": "likelihood",
    "output_key": "bls"
})

spectro run box_least_squares --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 duration_hours=[1.0,2.0,4.0] \
  --param n_periods=none \
  --param objective=likelihood \
  --param output_key=bls

{
  "tool": "box_least_squares",
  "arguments": {
    "session_id": "<session_id>",
    "params": {
      "time": null,
      "flux": null,
      "uncertainty": null,
      "light_curve_key": null,
      "period_min": null,
      "period_max": null,
      "duration_hours": [
        1.0,
        2.0,
        4.0
      ],
      "n_periods": null,
      "objective": "likelihood",
      "output_key": "bls"
    }
  }
}

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

References

  • Kovács, Zucker & Mazeh 2002, A&A 391, 369 — the box-fitting least squares algorithm: periodic alternation between two levels with a short low state of fractional length q ; detection driven by the effective SNR depth/σ (significant above ≈ 6 in their simulations).
  • astropy.timeseries.BoxLeastSquares — the wrapped implementation (likelihood / snr objectives ; depth, depth_err, depth_snr ; autoperiod grid heuristics).
  • Rousseeuw & Croux 1993, J. Am. Stat. Assoc. 88, 1273 — 1.4826 × MAD as a consistent robust estimate of σ for Gaussian noise, used as the uniform point uncertainty when the light curve carries none.