API reference

nn_periodogram.periodogram(time, mag, err=None, fmin=None, fmax=10.0, oversample=3.0, n_peaks=5, refine=20, prefer_shorter=None, method=None, n_candidates=40, proposers=('ls', 'mhls'), calibrated=True, model='periods-v4', device=None, batch=1024, weights=None, exact=False)[source]

Find the period of a light curve.

Parameters:

  • time – As for fap().

  • mag – As for fap().

  • err – As for fap().

  • fmin (float or Quantity, optional) – Frequency range in 1/day (or any frequency/period Quantity). fmin defaults to 2 / baseline; fmax to 10 / day.

  • fmax (float or Quantity, optional) – Frequency range in 1/day (or any frequency/period Quantity). fmin defaults to 2 / baseline; fmax to 10 / day.

  • oversample (float) – Grid samples per 1/baseline.

  • method ({"hybrid", "full"}, optional) – "hybrid" (default for the new models): fast Lomb-Scargle and multi-harmonic Lomb-Scargle periodograms propose candidates (their best peaks and each one’s 2x, 1/2x, 3x and 1/3x) and the network chooses among them. "full": the network scores every grid frequency, then refines the best n_peaks peaks. Slower, and independent of the classical methods.

  • n_candidates (int) – Hybrid: peaks taken from each proposing periodogram.

  • proposers (tuple of {"ls", "mhls", "pdm"}) – Hybrid: periodograms that propose candidates. "ls" (fast generalised Lomb-Scargle) and "mhls" (fast 3-harmonic Lomb-Scargle) cost O(N + M log M); "pdm" (phase dispersion) costs O(N M) and is mainly for comparison.

  • n_peaks (int) – Full: peaks refined, and fine-grid points per side.

  • refine (int) – Full: peaks refined, and fine-grid points per side.

  • prefer_shorter (bool, optional) – When the best period’s half scores within 25% of it, report the half (and say so in note). The default belongs to the model: on for models that cannot see 2P and P/2 side by side, off for those that can.

  • calibrated (bool) – Report best_fap as the false-alarm probability of the whole search: the fraction of pure-noise light curves of similar size (real survey cadences; white, red and outlier-ridden noise) whose best fold scores as well. Searching hundreds of periods makes some fold look good by chance, so the best fold’s own FAP (best_fap_fold) is far too optimistic for detection. Default True.

  • model – As for fap().

  • device – As for fap().

  • batch – As for fap().

  • weights – As for fap().

  • exact – As for fap().

Returns:

best_period, best_fap (of the search), best_fap_fold, peaks [(period, fold FAP), …], the scored freq and fap arrays, a note, and plot().

Return type:

Periodogram

nn_periodogram.check_period(time, mag, period, err=None, model='periods-v4', device=None, weights=None)[source]

Check a known period: is it right, a harmonic, or a sampling alias?

Scores period (from any method or catalogue) against 2P, P/2, 3P, P/3, 3P/2, 2P/3 and its +-1/sidereal-day and +-1/year aliases, and reports the one the network prefers. Costs a dozen folds, so it is cheap enough for whole catalogues.

Parameters:

  • time – As for fap().

  • mag – As for fap().

  • err – As for fap().

  • model – As for fap().

  • device – As for fap().

  • weights – As for fap().

  • period (float or Quantity) – The period to check, in days unless it carries units.

Returns:

best_period, best_fap, relation (e.g. "P", "2P", "alias +1/d") and every candidate as (relation, period, fap), best first.

Return type:

PeriodCheck

nn_periodogram.fap(time, mag, period, err=None, model='periods-v4', device=None, batch=1024, weights=None, exact=False)[source]

Neural-network false-alarm probability of one or more trial periods.

Parameters:

  • time (array-like, astropy Time or Quantity) – Observation times, in days unless they carry units. Any length from ~10 points.

  • mag (array-like or Quantity) – Magnitudes (or fluxes; only the shape of the folded curve matters).

  • period (float, array-like or Quantity) – Trial period(s), in days unless they carry units.

  • err (array-like or Quantity, optional) – Per-point uncertainties. Estimated from point-to-point scatter if omitted.

  • model (str) – Registered model name (see nn_periodogram.hub.MODELS).

  • device (str or torch.device, optional) – "cpu", "cuda" or "mps". Default: the best available.

  • batch (int) – Trial periods per pass (legacy model only; newer models size batches automatically).

  • weights (str, optional) – Path to a local weights file, bypassing the download.

  • exact (bool) – Legacy model only: compute features in float64 on the CPU, matching the 2022 code to ~1e-6.

Returns:

FAP in [0, 1] per period; low means the fold looks like a real periodic signal.

Return type:

float or numpy.ndarray

class nn_periodogram.Periodogram(freq: numpy.ndarray, fap: numpy.ndarray, peaks: list = <factory>, best_period: float = nan, best_fap: float = nan, note: str = '', best_fap_fold: float = nan)[source]
class nn_periodogram.PeriodCheck(period: float, best_period: float, best_fap: float, relation: str, candidates: list = <factory>)[source]