LombScargle¶

class
astropy.timeseries.
LombScargle
(t, y, dy=None, fit_mean=True, center_data=True, nterms=1, normalization='standard')[source]¶ Bases:
astropy.timeseries.BasePeriodogram
Compute the LombScargle Periodogram.
This implementations here are based on code presented in [1] and [2]; if you use this functionality in an academic application, citation of those works would be appreciated.
 Parameters
 tarray_like or
Quantity
[:ref: ‘time’] sequence of observation times
 yarray_like or
Quantity
sequence of observations associated with times t
 dy
float
, array_like, orQuantity
, optional error or sequence of observational errors associated with times t
 fit_meanbool, optional
if True, include a constant offset as part of the model at each frequency. This can lead to more accurate results, especially in the case of incomplete phase coverage.
 center_databool, optional
if True, precenter the data by subtracting the weighted mean of the input data. This is especially important if fit_mean = False
 nterms
int
, optional number of terms to use in the Fourier fit
 normalization{‘standard’, ‘model’, ‘log’, ‘psd’}, optional
Normalization to use for the periodogram.
 tarray_like or
References
 1
Vanderplas, J., Connolly, A. Ivezic, Z. & Gray, A. Introduction to astroML: Machine learning for astrophysics. Proceedings of the Conference on Intelligent Data Understanding (2012)
 2
VanderPlas, J. & Ivezic, Z. Periodograms for Multiband Astronomical Time Series. ApJ 812.1:18 (2015)
Examples
Generate noisy periodic data:
>>> rand = np.random.default_rng(42) >>> t = 100 * rand.random(100) >>> y = np.sin(2 * np.pi * t) + rand.standard_normal(100)
Compute the LombScargle periodogram on an automaticallydetermined frequency grid & find the frequency of max power:
>>> frequency, power = LombScargle(t, y).autopower() >>> frequency[np.argmax(power)] 1.0007641728995051
Compute the LombScargle periodogram at a userspecified frequency grid:
>>> freq = np.arange(0.8, 1.3, 0.1) >>> LombScargle(t, y).power(freq) array([0.0792948 , 0.01778874, 0.25328167, 0.01064157, 0.01471387])
If the inputs are astropy Quantities with units, the units will be validated and the outputs will also be Quantities with appropriate units:
>>> from astropy import units as u >>> t = t * u.s >>> y = y * u.mag >>> frequency, power = LombScargle(t, y).autopower() >>> frequency.unit Unit("1 / s") >>> power.unit Unit(dimensionless)
Note here that the LombScargle power is always a unitless quantity, because it is related to the \(\chi^2\) of the bestfit periodic model at each frequency.
Attributes Summary
Methods Summary
autofrequency
([samples_per_peak, …])Determine a suitable frequency grid for data.
autopower
([method, method_kwds, …])Compute LombScargle power at automaticallydetermined frequencies.
design_matrix
(frequency[, t])Compute the design matrix for a given frequency
distribution
(power[, cumulative])Expected periodogram distribution under the null hypothesis.
false_alarm_level
(false_alarm_probability[, …])Level of maximum at a given false alarm probability.
false_alarm_probability
(power[, method, …])False alarm probability of periodogram maxima under the null hypothesis.
from_timeseries
(timeseries[, …])Initialize a periodogram from a time series object.
model
(t, frequency)Compute the LombScargle model at the given frequency.
model_parameters
(frequency[, units])Compute the bestfit model parameters at the given frequency.
offset
()Return the offset of the model
power
(frequency[, normalization, method, …])Compute the LombScargle power at the given frequencies.
Attributes Documentation

available_methods
= ['auto', 'slow', 'chi2', 'cython', 'fast', 'fastchi2', 'scipy']¶
Methods Documentation

autofrequency
(samples_per_peak=5, nyquist_factor=5, minimum_frequency=None, maximum_frequency=None, return_freq_limits=False)[source]¶ Determine a suitable frequency grid for data.
Note that this assumes the peak width is driven by the observational baseline, which is generally a good assumption when the baseline is much larger than the oscillation period. If you are searching for periods longer than the baseline of your observations, this may not perform well.
Even with a large baseline, be aware that the maximum frequency returned is based on the concept of “average Nyquist frequency”, which may not be useful for irregularlysampled data. The maximum frequency can be adjusted via the nyquist_factor argument, or through the maximum_frequency argument.
 Parameters
 samples_per_peak
float
, optional The approximate number of desired samples across the typical peak
 nyquist_factor
float
, optional The multiple of the average nyquist frequency used to choose the maximum frequency if maximum_frequency is not provided.
 minimum_frequency
float
, optional If specified, then use this minimum frequency rather than one chosen based on the size of the baseline.
 maximum_frequency
float
, optional If specified, then use this maximum frequency rather than one chosen based on the average nyquist frequency.
 return_freq_limitsbool, optional
if True, return only the frequency limits rather than the full frequency grid.
 samples_per_peak
 Returns
 frequency
ndarray
orQuantity
[:ref: ‘frequency’] The heuristicallydetermined optimal frequency bin
 frequency

autopower
(method='auto', method_kwds=None, normalization=None, samples_per_peak=5, nyquist_factor=5, minimum_frequency=None, maximum_frequency=None)[source]¶ Compute LombScargle power at automaticallydetermined frequencies.
 Parameters
 method
str
, optional specify the lomb scargle implementation to use. Options are:
‘auto’: choose the best method based on the input
‘fast’: use the O[N log N] fast method. Note that this requires evenlyspaced frequencies: by default this will be checked unless
assume_regular_frequency
is set to True.‘slow’: use the O[N^2] purepython implementation
‘cython’: use the O[N^2] cython implementation. This is slightly faster than method=’slow’, but much more memory efficient.
‘chi2’: use the O[N^2] chi2/linearfitting implementation
‘fastchi2’: use the O[N log N] chi2 implementation. Note that this requires evenlyspaced frequencies: by default this will be checked unless
assume_regular_frequency
is set to True.‘scipy’: use
scipy.signal.lombscargle
, which is an O[N^2] implementation written in C. Note that this does not support heteroskedastic errors.
 method_kwds
dict
, optional additional keywords to pass to the lombscargle method
 normalization{‘standard’, ‘model’, ‘log’, ‘psd’}, optional
If specified, override the normalization specified at instantiation.
 samples_per_peak
float
, optional The approximate number of desired samples across the typical peak
 nyquist_factor
float
, optional The multiple of the average nyquist frequency used to choose the maximum frequency if maximum_frequency is not provided.
 minimum_frequency
float
orQuantity
[:ref: ‘frequency’], optional If specified, then use this minimum frequency rather than one chosen based on the size of the baseline. Should be
Quantity
if inputs to LombScargle areQuantity
. maximum_frequency
float
orQuantity
[:ref: ‘frequency’], optional If specified, then use this maximum frequency rather than one chosen based on the average nyquist frequency. Should be
Quantity
if inputs to LombScargle areQuantity
.
 method
 Returns
 frequency, power
ndarray
The frequency and LombScargle power
 frequency, power

design_matrix
(frequency, t=None)[source]¶ Compute the design matrix for a given frequency
 Parameters
 frequency
float
the frequency for the model
 tarray_like,
Quantity
, orTime
(optional) Times (length
n_samples
) at which to compute the model. If not specified, then the times and uncertainties of the input data are used.
 frequency
 Returns
 X
array
The design matrix for the model at the given frequency. This should have a shape of (
len(t)
,n_parameters
).
 X
See also

distribution
(power, cumulative=False)[source]¶ Expected periodogram distribution under the null hypothesis.
This computes the expected probability distribution or cumulative probability distribution of periodogram power, under the null hypothesis of a nonvarying signal with Gaussian noise. Note that this is not the same as the expected distribution of peak values; for that see the
false_alarm_probability()
method. Parameters
 powerarray_like
The periodogram power at which to compute the distribution.
 cumulativebool, optional
If True, then return the cumulative distribution.
 Returns
 dist
np.ndarray
The probability density or cumulative probability associated with the provided powers.
 dist
See also

false_alarm_level
(false_alarm_probability, method='baluev', samples_per_peak=5, nyquist_factor=5, minimum_frequency=None, maximum_frequency=None, method_kwds=None)[source]¶ Level of maximum at a given false alarm probability.
This gives an estimate of the periodogram level corresponding to a specified false alarm probability for the largest peak, assuming a null hypothesis of nonvarying data with Gaussian noise.
 Parameters
 false_alarm_probabilityarray_like
The false alarm probability (0 < fap < 1).
 maximum_frequency
float
The maximum frequency of the periodogram.
 method{‘baluev’, ‘davies’, ‘naive’, ‘bootstrap’}, optional
The approximation method to use; default=’baluev’.
 method_kwds
dict
, optional Additional methodspecific keywords.
 Returns
 power
np.ndarray
The periodogram peak height corresponding to the specified false alarm probability.
 power
See also
Notes
The true probability distribution for the largest peak cannot be determined analytically, so each method here provides an approximation to the value. The available methods are:
“baluev” (default): the upperlimit to the aliasfree probability, using the approach of Baluev (2008) [1].
“davies” : the Davies upper bound from Baluev (2008) [1].
“naive” : the approximate probability based on an estimated effective number of independent frequencies.
“bootstrap” : the approximate probability based on bootstrap resamplings of the input data.
Note also that for normalization=’psd’, the distribution can only be computed for periodograms constructed with errors specified.
References

false_alarm_probability
(power, method='baluev', samples_per_peak=5, nyquist_factor=5, minimum_frequency=None, maximum_frequency=None, method_kwds=None)[source]¶ False alarm probability of periodogram maxima under the null hypothesis.
This gives an estimate of the false alarm probability given the height of the largest peak in the periodogram, based on the null hypothesis of nonvarying data with Gaussian noise.
 Parameters
 powerarray_like
The periodogram value.
 method{‘baluev’, ‘davies’, ‘naive’, ‘bootstrap’}, optional
The approximation method to use.
 maximum_frequency
float
The maximum frequency of the periodogram.
 method_kwds
dict
, optional Additional methodspecific keywords.
 Returns
 false_alarm_probability
np.ndarray
The false alarm probability
 false_alarm_probability
See also
Notes
The true probability distribution for the largest peak cannot be determined analytically, so each method here provides an approximation to the value. The available methods are:
“baluev” (default): the upperlimit to the aliasfree probability, using the approach of Baluev (2008) [1].
“davies” : the Davies upper bound from Baluev (2008) [1].
“naive” : the approximate probability based on an estimated effective number of independent frequencies.
“bootstrap” : the approximate probability based on bootstrap resamplings of the input data.
Note also that for normalization=’psd’, the distribution can only be computed for periodograms constructed with errors specified.
References

classmethod
from_timeseries
(timeseries, signal_column_name=None, uncertainty=None, **kwargs)¶ Initialize a periodogram from a time series object.
If a binned time series is passed, the time at the center of the bins is used. Also note that this method automatically gets rid of NaN/undefined values when initializing the periodogram.
 Parameters
 signal_column_name
str
The name of the column containing the signal values to use.
 uncertainty
str
orfloat
orQuantity
, optional The name of the column containing the errors on the signal, or the value to use for the error, if a scalar.
 **kwargs
Additional keyword arguments are passed to the initializer for this periodogram class.
 signal_column_name

model
(t, frequency)[source]¶ Compute the LombScargle model at the given frequency.
The model at a particular frequency is a linear model: model = offset + dot(design_matrix, model_parameters)
 Parameters
 tarray_like or
Quantity
[:ref: ‘time’] Times (length
n_samples
) at which to compute the model. frequency
float
the frequency for the model
 tarray_like or
 Returns
 y
np.ndarray
The model fit corresponding to the input times (will have length
n_samples
).
 y
See also

model_parameters
(frequency, units=True)[source]¶ Compute the bestfit model parameters at the given frequency.
The model described by these parameters is:
\[y(t; f, \vec{\theta}) = \theta_0 + \sum_{n=1}^{\tt nterms} [\theta_{2n1}\sin(2\pi n f t) + \theta_{2n}\cos(2\pi n f t)]\]where \(\vec{\theta}\) is the array of parameters returned by this function.
 Parameters
 Returns
 theta
np.ndarray
(n_parameters,) The bestfit model parameters at the given frequency.
 theta
See also

offset
()[source]¶ Return the offset of the model
The offset of the model is the (weighted) mean of the y values. Note that if self.center_data is False, the offset is 0 by definition.
 Returns
 offsetscalar
See also

power
(frequency, normalization=None, method='auto', assume_regular_frequency=False, method_kwds=None)[source]¶ Compute the LombScargle power at the given frequencies.
 Parameters
 frequencyarray_like or
Quantity
[:ref: ‘frequency’] frequencies (not angular frequencies) at which to evaluate the periodogram. Note that in order to use method=’fast’, frequencies must be regularlyspaced.
 method
str
, optional specify the lomb scargle implementation to use. Options are:
‘auto’: choose the best method based on the input
‘fast’: use the O[N log N] fast method. Note that this requires evenlyspaced frequencies: by default this will be checked unless
assume_regular_frequency
is set to True.‘slow’: use the O[N^2] purepython implementation
‘cython’: use the O[N^2] cython implementation. This is slightly faster than method=’slow’, but much more memory efficient.
‘chi2’: use the O[N^2] chi2/linearfitting implementation
‘fastchi2’: use the O[N log N] chi2 implementation. Note that this requires evenlyspaced frequencies: by default this will be checked unless
assume_regular_frequency
is set to True.‘scipy’: use
scipy.signal.lombscargle
, which is an O[N^2] implementation written in C. Note that this does not support heteroskedastic errors.
 assume_regular_frequencybool, optional
if True, assume that the input frequency is of the form freq = f0 + df * np.arange(N). Only referenced if method is ‘auto’ or ‘fast’.
 normalization{‘standard’, ‘model’, ‘log’, ‘psd’}, optional
If specified, override the normalization specified at instantiation.
 fit_meanbool, optional
If True, include a constant offset as part of the model at each frequency. This can lead to more accurate results, especially in the case of incomplete phase coverage.
 center_databool, optional
If True, precenter the data by subtracting the weighted mean of the input data. This is especially important if fit_mean = False.
 method_kwds
dict
, optional additional keywords to pass to the lombscargle method
 frequencyarray_like or
 Returns
 power
ndarray
The LombScargle power at the specified frequency
 power