Binder badge

How to use lightkurve’s river plot function

When we are looking for periodic signals, sometimes it can be useful to see how they evolve overtime. You can do that using the lightkurve method plot_river on a FoldedLightCurve object. Let’s look at how to do that now

[1]:
% load_ext autoreload
% autoreload 2
[2]:
import lightkurve as lk

The first thing we are going to do is download some data. We’ll use the target KIC 6185476, which is also known as KOI-227. This object exhibits strong Transit Timing Variations (TTVs), where the planet candidate changes its transit time, and is not exactly periodic.

We can use lightkurve’s search_lightcurvefile function to get all of the light curves from MAST and stitch them together.

[3]:
lc = lk.search_lightcurvefile('KIC 6185476').download_all().PDCSAP_FLUX.stitch()
[4]:
lc.plot()
[4]:
<matplotlib.axes._subplots.AxesSubplot at 0x12311aa58>
../_images/tutorials_03-using-river-plots_5_1.png

When we plot the data, we see that there is a long term trend, likely from starspots. We can remove this with a simple Savitzky-Golay filter using lightkurve’s flatten method.

[5]:
clc = lc.flatten(21)
clc.plot()
[5]:
<matplotlib.axes._subplots.AxesSubplot at 0x1231a3630>
../_images/tutorials_03-using-river-plots_7_1.png

The light curve is now flat, let’s fold the light curve and plot it.

[6]:
# Period and t0 from NASA Exoplanet Archive
p, t0 = 17.660114, 136.57258
[7]:
folded_lc = clc.fold(p, t0)
folded_lc.scatter()
[7]:
<matplotlib.axes._subplots.AxesSubplot at 0x127a37f60>
../_images/tutorials_03-using-river-plots_10_1.png

It looks like there is a concentration of points that are around phase of 0, but they don’t seem to line up nicely. Let’s use river to plot the light curve in a more legible way.

[8]:
folded_lc.plot_river()
[8]:
<matplotlib.axes._subplots.AxesSubplot at 0x12b0532e8>
../_images/tutorials_03-using-river-plots_12_1.png

The river shows the same plot as the fold method, but each time the light curve is folded, a new row is started in the plot. The colorbar then shows the flux in each part of the light curve.

In this case we see a beautiful trend as the planet candidate orbit changes. In some cases, the signal won’t be this obvious. We can also use the river method to bin in time to increase the signal to noise in any bin.

[9]:
folded_lc.plot_river(bin_points=5, method='median')
[9]:
<matplotlib.axes._subplots.AxesSubplot at 0x12a911ef0>
../_images/tutorials_03-using-river-plots_14_1.png

Finally we can also use plot_river to look at the folded light curve in terms of standard deviation. This is useful when looking for signals that are of high significance.

[10]:
folded_lc.plot_river(method='sigma', bin_points=1)
[10]:
<matplotlib.axes._subplots.AxesSubplot at 0x124634a20>
../_images/tutorials_03-using-river-plots_16_1.png

We see in the above river plot that there is a signal around phase zero (our planet candidate) that is always \(< -3\sigma\) from the mean, showing that it is a significant detection.