eleanor Documentation

A single source observed by TESS.

Parameters

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

• gaia (int, optional) – The Gaia DR3 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)¶

Searches to see if the TESSCut cutout has already been downloaded.

tesscut_dir()¶

Creates a TESSCut directory in the hidden eleanor directory.

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¶

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

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

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

download_dir – Path to location of ffi_dir where FFIs will be downloaded

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

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

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

• download (str, optional) – Allows the user to download the short cadence target pixel files. By default, downloads all sectors that are available.

• 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

sc – If download == True : Returns a list of lightkurve.lightcurve.TessLightCurve object(s). If download == False : Returns a lightkurve.search.SearchResult object.

Return type

np.ndarray

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

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

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)¶

Downloads entire sector of data into FFI download directory.

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.