Getting Started

Welcome! You’ve found the documentation for elk, good for you!

You should know that this package relies heavily on lightkurve and I recommend you check out their documentation as well.

Okay, let’s get into this!

Basic imports

For more of the examples that I give in this documentation you’re probably going to need the following basic imports. You can always read more about numpy and astropy.units at those respective links.

import numpy as np
import astropy.units as u
import pandas as pd
import matplotlib.pyplot as plt

Generate your First Ensemble Light Curve

The central class in this package is EnsembleLC. The class gives you access to the functionality of the entire package with one convenient interface. This class will be the platform for all of our light curves.

For initializing our class we need a couple of things: a path to a folder in which to store the output, an identifier and location of a source that you want to analyse, a cluster age and radius, and a TESSCut cutout size. We also set verbose=True to allow elk to talk to us about what it is doing.

from elk.ensemble import EnsembleLC

c = EnsembleLC(output_path="../../output",
               identifier='NGC 330',
               location='14.031366421592, -72.463926813705',
               radius=.042,
               cutout_size=99,
               verbose=True)

Though this class is initialised, we still need to run the commands to correct the light curves.

elk is designed to query the TESS Full Frame Image (FFI) data based on your specified location for each available Sector of observation for your target.

In order to begin the correction of these light curves, you can run the create_output_table() function. This function makes use of the lightcurve classes, the details of which will be the subject of future tutorials.

c.create_output_table()

NGC 330 has 3 observations
Starting Quality Tests for Observation: 0
  Failed General Quality Test 
Starting Quality Tests for Observation: 1
  Failed General Quality Test 
Starting Quality Tests for Observation: 2

100%|█████| 9801/9801 [1:13:48<00:00,  2.21it/s]

  Passed Quality Tests 

This function has just

• Downloaded each available Sector of observation

• Tested the observation for being too close to the edge of the detector

• Corrected the light curve for systematics

• Tested the corrected light curve for residual scattered light

• Computed the swath of variabilty metrics for light curves that passed all quality checks

Notice how the the first 2 Sectors did not pass the quality tests, but the third one did!

We have fairly strict quality tests to ensure the highest quality integrated light curves. These tests can be read about further in Section 3.3 of Wainer+2023. Briefly, The general quality test primarily tests if the target is located too close the edge of a detector to perform uniform background analysis. If the general quality test fails, we do not provide a way to force the extraction. The scattered light test quantifies the amount of residual scattered light after the correction. If you wish to ignore this test, in EnsembleLC you can set “ignore_scattered_light” to True.

In order to access this light curve which passed these tests, do:

lc = c.lcs[2]
lc

<TESSCutLightcurve: TESS Sector 28, 3449 timesteps>

The 2 represents the indice where the good observation is located. There will no return for c.lcs[0], and c.lcs[1].

Observe the type of object returned: TESSCutLightcurve

This type of object has access to all of the tpfs information for this sector. This includes the pixel flux map, which can be desplayed by:

lc.tpfs.plot()

<Axes: title={'center': 'Target ID: 14.031366421592, -72.463926813705, Cadence: 0'}, xlabel='Pixel Column Number', ylabel='Pixel Row Number'>

If you have previously downloaded and corrected the light curve for this sector, when you run the class again you will see:

c = EnsembleLC(output_path="../../output",
               identifier='NGC 330',
               location='14.031366421592, -72.463926813705',
               radius=.042,
               cutout_size=99,
               verbose=True)


c.create_output_table()

Found previously corrected data for this target, loading it! (Set `ignore_previous_downloads=True` to ignore data)

And now the only returned lightcurve will be the one good sector observation, and the returned lightcurve will be ‘BasicLightcurve’ which does not have any saved tpfs information.

c.lcs

[<BasicLightcurve: TESS Sector 28, 3449 timesteps>]

To plot the light curve you can simply:

lc.plot()

(<Figure size 1200x800 with 1 Axes>,
 <Axes: title={'center': 'Lightcurve for Sector 28'}, xlabel='Time $\\rm [days]$', ylabel='Flux $[e / {\\rm s}]$'>)

For more investigation into your light curve, please visit: analysis

Note

This tutorial was generated from a Jupyter notebook that can be found here.