API Documentation

Periodic Modeling for Astronomical Time Series

class gatspy.periodic.LombScargle(optimizer=None, center_data=True, fit_offset=True, Nterms=1, regularization=None, regularize_by_trace=True, fit_period=False, optimizer_kwds=None)[source]

Lomb-Scargle Periodogram Implementation

This is a generalized periodogram implementation using the matrix formalism outlined in VanderPlas & Ivezic 2015. It allows computation of periodograms and best-fit models for both the classic normalized periodogram and truncated Fourier series generalizations.

Parameters:

optimizer : PeriodicOptimizer instance

Optimizer to use to find the best period. If not specified, the LinearScanOptimizer will be used.

center_data : boolean (default = True)

If True, then compute the weighted mean of the input data and subtract before fitting the model.

fit_offset : boolean (default = True)

If True, then fit a floating-mean sinusoid model.

Nterms : int (default = 1)

Number of Fourier frequencies to fit in the model

regularization : float, vector or None (default = None)

If specified, then add this regularization penalty to the least squares fit.

regularize_by_trace : boolean (default = True)

If True, multiply regularization by the trace of the matrix

fit_period : bool (optional)

If True, then fit for the best period when fit() method is called.

optimizer_kwds : dict (optional

Dictionary of keyword arguments for constructing the optimizer

See also

LombScargleAstroML, LombScargleMultiband, LombScargleMultibandFast

Examples

>>> rng = np.random.RandomState(0)
>>> t = 100 * rng.rand(100)
>>> dy = 0.1
>>> omega = 10
>>> y = np.sin(omega * t) + dy * rng.randn(100)
>>> ls = LombScargle().fit(t, y, dy)
>>> ls.optimizer.period_range = (0.2, 1.2)
>>> ls.best_period
Finding optimal frequency:
 - Estimated peak width = 0.0639
 - Using 5 steps per peak; omega_step = 0.0128
 - User-specified period range:  0.2 to 1.2
 - Computing periods at 2051 steps
Zooming-in on 5 candidate peaks:
 - Computing periods at 1000 steps
0.62827068275990694
>>> ls.predict([0, 0.5])
array([-0.01445853, -0.92762251])

Attributes

best_period Lazy evaluation of the best period given the model

Methods

find_best_periods([n_periods, return_scores]) Find the top several best periods for the model
fit(t, y[, dy]) Fit the multiterm Periodogram model to the data.
periodogram([periods]) Compute the periodogram for the given period or periods
periodogram_auto([oversampling, ...]) Compute the periodogram on an automatically-determined grid
predict(t[, period]) Compute the best-fit model at t for a given period
score([periods]) Compute the periodogram for the given period or periods
score_frequency_grid(f0, df, N) Compute the score on a frequency grid.
class gatspy.periodic.LombScargleFast(optimizer=None, center_data=True, fit_offset=True, use_fft=True, ls_kwds=None, Nterms=1, fit_period=False, optimizer_kwds=None, silence_warnings=False)[source]

Fast FFT-based Lomb-Scargle Periodogram Implementation

This implements the O[N log N] lomb-scargle periodogram, described in Press & Rybicki (1989) [1]. To compute the periodogram via the fast algorithm, use the score_frequency_grid() method. The score() method and periodogram() method will default to the slower algorithm. See Notes below for more information about the algorithm.

Parameters:

optimizer : PeriodicOptimizer instance

Optimizer to use to find the best period. If not specified, the LinearScanOptimizer will be used.

center_data : boolean (default = True)

If True, then compute the weighted mean of the input data and subtract before fitting the model.

fit_offset : boolean (default = True)

If True, then fit a floating-mean sinusoid model.

use_fft : boolean (default = True)

Specify whether to use the Press & Rybicki FFT algorithm to compute the result

ls_kwds : dict

Dictionary of keywords to pass to the lomb_scargle_fast routine.

fit_period : bool (optional)

If True, then fit for the best period when fit() method is called.

optimizer_kwds : dict (optional)

Dictionary of keyword arguments for constructing the optimizer. For example, silence optimizer output with optimizer_kwds={“quiet”: True}.

silence_warnings : bool (default=False)

If False, then warn the user when doing silly things, like calling score() rather than score_frequency_grid() or fitting this to small datasets (fewer than 50 points).

See also

LombScargle, LombScargleAstroML

Notes

Currently, a NotImplementedError will be raised if both center_data and fit_offset are False.

Note also that the fast algorithm is only an approximation to the true Lomb-Scargle periodogram, and as the number of points grows this approximation improves. On the other hand, for very small datasets (<~50 points or so) this approximation may produce incorrect results for some datasets.

References

[R1]Press W.H. and Rybicki, G.B, “Fast algorithm for spectral analysis of unevenly sampled data”. ApJ 1:338, p277, 1989

Examples

>>> rng = np.random.RandomState(0)
>>> t = 100 * rng.rand(100)
>>> dy = 0.1
>>> omega = 10
>>> y = np.sin(omega * t) + dy * rng.randn(100)
>>> ls = LombScargleFast().fit(t, y, dy)
>>> ls.optimizer.period_range = (0.2, 1.2)
>>> ls.best_period
Finding optimal frequency:
 - Estimated peak width = 0.0639
 - Using 5 steps per peak; omega_step = 0.0128
 - User-specified period range:  0.2 to 1.2
 - Computing periods at 2051 steps
Zooming-in on 5 candidate peaks:
 - Computing periods at 1000 steps
0.62826265739259146
>>> ls.predict([0, 0.5])
array([-0.02019474, -0.92910567])

Attributes

best_period Lazy evaluation of the best period given the model

Methods

find_best_periods([n_periods, return_scores]) Find the top several best periods for the model
fit(t, y[, dy]) Fit the multiterm Periodogram model to the data.
periodogram([periods]) Compute the periodogram for the given period or periods
periodogram_auto([oversampling, ...]) Compute the periodogram on an automatically-determined grid
predict(t[, period]) Compute the best-fit model at t for a given period
score([periods]) Compute the periodogram for the given period or periods
score_frequency_grid(f0, df, N) Compute the score on a frequency grid.
class gatspy.periodic.LombScargleAstroML(optimizer=None, Nterms=1, fit_offset=True, center_data=True, slow_version=False, fit_period=False, optimizer_kwds=None)[source]

Lomb-Scargle Periodogram Implementation using AstroML

This is a generalized periodogram implementation which uses the periodogram functions from astroML. Compared to LombScargle, this implementation is both faster and more memory-efficient.

Parameters:

optimizer : PeriodicOptimizer instance

Optimizer to use to find the best period. If not specified, the LinearScanOptimizer will be used.

Nterms : int (default = 1)

Number of terms for the fit. Only Nterms=1 is currently supported.

center_data : boolean (default = True)

If True, then compute the weighted mean of the input data and subtract before fitting the model.

fit_offset : boolean (default = True)

If True, then fit a floating-mean sinusoid model.

slow_version : boolean (default = False)

If True, use the slower pure-python version from astroML. Otherwise, use the faster version of the code from astroML_addons

fit_period : bool (optional)

If True, then fit for the best period when fit() method is called.

optimizer_kwds : dict (optional

Dictionary of keyword arguments for constructing the optimizer

See also

LombScargle, LombScargleMultiband, LombScargleMultibandFast

Examples

>>> rng = np.random.RandomState(0)
>>> t = 100 * rng.rand(100)
>>> dy = 0.1
>>> omega = 10
>>> y = np.sin(omega * t) + dy * rng.randn(100)
>>> ls = LombScargleAstroML().fit(t, y, dy)
>>> ls.optimizer.period_range = (0.2, 1.2)
>>> ls.best_period
Finding optimal frequency:
 - Estimated peak width = 0.0639
 - Using 5 steps per peak; omega_step = 0.0128
 - User-specified period range:  0.2 to 1.2
 - Computing periods at 2051 steps
Zooming-in on 5 candidate peaks:
 - Computing periods at 1000 steps
0.62827068275990694

Attributes

best_period Lazy evaluation of the best period given the model

Methods

find_best_periods([n_periods, return_scores]) Find the top several best periods for the model
fit(t, y[, dy]) Fit the multiterm Periodogram model to the data.
periodogram([periods]) Compute the periodogram for the given period or periods
periodogram_auto([oversampling, ...]) Compute the periodogram on an automatically-determined grid
predict(t[, period]) Compute the best-fit model at t for a given period
score([periods]) Compute the periodogram for the given period or periods
score_frequency_grid(f0, df, N) Compute the score on a frequency grid.
class gatspy.periodic.LombScargleMultiband(optimizer=None, Nterms_base=1, Nterms_band=1, reg_base=None, reg_band=1e-06, regularize_by_trace=True, center_data=True, fit_period=False, optimizer_kwds=None)[source]

Multiband Periodogram Implementation

This implements the generalized multi-band periodogram described in VanderPlas & Ivezic 2015.

Parameters:

optimizer : PeriodicOptimizer instance

Optimizer to use to find the best period. If not specified, the LinearScanOptimizer will be used.

Nterms_base : integer (default = 1)

number of frequency terms to use for the base model common to all bands

Nterms_band : integer (default = 1)

number of frequency terms to use for the residuals between the base model and each individual band

reg_base : float or None (default = None)

amount of regularization to use on the base model parameters

reg_band : float or None (default = 1E-6)

amount of regularization to use on the band model parameters

regularize_by_trace : bool (default = True)

if True, then regularization is expressed in units of the trace of the normal matrix

center_data : boolean (default = True)

if True, then center the y data prior to the fit

See also

LombScargle, LombScargleFast, LombScargleMultibandFast

Attributes

best_period Lazy evaluation of the best period given the model

Methods

find_best_periods([n_periods, return_scores]) Find the top several best periods for the model
fit(t, y[, dy, filts]) Fit the multiterm Periodogram model to the data.
periodogram([periods]) Compute the periodogram for the given period or periods
periodogram_auto([oversampling, ...]) Compute the periodogram on an automatically-determined grid
predict(t, filts[, period]) Compute the best-fit model at t for a given period
score([periods]) Compute the periodogram for the given period or periods
score_frequency_grid(f0, df, N) Compute the score on a frequency grid.
class gatspy.periodic.LombScargleMultibandFast(optimizer=None, Nterms=1, BaseModel=None, fit_period=False, optimizer_kwds=None)[source]

Fast Multiband Periodogram Implementation

This implements the specialized multi-band periodogram described in VanderPlas & Ivezic 2015 (with Nbase=0 and Nband=1) which is essentially a weighted sum of the standard periodograms for each band.

Parameters:

optimizer : PeriodicOptimizer instance

Optimizer to use to find the best period. If not specified, the LinearScanOptimizer will be used.

Nterms : integer (default = 1)

Number of fourier terms to use in the model

BaseModel : PeriodicModeler class (optional)

The base model to use for each individual band. By default it will use LombScargleFast if Nterms == 1, and LombScargle otherwise.

fit_period : bool (optional)

If True, then fit for the best period when fit() method is called.

optimizer_kwds : dict (optional

Dictionary of keyword arguments for constructing the optimizer

See also

LombScargle, LombScargleFast, LombScargleMultiband

Attributes

best_period Lazy evaluation of the best period given the model

Methods

find_best_periods([n_periods, return_scores]) Find the top several best periods for the model
fit(t, y[, dy, filts]) Fit the multiterm Periodogram model to the data.
periodogram([periods]) Compute the periodogram for the given period or periods
periodogram_auto([oversampling, ...]) Compute the periodogram on an automatically-determined grid
predict(t, filts[, period]) Compute the best-fit model at t for a given period
score([periods]) Compute the periodogram for the given period or periods
score_frequency_grid(f0, df, N) Compute the score on a frequency grid.
class gatspy.periodic.TrendedLombScargle(optimizer=None, center_data=True, fit_offset=True, Nterms=1, regularization=None, regularize_by_trace=True, fit_period=False, optimizer_kwds=None)[source]

Trended Lomb-Scargle Periodogram Implementation

This is a generalized periodogram implementation using the matrix formalism outlined in VanderPlas & Ivezic 2015. It fits both a floating mean and a trend parameter (as opposed to the LombScargle class, which fits only the mean).

Parameters:

optimizer : PeriodicOptimizer instance

Optimizer to use to find the best period. If not specified, the LinearScanOptimizer will be used.

center_data : boolean (default = True)

If True, then compute the weighted mean of the input data and subtract before fitting the model.

fit_offset : boolean (default = True)

If True, then fit a floating-mean sinusoid model.

Nterms : int (default = 1)

Number of Fourier frequencies to fit in the model

regularization : float, vector or None (default = None)

If specified, then add this regularization penalty to the least squares fit.

regularize_by_trace : boolean (default = True)

If True, multiply regularization by the trace of the matrix

fit_period : bool (optional)

If True, then fit for the best period when fit() method is called.

optimizer_kwds : dict (optional)

Dictionary of keyword arguments for constructing the optimizer. For example, silence optimizer output with optimizer_kwds={“quiet”: True}.

See also

LombScargle, LombScargleAstroML, LombScargleMultiband, LombScargleMultibandFast

Examples

>>> rng = np.random.RandomState(0)
>>> t = 100 * rng.rand(100)
>>> dy = 0.1
>>> omega = 10
>>> slope = 2.
>>> y = np.sin(omega * t) + slope * t + dy * rng.randn(100)
>>> ls = TrendedLombScargle().fit(t, y, dy)
>>> ls.optimizer.period_range = (0.2, 1.2)
>>> ls.best_period
Finding optimal frequency:
 - Estimated peak width = 0.0639
 - Using 5 steps per peak; omega_step = 0.0128
 - User-specified period range:  0.2 to 1.2
 - Computing periods at 2051 steps
Zooming-in on 5 candidate peaks:
 - Computing periods at 1000 steps
0.62827068275990694
>>> ls.predict([0, 0.5])
array([-0.01144474,  0.07567192])

Attributes

best_period Lazy evaluation of the best period given the model

Methods

find_best_periods([n_periods, return_scores]) Find the top several best periods for the model
fit(t, y[, dy]) Fit the multiterm Periodogram model to the data.
periodogram([periods]) Compute the periodogram for the given period or periods
periodogram_auto([oversampling, ...]) Compute the periodogram on an automatically-determined grid
predict(t[, period]) Compute the best-fit model at t for a given period
score([periods]) Compute the periodogram for the given period or periods
score_frequency_grid(f0, df, N) Compute the score on a frequency grid.
class gatspy.periodic.SuperSmoother(optimizer=None, fit_period=False, optimizer_kwds=None)[source]

Periodogram based on Friedman’s SuperSmoother.

Parameters:

optimizer : PeriodicOptimizer instance

Optimizer to use to find the best period. If not specified, the LinearScanOptimizer will be used.

fit_period : bool (optional)

If True, then fit for the best period when fit() method is called.

optimizer_kwds : dict (optional)

Dictionary of keyword arguments for constructing the optimizer. For example, silence optimizer output with optimizer_kwds={“quiet”: True}.

See also

LombScargle

Examples

>>> rng = np.random.RandomState(0)
>>> t = 100 * rng.rand(100)
>>> dy = 0.1
>>> omega = 10
>>> y = np.sin(omega * t) + dy * rng.randn(100)
>>> ssm = SuperSmoother().fit(t, y, dy)
>>> ssm.optimizer.period_range = (0.2, 1.2)
>>> ssm.best_period
Finding optimal frequency:
 - Estimated peak width = 0.0639
 - Using 5 steps per peak; omega_step = 0.0128
 - User-specified period range:  0.2 to 1.2
 - Computing periods at 2051 steps
Zooming-in on 5 candidate peaks:
 - Computing periods at 1000 steps
0.62819846183431927
>>> ssm.predict([0, 0.5])
array([-0.02195035, -0.92119149])

Attributes

best_period Lazy evaluation of the best period given the model

Methods

find_best_periods([n_periods, return_scores]) Find the top several best periods for the model
fit(t, y[, dy]) Fit the multiterm Periodogram model to the data.
periodogram([periods]) Compute the periodogram for the given period or periods
periodogram_auto([oversampling, ...]) Compute the periodogram on an automatically-determined grid
predict(t[, period]) Compute the best-fit model at t for a given period
score([periods]) Compute the periodogram for the given period or periods
score_frequency_grid(f0, df, N) Compute the score on a frequency grid.
class gatspy.periodic.SuperSmootherMultiband(optimizer=None, BaseModel=<class 'gatspy.periodic.supersmoother.SuperSmoother'>, fit_period=False, optimizer_kwds=None)[source]

Simple multi-band SuperSmoother, with each band smoothed independently

Parameters:

optimizer : PeriodicOptimizer instance

Optimizer to use to find the best period. If not specified, the LinearScanOptimizer will be used.

BaseModel : class type (default = SuperSmoother)

The base model to use for each individual band.

fit_period : bool (optional)

If True, then fit for the best period when fit() method is called.

optimizer_kwds : dict (optional)

Dictionary of keyword arguments for constructing the optimizer. For example, silence optimizer output with optimizer_kwds={“quiet”: True}.

Attributes

best_period Lazy evaluation of the best period given the model

Methods

find_best_periods([n_periods, return_scores]) Find the top several best periods for the model
fit(t, y[, dy, filts]) Fit the multiterm Periodogram model to the data.
periodogram([periods]) Compute the periodogram for the given period or periods
periodogram_auto([oversampling, ...]) Compute the periodogram on an automatically-determined grid
predict(t, filts[, period]) Compute the best-fit model at t for a given period
score([periods]) Compute the periodogram for the given period or periods
score_frequency_grid(f0, df, N) Compute the score on a frequency grid.
class gatspy.periodic.RRLyraeTemplateModeler(filts='ugriz', optimizer=None, fit_period=False, optimizer_kwds=None)[source]

Template-fitting periods for single-band RR Lyrae

This class contains functionality to evaluate the fit of the Sesar 2010 RR Lyrae templates to single-band data.

Parameters:

filts : list or iterable of characters (optional)

The filters of the templates to be used. Items should be among ‘ugriz’. Default is ‘ugriz’; i.e. all available templates.

optimizer : PeriodicOptimizer instance (optional)

Optimizer to use to find the best period. If not specified, the LinearScanOptimizer will be used.

fit_period : bool (optional)

If True, then fit for the best period when fit() method is called.

optimizer_kwds : dict (optional

Dictionary of keyword arguments for constructing the optimizer

See also

RRLyraeTemplateModelerMultiband
multiband version of template model

Attributes

best_period Lazy evaluation of the best period given the model

Methods

find_best_periods([n_periods, return_scores]) Find the top several best periods for the model
fit(t, y[, dy]) Fit the multiterm Periodogram model to the data.
periodogram([periods]) Compute the periodogram for the given period or periods
periodogram_auto([oversampling, ...]) Compute the periodogram on an automatically-determined grid
predict(t[, period]) Compute the best-fit model at t for a given period
score([periods]) Compute the periodogram for the given period or periods
score_frequency_grid(f0, df, N) Compute the score on a frequency grid.
class gatspy.periodic.RRLyraeTemplateModelerMultiband(optimizer=None, fit_period=False, optimizer_kwds=None, *args, **kwargs)[source]

Multiband version of RR Lyrae template-fitting modeler

This class contains functionality to evaluate the fit of the Sesar 2010 RR Lyrae templates to multiband data.

Parameters:

optimizer : PeriodicOptimizer instance (optional)

Optimizer to use to find the best period. If not specified, the LinearScanOptimizer will be used.

See also

RRLyraeTemplateModeler
single band version of template model

Attributes

best_period Lazy evaluation of the best period given the model

Methods

find_best_periods([n_periods, return_scores]) Find the top several best periods for the model
fit(t, y[, dy, filts]) Fit the multiterm Periodogram model to the data.
periodogram([periods]) Compute the periodogram for the given period or periods
periodogram_auto([oversampling, ...]) Compute the periodogram on an automatically-determined grid
predict(t, filts[, period]) Compute the best-fit model at t for a given period
score([periods]) Compute the periodogram for the given period or periods
score_frequency_grid(f0, df, N) Compute the score on a frequency grid.
class gatspy.periodic.NaiveMultiband(optimizer=None, BaseModel=<class 'gatspy.periodic.lomb_scargle.LombScargle'>, fit_period=False, optimizer_kwds=None, *args, **kwargs)[source]

Naive version of multiband fitting

Parameters:

optimizer : PeriodicOptimizer instance

Optimizer to use to find the best period. If not specified, the LinearScanOptimizer will be used.

BaseModel : PeriodicModeler instance

Single-band model to use on data from each band.

fit_period : bool (optional)

If True, then fit for the best period when fit() method is called.

optimizer_kwds : dict (optional

Dictionary of keyword arguments for constructing the optimizer

*args, **kwargs :

additional arguments are passed to BaseModel on construction.

Attributes

best_period

Methods

best_periods() Compute the scores under the various models
find_best_periods([n_periods, return_scores]) Find the top several best periods for the model
fit(t, y[, dy, filts]) Fit the multiterm Periodogram model to the data.
periodogram([periods]) Compute the periodogram for the given period or periods
periodogram_auto([oversampling, ...]) Compute the periodogram on an automatically-determined grid
predict(t, filts[, period]) Compute the best-fit model at t for a given period
score([periods]) Compute the periodogram for the given period or periods
score_frequency_grid(f0, df, N) Compute the score on a frequency grid.
scores(periods) Compute the scores under the various models
best_periods()[source]

Compute the scores under the various models

Parameters:

periods : array_like

array of periods at which to compute scores
Returns:

best_periods : dict

Dictionary of best periods. Dictionary keys are the unique filter names passed to fit()
scores(periods)[source]

Compute the scores under the various models

Parameters:

periods : array_like

array of periods at which to compute scores
Returns:

scores : dict

Dictionary of scores. Dictionary keys are the unique filter names passed to fit()