By the end of this tutorial, you will:
Lightkurve has three interactive tools which make it possible to perform quick inspections and analyses of target pixel files and light curves. These functions use the Bokeh library to create widgets within a Jupyter notebook. In this tutorial, we provide examples for how to best use the interactive tools in Lightkurve.
import lightkurve as lk
Using interact should be as convenient as downloading a Kepler target pixel file (TPF) and running the method .interact(). This method can only be run in a Jupyter notebook at the moment.
.interact() offers instantaneous interactive selection of the pixel mask, and instantaneous generation of the resulting light curve. You can click on individual pixels and the aperture photometry seamlessly updates. The mask can be defined with either individual clicking of pixels, or clicking and dragging a box over a rectangular set of pixels. Deselection of individual pixels works by re-clicking a pixel that you wish to take away from your mask. Finally, you can save your mask and light curve as a FITS file by clicking on the
Save Lightcurve button.
The default mask is the Kepler "pipeline" mask, and can be modified as described above.
In this tutorial, we introduce and explain the
tpf.interact() tool that accomplishes the goal of interactively inspecting the TPFs and ligh tcurve simultaneously.
Let's first look at the target HL Tau, a young star that possesses a gapped circumstellar disk which has been imaged by the Atacama Large Millimeter Array.
tpf = lk.search_targetpixelfile("HL Tau", author='K2', campaign=13, cadence='long').download()
The K2 postage stamp of HL Tau contains a portion of a nearby source of comparable brightness. The weakly overlapping point spread functions (PSFs) of these sources motivate some caution in aperture choice. Let's interactively assign a custom aperture photometry pixel mask:
You can move the large bottom left slider to change the location of the vertical red bar, which indicates which cadence is being shown in the TPF postage stamp image. The slider beneath the TPF postage stamp image controls the screen stretch, which defaults to logarithmic scaling initialized to 1% and 95% lower and upper limits respectively.
You can move your cursor over individual data points to show hover-over tooltips indicating additional information about that datum. Currently the tooltips list the cadence, time, flux, and quality flags. The tools on the right hand side of the plots enable zooming and pixel selection.
We see that the starting mask (the Kepler pipeline mask, by default), shows huge jumps in flux between times 3000 and 3020. These jagged artifacts disappear upon the selection of a larger aperture — large enough to encompass most of the point spread function of the star. The end result shows a time series light curve of a young disk-bearing star.
shift-clicking on multiple pixels shows the light curve using that pixel mask.
shift-clicking on an already selected pixel will deselect that pixel.
interact() tool works for Kepler/K2 or TESS data. Here we show an example using Kepler data — KOI 6.01 (KIC 3248033) sits four pixels away from eclipsing binary KOI 1759.01 (KIC 3248019). An unwise choice of pixels can give rise to a spurious exoplanet signal.
tpf = lk.search_targetpixelfile('KIC 3248033', author="Kepler", quarter=4).download()
You can see that the Kepler pointing is remarkably stable over this Kepler Quarter of 89 days. The value of interact arises from its ability to discern the spatial origin of signals. In this case, an eclipsing binary occupies the pixels towards the top of the postage stamp image. The target of interest occupies the pixels in the middle. The optimal aperture mask should avoid pixels near the top in order to mitigate an artificial planet signal.
Lightkurve has an additional tool to interactively inspect target pixel files —
.interact_sky. This method brings up a single frame of the target pixel file with targets identified by Gaia marked by red circles. The size of the circle scales with the magnitude of the target, where brighter sources are larger and fainter sources are smaller. Using your cursor, you can hover over the red circles to display useful information from Gaia, including its Gaia ID, G band magnitude, and coordinates.
.interact in section 1, .interact_sky allows you to change the screen stretch, giving you more control over the image display.
Finally, you can zoom in on different regions of the TPF by clicking the magnifying glass icon and scrolling over the image.
There is also an interactive tool for
LightCurve objects called .interact_bls. BLS, or Box Least Squares, is a method for identifying transit signals in a light curve. For more information about how to use BLS to find transiting planets in Kepler/K2 or TESS light curves, please see the companion tutorial on identifying transiting planet signals in a Kepler light curve.
.interact_bls method allows you to identify periodic transit signals in light curves by manually selecting the period and duration of the signal.
The light curve in the top right panel is phase-folded with the highest power period. When you zoom in on a region of period space in the BLS periodogram, it will automatically update the phase plot with the new period-at-max-power. Changing the duration using the slider in the bottom left will also update the BLS periodogram and phase-folded light curve. Finally, the parameters of the BLS model can be found in the bottom right panel.
There are a few known limitations of the interactive tools. First, they only work in a Jupyter notebook. Second, you must either run the interactive functions from the default Jupyter notebook address "localhost:8888," or tell the function the name of the notebook server, for example:
Otherwise, you will likely see an error message like this:
Other unexpected behaviors can occur. For example, when resetting the image views, the revised plot scaling may not display the data. Attempting to deselect with a box will cause unexpected toggling of pixels. Deselection only works with the tap tool, so box selections should use caution not to overlap with existing pixels. Surprisingly, deselection does not work for the most recently added pixel. Light curves with more than 200,000 cadences require either an increase in the
max_cadences kwarg, or slicing of your input TPF like so:
# Only show the first 1000 cadences to makes the tool faster tpf[0:1000].interact() # Override the maximum cadence limit tpf.interact(max_cadences=300000)
We'd like to thank the developers of Bokeh, upon which our interactive tools rely.
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.