# 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

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

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

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

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

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

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

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

`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.

`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 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 scores : dict Dictionary of scores. Dictionary keys are the unique filter names passed to fit()