API

class eleanor.Source(tic=None, gaia=None, coords=None, fn=None, sector=None, fn_dir=None)

A single source observed by TESS.

Parameters:

• tic (int, optional) – The TIC ID of the source.
• gaia (int, optional) – The Gaia DR2 source_id.
• coords (tuple or astropy.coordinates.SkyCoord, optional) – The (RA, Dec) coords of the object in degrees or an astropy SkyCoord object.
• fn (str, optional) – Filename of a TPF corresponding to the desired source.
• sector (int or str) – The sector for which data should be returned, or recent to obtain data for the most recent sector which contains this target.

tess_mag

The TESS magnitude from the TIC.

Type:float

sector

Sector in which source was observed by TESS.

Type:int

camera

TESS camera on which source falls.

Type:int

chip

TESS chip on which source falls.

Type:int

position_on_chip

Predicted (x,y) coords of object center on chip.

Type:(int, int)

postcard

Name of the best postcard (postcard where source should be located closest to the center).

Type:str

position_on_postcard

Predicted (x, y) coords of object center on the above-named postcard. Does NOT take into account additional pointing corrections; these will be applied when making the TPF.

Type:(int, int)

all_postcards

Names of all postcards where the source appears.

Type:list of strs

locate_on_chip()

Finds the TESS sector, camera, chip, and position on chip for the source. Sets attributes sector, camera, chip, position_on_chip.

locate_on_tess()

Finds the best TESS postcard(s) and the position of the source on postcard. Sets attributes postcard, position_on_postcard, all_postcards.

class eleanor.TargetData(source, height=13, width=13, save_postcard=True, do_pca=False, do_psf=False, bkg_size=None, crowded_field=False, cal_cadences=None)

Object containing the light curve, target pixel file, and related information for any given source.

Parameters:

• source (eleanor.Source) – The source object to use.
• height (int, optional) – Height in pixels of TPF to retrieve. Default value is 13 pixels. Must be an odd number, or else will return an aperture one pixel taller than requested so target falls on central pixel.
• width (int, optional) – Width in pixels of TPF to retrieve. Default value is 13 pixels. Must be an odd number, or else will return an aperture one pixel wider than requested so target falls on central pixel.
• bkg_size (int, optional) – Size of box to use for background estimation. If not set, will default to the width of the target pixel file.
• crowded_field (bool, optional) – If true, will return a light curve built using a small aperture (not more than 9 pixels in size).
• do_pca (bool, optional) – If true, will return a PCA-corrected light curve.
• do_psf (bool, optional) – If true, will return a light curve made with a simple PSF model.
• cal_cadences (tuple, optional) – Start and end cadence numbers to use for optimal aperture selection.

header

FITS header for saving/loading data.

Type:dict

source_info

Pointer to input source.

Type:eleanor.Source

aperture

Aperture to use if overriding default. To use default, set to None.

tpf

Target pixel file of fluxes; array with shape dimensions.

Type:np.ndarray

time

Time series.

Type:np.ndarray

post_obj

Pointer to Postcard objects containing this TPF.

Type:eleanor.Postcard

pointing_model

Table of matrices describing the transformation matrix from FFI default WCS and eleanor’s corrected pointing.

Type:astropy.table.Table

tpf_err

Errors on fluxes in tpf.

Type:np.ndarray

centroid_xs

Position of the source in x inferred from pointing model; has same length as time. Position is relative to the pixel coordinate system of the postcard.

Type:np.ndarray

centroid_ys

Position of the source in y inferred from pointing model; has same length as time. Position is relative to the pixel coordinate system of the postcard.

Type:np.ndarray

cen_x

Median x position of the source. Position is relative to the pixel coordinate system of the postcard.

Type:int

cen_y

Median y position of the source. Position is relative to the pixel coordinate system of the postcard.

Type:int

dimensions

Shape of tpf. Should be (time, height, width).

Type:tuple

all_apertures

List of aperture objects.

Type:list

aperture

Chosen aperture for producing raw_flux lightcurve. Format is array with shape (height, width). All entries are floats in range [0,1].

Type:array-like

all_lc_err

Estimated uncertainties on all_raw_lc.

Type:np.ndarray

all_raw_lc

All lightcurves extracted using all_apertures. Has shape (N_apertures, N_time).

Type:np.ndarray

all_corr_lc

All systematics-corrected lightcurves. See all_raw_lc.

Type:np.ndarray

best_ind

Index into all_apertures producing the best (least noisy) lightcurve.

Type:int

corr_flux

Systematics-corrected version of raw_flux.

Type:np.ndarray

flux_err

Estimated uncertainty on raw_flux.

Type:np.ndarray

raw_flux

Un-systematics-corrected lightcurve derived using aperture and tpf.

Type:np.ndarray

x_com

Position of the source in x inferred from TPF; has same length as time. Position is relative to the pixel coordinate system of the TPF.

Type:np.ndarray

y_com

Position of the source in y inferred from TPF; has same length as time. Position is relative to the pixel coordinate system of the TPF.

Type:np.ndarray

quality

Quality flag.

Type:int

Notes

save() and load() methods write/read these data to a FITS file with format:

Extension[0] = header

Extension[1] = (N_time, height, width) TPF, where n is the number of cadences in an observing run

Extension[2] = (3, N_time) time, raw flux, systematics corrected flux

bkg_subtraction(scope='tpf', sigma=2.5)

Subtracts background flux from target pixel file.

Parameters:

• scope (string, "tpf" or "postcard") – If tpf, will use data from the target pixel file only to estimate and remove the background. If postcard, will use data from the entire postcard region to estimate and remove the background.
• sigma (float) – The standard deviation cut used to determine which pixels are representative of the background in each cadence.

center_of_mass()

Calculates the position of the source across all cadences using muchbettermoments and self.best_aperture.

Finds the brightest pixel in a (height, width) region summed up over all cadence. Searches a smaller (3x3) region around this pixel at each cadence and uses muchbettermoments to find the maximum.

create_apertures(height, width)

Creates a range of sizes and shapes of apertures to test.

custom_aperture(shape=None, r=0.0, l=0.0, w=0.0, theta=0.0, pos=None, method='exact')

Creates a custom circular or rectangular aperture of arbitrary size.

Parameters:

• shape (str, optional) – The shape of the aperture to be used. Must be either circle or rectangle.
• r (float, optional) – If shape is circle the radius of the circular aperture to be used.
• l (float, optional) – If shape is rectangle the length of the rectangular aperture to be used.
• w (float, optional) – If shape is rectangle the width of the rectangular aperture to be used.
• theta (float, optional) – If shape is rectangle the rotation of the rectangle relative to detector coordinate. Uses units of radians.
• pos (tuple, optional) – The center of the aperture, in TPF coordinates. If not set, defaults to the center of the TPF.
• method (str, optional) – The method of producing a light curve to be used, either exact, center, or subpixel. Passed through to photutils and used as intended by that package.

fetch_dir()

Returns the default path to the directory where files will be saved or loaded.

By default, this method will return “~/.eleanor” and create this directory if it does not exist. If the directory cannot be access or created, then it returns the local directory (“.”).

Returns:download_dir – Path to location of ffi_dir where FFIs will be downloaded Return type:str

get_lightcurve(aperture=None)

Extracts a light curve using the given aperture and TPF. Can pass a user-defined aperture mask, otherwise determines which of a set of pre-determined apertures provides the lowest scatter in the light curve. Produces a mask, a numpy.ndarray object of the same shape as the target pixel file, which every pixel assigned a weight in the range [0, 1].

Parameters:aperture (numpy.ndarray) – (height, width) array of floats in the range [0,1] with desired weights for each pixel to create a light curve. If not set, ideal aperture is inferred automatically. If set, uses this aperture at the expense of all other set apertures.

get_time(coords)

Gets time, including light travel time correction to solar system barycenter for object given location

get_tpf_from_postcard(pos, postcard, height, width, bkg_size, save_postcard)

Gets TPF from postcard.

jitter_corr(flux, skip=30)

Corrects for jitter in the light curve by quadratically regressing with centroid position.

Parameters:skip (int) – The number of cadences at the start of each orbit to skip in determining optimal model weights.

k2_correction(flux)

Remove any systematics that are correlated with spacecraft pointing, as inferred through telescope pointing model.

Parameters:flux (numpy.ndarray) – Flux array to which detrending applied.

load(directory=None)

Loads in and sets all the attributes for a pre-created TPF file.

Parameters:directory (str, optional) – Directory to load file from.

pca(matrix_fn='a_matrix.txt', flux=None, modes=4)

Applies cotrending basis vectors, found through principal component analysis, to light curve to remove systematics shared by nearby stars.

Parameters:

• flux (numpy.ndarray) – Flux array to which cotrending basis vectors are applied. Default is self.corr_flux.
• modes (int) – Number of cotrending basis vectors to apply. Default is 8.

psf_lightcurve(nstars=1, model='gaussian', likelihood='gaussian', xc=None, yc=None)

Performs PSF photometry for a selection of stars on a TPF.

Parameters:

• nstars (int, optional) – Number of stars to be modeled on the TPF.
• model (string, optional) – PSF model to be applied. Presently must be gaussian, which models a single Gaussian. Will be extended in the future once TESS PRF models are made publicly available.
• likelihood (string, optinal) – The data statistics given the parameters. Options are: ‘gaussian’ and ‘poisson’.
• xc (list, optional) – The x-coordinates of stars in the zeroth cadence. Must have length nstars. While the positions of stars will be fit in all cadences, the relative positions of stars will be fixed following the delta values from this list.
• yc (list, optional) – The y-coordinates of stars in the zeroth cadence. Must have length nstars. While the positions of stars will be fit in all cadences, the relative positions of stars will be fixed following the delta values from this list.

save(output_fn=None, directory=None)

Saves a created TPF object to a FITS file.

Parameters:

• output_fn (str, optional) – Filename to save output as. Overrides default naming.
• directory (str, optional) – Directory to save file into.

set_header()

Defines the header for the TPF.

set_quality()

Reads in quality flags set in the postcard

class eleanor.Postcard(filename, ELEANORURL, location=None)

TESS FFI data for one postcard across one sector.

A postcard is an rectangular subsection cut out from the FFIs. It’s like a TPF, but bigger. The Postcard object contains a stack of these cutouts from all available FFIs during a given sector of TESS observations.

Parameters:

• filename (str) – Filename of the downloaded postcard.
• location (str, optional) – Filepath to filename.

dimensions

(x, y, time) dimensions of postcard.

Type:tuple

flux, flux_err

Arrays of shape postcard.dimensions containing flux or error on flux for each pixel.

Type:numpy.ndarray

time

?

Type:float

header

Stored header information for postcard file.

Type:dict

center_radec

RA & Dec coordinates of the postcard’s central pixel.

Type:tuple

center_xy

(x, y) coordinates corresponding to the location of the postcard’s central pixel on the FFI.

Type:tuple

origin_xy

(x, y) coordinates corresponding to the location of the postcard’s (0,0) pixel on the FFI.

Type:tuple

find_sources()

Finds the cataloged sources in the postcard and returns a table.

Returns:result – All the sources in a postcard with TIC IDs or Gaia IDs. Return type:astropy.table.Table

plot(frame=0, ax=None, scale='linear', **kwargs)

Plots a single frame of a postcard.

Parameters:

• frame (int, optional) – Index of frame. Default 0.
• ax (matplotlib.axes.Axes, optional) – Axes on which to plot. Creates a new object by default.
• scale (str) – Scaling for colorbar; acceptable inputs are ‘linear’ or ‘log’. Default ‘linear’.
• **kwargs (passed to matplotlib.pyplot.imshow) –

Returns:

ax

Return type:

matplotlib.axes.Axes

class eleanor.Visualize(object)

The main class for creating figures, movies, and interactive plots. Allows the user to have a grand ole time playing with their data!

Parameters:obj – Object must have minimum attributes of 2D array of flux. Will allow for plotting of both postcards & tpfs.

click_aperture(path=None)

Interactively set aperture.

mark_gaia_sources()

Mark Gaia sources within a given TPF or postcard.

Hover over the points to reveal the source’s TIC ID, Gaia ID, Tmag, and Gmag. Also crossmatches with TIC and identifies closest TIC object.

movie(output_fn=None, plot_lc=False, pointing_model=False, aperture=False, **kwargs)

This function allows the user to create a movie of a TPF or postcard

Parameters:

• output_fn (str, optional) – Output filename to save the movie to.
• plot_lc (bool, optional) – If True, plot the light curve and track location along light curve with time-dependent movie (Defaults to False).
• pointing_model (bool, optional) – If True, plot the movement of the pointing_model for a given source; only applicable on TPFs (Defaults to False).
• aperture (bool, optional) – If True, overplot the aperture on the TPF movie.
• **kwargs – Passed to matplotlib.pyplot.imshow.

Returns:

ani – Movie.

Return type:

matplotlib.animation.Animation