diff --git a/notebooks/tike_lcviz_tutorial.ipynb b/notebooks/tike_lcviz_tutorial.ipynb new file mode 100644 index 00000000..7ce7b380 --- /dev/null +++ b/notebooks/tike_lcviz_tutorial.ipynb @@ -0,0 +1,373 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "\n", + "# LCviz Tutorial\n", + "***\n", + "## Learning Goals\n", + "\n", + "\n", + "By the end of this tutorial, you will:\n", + "\n", + "- Understand how to load time series data into LCviz.\n", + "- Apply flattening to a light curve to remove low frequency trends.\n", + "- Use LCviz to create and display a phase-folded light curve." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "slide" + } + }, + "source": [ + "## Table of Contents\n", + "* [Introduction](#Introduction)\n", + "* [Imports](#Imports)\n", + "* [Using LCviz](#Using-LCviz)\n", + " * [Initializing LCviz](#Initializing-LCviz)\n", + " * [Loading Light Curves into LCviz](#Loading-light-curves-into-LCviz)\n", + " * [Flattening](#Flattening)\n", + " * [Phase Folding](#Phase-Folding)\n", + "* [Additional Resources](#Additional-Resources)\n", + "\n", + "## Introduction\n", + "In this notebook we will be exploring the use of the [LCviz](https://github.com/spacetelescope/lcviz) (light curve visualization and analysis) tool for investigating time series observations of a transiting exoplanet. LCviz is built on the [Jdaviz](https://github.com/spacetelescope/jdaviz/) data analysis and visualization tool and additionally relies heavily on the [lightkurve](https://github.com/lightkurve/lightkurve) and [astropy](https://github.com/astropy/astropy) packages.\n", + "\n", + "Specifically, we will be using LCviz to look at a Kepler long cadence light curve of HAT-P-11, a K4V host to\n", + "a transiting hot Neptune with a 4.8 day period, and a stellar rotation period of 29 days." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "slide" + } + }, + "source": [ + "## Imports\n", + "\n", + "- *s3fs* used to access cloud files as though they were local\n", + "- *astropy.units* used to define quantities with units attached\n", + "- *astropy.time Time* used to define the epoch for the ephemeris of the planet\n", + "- *astroquery.mast* used to search for and select data\n", + "- *lightkurve* for reading the light curve file\n", + "- *lcviz* for plotting and analyzing data" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "slideshow": { + "slide_type": "fragment" + } + }, + "outputs": [], + "source": [ + "import s3fs\n", + "\n", + "import astropy.units as u\n", + "from astropy.time import Time\n", + "from astroquery.mast import Observations\n", + "import lightkurve\n", + "\n", + "from lcviz import LCviz" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "***" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Using LCviz" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Initializing LCviz\n", + "\n", + "Starting the LCviz application takes two steps: first, we need to create an instance of\n", + "the `LCviz` class, and then we need to show the application in the notebook. The two lines\n", + "below will open an empty instance of LCviz in the output cell of the notebook. \n", + "\n", + "The two main sections of LCviz that you will see below are a viewer for displaying flux vs time\n", + "data on the left, and an open tray with expandable sections giving UI access to data analysis plugins\n", + "on the right. Hovering the cursor over the various buttons in the application will display tooltips\n", + "giving a short description of their purpose.\n", + "\n", + "In the next section, we will actually load data into LCviz to be shown in the flux vs time\n", + "viewer." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "jp-MarkdownHeadingCollapsed": true + }, + "outputs": [], + "source": [ + "# Create an instance of the LCviz class\n", + "lcviz = LCviz()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Now we show the application in the notebook. We keep this in a separate cell because\n", + "it is occasionally useful to refresh the display of the app without overwriting\n", + "it with a new instance:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "lcviz.show() # Show the LCviz app" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "It may be more convenient to open the application in a new tab within your Jupyter\n", + "Lab instance instead of scrolling up and down between the app and the code cells.\n", + "To do this you could un-comment and run the following line:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# lcviz.show(loc=\"sidecar:tab-after\") # Show the app in a new tab within Jupyter Lab" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "slide" + } + }, + "source": [ + "## Loading light curves into LCviz\n", + "\n", + "Because TIKE already runs in the cloud, it is fastest and easiest to load data that is also hosted in the cloud using the `s3fs` package, which allows you to access cloud data as if it were local. Here we will use [astroquery](https://astroquery.readthedocs.io/en/latest/) to get the URI for the file that we want to load. For more information about the code below, see [this TIKE webinar notebook](https://github.com/spacetelescope/tike_content/blob/main/content/notebooks/webinar-series/01-lightcurves/01-Lightcurves.ipynb).\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "Observations.enable_cloud_dataset() # use cloud data when possible\n", + "fs = s3fs.S3FileSystem(anon=True) # read cloud data as though local" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "slideshow": { + "slide_type": "fragment" + } + }, + "outputs": [], + "source": [ + "# Query for Kepler time series Observations of our target. This query\n", + "# will return data from all quarters.\n", + "kepler_table = Observations.query_criteria(objectname=\"HAT-P-11\",\n", + " obs_collection=\"Kepler\",\n", + " dataproduct_type=\"timeseries\",\n", + " obs_id=\"kplr010748390_lc_Q111111101110111011\"\n", + " ) \n", + "\n", + "# Get associated science products for each Observation\n", + "data_products = Observations.get_product_list(kepler_table)\n", + "\n", + "# Keep only the long cadence light curve science products\n", + "lc_prod = Observations.filter_products(data_products, productType=\"SCIENCE\", productSubGroupDescription = \"LLC\")\n", + "\n", + "# Get the cloud URI for the quarter 9 data. Note that this is the 8th entry because\n", + "# there is no file for quarter 7 in the results.\n", + "lc_uri = Observations.get_cloud_uri(lc_prod[8])" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Now that we have the cloud URI for the data, we can load the light curve\n", + "# into the LCviz app\n", + "light_curve = lightkurve.read(lc_uri)\n", + "lcviz.load_data(light_curve)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "tags": [] + }, + "source": [ + "## Flattening\n", + "\n", + "There are clearly some long term trends in the data, which we would like to remove\n", + "in order to more clearly see the transits. Here we use `Flatten` plugin to remove\n", + "low frequency trends from the light curves. Note that all of the options set here\n", + "are also available in the UI in the `Flatten` plugin, accessible in the plugin\n", + "tray on the right side of the app." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "flatten = lcviz.plugins['Flatten']\n", + "\n", + "# There is currently only one dataset, so we do not\n", + "# need to set flatten.dataset. If there were multiple\n", + "# light curves loaded, you could see the choices to set\n", + "# this with flatten.dataset.choices\n", + "flatten.window_length = 50\n", + "flatten.flatten();" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "tags": [] + }, + "source": [ + "## Phase Folding\n", + "\n", + "A common operation when dealing with light curves is to phase fold the data, so\n", + "that all of the transits are lined up with each other, essentially displaying all\n", + "of the data over a single orbit of the planet. Here we use the `Ephemeris` plugin\n", + "to phase fold the data using values from the literature for the epoch and period.\n", + "Running this code will create a second flux vs time viewer in the app to display\n", + "the new phase folded light curve." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "scrolled": true, + "tags": [] + }, + "outputs": [], + "source": [ + "# get the origin of the time axis in LCviz:\n", + "data = lcviz.get_data()\n", + "reference_time = data.time[0]\n", + "\n", + "# literature ephemeris for hot Neptune planet HAT-P-11 b:\n", + "morris2017_epoch = 2454605.89146 # BJD (TDB)\n", + "morris2017_period = 4.88780258 # days\n", + "\n", + "# phase-fold the transit light curve in an ephemeris viewer:\n", + "eph = lcviz.plugins['Ephemeris']\n", + "eph.period = morris2017_period\n", + "eph.t0 = (\n", + " (morris2017_epoch - reference_time) % eph.period\n", + ")\n", + "\n", + "# offset the wrapping phase so the transit (at phase 0) displays at center\n", + "eph.wrap_at = 0.5" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Additional Resources\n", + "\n", + "- [LCviz documentation](https://lcviz.readthedocs.io/en/stable/index.html)\n", + "- [LCviz Github](https://github.com/spacetelescope/lcviz)\n", + "- [lightkurve documentation](https://lightkurve.github.io/lightkurve/)\n", + "- [Kepler Archive Page (MAST)](https://archive.stsci.edu/kepler/)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Citations\n", + "\n", + "If you use `astropy`, `lightkurve`, or `Jdaviz` (via `LCviz`) for published research, please cite\n", + "the authors. Follow these links for more information about citing `astropy` and\n", + "`lightkurve`:\n", + "\n", + "* [Citing `astropy`](https://www.astropy.org/acknowledging.html)\n", + "* [Citing `lightkurve`](http://docs.lightkurve.org/about/citing.html)\n", + "\n", + "And cite Jdaviz through its [Zenodo record](https://doi.org/10.5281/zenodo.5513927).\n" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "slideshow": { + "slide_type": "slide" + } + }, + "source": [ + "## About this Notebook\n", + "\n", + "**Author(s):** Ricky O'Steen, Kyle Conroy, Brett Morris, Thomas Dutkiewicz
\n", + "**Keyword(s):** Tutorial, LCviz, TESS, introduction
\n", + "**First published:** Oct 2024
\n", + "**Last updated:** Oct 2024
\n", + "\n", + "***\n", + "[Top of Page](#top)\n", + "\"Space " + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "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.12.7" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +}