LightCurve

class lightkurve.lightcurve.LightCurve(time=None, flux=None, flux_err=None, time_format=None, time_scale=None, targetid=None, label=None, meta={})[source]

Bases: object

Implements a simple class for a generic light curve.

Attributes:
time : array-like

Time measurements

flux : array-like

Data flux for every time point

flux_err : array-like

Uncertainty on each flux data point

time_format : str

String specifying how an instant of time is represented, e.g. ‘bkjd’ or ‘jd’.

time_scale : str

String which specifies how the time is measured, e.g. tdb’, ‘tt’, ‘ut1’, or ‘utc’.

targetid : str

Identifier of the target.

label : str

Human-friendly object label, e.g. “KIC 123456789”

meta : dict

Free-form metadata associated with the LightCurve.

Attributes Summary

astropy_time Returns an astropy.time.Time object.

Methods Summary

append(others) Append LightCurve objects.
bin([binsize, method]) Bins a lightcurve in blocks of size binsize.
cdpp(**kwargs) DEPRECATED: use estimate_cdpp() instead.
copy() Returns a copy of the LightCurve object.
errorbar([linestyle]) Plots the light curve using matplotlib’s errorbar method.
estimate_cdpp([transit_duration, …]) Estimate the CDPP noise metric using the Savitzky-Golay (SG) method.
fill_gaps([method]) Fill in gaps in time with linear interpolation.
flatten([window_length, polyorder, …]) Removes the low frequency trend using scipy’s Savitzky-Golay filter.
fold(period[, transit_midpoint]) Folds the lightcurve at a specified period and transit_midpoint.
normalize() Returns a normalized version of the lightcurve.
plot(**kwargs) Plot the light curve using matplotlib’s plot method.
remove_nans() Removes cadences where the flux is NaN.
remove_outliers([sigma, return_mask]) Removes outlier data points using sigma-clipping.
scatter([colorbar_label, show_colorbar]) Plots the light curve using matplotlib’s scatter method.
show_properties() Prints a description of all non-callable attributes.
to_csv([path_or_buf]) Writes the LightCurve to a csv file.
to_fits([path, overwrite]) Writes the LightCurve to a FITS file.
to_pandas([columns]) Export the LightCurve as a Pandas DataFrame.
to_periodogram([nterms, nyquist_factor, …]) Returns a Periodogram power spectrum object.
to_table() Export the LightCurve as an AstroPy Table.

Attributes Documentation

astropy_time

Returns an astropy.time.Time object.

The Time object will be created using the values in self.time and the self.time_format and self.time_scale attributes. For Kepler data products, the times are Barycentric.

Raises:
ValueError

If self.time_format is not set or not one of the formats allowed by AstroPy.

Methods Documentation

append(others)[source]

Append LightCurve objects.

Parameters:
others : LightCurve object or list of LightCurve objects

Light curves to be appended to the current one.

Returns:
new_lc : LightCurve object

Concatenated light curve.

bin(binsize=13, method='mean')[source]

Bins a lightcurve in blocks of size binsize.

The value of the bins will contain the mean (method=’mean’) or the median (method=’median’) of the original data. The default is mean.

Parameters:
binsize : int

Number of cadences to include in every bin.

method: str, one of ‘mean’ or ‘median’

The summary statistic to return for each bin. Default: ‘mean’.

Returns:
binned_lc : LightCurve object

Binned lightcurve.

Notes

  • If the ratio between the lightcurve length and the binsize is not a whole number, then the remainder of the data points will be ignored.
  • If the original lightcurve contains flux uncertainties (flux_err), the binned lightcurve will report the root-mean-square error. If no uncertainties are included, the binned curve will return the standard deviation of the data.
  • If the original lightcurve contains a quality attribute, then the bitwise OR of the quality flags will be returned per bin.
cdpp(**kwargs)[source]

DEPRECATED: use estimate_cdpp() instead.

copy()[source]

Returns a copy of the LightCurve object.

This method uses the copy.deepcopy function to ensure that all objects stored within the LightCurve are copied (e.g. time and flux).

Returns:
lc_copy : LightCurve

A new LightCurve object which is a copy of the original.

errorbar(linestyle='', **kwargs)[source]

Plots the light curve using matplotlib’s errorbar method.

Parameters:
ax : matplotlib.axes._subplots.AxesSubplot

A matplotlib axes object to plot into. If no axes is provided, a new one will be generated.

normalize : bool

Normalize the lightcurve before plotting?

xlabel : str

Plot x axis label

ylabel : str

Plot y axis label

title : str

Plot set_title

style : str

Path or URL to a matplotlib style file, or name of one of matplotlib’s built-in stylesheets (e.g. ‘ggplot’). Lightkurve’s custom stylesheet is used by default.

linestyle : str

Connect the error bars using a line?

kwargs : dict

Dictionary of arguments to be passed to matplotlib.pyplot.scatter.

Returns:
ax : matplotlib.axes._subplots.AxesSubplot

The matplotlib axes object.

estimate_cdpp(transit_duration=13, savgol_window=101, savgol_polyorder=2, sigma=5.0)[source]

Estimate the CDPP noise metric using the Savitzky-Golay (SG) method.

A common estimate of the noise in a lightcurve is the scatter that remains after all long term trends have been removed. This is the idea behind the Combined Differential Photometric Precision (CDPP) metric. The official Kepler Pipeline computes this metric using a wavelet-based algorithm to calculate the signal-to-noise of the specific waveform of transits of various durations. In this implementation, we use the simpler “sgCDPP proxy algorithm” discussed by Gilliland et al (2011ApJS..197….6G) and Van Cleve et al (2016PASP..128g5002V).

The steps of this algorithm are:
  1. Remove low frequency signals using a Savitzky-Golay filter with window length savgol_window and polynomial order savgol_polyorder.
  2. Remove outliers by rejecting data points which are separated from the mean by sigma times the standard deviation.
  3. Compute the standard deviation of a running mean with a configurable window length equal to transit_duration.

We use a running mean (as opposed to block averaging) to strongly attenuate the signal above 1/transit_duration whilst retaining the original frequency sampling. Block averaging would set the Nyquist limit to 1/transit_duration.

Parameters:
transit_duration : int, optional

The transit duration in units of number of cadences. This is the length of the window used to compute the running mean. The default is 13, which corresponds to a 6.5 hour transit in data sampled at 30-min cadence.

savgol_window : int, optional

Width of Savitsky-Golay filter in cadences (odd number). Default value 101 (2.0 days in Kepler Long Cadence mode).

savgol_polyorder : int, optional

Polynomial order of the Savitsky-Golay filter. The recommended value is 2.

sigma : float, optional

The number of standard deviations to use for clipping outliers. The default is 5.

Returns:
cdpp : float

Savitzky-Golay CDPP noise metric in units parts-per-million (ppm).

Notes

This implementation is adapted from the Matlab version used by Jeff van Cleve but lacks the normalization factor used there: svn+ssh://murzim/repo/so/trunk/Develop/jvc/common/compute_SG_noise.m

fill_gaps(method='nearest')[source]

Fill in gaps in time with linear interpolation.

Parameters:
method : string {None, ‘backfill’/’bfill’, ‘pad’/’ffill’, ‘nearest’}

Method to use for gap filling. ‘nearest’ by default.

Returns:
nlc : LightCurve object

A new LightCurve in which NaNs values and gaps in time have been filled.

flatten(window_length=101, polyorder=2, return_trend=False, break_tolerance=5, **kwargs)[source]

Removes the low frequency trend using scipy’s Savitzky-Golay filter.

This method wraps scipy.signal.savgol_filter.

Parameters:
window_length : int

The length of the filter window (i.e. the number of coefficients). window_length must be a positive odd integer.

polyorder : int

The order of the polynomial used to fit the samples. polyorder must be less than window_length.

return_trend : bool

If True, the method will return a tuple of two elements (flattened_lc, trend_lc) where trend_lc is the removed trend.

break_tolerance : int

If there are large gaps in time, flatten will split the flux into several sub-lightcurves and apply savgol_filter to each individually. A gap is defined as a period in time larger than break_tolerance times the median gap. To disable this feature, set break_tolerance to None.

**kwargs : dict

Dictionary of arguments to be passed to scipy.signal.savgol_filter.

Returns:
flatten_lc : LightCurve object

Flattened lightcurve.

If `return_trend` is `True`, the method will also return:
trend_lc : LightCurve object

Trend in the lightcurve data

fold(period, transit_midpoint=0.0)[source]

Folds the lightcurve at a specified period and transit_midpoint.

This method returns a new LightCurve object in which the time values range between -0.5 to +0.5 (i.e. the phase). Data points which occur exactly at transit_midpoint or an integer multiple of transit_midpoint + n*period will have time value 0.0.

Parameters:
period : float

The period upon which to fold.

transit_midpoint : float, optional

Time reference point in the same units as the LightCurve’s time attribute.

Returns:
folded_lightcurve : LightCurve object

A new LightCurve in which the data are folded and sorted by phase.

normalize()[source]

Returns a normalized version of the lightcurve.

The normalized lightcurve is obtained by dividing flux and flux_err by the median flux.

Returns:
normalized_lightcurve : LightCurve object

A new LightCurve in which flux and flux_err are divided by the median.

plot(**kwargs)[source]

Plot the light curve using matplotlib’s plot method.

Parameters:
ax : matplotlib.axes._subplots.AxesSubplot

A matplotlib axes object to plot into. If no axes is provided, a new one will be generated.

normalize : bool

Normalize the lightcurve before plotting?

xlabel : str

Plot x axis label

ylabel : str

Plot y axis label

title : str

Plot set_title

style : str

Path or URL to a matplotlib style file, or name of one of matplotlib’s built-in stylesheets (e.g. ‘ggplot’). Lightkurve’s custom stylesheet is used by default.

kwargs : dict

Dictionary of arguments to be passed to matplotlib.pyplot.plot.

Returns:
ax : matplotlib.axes._subplots.AxesSubplot

The matplotlib axes object.

remove_nans()[source]

Removes cadences where the flux is NaN.

Returns:
clean_lightcurve : LightCurve object

A new LightCurve from which NaNs fluxes have been removed.

remove_outliers(sigma=5.0, return_mask=False, **kwargs)[source]

Removes outlier data points using sigma-clipping.

This method returns a new LightCurve object from which data points are removed if their flux values are greater or smaller than the median flux by at least sigma times the standard deviation.

Sigma-clipping works by iterating over data points, each time rejecting values that are discrepant by more than a specified number of standard deviations from a center value. If the data contains invalid values (NaNs or infs), they are automatically masked before performing the sigma clipping.

Note

This function is a convenience wrapper around astropy.stats.sigma_clip and provides the same functionality.

Parameters:
sigma : float

The number of standard deviations to use for both the lower and upper clipping limit. These limits are overridden by sigma_lower and sigma_upper, if input. Defaults to 5.

sigma_lower : float or None

The number of standard deviations to use as the lower bound for the clipping limit. Can be set to float(‘inf’) in order to avoid clipping outliers below the median at all. If None then the value of sigma is used. Defaults to None.

sigma_upper : float or None

The number of standard deviations to use as the upper bound for the clipping limit. Can be set to float(‘inf’) in order to avoid clipping outliers above the median at all. If None then the value of sigma is used. Defaults to None.

return_mask : bool

Whether or not to return a mask (i.e. a boolean array) indicating which data points were removed. Entries marked as True in the mask are considered outliers. Defaults to True.

iters : int or None

The number of iterations to perform sigma clipping, or None to clip until convergence is achieved (i.e., continue until the last iteration clips nothing). Defaults to 5.

cenfunc : callable

The function used to compute the center for the clipping. Must be a callable that takes in a masked array and outputs the central value. Defaults to the median (numpy.ma.median).

**kwargs : dict

Dictionary of arguments to be passed to astropy.stats.sigma_clip.

Returns:
clean_lc : LightCurve object

A new LightCurve from which outlier data points have been removed.

Examples

This example generates a new LightCurve in which all points that are more than 1 standard deviation from the median are removed:

>>> lc = LightCurve(time=[1, 2, 3, 4, 5], flux=[1, 1000, 1, -1000, 1])
>>> lc_clean = lc.remove_outliers(sigma=1)
>>> lc_clean.time
array([1, 3, 5])
>>> lc_clean.flux
array([1, 1, 1])

This example removes only points where the flux is larger than 1 standard deviation from the median, but leaves negative outliers in place:

>>> lc = LightCurve(time=[1, 2, 3, 4, 5], flux=[1, 1000, 1, -1000, 1])
>>> lc_clean = lc.remove_outliers(sigma_lower=float('inf'), sigma_upper=1)
>>> lc_clean.time
array([1, 3, 4, 5])
>>> lc_clean.flux
array([    1,     1, -1000,     1])
scatter(colorbar_label='', show_colorbar=True, **kwargs)[source]

Plots the light curve using matplotlib’s scatter method.

Parameters:
ax : matplotlib.axes._subplots.AxesSubplot

A matplotlib axes object to plot into. If no axes is provided, a new one will be generated.

normalize : bool

Normalize the lightcurve before plotting?

xlabel : str

Plot x axis label

ylabel : str

Plot y axis label

title : str

Plot set_title

style : str

Path or URL to a matplotlib style file, or name of one of matplotlib’s built-in stylesheets (e.g. ‘ggplot’). Lightkurve’s custom stylesheet is used by default.

colorbar_label : str

Label to show next to the colorbar (if c is given).

show_colorbar : boolean

Show the colorbar if colors are given using the c argument?

kwargs : dict

Dictionary of arguments to be passed to matplotlib.pyplot.scatter.

Returns:
ax : matplotlib.axes._subplots.AxesSubplot

The matplotlib axes object.

show_properties()[source]

Prints a description of all non-callable attributes.

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

to_csv(path_or_buf=None, **kwargs)[source]

Writes the LightCurve to a csv file.

Parameters:
path_or_buf : string or file handle, default None

File path or object, if None is provided the result is returned as a string.

**kwargs : dict

Dictionary of arguments to be passed to pandas.DataFrame.to_csv().

Returns:
csv : str or None

Returns a csv-formatted string if path_or_buf=None, returns None otherwise.

to_fits(path=None, overwrite=False, **extra_data)[source]

Writes the LightCurve to a FITS file.

Parameters:
path : string, default None

File path, if None returns an astropy.io.fits.HDUList object.

overwrite : bool

Whether or not to overwrite the file

extra_data : dict

Extra keywords or columns to include in the FITS file. Arguments of type str, int, float, or bool will be stored as keywords in the primary header. Arguments of type np.array or list will be stored as columns in the first extension.

Returns:
hdu : astropy.io.fits

Returns an astropy.io.fits object if path is None

to_pandas(columns=['time', 'flux', 'flux_err'])[source]

Export the LightCurve as a Pandas DataFrame.

Parameters:
columns : list of str

List of columns to include in the DataFrame. The names must match attributes of the LightCurve object (e.g. time, flux).

Returns:
dataframe : pandas.DataFrame object

A dataframe indexed by time and containing the columns flux and flux_err.

to_periodogram(nterms=1, nyquist_factor=1, oversample_factor=1, min_frequency=None, max_frequency=None, min_period=None, max_period=None, frequency=None, period=None, freq_unit=<Quantity 1. 1 / d>, **kwargs)[source]

Returns a Periodogram power spectrum object.

Parameters:
min_frequency : float

If specified, use this minimum frequency rather than one over the time baseline.

max_frequency : float

If specified, use this maximum frequency rather than nyquist_factor times the nyquist frequency.

min_period : float

If specified, use 1./minium_period as the maximum frequency rather than nyquist_factor times the nyquist frequency.

max_period : float

If specified, use 1./maximum_period as the minimum frequency rather than one over the time baseline.

frequency : array-like

The regular 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.

period : array-like

The regular 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.

nterms : int

Default 1. Number of terms to use in the Fourier fit.

nyquist_factor : int

Default 1. The multiple of the average Nyquist frequency. Is overriden by maximum_frequency (or minimum period).

oversample_factor : int

The frequency spacing, determined by the time baseline of the lightcurve, is divided by this factor, oversampling frequency space. This parameter is identical to the samples_per_peak parameter in astropy.LombScargle()

freq_unit : astropy.units.core.CompositeUnit

Default: 1/u.day. The desired frequency units for the Lomb Scargle periodogram. This implies that 1/freq_unit is the units for period.

kwargs : dict

Keyword arguments passed to astropy.stats.LombScargle()

Returns:
Periodogram : Periodogram object

Returns a Periodogram object extracted from the lightcurve.

to_table()[source]

Export the LightCurve as an AstroPy Table.

Returns:
table : astropy.table.Table object

An AstroPy Table with columns ‘time’, ‘flux’, and ‘flux_err’.