This page shows you what is new in Lightkurve v2. If you'd like to see our changelog, which tracks minor version changes and patches, you can click here.
Lightkurve v1 has been a tremendous success. Owing to the efforts of 67 contributors, Lightkurve grew into a popular tool to analyze the data archive of NASA's Kepler space telescope. The package has been cited by nearly 200 scientific publications to date.
In recent years, the success revealed a shortcoming: Lightkurve 1 was too focused on supporting Kepler data products. Over the past two years, our community has evolved in important ways:
In response to these changes, the TESS GI Office at NASA Goddard and the TESS Data Archive at STScI/MAST supported the modification of Lightkurve and its tutorials to better support TESS and other data sets in three important ways:
The remainder of this page briefly demonstrates these new features. They are explained in more detail in a new set of entry-level tutorials which are avaiable in the online documentation at docs.lightkurve.org/tutorials.
The most important change in Lightkurve 2 is that light curves are now extensions of AstroPy TimeSeries objects, which in turn are a sub-class of AstroPy Table.
Compared to a generic table, the key difference is that each LightCurve
object is guaranteed to have time
, flux
, and flux_err
columns. This allows Lightkurve to extend AstroPy with tools that are specific to the analysis of TESS-like time series photometry.
Light curves can still be created as before, but now look and act like tables:
from lightkurve import LightCurve
lc = LightCurve(time=[2000.0, 2000.1, 2000.2],
flux=[1.0, 1.0, 1.0],
flux_err=[0.1, 0.1, 0.1],
time_format="btjd")
lc
time | flux | flux_err |
---|---|---|
Time | float64 | float64 |
2000.0 | 1.0 | 0.1 |
2000.1 | 1.0 | 0.1 |
2000.2 | 1.0 | 0.1 |
Because light curves are now tables, they can contain arbitrary user-defined columns:
lc['color'] = ['red', 'green', 'blue']
lc
time | flux | flux_err | color |
---|---|---|---|
Time | float64 | float64 | str5 |
2000.0 | 1.0 | 0.1 | red |
2000.1 | 1.0 | 0.1 | green |
2000.2 | 1.0 | 0.1 | blue |
Just like Table objects, columns and rows can be accessed using index notation:
lc[1:3]
time | flux | flux_err | color |
---|---|---|---|
Time | float64 | float64 | str5 |
2000.1 | 1.0 | 0.1 | green |
2000.2 | 1.0 | 0.1 | blue |
lc['flux']
Lightkurve 2 extends AstroPy Time by adding support for the TESS and Kepler time formats ("BTJD" and "BKJD"). As a result, the time column is now always a Time object, which enables user to leverage this standard AstroPy feature:
lc.time
<Time object: scale='tdb' format='btjd' value=[2000. 2000.1 2000.2]>
lc.time.jd # Easy conversion to Julian Days
array([2459000. , 2459000.1, 2459000.2])
lc.time.iso # Easy conversion to ISO time stamps
array(['2020-05-30 12:00:00.000', '2020-05-30 14:24:00.000', '2020-05-30 16:48:00.000'], dtype='<U23')
Because light curves act like tables, they now have easy read()
and write()
methods which allow a variety of data formats to be used. For example, it is now much easier to store a light curve to a human-readable text file:
lc.write("/tmp/lightcurve.txt", format="ascii.fixed_width", overwrite=True)
!cat /tmp/lightcurve.txt
| time | flux | flux_err | color | | 2000.0 | 1.0 | 0.1 | red | | 2000.1 | 1.0 | 0.1 | green | | 2000.2 | 1.0 | 0.1 | blue |
LightCurve.read("/tmp/lightcurve.txt", format="ascii.fixed_width")
time | flux | flux_err | color |
---|---|---|---|
Time | float64 | float64 | str5 |
2000.0 | 1.0 | 0.1 | red |
2000.1 | 1.0 | 0.1 | green |
2000.2 | 1.0 | 0.1 | blue |
Lightkurve 2 significantly expands the data sets that can be searched and downloaded from the TESS & Kepler data archives at MAST.
The search operations now support all the Kepler & TESS light curves available from the data archive at MAST, including community-contributed light curves. A new author
column in the search results identifies the pipeline (click on a pipeline name for details). As an added bonus, the search and download operations are now much faster owing to improved caching.
import lightkurve as lk
lk.search_lightcurve("Polaris")
# | mission | year | author | exptime | target_name | distance |
---|---|---|---|---|---|---|
s | arcsec | |||||
0 | TESS Sector 19 | 2019 | SPOC | 120 | 303256075 | 0.0 |
1 | TESS Sector 60 | 2022 | SPOC | 120 | 303256075 | 0.0 |
2 | TESS Sector 19 | 2019 | TESS-SPOC | 1800 | 303256075 | 0.0 |
3 | TESS Sector 19 | 2019 | QLP | 1800 | 303256075 | 0.0 |
4 | TESS Sector 20 | 2019 | QLP | 1800 | 303256075 | 0.0 |
5 | TESS Sector 25 | 2020 | QLP | 1800 | 303256075 | 0.0 |
6 | TESS Sector 26 | 2020 | QLP | 1800 | 303256075 | 0.0 |
7 | TESS Sector 40 | 2021 | QLP | 600 | 303256075 | 0.0 |
8 | TESS Sector 47 | 2021 | QLP | 600 | 303256075 | 0.0 |
9 | TESS Sector 59 | 2022 | QLP | 200 | 303256075 | 0.0 |
10 | TESS Sector 60 | 2022 | QLP | 200 | 303256075 | 0.0 |
11 | TESS Sector 52 | 2022 | QLP | 600 | 303256075 | 0.0 |
12 | TESS Sector 53 | 2022 | QLP | 600 | 303256075 | 0.0 |
13 | TESS Sector 26 | 2020 | TASOC | 1800 | 303256075 | 0.0 |
14 | TESS Sector 26 | 2020 | TASOC | 1800 | 303256075 | 0.0 |
The TESS mission recently introduced a new 20-second exposure time mode and decreased the exposure time of its Full Frame Images to 10 minutes. In response, Lightkurve now allows user to specify the exact exposure time via the optional exptime
argument and column.
lk.search_lightcurve("AU Mic", exptime=20)
# | mission | year | author | exptime | target_name | distance |
---|---|---|---|---|---|---|
s | arcsec | |||||
0 | TESS Sector 27 | 2020 | SPOC | 20 | 441420236 | 0.0 |
You can also filter search results after the fact via attribute access, e.g. via search.exptime
:
search = lk.search_lightcurve("AU Mic")
search[search.exptime.value == 20].download().plot();
Lightkurve 2 adds a new CotrendingBasisVectors
class to provide a convenient interface to work with the official TESS and Kepler basis vector data products. We also re-implemented the CBVCorrector
class from scratch to perform the correction in a way that is more similar to the official Kepler/TESS pipeline. This work was led by one of the authors of the official pipeline, Jeff Smith.
# Download a light curve and apply the new CBVCorrector
from lightkurve.correctors import CBVCorrector
lc = lk.search_lightcurve("TIC 99180739", author="SPOC", sector=10).download(flux_column="sap_flux")
cbvCorrector = CBVCorrector(lc)
lc_corrected = cbvCorrector.correct()
Optimized Over-fitting metric: 0.9996581030332481 Optimized Under-fitting metric: 0.8255822538489808 Optimized Alpha: 9.472e+03
The corrector now produces detailed diagnostic plots showing the light curve before (grey) and after (black) the noise (blue) was removed:
cbvCorrector.diagnose();
A lightkurve.correctors.metrics
module was added to provide functions which can estimate the degree of over- and under-fitting of a corrected light curve. The new CBVCorrector
utilizes these metrics to find an appropriate, user-tuneable tradeoff. You can learn more about this new feature in the new CBVCorrector tutorial.
cbvCorrector.goodness_metric_scan_plot();
A new TargetPixelFile.plot_pixels()
method has been added which enables the light curves and periodograms of individual pixels to be inspected within a pixel file. This is very useful for investigating the location of specific signals. A dedicated tutorial explains this new feature in detail.
pixelfile = lk.search_targetpixelfile("KIC 2435971", mission="Kepler", quarter=9).download()
pixelfile.plot_pixels();
LightCurve.create_transit_mask(period, transit_time, duration)
method to conveniently mask planet or eclipsing binary transits.LightCurve.search_neighbors()
method to search for light curves around an existing one.TargetPixelFile.plot()
to use a more clear hatched style when visualizing the aperture mask on top of pixel data.SparseDesignMatrix
and modified RegressionCorrector
to enable systematics removal methods to benefit from scipy.sparse speed-ups.In addition, Lightkurve 2 contains numerous smaller improvements and bugfixes. To see a detailed list of all changes, please see the Full Changelog.
You can upgrade Lightkurve using pip:
python -m pip install --upgrade lightkurve
You can continue to use Lightkurve 1 by pinning the version number using pip, for example:
python -m pip install lightkurve==1.11
While we tried to maximize backwards compatibility, Lightkurve 2 does contain a small number of changes that may break existing code for the following reasons:
Time
objects yet. Existing code may have to be modified to pass lc.time.value
to NumPy/SciPy functions where lc.time
was passed before.lc.flux.value
instead of lc.flux
.lc.sector
is available as a shortcut for lc.meta['SECTOR']
.LightCurve.read(filename, format="tess")
.astropy.timeseries.aggregate_downsample
. This significantly alters the behavior of binning, because bins are now defined in time instead of by number of data points.TimeSeries.fold()
. For the same reason, the t0
argument has been deprecated in favor of epoch_time
, and the method now accepts the extra epoch_phase
, wrap_phase
, and normalize_phase
arguments.lc.astropy_time
=> lc.time
lc.time_format
=> lc.time.format
lc.time_scale
=> lc.time.scale
lc.flux_quantity
=> lc.flux
lc.flux_unit
=> lc.flux.unit
search_lightcurvefile()
=> search_lightcurve()
The people who contributed to Lightkurve 2 include:
Thomas Barclay, Geert Barentsen, Keaton Bell, Zachory K. Berta-Thompson, Colin J. Burke, Nuno Ramos Carvalho, Ann Marie Cody, Isabel Coleman, Kaiming Cui, Guy Davies, Jessie Dotson, Stephanie Douglas, Scott Fleming, Daniel Foreman-Mackey, Michael Gully-Santiago, Oliver Hall, Christina Hedges, Daniel Hey, Michael Higgins, Derek Homeier, Rebekah Hounsell, Sam Lee, Jose A. Lerma III, Ken Mighell, Susan Mullally, Szabo Pal, Sheila Sagear, Nicholas Saunders, Jeff Smith, Anand Sundaram, Emma Turtelboom, Andrew Vanderburg, Brennan Vincello, José Vinícius de Miranda Cardoso, Peter Williams, Johnny Zhang.