{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "iFa75AzBn2Ce"
   },
   "source": [
    "# Visualizing periodic signals using a river plot"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "bkI49sHSu1UH"
   },
   "source": [
    "## Learning Goals\n",
    "\n",
    "By the end of this tutorial, you will:\n",
    "\n",
    "- Understand what a river plot is.\n",
    "- Understand when river plots are useful.\n",
    "- Be able to create and interpret a river plot."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "PASflLFhtaTP"
   },
   "source": [
    "## Introduction\n",
    "\n",
    "A \"river plot\" is a method to visualize periodic signals that vary over time. It is created by breaking a light curve into segments of equal length, such as the period of a planet orbiting a star, and displaying the segments side by side to allow the flux values to be compared. This allows you to examine how an entire light curve varies relative to a fixed period. It is similar to a \"[waterfall plot](https://en.wikipedia.org/wiki/Waterfall_plot)\" which is used to similarly analyze time variation in spectra. \n",
    "\n",
    "This tutorial demonstrates how to create a river plot using [Lightkurve](https://docs.lightkurve.org)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "b0IfYc6BnfiQ"
   },
   "source": [
    "## Imports\n",
    "\n",
    "This tutorial requires the [**Lightkurve**](http://docs.lightkurve.org/) package, which uses [**Matplotlib**](https://matplotlib.org/) for plotting."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "id": "wLRaaDQHn2Cj"
   },
   "outputs": [],
   "source": [
    "import lightkurve as lk\n",
    "%matplotlib inline"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "yri_kQerqx-v"
   },
   "source": [
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "8oL_22i6njsl"
   },
   "source": [
    "## 1. When is a River Plot Useful?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "3Xs92gHOn2Cm"
   },
   "source": [
    "When we are looking for periodic signals in a light curve, sometimes it can be useful to see how they evolve over time. You can do this using the Lightkurve method `plot_river` on a `FoldedLightCurve` object.\n",
    "\n",
    "We start by downloading some example data. We'll use the target KIC 6185476, which is also known as KOI-227. This object exhibits strong transit timing variations (TTVs), that is, the transit time of the planet candidate changes over time. This happens when the orbit of a planet is not precisely periodic due to, for example, the presence of multiple moving stars or planets in the system.\n",
    "\n",
    "We can use Lightkurve's `search_lightcurve` function to get all of the available light curves from MAST and stitch them together."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "id": "-D5gkIgmn2Cp"
   },
   "outputs": [],
   "source": [
    "lc = lk.search_lightcurve('KIC 6185476', author='Kepler', cadence='long').download_all().stitch()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/",
     "height": 387
    },
    "executionInfo": {
     "elapsed": 61725,
     "status": "ok",
     "timestamp": 1601420302973,
     "user": {
      "displayName": "Geert Barentsen",
      "photoUrl": "https://lh3.googleusercontent.com/a-/AOh14Gj8sjdnDeqdejfe7OoouYPIclAQV0KSTpsU469Jyeo=s64",
      "userId": "05704237875861987058"
     },
     "user_tz": 420
    },
    "id": "ojtzDw0ln2Cr",
    "outputId": "2ca1abbf-ce90-48fb-cf8e-431bf408c32c"
   },
   "outputs": [],
   "source": [
    "lc.plot();"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "vJT7duQan2Cv"
   },
   "source": [
    "When we plot the data, we see that there is a long-term trend, likely from starspots. We can remove this with a Savitzky-Golay filter using Lightkurve's `flatten` method."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/",
     "height": 387
    },
    "executionInfo": {
     "elapsed": 62264,
     "status": "ok",
     "timestamp": 1601420303541,
     "user": {
      "displayName": "Geert Barentsen",
      "photoUrl": "https://lh3.googleusercontent.com/a-/AOh14Gj8sjdnDeqdejfe7OoouYPIclAQV0KSTpsU469Jyeo=s64",
      "userId": "05704237875861987058"
     },
     "user_tz": 420
    },
    "id": "H8PCJLurn2Cw",
    "outputId": "8b005563-7c40-4ed5-d86a-9909c2bc5f55"
   },
   "outputs": [],
   "source": [
    "clc = lc.flatten(21)\n",
    "clc.plot();"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "4WYwgZZ5n2Cz"
   },
   "source": [
    "The light curve is now flat. Let's fold the light curve and plot it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/",
     "height": 387
    },
    "executionInfo": {
     "elapsed": 2337,
     "status": "ok",
     "timestamp": 1601420575089,
     "user": {
      "displayName": "Geert Barentsen",
      "photoUrl": "https://lh3.googleusercontent.com/a-/AOh14Gj8sjdnDeqdejfe7OoouYPIclAQV0KSTpsU469Jyeo=s64",
      "userId": "05704237875861987058"
     },
     "user_tz": 420
    },
    "id": "eb1ASMVen2C2",
    "outputId": "a9633039-2f37-49fb-ead6-98f81696928c"
   },
   "outputs": [],
   "source": [
    "# Period (p) and and reference transit time (t0) are taken from the NASA Exoplanet Archive\n",
    "p, t0 = 17.660114, 136.57258\n",
    "folded_lc = clc.fold(period=p, epoch_time=t0)\n",
    "folded_lc.scatter();"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "RyxbnkN-yDfp"
   },
   "source": [
    "It looks like there is a concentration of points that are around phase of `0`, but they don't seem to line up nicely. This is caused by the transit of the planet occurring slightly before or after you would predict using a constant period. Cases of planets with meaningful TTVs are well suited for further analysis using a river plot."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "AwUM_pqenpxY"
   },
   "source": [
    "## 2. Creating a River Plot"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "6DYkaUWSn2C5"
   },
   "source": [
    "We can use the `plot_river` method to plot the light curve in a more legible way. This must be performed on a folded `LightCurve`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/",
     "height": 666
    },
    "executionInfo": {
     "elapsed": 71701,
     "status": "ok",
     "timestamp": 1601420313052,
     "user": {
      "displayName": "Geert Barentsen",
      "photoUrl": "https://lh3.googleusercontent.com/a-/AOh14Gj8sjdnDeqdejfe7OoouYPIclAQV0KSTpsU469Jyeo=s64",
      "userId": "05704237875861987058"
     },
     "user_tz": 420
    },
    "id": "DyiaewSxn2C6",
    "outputId": "2b417f85-23b4-4255-df83-ce517656ad0b"
   },
   "outputs": [],
   "source": [
    "folded_lc.plot_river();"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "OCW2BKqVn2C8"
   },
   "source": [
    "The river plot 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. \n",
    "\n",
    "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 `plot_river` method to bin in time to increase the signal to noise in any bin."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/",
     "height": 666
    },
    "executionInfo": {
     "elapsed": 79362,
     "status": "ok",
     "timestamp": 1601420320734,
     "user": {
      "displayName": "Geert Barentsen",
      "photoUrl": "https://lh3.googleusercontent.com/a-/AOh14Gj8sjdnDeqdejfe7OoouYPIclAQV0KSTpsU469Jyeo=s64",
      "userId": "05704237875861987058"
     },
     "user_tz": 420
    },
    "id": "JrP1e7DQn2C8",
    "outputId": "8a3ec320-4338-4d39-b10d-9bd0e49ee402"
   },
   "outputs": [],
   "source": [
    "folded_lc.plot_river(bin_points=5, method='median');"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "kduilBvansgp"
   },
   "source": [
    "## 3. Changing the Scale to Standard Deviation"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "Vi6tZjGwn2DA"
   },
   "source": [
    "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."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/",
     "height": 648
    },
    "executionInfo": {
     "elapsed": 91078,
     "status": "ok",
     "timestamp": 1601420332465,
     "user": {
      "displayName": "Geert Barentsen",
      "photoUrl": "https://lh3.googleusercontent.com/a-/AOh14Gj8sjdnDeqdejfe7OoouYPIclAQV0KSTpsU469Jyeo=s64",
      "userId": "05704237875861987058"
     },
     "user_tz": 420
    },
    "id": "f9w3k0bMn2DA",
    "outputId": "2d7ab3d5-b867-497d-9064-96f10794b9d3"
   },
   "outputs": [],
   "source": [
    "folded_lc.plot_river(bin_points=1, method='sigma');"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "b1OYUWkqn2DD"
   },
   "source": [
    "We see in the above river plot that there is a signal around phase of `0` (our planet candidate) that has a clear deviation from the mean, showing that it is a significant detection."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "cYvZcf-IoNAT"
   },
   "source": [
    "## About this Notebook\n",
    "\n",
    "**Authors:** Christina Hedges (christinalouisehedges@gmail.com), Nicholas Saunders (nksaun@hawaii.edu)\n",
    "\n",
    "**Updated On:** 2020-09-29"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "2oxYjZlpoQY2"
   },
   "source": [
    "## Citing Lightkurve and its Dependencies\n",
    "\n",
    "If you use `lightkurve` or its dependencies for published research, please cite the authors. Click the buttons below to copy BibTeX entries to your clipboard."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/",
     "height": 144
    },
    "executionInfo": {
     "elapsed": 91066,
     "status": "ok",
     "timestamp": 1601420332466,
     "user": {
      "displayName": "Geert Barentsen",
      "photoUrl": "https://lh3.googleusercontent.com/a-/AOh14Gj8sjdnDeqdejfe7OoouYPIclAQV0KSTpsU469Jyeo=s64",
      "userId": "05704237875861987058"
     },
     "user_tz": 420
    },
    "id": "UbLg8mrRoNj3",
    "outputId": "3b6bec0f-d4a2-4db3-a6ca-b14237408f1f"
   },
   "outputs": [],
   "source": [
    "lk.show_citation_instructions()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "9-YnV2qVoTMk"
   },
   "source": [
    "<img style=\"float: right;\" src=\"https://raw.githubusercontent.com/spacetelescope/notebooks/master/assets/stsci_pri_combo_mark_horizonal_white_bkgd.png\" alt=\"Space Telescope Logo\" width=\"200px\"/>"
   ]
  }
 ],
 "metadata": {
  "colab": {
   "collapsed_sections": [],
   "name": "How to visualize periodic signals using a river plot",
   "provenance": [
    {
     "file_id": "https://github.com/KeplerGO/lightkurve/blob/master/docs/source/tutorials/03-using-river-plots.ipynb",
     "timestamp": 1601412773557
    }
   ]
  },
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}