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)
}