{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Understanding LightCurve Objects" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Learning Goals\n", "\n", "In our [TargetPixelFile tutorial](Target-Pixel-Files.html) we learned, how to obtain data files for our objects of interest and how to examine the `metadata` stored in the headers.\n", "\n", "In this tutorial we will learn the following,\n", "- How to use *Lightkurve* to create a [`TESSLightCurve`](https://docs.lightkurve.org/api/lightkurve.lightcurve.TessLightCurve.html#lightkurve.lightcurve.TessLightCurve) object.\n", "- How to examine the object data, and understand its format.\n", "- What is simple aperture photometry (SAP).\n", "- How to plot a light curve." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## What is LightCurve object?\n", "You can create a `TESSLightCurve` object from a `TargetPixelFile` (TPF) object using Simple Aperture Photometry (SAP). \n", "\n", "## What is Simple Aperture Photometry (SAP)?\n", "Aperture Photometry is the act of summing up the values of all the pixels in a pre-defined aperture as a function of time. By carefully choosing the shape of the aperture mask, you can avoid nearby contaminants or improve the strength of the specific signal you are trying to measure relative to the background.\n", "\n", "The SAP light curve is a pixel summation time-series of all calibrated flux falling within the optimal aperture, as stored and defined in the TPF.\n", "\n", "In this notebook we will demonstrate, let's create a `TESSLightCurve` from a `TESSTargetPixelFile`. " ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Imports\n", "This tutorial requires that you import *Lightkurve*." ] }, { "cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [], "source": [ "%matplotlib inline \n", "import lightkurve as lk" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Defining Terms\n", "\n", "- Target Pixel File (TPF): A file containing the original CCD pixel observations from which light curves are extracted. \n", "\n", "- LightCurve Object: Obtained from a TPF and contains lightcurve information derived using simple aperture photometry.\n", "\n", "- Cadence: The rate at which TESS photometric observations are stored. \n", "\n", "- Sector: One of TESS's 27 (to date) observing periods, approximately ~27 days in duration.\n", "\n", "- Simple Aperture Photometry (SAP): The act of summing all pixel values in a pre-defined aperture as a function of time." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Downloading the TPF\n", "For this tutorial we will use the [L 98-59 System](https://arxiv.org/pdf/1903.08017.pdf) focusing on planet c.\n", "\n", "First we search for appropriate Target Pixel Files on [MAST](https://archive.stsci.edu/tess/) using the [`search_targetpixelfile`](https://docs.lightkurve.org/api/lightkurve.search.search_targetpixelfile.html?highlight=search_targetpixelfile) function. " ] }, { "cell_type": "code", "execution_count": 2, "metadata": {}, "outputs": [ { "data": { "text/html": [ "SearchResult containing 7 data products.\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "
#observationauthortarget_nameproductFilenamedistance
0TESS Sector 2SPOC307210830tess2018234235059-s0002-0000000307210830-0121-s_tp.fits0.0
1TESS Sector 5SPOC307210830tess2018319095959-s0005-0000000307210830-0125-s_tp.fits0.0
2TESS Sector 8SPOC307210830tess2019032160000-s0008-0000000307210830-0136-s_tp.fits0.0
3TESS Sector 9SPOC307210830tess2019058134432-s0009-0000000307210830-0139-s_tp.fits0.0
4TESS Sector 10SPOC307210830tess2019085135100-s0010-0000000307210830-0140-s_tp.fits0.0
5TESS Sector 11SPOC307210830tess2019112060037-s0011-0000000307210830-0143-s_tp.fits0.0
6TESS Sector 12SPOC307210830tess2019140104343-s0012-0000000307210830-0144-s_tp.fits0.0
" ], "text/plain": [ "SearchResult containing 7 data products.\n", "\n", " # observation author target_name productFilename distance\n", "--- -------------- ------ ----------- ------------------------------------------------------- --------\n", " 0 TESS Sector 2 SPOC 307210830 tess2018234235059-s0002-0000000307210830-0121-s_tp.fits 0.0\n", " 1 TESS Sector 5 SPOC 307210830 tess2018319095959-s0005-0000000307210830-0125-s_tp.fits 0.0\n", " 2 TESS Sector 8 SPOC 307210830 tess2019032160000-s0008-0000000307210830-0136-s_tp.fits 0.0\n", " 3 TESS Sector 9 SPOC 307210830 tess2019058134432-s0009-0000000307210830-0139-s_tp.fits 0.0\n", " 4 TESS Sector 10 SPOC 307210830 tess2019085135100-s0010-0000000307210830-0140-s_tp.fits 0.0\n", " 5 TESS Sector 11 SPOC 307210830 tess2019112060037-s0011-0000000307210830-0143-s_tp.fits 0.0\n", " 6 TESS Sector 12 SPOC 307210830 tess2019140104343-s0012-0000000307210830-0144-s_tp.fits 0.0" ] }, "execution_count": 2, "metadata": {}, "output_type": "execute_result" } ], "source": [ "search = lk.search_targetpixelfile('TIC 307210830 c')\n", "search" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Our object of interest can be found in seven sectors. Let's take the first sector, sector 2 and download that." ] }, { "cell_type": "code", "execution_count": 3, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "TessTargetPixelFile(TICID: 307210830)" ] }, "execution_count": 3, "metadata": {}, "output_type": "execute_result" } ], "source": [ "tpf = lk.search_targetpixelfile('TIC 307210830 c', sector=2).download()\n", "tpf" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Creating and analizing the LightCurve Object" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Great we now have our TPF! Lets convert this TPF into a `TessLightCurve` object using the [`to_lightcurve`](https://docs.lightkurve.org/api/lightkurve.targetpixelfile.TessTargetPixelFile.html#lightkurve.targetpixelfile.TessTargetPixelFile.to_lightcurve) function. \n", "\n", "To create the SAP lightcurve we will pass an **aperture_mask** to the `to_lightcurve` function. The default is to use the [`SPOC`](https://heasarc.gsfc.nasa.gov/docs/tess/pipeline.html) pipeline aperture, which sums all the pixels in its defined mask." ] }, { "cell_type": "code", "execution_count": 4, "metadata": {}, "outputs": [ { "data": { "text/html": [ "TessLightCurve targetid=307210830 length=18317\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "
timefluxflux_errcentroid_colcentroid_rowcadencenoquality
electron / selectron / spixpix
objectfloat32float32float64float64int32int32
1354.108823127242721566.34960937516.116119384765625664.6090864691554339.4764484490161911910
1354.110211988899421563.8867187516.118038177490234664.6261723169015339.46842003296774911920
1354.11298971215321475.16210937516.089221954345703664.606630403678339.4604662968742911940
1354.114378573809721583.3085937516.12527084350586664.6414481151693339.4832617761526911950
1354.115767435524321575.64062516.121679306030273664.6354584758038339.4735678477034911960
1354.117156297180421563.101562516.115528106689453664.6334974032626339.472138768046911970
1354.118545158894721552.93554687516.112627029418945664.625177003332339.46675685339096911980
1354.119934020551521532.9023437516.10567855834961664.6301979867933339.4699372207359911990
1354.121322882266721533.82812516.105731964111328664.6262018316135339.46553338843912000
.....................
1381.500103252329421262.49414062516.291688919067383664.5744500858646339.35132780163921109130
1381.501492120737821289.82812516.302898406982422664.5797804765874339.34913985203471109140
1381.502880989145821266.351562516.29288673400879664.5790106545255339.35133129076251109150
1381.504269857438221234.84570312516.279603958129883664.5730941550626339.35556313817051109160
1381.505658725846621244.95312516.281909942626953664.5782007755507339.34683164655671109170
1381.507047594255521210.757812516.267162322998047664.5770708377116339.34423590600691109180
1381.50843646254821231.0117187516.27315330505371664.5786574675517339.342172455105361109190
1381.509825330956321250.46679687516.277507781982422664.5722297003167339.35132729757531109200
1381.511214199248821236.3554687516.2720890045166664.582152318805339.34521784277111109210
1381.512603067657721265.8398437516.278945922851562664.5729270180528339.3497104930431109220
" ], "text/plain": [ "\n", " time flux flux_err ... cadenceno quality\n", " electron / s electron / s ... \n", " object float32 float32 ... int32 int32 \n", "------------------ --------------- ------------------ ... --------- -------\n", "1354.1088231272427 21566.349609375 16.116119384765625 ... 91191 0\n", "1354.1102119888994 21563.88671875 16.118038177490234 ... 91192 0\n", " 1354.112989712153 21475.162109375 16.089221954345703 ... 91194 0\n", "1354.1143785738097 21583.30859375 16.12527084350586 ... 91195 0\n", "1354.1157674355243 21575.640625 16.121679306030273 ... 91196 0\n", "1354.1171562971804 21563.1015625 16.115528106689453 ... 91197 0\n", "1354.1185451588947 21552.935546875 16.112627029418945 ... 91198 0\n", "1354.1199340205515 21532.90234375 16.10567855834961 ... 91199 0\n", "1354.1213228822667 21533.828125 16.105731964111328 ... 91200 0\n", " ... ... ... ... ... ...\n", "1381.5001032523294 21262.494140625 16.291688919067383 ... 110913 0\n", "1381.5014921207378 21289.828125 16.302898406982422 ... 110914 0\n", "1381.5028809891458 21266.3515625 16.29288673400879 ... 110915 0\n", "1381.5042698574382 21234.845703125 16.279603958129883 ... 110916 0\n", "1381.5056587258466 21244.953125 16.281909942626953 ... 110917 0\n", "1381.5070475942555 21210.7578125 16.267162322998047 ... 110918 0\n", " 1381.508436462548 21231.01171875 16.27315330505371 ... 110919 0\n", "1381.5098253309563 21250.466796875 16.277507781982422 ... 110920 0\n", "1381.5112141992488 21236.35546875 16.2720890045166 ... 110921 0\n", "1381.5126030676577 21265.83984375 16.278945922851562 ... 110922 0" ] }, "execution_count": 4, "metadata": {}, "output_type": "execute_result" } ], "source": [ "lc = tpf.to_lightcurve(aperture_mask=tpf.pipeline_mask)\n", "lc" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "We've built a new `TESSLightCurve` object called `lc`. Note although we used the SPOC aperture mask you can pass your own aperture, (specified by a boolean `numpy` array) as seen in the [Making Custom Apertures tutorial](Making-Custom-Apertures.html).\n", "\n", "The above table displays all the lightcurve data. " ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Metadata\n", "\n", "`TESSLightCurve` objects have many useful functions that you can use. As with a TPF you can access the meta data very simply." ] }, { "cell_type": "code", "execution_count": 5, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "2" ] }, "execution_count": 5, "metadata": {}, "output_type": "execute_result" } ], "source": [ "lc.sector" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Of course you still have access to time and flux attributes. In a lightcurve, there is only one flux point for every cadence. " ] }, { "cell_type": "code", "execution_count": 6, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "(,\n", "