Skip to content

src/core/periodogram.js ​

text
Periodic signals in transit-timing residuals.

  lombScargle            generalised Lomb-Scargle periodogram (Zechmeister & Kuerster 2009): weighted,
                         floating mean, on any frequency grid. Same numbers as astropy.timeseries.LombScargle.
  frequencyGrid          astropy's autofrequency() rule, for comparisons with it
  timingFrequencyGrid    the grid used for transit epochs (see "Frequency range" below)
  falseAlarmProbability / falseAlarmLevel     Baluev (2008) analytic bound; also 'davies', 'naive', 'single'
  bootstrapFalseAlarm    the same quantities by resampling the residuals
  fitSinusoids           polynomial baseline + sinusoids by weighted least squares, linear at fixed periods,
                         then the periods refined (Gauss-Newton) with a full covariance
  timingPeriodogram      the sequence of EXOTIC's ephemeris_fitter.plot_periodogram: linear ephemeris ->
                         residuals -> periodogram -> strongest period -> 1-sinusoid fit -> periodogram of what
                         is left -> 2-sinusoid fit -> BIC comparison and a plain-language verdict

Frequency range for transit epochs. Mid-transit times exist only at whole orbits, so the sampling is a
lattice with step g epochs (g = greatest common divisor of the epoch differences, 1 in practice). On a
lattice, frequencies f and 1/g - f give identical sinusoids at every sample: this is a true Nyquist limit,
not the "average Nyquist" of irregular sampling. Everything that can be said about the data is inside
0 < f < 1/(2g) cycles per epoch, i.e. periods longer than 2g epochs; a physical signal with a shorter period
appears at its alias inside that range. The default grid therefore runs from period 2g epochs (exclusive)
up to twice the time span (longer periods are not distinguishable from curvature of the ephemeris), in
steps of 1/(oversample * span) with oversample = 10. Periods are in epochs; multiply by the orbital period
for days (the O-C is thousands of times smaller than the period, so a periodogram against time in days
is the same curve with the axis rescaled).

Normalisations (same definitions as astropy), with chi2_ref the chi-square about the weighted mean and
chi2(f) that of the best sinusoid + mean at frequency f:
  'standard'  1 - chi2(f)/chi2_ref            in [0, 1]   (default)
  'model'     chi2_ref/chi2(f) - 1
  'log'       ln(chi2_ref/chi2(f))
  'psd'       (chi2_ref - chi2(f)) / 2

Uncertainties everywhere come from the supplied error bars and are not rescaled by chi-square, like
ephemeris.js. No DOM, no dependencies beyond ephemeris.js and the seeded generator in stats.js.

Import: import { … } from './src/core/periodogram.js' — no DOM, runs in Node and the browser.

gammaln ​

js
function gammaln(x)
text
ln Gamma(x), x > 0 (Lanczos, g = 7; relative error below 1e-14).

lombScargle ​

js
function lombScargle(t, y, dy, freqs, opt = {})
text
Generalised Lomb-Scargle power at each frequency.
t, y: samples; dy: 1-sigma errors or null (equal weights); freqs: cycles per unit of t.
opt: { normalization: 'standard' | 'model' | 'log' | 'psd', fitMean: true }
  fitMean true  (default) the mean is a free parameter at every frequency (floating mean, "GLS")
  fitMean false           the weighted mean is subtracted once (classical Lomb-Scargle with weights)
Returns a Float64Array the length of freqs. Cost: freqs.length * t.length sine/cosine pairs.

frequencyGrid ​

js
function frequencyGrid(t, opt = {})
text
astropy's LombScargle.autofrequency(): df = 1/(samplesPerPeak * span), from minFrequency (default df/2)
to maxFrequency (default nyquistFactor * n / (2 span), the "average Nyquist" rule). For comparisons with astropy;
for transit epochs use timingFrequencyGrid.

timingFrequencyGrid ​

js
function timingFrequencyGrid(x, opt = {})
text
Frequency grid for a timing series (see the header). x: epochs (whole numbers) or times.
opt: { oversample = 10, minPeriod, maxPeriod }  (periods in the unit of x)
Returns { freqs, df, span, lattice, nyquistPeriod, minPeriod, maxPeriod }.
  lattice        g, the step of the epoch lattice (null when x is not whole numbers)
  nyquistPeriod  2g; for non-integer x, twice the smallest spacing (only a guide there)
The grid stops strictly below 1/minPeriod, so the exactly degenerate Nyquist frequency is never evaluated.

falseAlarmProbability ​

js
function falseAlarmProbability(z, ctx, opt = {})
text
Probability that pure noise produces a highest peak of at least z somewhere below fmax.
ctx: { t, dy (or null), fmax }   the sample positions, their errors, and the highest frequency SEARCHED
opt: { method: 'baluev' (default) | 'davies' | 'naive' | 'single', normalization: 'standard' }
  'baluev'  Baluev (2008) eq. 6 with the effective time span sqrt(4 pi var_w(t)): an upper limit that is
            close for small probabilities. Assumes white Gaussian noise and no spectral leakage.
  'davies'  the Davies bound it is built on (can exceed 1)
  'naive'   1 - (1 - p_single)^(fmax * span) independent frequencies
  'single'  the probability at one pre-chosen frequency (no search)
Same formulae as astropy 6.1 (false_alarm_probability), which the tests compare against.

falseAlarmLevel ​

js
function falseAlarmLevel(p, ctx, opt = {})

Power that noise exceeds with probability p (inverse of falseAlarmProbability on its falling branch). Same ctx and opt.

bootstrapFalseAlarm ​

js
function bootstrapFalseAlarm(t, y, dy, freqs, opt = {})
text
False alarms by bootstrap: the (y, dy) pairs are shuffled with replacement over the fixed sample positions,
which destroys any periodicity but keeps the sampling and the noise distribution; the highest peak of each
shuffled series is recorded. opt: { n = 1000, seed = 1, normalization, fitMean }.
Returns { maxPowers (sorted Float64Array), fap(z), level(p) }. The smallest probability it can state is 1/n
(fap(z) is 0 above every resample; level(p) is NaN for p < 1/n).
Cost: n periodograms.

fitSinusoids ​

js
function fitSinusoids(x, y, dy, periods, opt = {})
text
Polynomial baseline plus sinusoids:
  y(x) = sum_{j<=order} c_j x^j  +  sum_m [ S_m sin(2 pi x / P_m) + C_m cos(2 pi x / P_m) ]
       = ...                      +  sum_m A_m sin(2 pi x / P_m + phi_m)
x, y, dy: samples and 1-sigma errors (dy null: unit weights). periods: starting periods P_m, in the unit of x.
opt: { order = 0 (0 constant, 1 line, 2 parabola),
       refine = true   after the linear solution at the given periods, the periods are freed and the fit is
                       polished by Gauss-Newton; each period may move by at most one resolution element
                       (1/span in frequency) from where it started, so it stays on its periodogram peak }
Returns {
  n, order, refined (bool: the period refinement converged), iterations,
  k        free parameters counted: order + 1 + 2 per sinusoid, + 1 per refined period
  kLinear  order + 1 + 2 per sinusoid (the count EXOTIC/statsmodels use, period not counted)
  chi2, dof (n - k),
  poly: [c_0..c_order], polyErr          coefficients of x^j at x = 0 (so for epochs: T0, P, dP/dE / 2)
  terms: [{ period, periodErr, freq, freqErr, sin, cos, sinErr, cosErr, amp, ampErr, phase, phaseErr }]
           sin, cos, phase refer to x = 0; phase in radians in (-pi, pi]; periodErr is NaN when not refined.
           amp is sqrt(sin^2 + cos^2), which is biased upward when it is not well above its error.
  cov      covariance of the internal parameters [c'_0..c'_order, S'_1, C'_1, ..., f_1, ...] (centred, scaled x)
  model(x), periodic(x)   full model and the sinusoid part alone
  predict(x) -> { y, sigma, periodic, periodicSigma }   with 1-sigma from the full covariance (periods included)
}
Throws when there are too few points or the columns are degenerate (two equal periods, a period the sampling
cannot distinguish from the baseline).

bicScaled ​

js
function bicScaled(chi2, n, k, errs)
text
BIC with the noise scale left free (errors known only up to a common factor), the definition statsmodels
uses for WLS and therefore the one EXOTIC prints:  n ln(chi2) + n (1 + ln(2 pi / n)) - sum ln(1/err^2) + k ln n.
Differences between models are n ln(chi2_a / chi2_b) + (k_a - k_b) ln n. Compare with the fixed-error
BIC = chi2 + k ln n used elsewhere in this app: the two agree when the reduced chi-square is 1.

timingPeriodogram ​

js
function timingPeriodogram(epochs, times, errs, opt = {})
text
Search transit-timing residuals for periodic signals, in the manner of EXOTIC's plot_periodogram.

epochs: whole orbit numbers; times, errs: mid-transit times and 1-sigma errors, days (Julian dates are fine:
times[0] is subtracted before anything is fitted).
opt: {
  order = 1          baseline: 1 linear ephemeris (EXOTIC), 2 quadratic (search on top of a period change)
  oversample = 10, minPeriod, maxPeriod     grid, see timingFrequencyGrid (periods in epochs)
  normalization = 'standard'
  fapLevels = [0.1, 0.01, 0.001]            levels drawn on the plot
  fapThreshold = 0.01                       a peak counts as significant below this (EXOTIC's "99% FAP")
  fapMethod = 'baluev'
  bootstrap = 0                             > 0: that many bootstrap periodograms for each stage (slow for large sets)
  seed = 1
  refine = true                             free the periods in the sinusoid fits
  countPeriods = true                       count each fitted period as a parameter in k, BIC and dof
                                            (false reproduces EXOTIC's count: 4 and 6 parameters)
  nPeaks = 5                                peaks listed per periodogram
}
Returns {
  n, order, tRef, period (days per epoch, from the baseline fit),
  epochs, errs, residuals      Float64Arrays; residuals = times - baseline ephemeris, days (what periodogram 1 saw)
  linear                       fitEphemeris(epochs, times, errs, 1)
  baseline                     fitEphemeris(..., order)   (=== linear when order is 1)
  grid                         from timingFrequencyGrid, without the freqs array, plus fmax
  periodograms: [pg1, pg2]     pg2 is of the residuals after the 1-sinusoid model (null if that fit failed)
    pg = { label, freq, period, power (Float64Arrays; period = 1/freq, descending), normalization,
           fapMethod, fapLevels: [{ fap, power }],
           peaks: [{ freq, period (epochs), periodDays, power, fap, fapBootstrap? }]   strongest first;
                  peaks[0] is refined between grid points; fap of the others is the probability for a
                  highest peak of that height, quoted for orientation only
           bootstrap: { n, levels: [{ fap, power }] } | undefined }
  models: [linear, sin1, sin2] (the last two null when they could not be fitted), each
    { key: 'linear'|'sin1'|'sin2', name, k, chi2, dof, redChi2, bic (chi2 + k ln n), bicScaled,
      t0, per, dPdE (0 unless order 2), err: { t0, per, dPdE },
      terms: [{ period, periodErr (epochs), periodDays, periodDaysErr, amp, ampErr (days), phase, phaseErr (rad, at epoch 0),
                sin, cos, sinErr, cosErr (days), freq, freqErr }],
      refined, fit (the fitSinusoids result; null for the baseline) }
  best            index into models of the lowest bic
  bestScaled      the same with bicScaled
  deltaBic        [0, bic(sin1) - bic(linear), bic(sin2) - bic(linear)]  (NaN where missing)
  significant     peaks[0] of periodogram 1 has fap < fapThreshold (and fapBootstrap < fapThreshold when a bootstrap was run)
  significant2    the same for periodogram 2, and only if the first is
  recommended     index of the model to adopt: a sinusoid is taken only when its peak is significant AND it lowers
                  the BIC. The BIC alone prefers a sinusoid in most signal-free data sets, because it does not
                  know the period was searched for (see test/periodogram.test.mjs).
  nEff            (sum w)^2 / sum w^2, the number of equally weighted transits the error bars amount to
  fapThreshold
  verdict         one paragraph of plain language
  notes           [strings] caveats that apply (aliases, error bars too small, ...)
  curve(i, nPts = 400, pad = 0.04) -> { E, y, lo, hi }   model i minus the LINEAR ephemeris with its 1-sigma band,
                  days: the shape renderOC() takes as d.curve (null for a missing model; zeros for the linear one)
}

MIT licensed · Kyle A. Pearson