Ctrl+K

Searching for Kepler/K2 and TESS Data Products Using Lightkurve

Searching for Kepler/K2 and TESS Data Products Using Lightkurve#

Learning Goals#

By the end of this tutorial, you will:

  • Understand the data products available to query and download.

  • Be able to use Lightkurve to search for Kepler/K2 and TESS data products.

  • Know how to download TESS Full Frame Image cutouts.

  • Be able to perform a cone search.

Introduction#

The Lightkurve Python package has functions to search for and download observations from Kepler/K2 and TESS. These tools are built to make accessing space telescope data clear and straightforward, with intuitive method and keyword names.

This tutorial outlines what data products are available to query with Lightkurve, and gives examples of how to use the functions to search for and download space telescope observations.

Imports#

This tutorial requires the Lightkurve package, which uses Matplotlib for plotting.

import lightkurve as lk
import matplotlib.pyplot as plt
%matplotlib inline

1. What Data Products are Available?#

Kepler/K2 and TESS data products are stored on the Mikulski Archive for Space Telescopes (MAST) in two main forms:

  • Light curve products: tables containing the measured flux at each observation time.

  • Target pixel file products: stacks of images with the pixel-level observation at each observation time.

There are also the following additional products available to query and download using Lightkurve:

  • High Level Science Products (HLSPs): a specific version of a data product produced by an analysis or photometry pipeline. Lightkurve has access to HLSP light curves produced by the photometry pipelines EVEREST, K2SFF, and K2SC. For more information about HLSPs, please see this article on the Space Telescope Science Institute’s archive.

  • Full Frame Images (FFIs): a download of all active detector pixels at once. TESS FFIs are captured with 30-minute cadence, and custom cutouts of TESS FFIs can be queried and downloaded using Lightkurve.

Lightkurve allows you to query and download each of these data products. The following sections contain examples of how to use the search functions in Lightkurve.

2. Searching for Light Curves#

Lightkurve uses Astroquery to search for data products. Astroquery allows searches based on a target’s coordinates, catalog ID number, or name.

This is passed into the search function using the target keyword, and all valid inputs for identifying a target include:

  • The name of the object as a string, for example, “Kepler-10.”

  • The KIC or EPIC identifier as an integer, for example, “11904151.”

  • A coordinate string in decimal format, for example, “285.67942179 +50.24130576.”

  • A coordinate string in sexagesimal format, for example, “19:02:43.1 +50:14:28.7.”

  • An astropy.coordinates.SkyCoord object.

You can also specify which mission you would like to retrieve data from using the mission keyword, which takes “Kepler,” “K2,” or “TESS.” By default, all available missions will be returned.

We will start with the case of searching for a Kepler target using its Kepler Input Catalog (KIC) ID number. Below, we search for KIC 3733346, an RR Lyrae star, using the search_lightcurve function.

search_result = lk.search_lightcurve('KIC 3733346', mission='Kepler')
search_result
SearchResult containing 18 data products.
#missionyearauthorexptimetarget_namedistance
sarcsec
0Kepler Quarter 012009Kepler1800kplr0037333460.0
1Kepler Quarter 022009Kepler1800kplr0037333460.0
2Kepler Quarter 032009Kepler1800kplr0037333460.0
3Kepler Quarter 042010Kepler1800kplr0037333460.0
4Kepler Quarter 052010Kepler1800kplr0037333460.0
5Kepler Quarter 062010Kepler1800kplr0037333460.0
6Kepler Quarter 072010Kepler1800kplr0037333460.0
7Kepler Quarter 112011Kepler60kplr0037333460.0
8Kepler Quarter 102011Kepler1800kplr0037333460.0
9Kepler Quarter 092011Kepler1800kplr0037333460.0
10Kepler Quarter 082011Kepler1800kplr0037333460.0
11Kepler Quarter 112012Kepler1800kplr0037333460.0
12Kepler Quarter 122012Kepler1800kplr0037333460.0
13Kepler Quarter 132012Kepler1800kplr0037333460.0
14Kepler Quarter 142012Kepler1800kplr0037333460.0
15Kepler Quarter 152013Kepler1800kplr0037333460.0
16Kepler Quarter 162013Kepler1800kplr0037333460.0
17Kepler Quarter 172013Kepler1800kplr0037333460.0

search_lightcurve returns a SearchResult table, which contains information about the data products available to download. This search result tells us that KIC 3733346 was observed in Kepler Quarters 1–16.

You can select an individual entry in this search result by indexing the search result.

search_result[0]
SearchResult containing 1 data products.
#missionyearauthorexptimetarget_namedistance
sarcsec
0Kepler Quarter 012009Kepler1800kplr0037333460.0

For more information about the available data products, the SearchResult has a full table accessible by calling .table. This full table contains the columns listed below. Definitions of each of these terms can be found here.

for column in search_result.table.columns:
  print(column)

intentType
obs_collection
provenance_name
instrument_name
project
filters
wavelength_region
target_name
target_classification
obs_id
s_ra
s_dec
dataproduct_type
proposal_pi
calib_level
t_min
t_max
t_exptime
em_min
em_max
obs_title
t_obs_release
proposal_id
proposal_type
sequence_number
s_region
jpegURL
dataURL
dataRights
mtFlag
srcDen
obsid
objID
exptime
distance
obsID
obs_collection_products
dataproduct_type_products
description
type
dataURI
productType
productGroupDescription
productSubGroupDescription
productDocumentationURL
project_products
prvversion
proposal_id_products
productFilename
size
parent_obsid
dataRights_products
calib_level_products
author
mission
#
year
sort_order

These column names can also be used to search for specific entries in the table.

# import numpy, which we will use to find the desired index in the table
import numpy as np
quarter2_index = np.where(search_result.table['mission'] == 'Kepler Quarter 02')[0]
search_result[quarter2_index]
SearchResult containing 1 data products.
#missionyearauthorexptimetarget_namedistance
sarcsec
0Kepler Quarter 022009Kepler1800kplr0037333460.0

You can also narrow down the list of observations when you make the search using the following mission-specific keywords:

  • Kepler: quarter

  • K2: campaign

  • TESS: sector

Let’s perform the search for KIC 3733346 again, this time specifying that we only want data from Kepler Quarter 2.

search_result_q2 = lk.search_lightcurve('KIC 3733346', mission='Kepler', quarter=2)
search_result_q2
SearchResult containing 1 data products.
#missionyearauthorexptimetarget_namedistance
sarcsec
0Kepler Quarter 022009Kepler1800kplr0037333460.0

2.1 Downloading a single light curve#

A light curve can be downloaded by calling .download().

lc = search_result_q2.download()
lc
KeplerLightCurve length=4075 LABEL="KIC 3733346" QUARTER=2 AUTHOR=Kepler FLUX_ORIGIN=pdcsap_flux
timefluxflux_errqualitytimecorrcentroid_colcentroid_rowcadencenosap_fluxsap_flux_errsap_bkgsap_bkg_errpdcsap_fluxpdcsap_flux_errsap_qualitypsf_centr1psf_centr1_errpsf_centr2psf_centr2_errmom_centr1mom_centr1_errmom_centr2mom_centr2_errpos_corr1pos_corr2
electron / selectron / sdpixpixelectron / selectron / selectron / selectron / selectron / selectron / spixpixpixpixpixpixpixpixpixpix
Timefloat32float32int32float32float64float64int32float32float32float32float32float32float32int32float64float32float64float32float64float32float64float32float32float32
169.76594184216819.2319516e+049.2697735e+0003.263322e-03781.81123786.7305129778.9092305e+048.8779488e+002.0773477e+037.0835429e-019.2319516e+049.2697735e+000————————————781.811231.2057812e-04786.730511.4581889e-041.0092091e-01-1.9298431e-01
169.78637605579578.9214008e+049.1563263e+0003.263836e-03781.80745786.7300529788.6126133e+048.7672691e+002.0793108e+037.0831001e-018.9214008e+049.1563263e+000————————————781.807451.2411721e-04786.730051.5003627e-041.0036582e-01-1.9279599e-01
169.806810069188948.5608195e+049.0206089e+0003.264349e-03781.80376786.7291829798.2681344e+048.6362791e+002.0772085e+037.0797533e-018.5608195e+049.0206089e+000————————————781.803761.2850568e-04786.729181.5526263e-041.0042009e-01-1.9289577e-01
169.82724428234368.3063625e+048.9255180e+0003.264862e-03781.80081786.7291329808.0246992e+048.5434341e+002.0767546e+037.0811391e-018.3063625e+048.9255180e+000————————————781.800811.3182692e-04786.729131.5920549e-041.0021163e-01-1.9266903e-01
169.847678295271188.4244992e+048.9700022e+0003.265375e-03781.80242786.7290529818.1373969e+048.5879698e+002.0805510e+037.0775980e-018.4244992e+048.9700022e+000————————————781.802421.3028238e-04786.729051.5737538e-041.0010726e-01-1.9241102e-01
169.868112507734629.7360805e+049.4567146e+0003.265888e-03781.81441786.7321029829.3887734e+049.0560179e+002.0782170e+037.0836788e-019.7360805e+049.4567146e+000————————————781.814411.1529749e-04786.732101.3958653e-049.8970458e-02-1.9224431e-01
169.888546519956441.2825345e+051.0503614e+0103.266400e-03781.83651786.7350029831.2337022e+051.0063412e+012.0774846e+037.0743954e-011.2825345e+051.0503614e+010————————————781.836519.1639682e-05786.735001.1152634e-049.9608414e-02-1.9224758e-01
169.908980631953451.5187158e+051.1233888e+0103.266912e-03781.84701786.7360629841.4590969e+051.0766508e+012.0792261e+037.0833290e-011.5187158e+051.1233888e+010————————————781.847017.9801415e-05786.736069.7487238e-059.8825477e-02-1.9200189e-01
169.92941484371841.6871948e+051.1725034e+0103.267424e-03781.85356786.7361529851.6198620e+051.1240104e+012.0780894e+037.0873052e-011.6871948e+051.1725034e+010————————————781.853567.3274212e-05786.736158.9778732e-059.9280514e-02-1.9207963e-01
...........................................................................
258.26318288111369.4131328e+049.3219748e+0002.598361e-03781.66350787.0677473088.9727844e+048.9079256e+002.1440417e+037.0889163e-019.4131328e+049.3219748e+000————————————781.663501.2083405e-04787.067741.4286327e-04-5.0929710e-021.4663801e-01
258.283615696942439.2878820e+049.2731094e+0002.597577e-03781.66157787.0674073098.8527227e+048.8611145e+002.1467869e+037.0827138e-019.2878820e+049.2731094e+000————————————781.661571.2219569e-04787.067401.4442031e-04-5.1394299e-021.4658417e-01
258.30404841276329.2034094e+049.2417078e+0011000000000000000002.596793e-03781.65987787.0677273108.7705906e+048.8319845e+002.1418911e+037.0921260e-019.2034094e+049.2417078e+001100000000000000000————————————781.659871.2317530e-04787.067721.4557109e-04-5.2788489e-021.4718631e-01
258.324481328127159.1409266e+049.2205820e+0002.596008e-03781.66046787.0677473118.7112359e+048.8111296e+002.1419580e+037.0941931e-019.1409266e+049.2205820e+000————————————781.660461.2387938e-04787.067741.4640002e-04-5.1082097e-021.4737232e-01
258.344914143483049.0934453e+049.2037315e+0002.595223e-03781.66006787.0673373128.6663805e+048.7947636e+002.1399746e+037.0873111e-019.0934453e+049.2037315e+000————————————781.660061.2442317e-04787.067331.4701700e-04-5.1297914e-021.4743482e-01
258.36534685837989.0627711e+049.1926651e+0002.594438e-03781.65842787.0674873138.6410219e+048.7850523e+002.1412927e+037.0846963e-019.0627711e+049.1926651e+000————————————781.658421.2473276e-04787.067481.4736662e-04-5.3477854e-021.4825350e-01
258.40621258794279.2799812e+049.2735319e+0002.592868e-03781.66311787.0660273158.8482406e+048.8615150e+002.1397761e+037.0821041e-019.2799812e+049.2735319e+000————————————781.663111.2222759e-04787.066021.4448226e-04-5.0823554e-021.4643176e-01
258.42664530213379.2305727e+049.2546864e+0002.592082e-03781.66219787.0656873168.8041828e+048.8437214e+002.1407056e+037.0872313e-019.2305727e+049.2546864e+000————————————781.662191.2274201e-04787.065681.4511198e-04-5.2071981e-021.4703403e-01
258.44707811633278.9541500e+049.1516228e+0002.591296e-03781.65845787.0656273178.5375305e+048.7458200e+002.1410559e+037.0890176e-018.9541500e+049.1516228e+000————————————781.658451.2598942e-04787.065621.4883128e-04-5.3206120e-021.4745203e-01
258.467511030292378.5948555e+049.0121727e+0002.590510e-03781.65486787.0646573188.1906250e+048.6120892e+002.1406807e+037.0841718e-018.5948555e+049.0121727e+000————————————781.654861.3045572e-04787.064651.5403067e-04-5.2536737e-021.4800853e-01

This returns a single KeplerLightCurve object, which is shown above in the form of an astropy table. We can examine the light curve using the plot method.

lc.plot();
../../../_images/fabb360a6676d126ce89ef1591b12c6f2dd78c3a6896f84f5bb152b3086da28c.png

2.2 Downloading a collection of light curves#

The SearchResult object also has a download_all method, allowing you to download multiple light curves. This returns a LightCurveCollection, a convenient container for LightCurve objects.

lc_collection = search_result[:5].download_all()
lc_collection

LightCurveCollection of 5 objects:
    0: <KeplerLightCurve LABEL="KIC 3733346" QUARTER=1 AUTHOR=Kepler FLUX_ORIGIN=pdcsap_flux>
    1: <KeplerLightCurve LABEL="KIC 3733346" QUARTER=2 AUTHOR=Kepler FLUX_ORIGIN=pdcsap_flux>
    2: <KeplerLightCurve LABEL="KIC 3733346" QUARTER=3 AUTHOR=Kepler FLUX_ORIGIN=pdcsap_flux>
    3: <KeplerLightCurve LABEL="KIC 3733346" QUARTER=4 AUTHOR=Kepler FLUX_ORIGIN=pdcsap_flux>
    4: <KeplerLightCurve LABEL="KIC 3733346" QUARTER=5 AUTHOR=Kepler FLUX_ORIGIN=pdcsap_flux>

The LightCurveCollection has a number of useful functions for plotting and manipulating the light curves. For more information about how to combine multiple light curves, please see the tutorial on combining multiple quarters of Kepler observations.

One of the methods the collection enables you to use is plot, making it possible to quickly visualize all observations in your collection.

# Create a larger figure for clarity
fig, ax = plt.subplots(figsize=(20,5))
# Plot the light curve collection
lc_collection.plot(ax=ax);
../../../_images/aaf720cfdc437c9abd5b167085b8aa1c2555326f964828aea91aae7f1c2f2b75.png

You can also iterate through a collection to label them more clearly and to perform additional actions like normalization.

fig, ax = plt.subplots(figsize=(20,5))
for lc in lc_collection:
  lc.normalize().plot(ax=ax, label=f'Quarter {lc.quarter}');
../../../_images/53ac402ac2c9760d9986b23d820e3a2cf11e56273cd874cc2b12b0db017d3a1b.png

3. Searching for Target Pixel Files#

The other primary data product used by Lightkurve is the TargetPixelFile, or TPF. A TPF is a stack of images containing the flux in each pixel at each cadence.

Similar to the approach above, we can use the search_targetpixelfile method to identify available observations.

search_result = lk.search_targetpixelfile('K2-199')
search_result
SearchResult containing 3 data products.
#missionyearauthorexptimetarget_namedistance
sarcsec
0K2 Campaign 062015K21800ktwo2127795960.0
1K2 Campaign 172018K260ktwo2127795960.0
2K2 Campaign 172018K21800ktwo2127795960.0

This returns a table which contains the same information as a light curve search result.

3.1 Downloading a single target pixel file#

When you call download on a search result containing more than one entry, it will download only the first entry in the search result. Lightkurve will raise a friendly warning to let you know when this occurs.

tpf = search_result.download()

/opt/hostedtoolcache/Python/3.11.8/x64/lib/python3.11/site-packages/lightkurve/search.py:424: LightkurveWarning: Warning: 3 files available to download. Only the first file has been downloaded. Please use `download_all()` or specify additional criteria (e.g. quarter, campaign, or sector) to limit your search.
  warnings.warn(

We can view a single cadence of the TPF using the plot method.

tpf.plot();
../../../_images/0a8f72810d30f42eb8f480d100013460ab7ac6ae497ba4aa7636cf3d860698cf.png

If we want to turn the TPF into a light curve, there is a to_lightcurve method.

lc = tpf.to_lightcurve()
lc.plot();
../../../_images/1c9a96ef02a6302e6bd52f11e2fe08c6b3b799b776e270e9a551566b01c15b24.png

For more information about using and plotting TPFs, please see the tutorials on using Kepler target pixel file products with Lightkurve and plotting Kepler target pixel file products with Lightkurve.

3.2 Downloading a collection of target pixel files#

You can also download multiple TPFs at a time using the download_all method, which returns a TargetPixelFileCollection.

tpf_collection = search_result.download_all()
tpf_collection

TargetPixelFileCollection of 3 objects:
    0: KeplerTargetPixelFile Object (ID: 212779596)
    1: KeplerTargetPixelFile Object (ID: 212779596)
    2: KeplerTargetPixelFile Object (ID: 212779596)

A single cadence of each of these TPFs can be inspected with the plot method.

tpf_collection.plot();
../../../_images/36c1cfd7bf8a8daa83fc20a1d192d8a36f1940489af7897c5f62e09fb1f59a51.png

4. Searching for TESS Full Frame Image (FFI) Cutouts#

It is also possible to download targets observed in the TESS Full Frame Images (FFIs) using Lightkurve. This is done using search_tesscut, which utilizes the TESSCut tool (Brasseur et. al 2019).

search_result = lk.search_tesscut('Pi Men')
search_result
SearchResult containing 20 data products.
#missionyearauthorexptimetarget_namedistance
sarcsec
0TESS Sector 042018TESScut1426Pi Men0.0
1TESS Sector 012018TESScut1426Pi Men0.0
2TESS Sector 132019TESScut1426Pi Men0.0
3TESS Sector 112019TESScut1426Pi Men0.0
4TESS Sector 122019TESScut1426Pi Men0.0
5TESS Sector 082019TESScut1426Pi Men0.0
6TESS Sector 272020TESScut475Pi Men0.0
7TESS Sector 312020TESScut475Pi Men0.0
8TESS Sector 282020TESScut475Pi Men0.0
9TESS Sector 392021TESScut475Pi Men0.0
10TESS Sector 382021TESScut475Pi Men0.0
11TESS Sector 342021TESScut475Pi Men0.0
12TESS Sector 352021TESScut475Pi Men0.0
13TESS Sector 682023TESScut158Pi Men0.0
14TESS Sector 672023TESScut158Pi Men0.0
15TESS Sector 612023TESScut158Pi Men0.0
16TESS Sector 652023TESScut158Pi Men0.0
17TESS Sector 662023TESScut158Pi Men0.0
18TESS Sector 622023TESScut158Pi Men0.0
19TESS Sector 642023TESScut158Pi Men0.0

TESS FFI cutouts are downloaded as TargetPixelFile objects. This is done using the same download function as above, but it now takes an additional argument cutout_size, which describes the number of pixels along the side of the cutout, and can be an int or a tuple.

tpf_cutout = search_result[0].download(cutout_size=10)
tpf_cutout.plot();
../../../_images/1fce191dd730ed4f5acc032fe7fde0b620afd262a61ee01189a8d796b19b3809.png

About this Notebook#

Authors: Nicholas Saunders (nksaun@hawaii.edu)

Updated: September 28, 2020

Citing Lightkurve and Astropy#

If you use lightkurve or its dependencies in your published research, please cite the authors. Click the buttons below to copy BibTeX entries to your clipboard.

lk.show_citation_instructions()

When using Lightkurve, we kindly request that you cite the following packages:

  • lightkurve
  • astropy
  • astroquery — if you are using search_lightcurve() or search_targetpixelfile().
  • tesscut — if you are using search_tesscut().

Space Telescope Logo
Contents