LightCurve objects

Understanding LightCurve objects

Learning goals

In our TargetPixelFile tutorial we learned, how to obtain data files for our objects of interest and how to examine the metadata stored in the headers.

In this tutorial we will learn the following, - How to use Lightkurve to create a TESSLightCurve object. - How to examine the object data, and understand its format. - What is simple aperture photometry (SAP). - How to plot a light curve.

What is LightCurve object?

You can create a TESSLightCurve object from a TargetPixelFile (TPF) object using Simple Aperture Photometry (SAP).

What is Simple Aperture Photometry (SAP)?

Aperture Photometry is the act of summing up the values of all the pixels in a pre-defined aperture as a function of time. By carefully choosing the shape of the aperture mask, you can avoid nearby contaminants or improve the strength of the specific signal you are trying to measure relative to the background.

The SAP light curve is a pixel summation time-series of all calibrated flux falling within the optimal aperture, as stored and defined in the TPF.

In this notebook we will demonstrate, let’s create a TESSLightCurve from a TESSTargetPixelFile.


This tutorial requires that you import Lightkurve.

%matplotlib inline
import lightkurve as lk

Defining terms

  • Target Pixel File (TPF): A file containing the original CCD pixel observations from which light curves are extracted.
  • LightCurve Object: Obtained from a TPF and contains light curve information derived using simple aperture photometry.
  • Cadence: The rate at which TESS photometric observations are stored.
  • Sector: One of TESS’s 27 (to date) observing periods, approximately ~27 days in duration.
  • Simple Aperture Photometry (SAP): The act of summing all pixel values in a pre-defined aperture as a function of time.

Downloading the TPF

For this tutorial we will use the L 98-59 System focusing on planet c.

First we search for appropriate Target Pixel Files on MAST using the search_targetpixelfile function.

search = lk.search_targetpixelfile('TIC 307210830 c')
SearchResult containing 7 data products.
0TESS Sector 2SPOC307210830tess2018234235059-s0002-0000000307210830-0121-s_tp.fits0.0
1TESS Sector 5SPOC307210830tess2018319095959-s0005-0000000307210830-0125-s_tp.fits0.0
2TESS Sector 8SPOC307210830tess2019032160000-s0008-0000000307210830-0136-s_tp.fits0.0
3TESS Sector 9SPOC307210830tess2019058134432-s0009-0000000307210830-0139-s_tp.fits0.0
4TESS Sector 10SPOC307210830tess2019085135100-s0010-0000000307210830-0140-s_tp.fits0.0
5TESS Sector 11SPOC307210830tess2019112060037-s0011-0000000307210830-0143-s_tp.fits0.0
6TESS Sector 12SPOC307210830tess2019140104343-s0012-0000000307210830-0144-s_tp.fits0.0

Our object of interest can be found in seven sectors. Let’s take the first sector, sector 2 and download that.

tpf = lk.search_targetpixelfile('TIC 307210830 c', sector=2).download()
TessTargetPixelFile(TICID: 307210830)

Creating and analizing the LightCurve object

Great we now have our TPF! Lets convert this TPF into a TessLightCurve object using the to_lightcurve function.

To create the SAP lightcurve we will pass an aperture_mask to the to_lightcurve function. The default is to use the SPOC pipeline aperture, which sums all the pixels in its defined mask.

lc = tpf.to_lightcurve(aperture_mask=tpf.pipeline_mask)
TessLightCurve targetid=307210830 length=18317
electron / selectron / spixpix

We’ve built a new TESSLightCurve object called lc. Note although we used the SPOC aperture mask you can pass your own aperture, (specified by a boolean numpy array) as seen in the Making Custom Apertures tutorial.

The above table displays all the light curve data.


TESSLightCurve objects have many useful functions that you can use. As with a TPF you can access the meta data very simply.


Of course you still have access to time and flux attributes. In a light curve, there is only one flux point for every cadence.

lc.flux, lc.time
(<Quantity [21566.35 , 21563.887, 21475.162, ..., 21250.467, 21236.355,
            21265.84 ] electron / s>,
 <Time object: scale='tdb' format='btjd' value=[1354.10882313 1354.11021199 1354.11298971 ... 1381.50982533 1381.5112142

You can also check the Combined Differential Photometric Precision (CDPP) RMS per transit duration noise metric (see Gilliland et al., 2011 for more details) of the light curve using the built in method estimate_cdpp:

300.86106  ppm

The above is the Savitzky-Golay CDPP noise metric in units parts-per-million (ppm)

Plotting the light curve

We can now use the built in plot function on the TESSLightCurve object to plot the time series. You can pass plot any keywords you would normally pass to matplotlib.pyplot.plot.

%matplotlib inline

Manipulating the light curve

There are a set of useful functions in LightCurve objects which you can use to work with the data. These include: * flatten(): Remove long term trends using a Savitzky–Golay filter * remove_outliers(): Remove outliers using simple sigma clipping * remove_nans(): Remove infinite or NaN values (these can occur during thruster firings) * fold(): Fold the data at a particular period * bin(): Reduce the time resolution of the array, taking the average value in each bin.

We can use these simply on a light curve object

flat_lc = lc.flatten(window_length=401)

Folding the light curve

From the L 98-59 System paper we know that planet c has a time corresponding to zero phase (noted as epoch_time) of 1367.2755 BTJD days and period of 3.690621 days. We can use the fold() function to find the transit in our data.

folded_lc = flat_lc.fold(period=3.690621,  epoch_time=1367.2755)

Binning data

Often to see a trend it can be beneficial to bin the data, this can be achieved via the bin() function.

binned_lc = folded_lc.bin(time_bin_size=0.025)

We can now see our transit very clearly! Note that we can achieve the same plot from our data using one line of code instead of several, see below.

lc.remove_nans().flatten(window_length=401).fold(period=3.690621,  epoch_time=1367.2755).bin(time_bin_size=0.025).plot();