QuickLook

quicklook is a Python program that runs a simple pipeline to search for transit signal in TESS (and Kepler soon) light curves. This program can be run in a jupyter notebook (see example) or from the terminal using the ql script.

Use case

Given target name, run periodogram on a TESS or Kepler lightcurve (if it exists) to estimate the stellar rotation period and the orbital period of a potential companion i.e. planet, brown dwarf, or star. Although quicklook is optimized to find transiting exoplanets, this tool can also find eclipsing binaries and many other periodic signals.

Try it on Google colab

Installation

Create a conda environment called, say my_env, and install there an editable version of quicklook

$ conda create -n my_env python=3.10
$ conda activate my_env
(my_env) $ python -m python -m pip install -r https://raw.githubusercontent.com/jpdeleon/quicklook/main/requirements.txt
(my_env) $ python -m pip install -e git+https://github.com/jpdeleon/quicklook.git#egg=quicklook

If you want to run quicklook in a notebook, you also need to install jupyter

(my_env) $ python -m pip install jupyterlab

Command line script

(my_env) $ ql
usage: ql [-h] [--name NAME] [--sector SECTOR] [--fluxtype {pdcsap,sap}] [--pipeline {spoc,tess-spoc,tasoc,cdips,pathos,qlp,tglc}] [--exptime EXPTIME] [--flatten_method FLATTEN_METHOD] [--pg_method {gls,ls,bls}] [--window_length WINDOW_LENGTH]
          [--edge_cutoff EDGE_CUTOFF] [--sigma_clip_raw SIGMA_CLIP_RAW SIGMA_CLIP_RAW] [--sigma_clip_flat SIGMA_CLIP_FLAT SIGMA_CLIP_FLAT] [--period_limits PERIOD_LIMITS PERIOD_LIMITS] [-save] [--outdir OUTDIR] [-verbose] [-overwrite]
          [--survey {dss1,poss2ukstu_red,poss2ukstu_ir,poss2ukstu_blue,poss1_blue,poss1_red,all,quickv,phase2_gsc2,phase2_gsc1}] [--custom_ephem CUSTOM_EPHEM CUSTOM_EPHEM CUSTOM_EPHEM CUSTOM_EPHEM CUSTOM_EPHEM CUSTOM_EPHEM] [-mask_ephem]

Run a quick look analysis of a TESS lightcurve. Note: use single hyphen (-flag) if no value is needed. Note: use double hyphen (--flag value) if value is needed.

options:
  -h, --help            show this help message and exit
  --name NAME           target name
  --sector SECTOR       TESS sector (default=-1 (last available sector))
  --fluxtype {pdcsap,sap}
                        type of lightcurve
  --pipeline {spoc,tess-spoc,tasoc,cdips,pathos,qlp,tglc}
                        lightcurve produced from which pipeline (default=SPOC)
  --exptime EXPTIME     exposure time (default is whatever is used in available sector)
  --flatten_method FLATTEN_METHOD
                        wotan flatten method (default=biweight)
  --pg_method {gls,ls,bls}
                        periodogran method (default=gls)
  --window_length WINDOW_LENGTH
                        flatten method window length (default=0.5 days)
  --edge_cutoff EDGE_CUTOFF
                        cut each edges (default=0.1 days)
  --sigma_clip_raw SIGMA_CLIP_RAW SIGMA_CLIP_RAW
                        (sigma_lo,sigma_hi) for outlier rejection of raw lc before flattening/detrending
  --sigma_clip_flat SIGMA_CLIP_FLAT SIGMA_CLIP_FLAT
                        (sigma_lo,sigma_hi) for outlier rejection of flattened/detrended lc
  --period_limits PERIOD_LIMITS PERIOD_LIMITS
                        period limits in TLS search; default=(0.5, baseline/2) d
  -save                 save figure and tls
  --outdir OUTDIR       output directory
  -verbose              show details
  -overwrite            overwrite files
  --survey {dss1,poss2ukstu_red,poss2ukstu_ir,poss2ukstu_blue,poss1_blue,poss1_red,all,quickv,phase2_gsc2,phase2_gsc1}
                        archival image survey name if using img option (default=dss1)
  --custom_ephem CUSTOM_EPHEM CUSTOM_EPHEM CUSTOM_EPHEM CUSTOM_EPHEM CUSTOM_EPHEM CUSTOM_EPHEM
                        custom ephemeris in days. Example: --custom_ephem P Perr Tc Tcerr Tdur Tdurerr
  -mask_ephem           mask transits either using TFOP or custom ephemerides if available (default=False)

Examples

Run quicklook on TOI 1150.01's most recent TESS lightcurve

(my_env) $ ql --name TOI-1150

The figure above shows 9 panels. Let's break them down.

top row
- left (panel 1): raw lightcurve (blue marker) and trend (red line)
- middle (panel 2): Lomb-Scargle periodogram used to estimate the star's rotation period; this is useful to find active and variable stars
- right (panel 3): raw lightcurve phase-folded at the computed peak of Lomb-Scargle periodogram (corresponding to the stellar rotation period) from panel 1;
middle row
- left (panel 4): flattened lightcurve and detected transits (determined from the TLS periodogram on panel 5)
- middle (panel 5): periodogram using the transit least squares (TLS) algorithm
- right (panel 6): TESS aperture (blue polygon) and annotated Gaia sources (orange and red markers) overlaid on archival DSS image centered on the target; this is useful to see if there are potential sources of the signal other than the target
bottom row
- left (panel 7): phase-folded lightcurve at the derived peak of TLS periodogram (corresponding to the orbital period); odd (red markers) and even transits (blue markers) and best-fit transit model (black line) are also shown
- middle (panel 8): phase-folded lightcurve zoomed at phase=0.5 to check for a secondary eclipse which is a strong indicator of a self-luminous companion such as an eclipsing binary or a high-albedo brown dwarf; the computed transit depth (dashed line) is shown for reference
- right (panel 9): summary info about the star and potential companion (e.g. planet candidate)

Try changing the parameters:

(my_env) $ ql --name TIC52368076 -verbose -save | tee output.log
(my_env) $ ql --name TOI-125.01 --pipeline qlp #specific pipeline
(my_env) $ ql --name TOI-125.01 --sector 2 #specific TESS sector
(my_env) $ ql --name TOI-125.01 --flatten_method cosine #specific function to detrend baseline
(my_env) $ ql --name TOI-125.01 --period_limits 1 5 #limit search between 1-5 days

Advanced usage

If you would like to run ql on a list of TIC IDs (saved as tic_ids.txt), then you can make a batch script named run_ql_given_tic.batch. The output files containing the plots (.png) and periodogram results (_tls.h5) will be saved in tic_dir directory:

(my_env) $ cat tic_ids.txt | while read tic; do echo ql --name TIC$tic -save --outdir tic_dir > TIC$tic.log 2>&1; done > run_ql_given_tic.batch

To test the Nth line of the batch script,

(my_env) $ cat run_ql_given_tic.batch | sed -n Np | sh

To run all the lines in parallel using GNU parallel with N cores,

(my_env) $ cat run_ql_given_tic.batch | parallel -j N

After the batch script is done running, we can rank ql output in terms of Signal Detection Efficiency (SDE, See Hippke et al. 2019) using read_tls script:

(my_env) $ read_tls tic_dir