LombScarglePeriodogram¶

class
lightkurve.periodogram.
LombScarglePeriodogram
(*args, **kwargs)¶ Bases:
lightkurve.periodogram.Periodogram
Subclass of
Periodogram
representing a power spectrum generated using the Lomb Scargle method.Attributes Summary
Returns the frequency corresponding to the highest peak in the periodogram.
Returns the power of the highest peak in the periodogram.
Returns the array of periods, i.e.
Returns the period corresponding to the highest peak in the periodogram.
Methods Summary
bin
(self[, binsize, method])Bins the power spectrum.
copy
(self)Returns a copy of the Periodogram object.
flatten
(self[, method, filter_width, …])Estimates the SignalToNoise (SNR) spectrum by dividing out an estimate of the noise background.
from_lightcurve
(lc[, minimum_frequency, …])Creates a Periodogram from a LightCurve using the LombScargle method.
model
(self, time[, frequency])Obtain the flux model for a given frequency and time
plot
(self[, scale, ax, xlabel, ylabel, …])Plots the Periodogram.
show_properties
(self)Prints a summary of the noncallable attributes of the Periodogram object.
smooth
(self[, method, filter_width])Smooths the power spectrum using the ‘boxkernel’ or ‘logmedian’ method.
to_seismology
(self, **kwargs)Returns a
Seismology
object to analyze the periodogram.to_table
(self)Exports the Periodogram as an Astropy Table.
Attributes Documentation

frequency_at_max_power
¶ Returns the frequency corresponding to the highest peak in the periodogram.

max_power
¶ Returns the power of the highest peak in the periodogram.

period
¶ Returns the array of periods, i.e. 1/frequency.

period_at_max_power
¶ Returns the period corresponding to the highest peak in the periodogram.
Methods Documentation

bin
(self, binsize=10, method='mean')¶ Bins the power spectrum.
 Parameters
 binsizeint
The factor by which to bin the power spectrum, in the sense that the power spectrum will be smoothed by taking the mean in bins of size N / binsize, where N is the length of the original frequency array. Defaults to 10.
 methodstr, one of ‘mean’ or ‘median’
Method to use for binning. Default is ‘mean’.
 Returns
 binned_periodograma
Periodogram
object Returns a new
Periodogram
object which has been binned.
 binned_periodograma

copy
(self)¶ Returns a copy of the Periodogram object.
This method uses the
copy.deepcopy
function to ensure that all objects stored within the Periodogram are copied. Returns
 pg_copyPeriodogram
A new
Periodogram
object which is a copy of the original.

flatten
(self, method='logmedian', filter_width=0.01, return_trend=False)¶ Estimates the SignalToNoise (SNR) spectrum by dividing out an estimate of the noise background.
This method divides the power spectrum by a background estimated using a moving filter in log10 space by default. For details on the
method
andfilter_width
parameters, seePeriodogram.smooth()
Dividing the power through by the noise background produces a spectrum with no units of power. Since the signal is divided through by a measure of the noise, we refer to this as a
SignalToNoise
spectrum. Parameters
 methodstr, one of ‘boxkernel’ or ‘logmedian’
Background estimation method passed on to
Periodogram.smooth()
. Defaults to ‘logmedian’. filter_widthfloat
If
method
= ‘boxkernel’, this is the width of the smoothing filter in units of frequency. If method =logmedian
, this is the width of the smoothing filter in log10(frequency) space. return_trendbool
If True, then the background estimate, alongside the SNR spectrum, will be returned.
 Returns
 snr_spectrum
Periodogram
object Returns a periodogram object where the power is an estimate of the signaltonoise of the spectrum, creating by dividing the powers with a simple estimate of the noise background using a smoothing filter.
 bkg
Periodogram
object The estimated power spectrum of the background noise. This is only returned if
return_trend = True
.
 snr_spectrum

static
from_lightcurve
(lc, minimum_frequency=None, maximum_frequency=None, minimum_period=None, maximum_period=None, frequency=None, period=None, nterms=1, nyquist_factor=1, oversample_factor=None, freq_unit=None, normalization='amplitude', ls_method='fast', **kwargs)¶ Creates a Periodogram from a LightCurve using the LombScargle method.
By default, the periodogram will be created for a regular grid of frequencies from one frequency separation to the Nyquist frequency, where the frequency separation is determined as 1 / the time baseline.
The min frequency and/or max frequency (or max period and/or min period) can be passed to set custom limits for the frequency grid. Alternatively, the user can provide a custom regular grid using the
frequency
parameter or a custom regular grid of periods using theperiod
parameter.The sampling of the spectrum can be changed using the
oversample_factor
parameter. An oversampled spectrum (oversample_factor > 1) is useful for displaying the full details of the spectrum, allowing the frequencies and amplitudes to be measured directly from the plot itself, with no fitting required. This is recommended for most applications, with a value of 5 or 10. On the other hand, an oversample_factor of 1 means the spectrum is critically sampled, where every point in the spectrum is independent of the others. This may be used when Lorentzians are to be fitted to modes in the power spectrum, in cases where the mode lifetimes are shorter than the timebase of the data (which is sometimes the case for solarlike oscillations). An oversample_factor of 1 is suitable for these stars because the modes are usually fully resolved. That is, the power from each mode is spread over a range of frequencies due to damping. Hence, any small error from measuring mode frequencies by taking the maximum of the peak is negligible compared with the intrinsic linewidth of the modes.The
normalization
parameter will normalize the spectrum to either power spectral density (“psd”) or amplitude (“amplitude”). Users doing asteroseismology on classical pulsators (e.g. delta Scutis) typically prefernormalization="amplitude"
because “amplitude” has higher dynamic range (high and low peaks visible simultaneously), and we often want to read off amplitudes from the plot. Ifnormalization="amplitude"
, the default value foroversample_factor
is set to 5 andfreq_unit
is 1/day. Alternatively, users doing asteroseismology on solarlike oscillators tend to prefernormalization="psd"
because power density has a scaled axis that depends on the length of the observing time, and is used when we are interested in noise levels (e.g. granulation) and are looking at damped oscillations. Ifnormalization="psd"
, the default value foroversample_factor
is set to 1 andfreq_unit
is set to microHz. Default values offreq_unit
andoversample_factor
can be overridden. See Appendix A of Kjeldsen & Bedding, 1995 for a full discussion of normalization and measurement of oscillation amplitudes (http://adsabs.harvard.edu/abs/1995A%26A…293…87K).The parameter nterms controls how many Fourier terms are used in the model. Setting the Nyquist_factor to be greater than 1 will sample the space beyond the Nyquist frequency, which may introduce aliasing.
The
freq_unit
parameter allows a request for alternative units in frequency space. By default frequency is in (1/day) and power in (amplitude). Asteroseismologists for example may want frequency in (microHz) in which case they would passfreq_unit=u.microhertz
.By default this method uses the LombScargle ‘fast’ method, which assumes a regular grid. If a regular grid of periods (i.e. an irregular grid of frequencies) it will use the ‘slow’ method. If nterms > 1 is passed, it will use the ‘fastchi2’ method for regular grids, and ‘chi2’ for irregular grids.
Caution: this method assumes that the LightCurve’s time (lc.time) is given in units of days.
 Parameters
 lcLightCurve object
The LightCurve from which to compute the Periodogram.
 minimum_frequencyfloat
If specified, use this minimum frequency rather than one over the time baseline.
 maximum_frequencyfloat
If specified, use this maximum frequency rather than nyquist_factor times the nyquist frequency.
 minimum_periodfloat
If specified, use 1./minium_period as the maximum frequency rather than nyquist_factor times the nyquist frequency.
 maximum_periodfloat
If specified, use 1./maximum_period as the minimum frequency rather than one over the time baseline.
 frequencyarraylike
The grid of frequencies to use. If given a unit, it is converted to units of freq_unit. If not, it is assumed to be in units of freq_unit. This over rides any set frequency limits.
 periodarraylike
The grid of periods to use (as 1/period). If given a unit, it is converted to units of freq_unit. If not, it is assumed to be in units of 1/freq_unit. This overrides any set period limits.
 ntermsint
Default 1. Number of terms to use in the Fourier fit.
 nyquist_factorint
Default 1. The multiple of the average Nyquist frequency. Is overriden by maximum_frequency (or minimum period).
 oversample_factorint
Default: None. The frequency spacing, determined by the time baseline of the lightcurve, is divided by this factor, oversampling the frequency space. This parameter is identical to the samples_per_peak parameter in astropy.LombScargle(). If normalization=’amplitude’, oversample_factor will be set to 5. If normalization=’psd’, it will be 1. These defaults can be overridden.
 freq_unit
astropy.units.core.CompositeUnit
Default: None. The desired frequency units for the Lomb Scargle periodogram. This implies that 1/freq_unit is the units for period. With default normalization (‘amplitude’), the freq_unit is set to 1/day, which can be overridden. ‘psd’ normalization will set freq_unit to microhertz.
 freq_unit
 normalization‘psd’ or ‘amplitude’
Default:
'amplitude'
. The desired normalization of the spectrum. Can be either power spectral density ('psd'
) or amplitude ('amplitude'
). ls_methodstr
Default:
'fast'
. Passed to themethod
keyword ofastropy.stats.LombScargle()
. kwargsdict
Keyword arguments passed to
astropy.stats.LombScargle()
 Returns
 Periodogram
Periodogram
object Returns a Periodogram object extracted from the lightcurve.
 Periodogram

model
(self, time, frequency=None)¶ Obtain the flux model for a given frequency and time
 Parameters
 timenp.ndarray
Time points to evaluate model.
 frequencyfrequency to evaluate model. Default is the frequency at
max power.
 Returns
 resultlightkurve.LightCurve
Model object with the time and flux model

plot
(self, scale='linear', ax=None, xlabel=None, ylabel=None, title='', style='lightkurve', view=None, unit=None, **kwargs)¶ Plots the Periodogram.
 Parameters
 scale: str
Set x,y axis to be “linear” or “log”. Default is linear.
 ax
Axes
A matplotlib axes object to plot into. If no axes is provided, a new one will be generated.
 xlabelstr
Plot x axis label
 ylabelstr
Plot y axis label
 titlestr
Plot set_title
 stylestr
Path or URL to a matplotlib style file, or name of one of matplotlib’s builtin stylesheets (e.g. ‘ggplot’). Lightkurve’s custom stylesheet is used by default.
 viewstr
{‘frequency’, ‘period’}. Default ‘frequency’. If ‘frequency’, xaxis units will be frequency. If ‘period’, the xaxis units will be period and ‘log’ scale.
 kwargsdict
Dictionary of arguments to be passed to
matplotlib.pyplot.plot
.
 Returns
 ax
Axes
The matplotlib axes object.
 ax

show_properties
(self)¶ Prints a summary of the noncallable attributes of the Periodogram object.
Prints in order of type (ints, strings, lists, arrays and others). Prints in alphabetical order.

smooth
(self, method='boxkernel', filter_width=0.1)¶ Smooths the power spectrum using the ‘boxkernel’ or ‘logmedian’ method.
If
method
is set to ‘boxkernel’, this method will smooth the power spectrum by convolving with a numpy Box1DKernel with a width offilter_width
, wherefilter width
is in units of frequency. This is best for filtering out noise while maintaining seismic mode peaks. This method requires the Periodogram to have an evenly spaced grid of frequencies. AValueError
exception will be raised if this is not the case.If
method
is set to ‘logmedian’, it smooths the power spectrum using a moving median which moves across the power spectrum in a steps oflog10(x0) + 0.5 * filter_width
where
filter width
is in log10(frequency) space. This is best for estimating the noise background, as it filters over the seismic peaks.Periodograms that are unsmoothed have multiplicative noise that is distributed as chi squared 2 degrees of freedom. This noise distribution has a well defined mean and median but the two are not equivalent. The mean of a chi squared 2 dof distribution is 2, but the median is 2(8/9)**3. (see https://en.wikipedia.org/wiki/Chisquared_distribution) In order to maintain consistency between ‘boxkernel’ and ‘logmedian’ a correction factor of (8/9)**3 is applied to (i.e., the median is divided by the factor) to the median values.
In addition to consistency with the ‘boxkernel’ method, the correction of the median values is useful when applying the periodogram flatten method. The flatten method divides the periodgram by the smoothed periodogram using the ‘logmedian’ method. By appyling the correction factor we follow asteroseismic convention that the signaltonoise power has a mean value of unity. (note the signaltonoise power is really the signal plus noise divided by the noise and hence should be unity in the absence of any signal)
 Parameters
 methodstr, one of ‘boxkernel’ or ‘logmedian’
The smoothing method to use. Defaults to ‘boxkernel’.
 filter_widthfloat
If
method
= ‘boxkernel’, this is the width of the smoothing filter in units of frequency. If method =logmedian
, this is the width of the smoothing filter in log10(frequency) space.
 Returns
 smoothed_pg
Periodogram
object Returns a new
Periodogram
object in which the power spectrum has been smoothed.
 smoothed_pg

to_seismology
(self, **kwargs)¶ Returns a
Seismology
object to analyze the periodogram. Returns
 seismology
Seismology
Helper object to run asteroseismology methods.
 seismology
