BoxLeastSquaresPeriodogram¶

class lightkurve.periodogram.BoxLeastSquaresPeriodogram(*args, **kwargs)

Subclass of Periodogram representing a power spectrum generated using the Box Least Squares (BLS) method.

Attributes Summary

 depth_at_max_power Returns the depth corresponding to the highest peak in the periodogram. duration_at_max_power Returns the duration corresponding to the highest peak in the periodogram. 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. period_at_max_power Returns the period corresponding to the highest peak in the periodogram. transit_time_at_max_power Returns the transit time corresponding to the highest peak in the periodogram.

Methods Summary

 bin(self[, binsize, method]) Bins the power spectrum. compute_stats(self[, period, duration, …]) Computes commonly used vetting statistics for a transit model. copy(self) Returns a copy of the Periodogram object. flatten(self, **kwargs) Estimates the Signal-To-Noise (SNR) spectrum by dividing out an estimate of the noise background. from_lightcurve(lc, **kwargs) Creates a Periodogram from a LightCurve using the Box Least Squares (BLS) method. get_transit_mask(self[, period, duration, …]) Computes the transit mask using the BLS, returns a lightkurve.LightCurve get_transit_model(self[, period, duration, …]) Computes the transit model using the BLS, returns a lightkurve.LightCurve plot(self, **kwargs) Plot the BoxLeastSquaresPeriodogram spectrum using matplotlib’s plot method. Prints a summary of the non-callable attributes of the Periodogram object. smooth(self, **kwargs) 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

depth_at_max_power

Returns the depth corresponding to the highest peak in the periodogram.

duration_at_max_power

Returns the duration corresponding to the highest peak in the periodogram.

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.

transit_time_at_max_power

Returns the transit time 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.

compute_stats(self, period=None, duration=None, transit_time=None)

Computes commonly used vetting statistics for a transit model.

See astropy.stats.bls docs for further details.

Parameters
periodfloat or Quantity

Period of the transits. Default is period_at_max_power

durationfloat or Quantity

Duration of the transits. Default is duration_at_max_power

transit_timefloat or Quantity

Transit midpoint of the transits. Default is transit_time_at_max_power

Returns
statsdict

Dictionary of vetting statistics

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, **kwargs)

Estimates the Signal-To-Noise (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 and filter_width parameters, see Periodogram.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 Signal-To-Noise 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_spectrumPeriodogram object

Returns a periodogram object where the power is an estimate of the signal-to-noise of the spectrum, creating by dividing the powers with a simple estimate of the noise background using a smoothing filter.

bkgPeriodogram object

The estimated power spectrum of the background noise. This is only returned if return_trend = True.

static from_lightcurve(lc, **kwargs)

Creates a Periodogram from a LightCurve using the Box Least Squares (BLS) method.

get_transit_mask(self, period=None, duration=None, transit_time=None)

Computes the transit mask using the BLS, returns a lightkurve.LightCurve

True where there are no transits.

Parameters
periodfloat or Quantity

Period of the transits. Default is period_at_max_power

durationfloat or Quantity

Duration of the transits. Default is duration_at_max_power

transit_timefloat or Quantity

Transit midpoint of the transits. Default is transit_time_at_max_power

Returns

Mask that removes transits. Mask is True where there are no transits.

get_transit_model(self, period=None, duration=None, transit_time=None)

Computes the transit model using the BLS, returns a lightkurve.LightCurve

See astropy.stats.bls docs for further details.

Parameters
periodfloat or Quantity

Period of the transits. Default is period_at_max_power

durationfloat or Quantity

Duration of the transits. Default is duration_at_max_power

transit_timefloat or Quantity

Transit midpoint of the transits. Default is transit_time_at_max_power

Returns
modellightkurve.LightCurve

Model of transit

plot(self, **kwargs)

Plot the BoxLeastSquaresPeriodogram spectrum using matplotlib’s plot method. See Periodogram.plot for details on the accepted arguments.

Parameters
kwargsdict

Dictionary of arguments ot be passed to Periodogram.plot.

Returns
axAxes

The matplotlib axes object.

show_properties(self)

Prints a summary of the non-callable attributes of the Periodogram object.

Prints in order of type (ints, strings, lists, arrays and others). Prints in alphabetical order.

smooth(self, **kwargs)

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 of filter_width, where filter 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. A ValueError 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 of

log10(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/Chi-squared_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 signal-to-noise power has a mean value of unity. (note the signal-to-noise 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_pgPeriodogram object

Returns a new Periodogram object in which the power spectrum has been smoothed.

to_seismology(self, **kwargs)

Returns a Seismology object to analyze the periodogram.

Returns
seismologySeismology

Helper object to run asteroseismology methods.

to_table(self)

Exports the Periodogram as an Astropy Table.

Returns
tableTable object

An AstroPy Table with columns ‘frequency’, ‘period’, and ‘power’.