API

Transit Tools is centered around the lightcurve constructor object with many different analysis tools integrated as methods into the class.

Constructor

It is possible to initialize a lightcurve object by providing a lightkurve.LightCurve object, providing the time, flux, and optionally flux error arrays, or by providing a target name to instruct the constructor to retrieve or extract a light curve from archival data. lightcurve also has the capability to simulate a light curve using BATMAN and optionally inject it into a specified existing light curve.

class transit_tools.lightcurve(*args, lc=None, obj=None, method='2min', sector=None, mission='TESS', find_knownpls=True, values='all', **kwargs)

Initialization function for all of transit_tools that defines the light curve to be used. This class wraps lightkurve.LightCurve and as such retains all functionality of that class with some additions. The light curve can either be user-defined with a lightkurve.LightCurve object or arrays of time, flux, and flux error or can be generated via a target name.

Parameters

• lc (lightkurve.LightCurve or None) – lightkurve.LightCurve object. Mutually exclusive with *args and obj inputs. Default None.

• *args – Up to three arguments specifying the time, flux, and flux error of the light curve. Mutually exclusive with lc and obj inputs.

• obj (str or None) – Name of target to search MAST for a light curve. Mutually exclusive with lc and *args inputs. Default None.

• method (str) – Method for acquiring a specified light curve through a search of MAST. Options are currently '2min', 'eleanor', and 'batman'. If 'batman' is provided, user will also need to pass **kwargs to the transit_tools.batman function. Default is '2min'.

• sector (list or None) – List of sectors to include in final assembled light curve. If None is specified, all possible sectors will be included. Default None.

• mission (str) – Current placeholder. Will eventually allow user to specify mission from which light curve will be assembled. At this point, only TESS is supported.

• find_knownpls (bool) – Flag to control whether a query to the NASA Exoplanet Archive is searched for any known planets in the target system. Default True.

• values (list or str) – Quantities to retrieve from the NASA Exoplanet Archive if find_knownpls is True. If set to 'all', all available quantities will be retrieved. Default 'all'.

• **kwargs (dict) – Additional arguments to pass to lighturve.LightCurve initializer.

time

The timestamps of the light curve.

Type

np.array

flux

The flux at each timestamp in the light curve.

Type

np.array

flux_err

The flux error for each flux in the light curve.

Type

np.array

method

The method used to generate the light curve.

Type

str or None

sector

The list of sectors the generated light curve represents.

Type

list

name

The name of the target from the light curve query.

Type

str or None

tic

TIC ID of target, if it has one.

Type

int

known_pls

The known planets in the system, if any.

Type

np.array of dicts or None

star_params

A dictionary containing known star params if a query for such has been performed.

Type

dict

star_params_tls

The star params used for Transit Least Squares searches, if such a search has been run.

Type

dict

raw_lc

Nested lightcurve object with time, flux, and flux_err attributes of the original input lightcurve prior to processing or masking.

Type

object

trend

Trend of light curve based on the process method, if detrending was performed.

Type

np.array

mask_arr

Boolean array of equal length to the light curve mapping the masked data points.

Type

np.array

routine

The shape used by the most recent Transit Least Squares search on the light curve.

Type

str

sde_thresh

The Signal Detection Efficiency threshold for a significant detection specified in the most recent Transit Least Squares search.

Type

float

results

Output results of each iteration of transit searches from the most recent call of the signal_search method.

Type

np.array of dicts

cleanlc

Light curves with significant periodic signals from the most recent call of the signal_search method subtracted.

Type

list of objects

bad_search

Results from the most recent call of signal_search that did not meet the specified sde_thresh value.

Type

dict

blsobjs

List of dicts containing the BLS periodogram objects produced by each BLS run in the most recent BLS run.

Type

list of dicts

binlc(**kwargs)

Method to bin the light curve. Wraps the lightkurve.LightCurve.bin function.

Parameters

**kwargs – Additional arguments that will be passed to the lightkurve.LightCurve.bin function.

get_starparams(cat='all')

Method to gather stellar parameters and save them as the star_params and stellar_params_tls attributes.

Parameters

• cat (str) – Specify which calatog to retrieve stellar parameters from. If 'all' is entered, values will be gathered from the Gaia DR2 and TESS Input Catalog, with the Gaia DR2 taking precedence

• **kwargs (dict) – Additional arguments to be passed to the 'utils.catalog_info' command.

mask(**kwargs)

Method to mask out parts of the light curve. Wraps the lcprocess.mask function. Can be performed iteratively to mask out multiple areas or ranges of times in the light curve.

Parameters

**kwargs (dict) – Arguments to be passed to transit_tools.lcprocess.mask, with the exception of the out_mask argument.

process(**kwargs)

Method to process light curve for further analysis. Must be performed on a lightkurve.LightCurve object.

Parameters

**kwargs (dict) – Arguments to be passed to the process_lc.

reset()

Method to bring the raw, original light curve back as the main, working light curve. Useful if the user is testing different processing methods and does not wish to reload a ‘lightcurve’ instance after each one.

searchsum()

Method to display periodic signal search results in a user-friendly format. Wraps search_summary from utils.py.

signal_search(routine='tls', plot_live=False, max_runs=5, sde=7.0, exact=False, **kwargs)

Method to search the light curve for periodic signals using a variety of search algorithms, including Transit Least Squares and Box Least Squares from a number of packages.

Parameters

• routine (str) – The desired routine to be used for finding periodic signals in the light curve. Options are ‘tls’ for Transit Least Squares and ‘bls’ for Box Least Squares.

• plot_live (bool) – Placeholder argument for the option to view vetting plots as runs are finished for a more interactive transit search.

• max_runs (int) – The maximum number of runs allowed. This will be the number of runs for BLS runs.

• sde (float) – The threshold for the Source Detection Efficiency to be used to determine whether a signal is significant or not in TLS runs.

• exact (bool) – Flag to indicate that the exact number of iterations specified in max_runs will be performed.

update_pls(name=None, per=None, t0=None, dur=None, params=None, append=False)

Method to update the lightcurve.known_pls attribute with user-defined values or a provided dictionary.

Parameters

• name (str or list or None) – Name(s) of the planets.

• per (float,` np.array` or None) – Period of the planet(s). Will expect a period in days.

• t0 (float, np.array or None) – Mid-transit time(s) of the first transit(s). Will expect a value in MJD.

• dur (float, np.array or None) – Duration of transit(s). Will expect a value in days.

• params (dict, list or None) – Dictionary of additional parameters or all orbital parameters. Will expect keys similar to those output by transit_tools.utils.known_pls.

• append (bool) – Flag whether or not to append provided planet parameters as a new entry in the lightcurve.known_pls attribute or to overwrite the current entry with the user-provided values.

vetsheet(pls='all', routine=None, save=False, **kwargs)

Method to plot the vetting sheet for a given set of signal_search results.

Parameters

• pls (int or str) – signal_search iteration to display results for. If set to ‘all’, all significant results will be displayed in separate windows. If set to -1, the most recent set of results that did not meet the significance threshold will be displayed.

• routine (str) – The search routine that you would like to plot the vetsheets for. Currently 'tls' and 'bls' are supported. Default is whichever was most recently run.

• save (bool) – Flag to determine whether the plot is saved or not. Save filename is specified and passed as a part of **kwargs**.

• **kwargs (dict) – Additional arguments to be passed to the transit_tools.plotting.tls_vetsheet command.

Standalone Analysis Functions

Many of the analysis functions that are wrapped into the lightcurve object can also be run as standalone functions through the Transit Tools package.

Light Curve Fetching

transit_tools.gather_lc(coords=None, tic=None, name=None, cadence='shortest', ffi_only=False, sectors='all', eleanor_flag=False, return_method=False, return_sectors=False, obsinfo=None, verbose=False, **kwargs)

Function to gather the light curve of a given TIC using the specified method. Currently, 2 minute SPOC pipeline light curves, machine learning FFI light curves, and eleanor light curves are supported.

Parameters

• coords (tuple or array) – Coords of input

• name (string) – common name

• ffi_only (bool) – whether to default to 2min or have everything be ffis

• tic (int) – TESS Input Catalog ID for desired target. At this time, common names are not accepted input, only TIC IDs.

• sectors (str or list or numpy array) – List of sectors to be included in the fetching of the light curve. If ‘all’ or None is passed, all available light curves will be fetched. Thresholds can be passed according to the valid syntax of the method specified.

• return_method (bool) – A flag to indicate whether the method used to gather the light curve will be returned. Useful if the chosen method is not known or expected to return a valid light curve. An additional output will be expected.

• return_sectors (bool) – A flag to indicate the sectors that the light curve was recovered from. An additional output will be expected. Currently in progress for most methods.

• obsinfo (dict) – A dictionary of observational information that can be passed to make some processes run faster if inlc is specified. Assumes output format of transit_tools.tessobs_info command.

• **kwargs – Additional arguments to be passed to the selected method fetching function.

Returns

• lc (‘LightCurve’) – Light curve containing light curves from all sectors contained within the query of sectors.

• method (str, optional) – The method with which the output light curve was gathered.

• sectors (numpy array, optional) – The sectors that the light curve was gathered from.

transit_tools.get_eleanor(sectors='all', tic=None, coords=None, out_sec=False, height=15, width=15, bkg_size=31, do_psf=False, do_pca=False, out_flux='corr_flux', norm=True, errorcalc=True, qual_flag=True)

Function to get a light curve from the TESS full frame images (FFIs) using the Python package eleanor.

Parameters

• sectors (str or array or list) – The sectors that eleanor will use to produce the light curve. If set to ‘all’, then all available sectors will be used in the light curve production.

• tic (int or None) – TIC ID for the object that a light curve is desired for. If set to None, coords must have a valid input.

• coords (tuple of floats) – The RA and Dec of the object that a light curve is desired for. Must be of the form (RA, Dec) in decimal degrees. If set to None, the tic argument cannot be None.

• out_sec (bool) – Flag controlling whether an array containing the sectors used to extract the light curve will be output. If True, an additional output will be expected.

• height (int) – Height in pixels of the postage stamp with which to extract the light curve.

• width (int) – Height in pixels of the postage stamp with which to extract the light curve.

• bkg_size (int) – Background size to be considered for the background subtraction from the light curve.

• do_psf (bool) – Flag to determine whether a PSF-corrected light curve will be generated as an additional option to the corrected light curve.

• do_pca (bool) – Flag to deteremine whether a PCA-corrected light curve will be generated as an additional option to the corrected light curve.

• out_flux (str) – Which of the light curves to output. Options are ‘corr_flux’, ‘psf_flux’, and ‘pca_flux’. Only one may be selected. If either ‘psf_flux’ or ‘pca_flux’ are selected, the do_psf and do_pca flags must be set to True, respectively.

• norm (bool) – Flag determining whether the light curve will be normalized prior to output.

• errorcalc (bool) – Flag determining whether the RMS errors will be calculated for the light curve.

• qual_flag (bool) – Flag determining whether the timestamps with bad quality flags will be excluded automatically.

Returns

• lc (‘LightCurve’ object) – The combined light curve from each sector for the coordinates or TIC ID requested.

• sectors (array) – Optional output array containing the sectors that the combined light curve was extracted from.

Transit Search

transit_tools.tls_search(*args, tic=None, shape='default', star_params=None, rms_calc=True, norm_val=1.0, clean_lc=False, starparams_out=False, del_dur=1.0, verbose=False, nthreads=6, **kwargs)

Function to perform a search for periodic signals using the Transit Least Squares (TLS) algorithm developed by Hippke & Heller 2018. While slower than Box Least Squares, the transit shape used in the search is more realistic.

Parameters

• *args (lightkurve.LightCurve object or multiple numpy array arguments) – If the len = 1, then the argument is assumed to be a lightkurve.LightCurve object with at least two columns, labeled 'time' and 'flux', respectively, with an optional 'flux_err' column as the third column. If the len of > 1, then it is assumed the user is passing time, flux, and flux_err (optional), respectively. These columns or arguments should be arrays of equal length.

• tic (int or None) – TIC ID of the source that the light curve comes from. This will be used to query the TIC for the stellar parameters of the system. May be set to None if a full dictionary of stellar params are provided to the star_params keyword.

• shape (str) – The shape used by TLS to search for periodic signals. The user may specify 'default', 'grazing', or 'box'. See Hippke & Heller 2018 for an in-depth description of these shapes.

• star_params (dict or None) – A dictionary containing stellar parameters to be used in the TLS search. The dictionary can contain an array of limb-darkening parameters, stellar radius, lower radius error, upper radius error, stellar mass, lower mass error, and upper mass error labeled 'ab', 'rstar', 'rlow', 'rhigh', 'mstar', 'mlow', and 'mhigh', respectively. The error values are the errors themselves and not the upper and lower values for each of the parameters. A partial list may be included, but in this case, the TIC must also be given.

• rms_calc (bool) – A flag to denote whether the root mean square error will be applied in the case that error values are not provided.

• norm_val (float) – Value that the light curve is normalized to. Default is 1. Only 1 or 0 are valid normalizations for TLS.

• clean_lc (bool) – Flag to indicate whether or not to output a cleaned lightcurve with the recovered periodic signal masked out. Results in an additional expected output. Default False.

• starparams_out (bool) – Flag to indicate whether or not to output the dictionary of stellar parameters used in the TLS search. Results in an additional expected output.

• del_dur (float) – How many durations worth of data points should be excluded from cleaned light curve centered on the transit center. Default is 1. Values < 1 will result in some in-transit points remaining while values > 1 will remove some points outside the transit.

• verbose (bool) – Flag to have function print more while it runs.

• nthreads (int) – Number of threads to be used for running the signal search. Many times, cores have the capability to run multiple threads, so be sure to check your machine to optimize this parameter.

• **kwargs (dict) – Optional arguments passed to the transitleastsquares.power function.

Returns

• results (dict) – Results of the TLS fit. See TLS documentation for the contents of this dictionary and descriptions of each element.

• cleaned_lc (lightkurve.LightCurve object, optional) – A light curve with the transits masked out based on the results of the TLS search.

transit_tools.bls_search(*args, minimum_period=1, maximum_period=None, frequency_factor=1, per_trials=10000, period=None, rms_calc=True, clean_lc=False, del_dur=1.0, blsobj_out=False)

Function to search a light curve using the Box Least Squares function

Parameters

• *args – either t, f , f_err or lightkurve obj

• minimum_period (float) – Minimum of period range to search. Default 0.1.

• maximum_period (float or None) – Maximum of period range to search in same units of the light curve. If None, defaults to half the duration of the light curve.

• per_trials (int or None) – Number of trials to search in the period range. Default is 10000. Might consider deprecating.

• periods (np.array) – User can specify exact periods to sample rather than the min, max, and number of trials.

• frequency_factor (float) – Spacing between frequencies. Used to generate period search grid.

• rms_calc (bool) – If the RMS should be calculated in the event of no error input.

• clean_lc (bool) – Flag to indicate whether or not to output a cleaned lightcurve with the recovered periodic signal masked out. Results in an additional expected output. Default False.

• del_dur (float) – How many durations worth of data points should be excluded from cleaned light curve centered on the transit center. Default is 1. Values < 1 will result in some in-transit points remaining while values > 1 will remove some points outside the transit.

• blsobj_out (bool) – Flag to determine if the bls periodogram object will be included in the outputs. If True, another output will be expected. Default False.

• **kwargs – Additional arguments to be passed to lightkurve.BoxLeastSquaresPeriodogram.from_lightcurve and astropy.timeseries.BoxLeastSquares.power.

Returns

• results (dict) – Results of the BLS fit.

• cleaned_lc (lightkurve.LightCurve object, optional) – A light curve with the transits masked out based on the results of the BLS search.

Plotting

transit_tools.get_starfield(tic, sectors=None, aperture=None, cadence='2min', depth=None, target_out=False, show_plots=True)

Function to fetch and display the stars around a TESS target.

Parameters

• tic (int) – TIC ID for the desired target source.

• sectors (array or list or None) – TESS sectors in which the target was observed. If None, all valid observed sectors will be collected and used.

• aperture (numpy array or None) – Array of aperture arrays with pixel coordinates of the form [col, row] for each pixel included in the aperture for each TESS sector. If None, the apertures will attempt to be

Light Curve Simulation

Signal Vetting/Validation

transit_tools.calcfpp_tr(lc=None, *args, period=None, t0=None, depth=None, tic=None, binsize=1, folded=False, target_in=None, target_out=False, show_plots=True, **kwargs)

Function to calculate the FPP for a signal using TRICERATOPS.

Parameters

• lc (object) – Object that contains a folded light curve with time in units of days from midtransit and flux normalized to 1. At minimum, this must contain time and flux attributes, but may contain flux_err as well.

• *args – Time, flux, and optional flux_err arguments. Arguments passed must be arrays containing time from midtransit in days, flux normalized to 1, and optionally flux_err for each data point. lc must be None for args to be specified.

• period (float) – Orbital period of the signal in days. Not required if input light curve is already folded.

• depth (float) – Depth of midtransit. Not required if target_in is not None.

• sectors (array or list) – Array or list of sectors in which this signal was observed. Not required if target_in is not None.

• binsize (int) – Number of points per bin for binning the folded light curve.

• folded (bool) – Flag indicating if the light curve input is folded or not.

• target_in (object) – Input target object if TRICERATOPS has been run previously or the get_starfield plot has been run. Default is None.

• target_out (bool) – Flag to indicate whether the target object used in this function should be returned. If True, an additional output will be expected.

Returns

target – Optional output containing the target object used in the TRICERATOPS run in this function.

Return type

object

Utility Functions

There are some functions included in Transit Tools that do not perform analysis of a light curve but instead are simply used as helper functions.

transit_tools.catalog_info(tic=None, ra=None, dec=None, cat='all', out_cat=False)

Function to fetch catalog info about the target system from various catalogs. The GAIA catalog takes precedence over the TIC in the values where they overlap, such as RA and Dec.

Parameters

• tic (int or None) – TIC ID of target object. If None, ra and dec must both not be None.

• ra (float or None) – RA of target object. If None, tic must not be None.

• dec (float or None) – Dec of target object. If None, tic must not be None.

• cat (string) – Catalog(s) to be queried. Currently, only ‘tic’ and ‘gaia’ are supported.

• out_cat (bool) – Flag determining whether the catagories searched will be output as an array of strings. If True, an additional output will be expected.

Returns

• info (dict) – Dictionary of stellar parameters for target object.

• catalogs (array, optional) – Array containing strings denoting which catalogs were queried for stellar parameters.

transit_tools.tessobs_info(tic=None, ra=None, dec=None)

Function to retrieve observation information for objects observed by TESS.

Parameters

• tic (int or None) – TIC ID of target to be queried. Must not be None if ra and dec are None.

• ra (float or None) – RA of target to be queried. Must not be None if tic is None.

• dec (float or None) – Dec of target to be queried. Must not be None if tic is None.

Returns

info – Dictionary continaing TESS observation info.

Return type

dict

transit_tools.coord_to_tic(ra, dec)

Function to convert input RA and Dec coordinates to the nearest TIC ID from the TESS Input Catalog (TIC).

Parameters

• ra (float) – The RA of the target source.

• dec (float) – The Dec of the target source.

Returns

tic – TIC ID of the source nearest to the input RA and Dec from the TIC.

Return type

int

transit_tools.known_pls(name=None, ra=None, dec=None, radius=5.0, table='ps', values='all', verbose=False)

A function to gather information on any known planets in a given system. Queries the NASA Exoplanet Archive for objects and their known parameters.

Parameters

• name (str) – Common name of the system being checked. Optional if RA/Dec are provided.

• ra (float) – RA in decimal degrees. Optional if name is provided. If provided, Dec is also required.

• dec (float) – Dec in decimal degrees. Optional if name is provided. If provided, RA is also required.

• radius (float) – Radius in arcseconds around which the provided RA and Dec will be searched for planets.

• table (str) – Specifies the table to search for planet parameters. See documentation on the Exoplanet Archive website for a full list of possible tables and their contents. Default is the ‘exoplanets’ table, which is the default for the Exoplanet Archive.

• values (str) – Specifies how many values are collected. Current supported options are ‘minimum’ and ‘all’.

• verbose (bool) – Flag to determine whether some of the parameters of the known planets in the system are printed.

Returns

info – List containing a dictionary of all known planet parameters for each planet in the queried system.

Return type

list of dicts

transit_tools.name_to_tic(name)

Function to convert common name to TIC ID. Queries the MAST for TIC entry nearest to known position for common name.

Parameters

name (str) – Common name to be converted to TIC.

Returns

tic – TIC ID of closest match to input name’s position from TIC on MAST.

Return type

int

transit_tools.tic_to_name(tic, ra=None, dec=None)

Function to determine the common name of a TIC ID or given RA/Dec position, if it has one. Queries the MAST and Simbad to gather this information.

!!Keysort so planet doesn’t come first?!!

Parameters

• tic (int) – The TIC ID of the object for which the common name is desired.

• ra (float) – The RA in decimal degrees. Optional with Dec to circumvent querying MAST.

• dec (float) – The Dec in decimal degrees. Optional with TA to circumvent querying MAST.

Returns

name – The common name of the input TIC ID.

Return type

str

transit_tools.rms(data, norm_val=1.0)

Calculates the Root Mean Square of the provided data.

Parameters

• data (numpy array) – Data for which the root mean square will be calculated

• norm_val (float or numpy array) – The value(s) that the data array is normalized to or the value of the model that the data values are being compared against if RMS is non- uniform.

Returns

rms – The calculated root mean square of the data.

Return type

float

transit_tools.canonical_name(name)

Function to obtain the canonical name of an object from the MAST.

Parameters

• name (str) – Name of object to be queried for canonical name.

• Results –

• ------- –

• canonical_name (str) – Canonical name of the object according to the MAST.