# API¶

eleanor.multi_sectors(sectors, tic=None, gaia=None, coords=None, name=None, tc=False, local=False, post_dir=None, pm_dir=None, metadata_path=None, tesscut_size=31)

Obtain a list of Source objects for a single target, for each of multiple sectors for which the target was observed.

Parameters
• sectors (list or str) – The list of sectors for which data should be returned, or ‘all’ to return all sectors for which there are data.

• tic (int, optional) – The TIC ID of the source.

• gaia (int, optional) – The Gaia DR2 source_id.

• coords (tuple, optional) – The (RA, Dec) coords of the object in degrees.

• tc (bool, optional) – If True, use a TessCut cutout to produce postcards rather than downloading the eleanor postcard data products.

• tesscut_size (int, array-like, astropy.units.Quantity) – The size of the cutout array, when tc is True. Details can be seen in astroquery.mast.TesscutClass.download_cutouts

###
class eleanor.Source(tic=None, gaia=None, coords=None, name=None, fn=None, sector=None, fn_dir=None, tc=False, local=False, post_dir=None, pm_dir=None, metadata_path=None, tesscut_size=31)

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.

• name (str, optional) – The name of your target (e.g. “HD#####” or “M31”).

• 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.

• tc (bool, optional) – If True, use a TessCut cutout to produce postcards rather than downloading the eleanor postcard data products.

• tesscut_size (int, array-like, astropy.units.Quantity) – The size of the cutout array, when tc is True. Details can be checked in astroquery.mast.TesscutClass.download_cutouts

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_tess()

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

sector
Type

int

camera
Type

int

chip
Type

int

position_on_chip
Type

np.array

locate_postcard(local)

Finds the eleanor postcard, if available, this star falls on.

postcard
Type

str

postcard_bkg
Type

str

postcard_path
Type

str

position_on_postcard
Type

list

all_postcards
Type

list

mast_list
Type

astropy.table.Table

locate_with_tesscut()

Finds the best TESS postcard(s) and the position of the source on postcard.

postcard
Type

list

postcard_path
Type

str

position_on_postcard
Type

list

all_postcards
Type

list

sector
Type

int

camera
Type

int

chip
Type

int

position_on_chip
Type

np.array

search_tesscut(download_dir, coords)

tesscut_dir()

Creates a TESSCut directory in the hidden eleanor directory.

class eleanor.TargetData(source, height=13, width=13, save_postcard=True, do_pca=False, do_psf=False, bkg_size=None, aperture_mode='normal', cal_cadences=None, try_load=True, regressors=None, language='English')

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.

• aperture_mode (str, optional) – If small, will only consider apertures 8 pixels in size or smaller. If large, will only consider apertures larger than 8 pixels in size. If all all apertures will be considered. If normal will test many different apertures, following rules based on the magnitude of the target star and the contamination ratio recorded in the TIC. small and large can often be useful for faint stars/stars in crowded fields or bright stars, respectively.

• 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.

• 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.

• try_load (bool, optional) – If true, will search hidden ~/.eleanor directory to see if TPF has already been created.

• regressors (numpy.ndarray or str) – Extra data to regress against in the correction. Should be shape (len(data.time), N) or ‘corner’. If ‘corner’ will use the four corner pixels of the TPF as extra information in the regression.

header

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

aperture_mode

Integer corresponding to the used aperture mode as input by the user.

Type

int

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

tpf_star_x

x position of the star on the TPF. Position is relative to the size of the TPF.

Type

int

tpf_star_y

y position of the star on the TPF. Position is relative to the size of the TPF.

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_flux_err

Estimated uncertainties on all_raw_flux.

Type

np.ndarray

all_raw_flux

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

Type

np.ndarray

all_corr_flux

All systematics-corrected lightcurves. See all_raw_flux.

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[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.

corrected_flux(flux=None, skip=0.25, modes=3, pca=False, bkg=None, regressors=None)

Corrects for jitter in the light curve by quadratically regressing with centroid position. :param skip: The length of time in days at the start of each orbit to skip in determining optimal model weights.

Default is 0.62 days.

Parameters
• modes (int, optional) – If doing a PCA-based correction, the number of cotrending basis vectors to regress against. Default is 3.

• pca (bool, optional) – Allows users to decide whether or not to use PCA analysis. Default is False.

• regressors (numpy.ndarray or str) – Extra data to regress against in the correction. Should be shape (len(data.time), N) or ‘corner’. If ‘corner’ will use the four corner pixels of the TPF as extra information in the regression.

create_apertures(height, width)

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

custom_aperture(shape=None, r=0.0, h=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.

• h (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

Return type

str

get_cbvs()

Obtains the cotrending basis vectors (CBVs) as convolved down from the short-cadence targets.

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, source)

Gets TPF from postcard.

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, fn=None)

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

Parameters

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

psf_lightcurve(data_arr=None, err_arr=None, bkg_arr=None, nstars=1, model='gaussian', likelihood='gaussian', xc=None, yc=None, verbose=True, err_method=True, ignore_pixels=None)

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

Parameters
• data_arr (numpy.ndarray, optional) – Data array to fit with the PSF model. If None, will default to TargetData.tpf.

• err_arr (numpy.ndarray, optional) – Uncertainty array to fit with the PSF model. If None, will default to TargetData.tpf_flux_err.

• bkg_arr (numpy.ndarray, optional) – List of background values to include as initial guesses for the background model. If None, will default to TargetData.flux_bkg.

• 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.

• verbose (bool, optional) – If True, return information about the shape of the PSF at every cadence as well as the PSF-inferred centroid shape.

• err_method (bool, optional) – If True, use the photometric uncertainties for each pixel in the TPF as delivered by the TESS team. Otherwise, each pixel takes an equal uncertainty. If err_arr is passed through instead, this setting is ignored.

• ignore_pixels (int, optional) – If not None, ignore a certain percentage of the brightest pixels away from the source target, effectively masking other nearby, bright stars. This strategy appears to do a reasonable job estimating the background more accurately in relatively crowded regions.

save(output_fn=None, directory=None, lite=False)

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.

• lite (bool, optional) – Whether to only save the light curve and not the target pixel data. Will reduce file size by a factor of ~19x by removing all pixel information and all light curves except the optimal one selected by eleanor.

set_header(lite=False)

Defines the header for the TPF.

set_quality()

Reads in quality flags set in the postcard

stitch(objects, flux='corrected')

Stitches together basic light curve information from different eleanor.TargetData objects.

Parameters
• objects (np.ndarray) – An array of eleanor.TargetData objects.

• flux (str, optional) – The keyword for which flux to stitch together and return. Sectors will be normalized by itself. Default is ‘corrected’.

Returns

• time (np.ndarray) – An array of stitched times.

• flux (np.ndarray) – An array of stitched normalized fluxes.

• quality (np.ndarray) – An array of stitched quality flags.

• flux_err (np.ndarray) – An array of stitched flux errors.

to_lightkurve(flux=None, quality_mask=None)

Creates a lightkurve.lightcurve.LightCurve() object with eleanor attributes. All inputs have been quality masked.

Parameters
• flux (np.ndarray, optional) – An array of flux. Default is eleanor.TargetData.corr_flux.

• quality_mask (np.ndarray, optional) – An array of quality flags. Default is eleanor.TargetData.quality.

Returns

Return type

lightkurve.lightcurve.TessLightCurve object

class eleanor.Postcard(filename, background, filepath)

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

• 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

background2d

The 2D modeled background array.

Type

np.ndarray

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, obj_type='tpf')

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.

• obj_type – Object type can be set to “tpf” or “postcard”. Default is “tpf”.

aperture_contour(aperture=None, ap_color='w', ap_linewidth=4, ax=None, **kwargs)

Overplots the countour of an aperture on a target pixel file. Contribution from Gijs Mulders.

Parameters
• aperture (np.2darray, optional) – A 2D mask the same size as the target pixel file. Default is the eleanor default aperture.

• ap_color (str, optional) – The color of the aperture contour. Takes a matplotlib color. Default is red.

• ap_linewidth (int, optional) – The linewidth of the aperture contour. Default is 4.

• ax (matplotlib.axes._subplots.AxesSubplot, optional) – Axes to plot on.

pixel_by_pixel(colrange=None, rowrange=None, cmap='viridis', data_type='corrected', mask=None, xlim=None, ylim=None, color_by_pixel=False, color_by_aperture=True, freq_range=[0.05, 10.0], aperture=None, ap_color='r', ap_linewidth=2)

Creates a pixel-by-pixel light curve using the corrected flux. Contribution from Oliver Hall.

Parameters
• colrange (np.array, optional) – A list of start column and end column you’re interested in zooming in on.

• rowrange (np.array, optional) – A list of start row and end row you’re interested in zooming in on.

• cmap (str, optional) – Name of a matplotlib colormap. Default is ‘viridis’.

• data_type (str, optional) – The type of flux used. Either: ‘raw’, ‘corrected’, ‘amplitude’, or ‘periodogram’. If not, default set to ‘corrected’.

• mask (np.array, optional) – Specifies the cadences used in the light curve. If not, default set to good quality cadences.

• xlim (np.array, optional) – Specifies the xlim on the subplots. If not, default is set to the entire light curve.

• ylim (np.array, optional) – Specifies the ylim on the subplots, If not, default is set to the entire light curve flux range.

• color_by_pixel (bool, optional) – Colors the light curve given the color of the pixel. If not, default is set to False.

• freq_range (list, optional) – List of minimum and maximum frequency to search in Lomb Scargle periodogram. Only used if data_type = ‘periodogram’. If None, default = [1/20., 1/0.1].

plot_gaia_overlay(tic=None, tpf=None, magnitude_limit=18)

Check if the source is contaminated.

tess_the_movie()

Opens the link to Ethan Kruse’s TESS: The Movie YouTube videos for the sector your target is observed in.

movie_url
Type

str

class eleanor.Crossmatch(object)

This class can be used to find the same light curve from different pipelines. The current available light curves are from the TESS Asteroseismic Science Consortium (TASC) and Oelkers & Stassun (2019). Oelkers & Stassun light curves are only available through Sector 5.

Parameters

obj – Object must be an eleanor.TargetData object.

oelkers_lc()

Grabs the Oelkers & Stassun (2019) associated light curve.

time
Type

np.array

mag
Type

np.array

mag_err
Type

np.array

tasoc_lc()

Grabs the T’DA available light curves for your target. For more information, see the TASOC light curve documentation: https://tasoc.dk/code/.

tasoc_header
tasoc_tpf
Type

np.2darray

tasoc_aperture
Type

np.2darray

tasoc_time
Type

np.array

tasoc_quality
Type

np.array

tasoc_timecorr
Type

np.array

tasoc_cadenceno
Type

np.array

tasoc_flux_raw
Type

np.array

tasoc_flux_raw_err
Type

np.array

tasoc_flux_corr
Type

np.array

tasoc_flux_corr_err
Type

np.array

tasoc_flux_bkg
Type

np.array

tasoc_pixel_quality

Quality flags for the data; use these not tasoc_quality.

Type

np.array

tasoc_pos_corr1
Type

np.array

tasoc_pos_corr2
Type

np.array

tasoc_mom_centr1
Type

np.array

tasoc_mom_centr2
Type

np.array

two_minute(download=False, sectors=None)

Checks to see if short cadence data is available for your target.

Parameters

• sectors (np.ndarray, optional) – Allows the user to specify which sector to search for two-minute data. By default, downloads the sector assigned to the 30-minute data.

Returns

Return type

np.ndarray

class eleanor.ffi(sector=None, camera=None, chip=None)
This class allows the user to download all full-frame images for a given sector,

camera, and chip. It also allows the user to create their own pointing model based on each cadence for a given combination of sector, camera, and chip.

No individual user should have to download all of the full-frame images because

stacked postcards will be available for the user to download from MAST.

Parameters
• sector (int, optional) –

• camera (int, optional) –

• chip (int, optional) –

build_pointing_model(pos_predicted, pos_inferred, outlier_removal=False)
Builds an affine transformation to correct the positions of stars

from a possibly incorrect WCS.

Parameters
• pos_predicted (tuple) – Positions taken straight from the WCS; [[x,y],[x,y],…] format.

• pos_inferred (tuple) – Positions taken using any centroiding method; [[x,y],[x,y],…] format.

• outlier_removal (bool, optional) – Whether to clip 1-sigma outlier frames. Default False.

Returns

xhat – (3, 3) affine transformation matrix between WCS positions and inferred positions.

Return type

np.ndarray

download_ffis(download_dir=None)

Parameters

download_dir (str) – Location where the data files will be stored. Defaults to “~/.eleanor/sector_{}/ffis” if None is passed.

pointing_model_per_cadence(out_dir=None, n_sources=350)

Step through build_pointing_model for each cadence.

sort_by_date()

Sorts FITS files by start date of observation.

eleanor.use_pointing_model(coords, pointing_model)

Applies pointing model to correct the position of star(s) on postcard.

Parameters
• coords (tuple) – (x, y) position of star(s).

• pointing_model (astropy.table.Table) – pointing_model for ONE cadence.

Returns

coords – Corrected position of star(s).

Return type

tuple

eleanor.load_pointing_model(pm_dir, sector, camera, chip)

eleanor.pm_quality(time, sector, camera, chip, pm=None)
eleanor.set_quality_flags(ffi_start, ffi_stop, shortCad_fn, sector, camera, chip, pm=None)