TessLightCurve¶

class lightkurve.lightcurve.TessLightCurve(time=None, flux=None, flux_err=None, time_format=None, time_scale=None, centroid_col=None, centroid_row=None, quality=None, quality_bitmask=None, cadenceno=None, sector=None, camera=None, ccd=None, targetid=None, ra=None, dec=None, label=None, meta={})¶

Bases: lightkurve.lightcurve.LightCurve

Subclass of LightCurve which holds extra data specific to the TESS mission.

Attributes:

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’. centroid_col, centroid_row : array-like, array-like Centroid column and row coordinates as a function of time quality : array-like Array indicating the quality of each data point quality_bitmask : int Bitmask specifying quality flags of cadences that should be ignored cadenceno : array-like Cadence numbers corresponding to every time measurement targetid : int Tess Input Catalog ID number

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’.
centroid_col, centroid_row : array-like, array-like: Centroid column and row coordinates as a function of time
quality : array-like: Array indicating the quality of each data point
quality_bitmask : int: Bitmask specifying quality flags of cadences that should be ignored
cadenceno : array-like: Cadence numbers corresponding to every time measurement
targetid : int: Tess Input Catalog ID number

Attributes Summary

astropy_time Returns the time values as an Astropy Time object (if time_format is set).

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[, t0, transit_midpoint])	Folds the lightcurve at a specified `period` and reference time `t0`.
`normalize`()	Returns a normalized version of the light curve.
`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 light curve to a csv file.
`to_fits`([path, overwrite, aperture_mask])	Writes the KeplerLightCurve to a FITS file.
`to_pandas`([columns])	Converts the light curve to a Pandas `DataFrame` object.
`to_periodogram`([method])	Converts the light curve to a `Periodogram` power spectrum object.
`to_table`()	Converts the light curve to an Astropy `Table` object.

Attributes Documentation

astropy_time¶

Returns the time values as an Astropy Time object (if time_format is set).

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

Raises:	ValueError If the `time_format` attribute is not set or not one of the formats allowed by AstroPy.

Methods Documentation

append(others)¶

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')¶

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` A new light curve which has been binned.

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 light curve 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)¶: DEPRECATED: use estimate_cdpp() instead.

copy()¶

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

Plots the light curve using Matplotlib’s errorbar() method.

Parameters:

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.

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

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:

Remove low frequency signals using a Savitzky-Golay filter with window length savgol_window and polynomial order savgol_polyorder.
Remove outliers by rejecting data points which are separated from the mean by sigma times the standard deviation.
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:

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

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')¶

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:	filled_lightcurve : `LightCurve` A new light curve object in which NaN values and gaps in time have been filled.

flatten(window_length=101, polyorder=2, return_trend=False, break_tolerance=5, niters=3, sigma=3, mask=None, **kwargs)¶

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

This method wraps scipy.signal.savgol_filter.

Parameters:

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. niters : int Number of iterations to iteratively sigma clip and flatten. If more than one, will perform the flatten several times, removing outliers each time. sigma : int Number of sigma above which to remove outliers from the flatten mask : boolean array with length of self.time Boolean array to mask data with before flattening. Flux values where mask is True will not be used to flatten the data. An interpolated result will be provided for these points. Use this mask to remove data you want to preserve, e.g. transits. **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

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.
niters : int: Number of iterations to iteratively sigma clip and flatten. If more than one, will perform the flatten several times, removing outliers each time.
sigma : int: Number of sigma above which to remove outliers from the flatten
mask : boolean array with length of self.time: Boolean array to mask data with before flattening. Flux values where mask is True will not be used to flatten the data. An interpolated result will be provided for these points. Use this mask to remove data you want to preserve, e.g. transits.
**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, t0=None, transit_midpoint=None)¶

Folds the lightcurve at a specified period and reference time t0.

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

Parameters:	period : float The period upon which to fold. t0 : float, optional Time corresponding to zero phase. In the same units as the LightCurve’s `time` attribute. Defaults to 0 if not set. transit_midpoint : float, optional Deprecated. Use `t0` instead.
Returns:	folded_lightcurve : `FoldedLightCurve` A new light curve object in which the data are folded and sorted by phase. The object contains an extra `phase` attribute.

normalize()¶

Returns a normalized version of the light curve.

The normalized light curve is obtained by dividing the flux and flux_err object attributes by the by the median flux.

Returns:	normalized_lightcurve : `LightCurve` A new light curve object in which `flux` and `flux_err` are divided by the median.

plot(**kwargs)¶

Plot the light curve using Matplotlib’s plot() method.

Parameters:

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.

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()¶

Removes cadences where the flux is NaN.

Returns:	clean_lightcurve : `LightCurve` A new light curve object from which NaNs fluxes have been removed.

remove_outliers(sigma=5.0, return_mask=False, **kwargs)¶

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:

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` A new light curve object from which outlier data points have been removed.

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: A new light curve object from which outlier data points have been removed.

Examples

This example generates a new light curve 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)¶

Plots the light curve using Matplotlib’s scatter() method.

Parameters:

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.

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()¶

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

Writes the light curve 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, aperture_mask=None, **extra_data)¶

Writes the KeplerLightCurve to a FITS file.

Parameters:

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 aperture_mask : array-like Optional 2D aperture mask to save with this lightcurve object, if defined. The mask can be either a boolean mask or an integer mask mimicking the Kepler/TESS convention; boolean masks are automatically converted to the Kepler/TESS conventions 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

path : string, default None: File path, if None returns an astropy.io.fits.HDUList object.
overwrite : bool: Whether or not to overwrite the file
aperture_mask : array-like: Optional 2D aperture mask to save with this lightcurve object, if defined. The mask can be either a boolean mask or an integer mask mimicking the Kepler/TESS convention; boolean masks are automatically converted to the Kepler/TESS conventions
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'])¶

Converts the light curve to a Pandas DataFrame object.

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` A data frame indexed by `time` and containing the columns `flux` and `flux_err`.

to_periodogram(method='lombscargle', **kwargs)¶

Converts the light curve to a Periodogram power spectrum object.

This method will call either lightkurve.periodogram.LombScarglePeriodogram.from_lightcurve() or lightkurve.periodogram.BoxLeastSquaresPeriodogram.from_lightcurve(), which in turn wrap astropy.stats.LombScargle and astropy.stats.BoxLeastSquares.

Optional keywords accepted if method='lombscargle' are:: minimum_frequency, maximum_frequency, mininum_period, maximum_period, frequency, period, nterms, nyquist_factor, oversample_factor, freq_unit, normalization.
Optional keywords accepted for method='bls' are:: minimum_period, maximum_period, period, frequency_factor, duration.

Parameters:	method : {‘lombscargle’, ‘boxleastsquares’, ‘ls’, ‘bls’} Use the Lomb Scargle or Box Least Squares (BLS) method to extract the power spectrum. Defaults to `'lombscargle'`. `'ls'` and `'bls'` are shorthands for `'lombscargle'` and `'boxleastsquares'`. kwargs : dict Keyword arguments passed to either `LombScarglePeriodogram` or `BoxLeastSquaresPeriodogram`.
Returns:	Periodogram : `Periodogram` object The power spectrum object extracted from the light curve.

to_table()¶

Converts the light curve to an Astropy Table object.

Returns:	table : `astropy.table.Table` An AstroPy Table with columns ‘time’, ‘flux’, and ‘flux_err’.