`MovingTPF`

MovingTPF

MovingTPF(
    target: str,
    ephem: DataFrame,
    barycentric: bool = True,
    metadata: dict = {},
)

Create a TPF for a moving target (e.g. asteroid) from a TESS FFI. Includes methods to efficiently retrieve the data, correct the background, define an aperture mask and save a TPF in the SPOC format.

Extract a lightcurve from the TPF, using aperture or psf photometry. Includes methods to create quality flags and save the lightcurve as a FITS file.

Parameters:

target (str) –

Target ID. This is only used when saving the TPF.
ephem (DataFrame) –
Target ephemeris with columns ['time', 'sector', 'camera', 'ccd', 'column', 'row']. Optional columns: ['vmag', 'hmag', 'sun_distance', 'obs_distance', 'sto_angle'].
- 'time' : float in format (JD - 2457000) in TDB. See also barycentric below.
- 'sector', 'camera', 'ccd' : int
- 'column', 'row' : float. These must be one-indexed, where the lower left pixel of the FFI is (1,1).
- 'vmag' : float, optional. Visual magnitude.
- 'hmag' : float, optional. Absolute magnitude.
- 'sun_distance' : float, optional. Distance from Sun, in AU.
- 'obs_distance' : float, optional. Distance from observer (TESS), in AU.
- 'sto_angle' : float, optional. Sun-Target-Observer angle, in degrees. Closely approximates true phase angle. See Horizons documentation for definition: https://ssd.jpl.nasa.gov/horizons/manual.html#obsquan
barycentric (bool, default: True ) –
- If True, the input ephem['time'] must be in TDB measured at the solar system barycenter. This is the case for the 'TSTART'/'TSTOP' keywords in SPOC FFI headers and the 'TIME' column in SPOC TPFs and LCFs.
- If False, the input ephem['time'] must be in TDB measured at the spacecraft. This can be recovered from the SPOC data products: for FFIs subtract header keyword 'BARYCORR' from 'TSTART'/'TSTOP' and for TPFs/LCFs subtract the 'TIMECORR' column from the 'TIME' column.
metadata (dict, default: {} ) –
A dictionary with optional keys {'eccentricity': float, 'inclination': float, 'perihelion': float, 'ephem_date': str}.
- 'eccentricity' : Target's orbital eccentricity. This is saved in the TPF/LCF headers.
- 'inclination' : Target's orbital inclination, in degrees. This is saved in the TPF/LCF headers.
- 'perihelion' : Target's perihelion distance, in AU. This is saved in the TPF/LCF headers.
- 'ephem_date' : Date the ephemeris was generated. Format must be YYYY-MM-DD. This is saved in the TPF/LCF headers.

from_name `staticmethod`

from_name(
    target: str,
    sector: int,
    camera: Optional[int] = None,
    ccd: Optional[int] = None,
    time_step: float = 0.1,
)

Initialises MovingTPF from target name and TESS sector. Uses JPL/Horizons to retrieve ephemeris of target. Specifying a camera and CCD will only use the ephemeris from that camera/ccd.

Parameters:

target (str) –

JPL/Horizons target ID of e.g. asteroid, comet.
sector (int) –

TESS sector number.
camera (int, default: None ) –

TESS camera. Must be defined alongside ccd. If None, full ephemeris will be used to initialise MovingTPF.
ccd (int, default: None ) –

TESS CCD. Must be defined alongside camera. If None, full ephemeris will be used to initialise MovingTPF.
time_step (float, default: 0.1 ) –

Resolution of ephemeris, in days.

Returns:

MovingTPF –
Initialised MovingTPF with ephemeris and orbital elements from JPL/Horizons. Target ephemeris has columns ['time', 'sector', 'camera', 'ccd', 'column', 'row', 'vmag', 'hmag' 'sun_distance', 'obs_distance', 'sto_angle'].
- 'time' : float with units (JD - 2457000) in TDB at spacecraft.
- 'sector', 'camera', 'ccd' : int
- 'column', 'row' : float. These are one-indexed, where the lower left pixel of the FFI is (1,1).
- 'vmag' : float. Visual magnitude.
- 'hmag' : float. Absolute magntiude.
- 'sun_distance' : float. Distance from Sun, in AU.
- 'obs_distance' : float. Distance from observer (TESS), in AU.
- 'sto_angle' : float. Sun-Target-Observer phase angle, in degrees. Closely approximates true phase angle. See Horizons documentation for definition: https://ssd.jpl.nasa.gov/horizons/manual.html#obsquan

make_tpf

make_tpf(
    shape: Tuple[int, int] = (11, 11),
    bg_method: str = "linear_model",
    ap_method: str = "prf",
    save: bool = False,
    outdir: str = "",
    file_name: Optional[str] = None,
    **kwargs,
)

Performs all steps to create and save a SPOC-like TPF for a moving target.

Parameters:

shape (Tuple(int, int), default: (11, 11) ) –

Defined as (nrows,ncols), in pixels. Defines the pixels that will be retrieved, centred on the target, at each timestamp.
bg_method (str, default: 'linear_model' ) –

Method used for background correction. One of [rolling, linear_model].
ap_method (str, default: 'prf' ) –

Method used to create aperture. One of [threshold, prf, ellipse].
save (bool, default: False ) –

If True, save the TPF HDUList to a FITS file.
outdir (str, default: '' ) –

If save, this is the directory into which the file will be saved.
file_name (str, default: None ) –

If save, this is the filename that will be used. Format must be '.fits'. If no filename is given, a default one will be generated.
**kwargs –

Keyword arguments passed to create_pixel_quality(), background_correction(), create_aperture() and to_fits().

make_lc

make_lc(
    method: str = "all",
    save: bool = False,
    file_name: Optional[str] = None,
    outdir: str = "",
    **kwargs,
)

Performs all steps to create a lightcurve from the moving TPF, with the option to save.

Parameters:

method (str, default: 'all' ) –

Method to extract lightcurve. One of [all, aperture, psf].
save (bool, default: False ) –

If True, save the lightcurve HDUList to a FITS file.
outdir (str, default: '' ) –

If save, this is the directory into which the file will be saved.
file_name (str, default: None ) –

If save, this is the filename that will be used. Format must be '.fits'. If no filename is given, a default one will be generated.
**kwargs –

Keyword arguments passed to to_lightcurve() and to_fits().

get_data

get_data(shape: Tuple[int, int] = (11, 11))

Retrieve pixel data for a moving target from a TESS FFI.

Parameters:

shape (Tuple(int, int), default: (11, 11) ) –

Defined as (nrows,ncols), in pixels. Defines the pixels that will be retrieved, centred on the target, at each timestamp.

reshape_data

reshape_data()

Reshape flux data into cube with shape (len(self.time), self.shape).

background_correction

background_correction(
    method: str = "linear_model", **kwargs
)

Apply background correction to reshaped flux data.

Parameters:

method (str, default: 'linear_model' ) –

Method used for background correction. One of [rolling, linear_model].
**kwargs –

Keyword arguments passed to _bg_rolling_median() and _bg_linear_model().

create_aperture

create_aperture(method: str = 'prf', **kwargs)

Creates an aperture mask using method threshold, prf or ellipse. It creates the self.aperture_mask attribute with the 3D mask.

Parameters:

method (str, default: 'prf' ) –

Method used for aperture estimation. One of [threshold, prf, ellipse].
kwargs (dict, default: {} ) –

Keywords arguments passed to aperture mask method, e.g self._create_threshold_mask takes threshold and reference_pixel.

create_pixel_quality

create_pixel_quality(
    sat_level: float = 100000.0,
    sat_buffer_rad: int = 1,
    **kwargs,
)

Create 3D pixel quality flags. This is stored in the self.pixel_quality attribute.

Each flag is a bit-wise combination of the following bits:

Bit - Description

1 - pixel is outside of science array
2 - pixel is in a strap column
3 - pixel is saturated
4 - pixel is within sat_buffer_rad pixels of a saturated pixel
5 - pixel has no scattered light correction. Only relevant if linear_model background correction was used.
6 - pixel had no background star model, value is nan. Only relevant if linear_model background correction was used.
7 - pixel had negative flux value BEFORE background correction was applied. This can happen near bleed columns from saturated stars (e.g. see Sector 6, Camera 1, CCD 4).
8 - pixel has a poor fitting background star model. Only relevant if linear_model background correction was used.

Parameters:

sat_level (float, default: 100000.0 ) –

Flux (e-/s) above which to consider a pixel saturated.
sat_buffer_rad (int, default: 1 ) –

Approximate radius of saturation buffer (in pixels) around each saturated pixel.

to_lightcurve

to_lightcurve(method: str = 'aperture', **kwargs)

Extract lightcurve from the moving TPF, using either aperture or psf photometry. This function creates the self.lc attribute, which stores the time series data.

Parameters:

method (str, default: 'aperture' ) –

Method to extract lightcurve. One of aperture or psf.
kwargs (dict, default: {} ) –

Keyword arguments, e.g self._aperture_photometry takes bad_bits, self._psf_photometry takes time_bin_size

_create_lc_quality

_create_lc_quality(
    pixel_mask: Union[list, ndarray],
    pixel_quality: Union[list, ndarray],
    prf_nan_mask: ndarray,
    time_sc: Union[
        ndarray, Tuple[ndarray, ndarray, ndarray]
    ],
    bad_bit_value: Optional[int] = None,
    psf_flux: Optional[ndarray] = None,
)

Creates quality flags for lightcurve. This is defined independently of SPOC quality flags. This function is called internally by _aperture_photometry() and _psf_photometry().

If you are creating LC quality for aperture photometry:

pixel_mask should correspond to the pixels inside the aperture mask.
time_sc should be an array corresponding to time at the spacecraft.
bad_bit_value should correspond to bad_bits defined by user in _aperture_photometry().
psf_flux should be None.

If you are creating LC quality for PSF photometry:

pixel_mask should correspond to the pixels that were used to fit the PRF model in _psf_photometry().
time_sc should be a tuple of arrays for time at the spacecraft, upper error on bin and lower error on bin.
bad_bit_value should be None.
psf_flux should be the PSF flux time-series from _psf_photometry().

The flag is a bit-wise combination of the following bits:

Bit - Description

1 - no pixels inside mask.
2 - at least one non-science pixel inside mask.
3 - at least one pixel inside mask is in a strap column.
4 - at least one saturated pixel inside mask.
5 - at least one pixel inside mask is 4-adjacent to a saturated pixel.
6 - all pixels inside aperture are bad_bits. Only defined if bad_bit_value is not None (relevant for aperture photometry).
7 - PRF model contained nans.
8 - at least one pixel inside mask does not have scattered light correction. Only relevant if linear_model background correction was used.
9 - at least one pixel inside mask had no star model (value is nan). Only relevant if linear_model background correction was used.
10 - at least one pixel inside mask had negative value BEFORE background correction was applied.
11 - PSF fit failed due to singular matrix (see np.linalg.LinAlgError) or because all pixels used to fit the PRF model had NaN flux values. Only relevant if method=psf.
12 - at least one pixel inside mask had a poor fitting background star model. Only relevant if linear_model background correction was used.
13 - mask has two or more discrete regions.
14 - non-science data from sector 3, as defined in data release notes: https://archive.stsci.edu/missions/tess/doc/tess_drn/tess_sector_03_drn04_v02.pdf

Parameters:

pixel_mask (ndarray or list) –

Pixels used to define LC quality. For aperture photometry, this should be the aperture mask. For PSF photometry, this should be the pixels used to fit the PRF model.
pixel_quality (ndarray or list) –

Pixel quality mask, defined by create_pixel_quality(). This must have the same shape as pixel_mask.
prf_nan_mask (ndarray) –

Cadences where the PRF model is NaN, as returned by _create_target_prf_model(). This must have length equal to the first dimension of pixel_mask.
time_sc (ndarray or tuple) –

For aperture photometry, this should be an ndarray corresponding to time at the spacecraft. For PSF photometry, this should be a tuple of arrays for time at the spacecraft, upper error on bin and lower error on bin. This is used to identify non-science data in sector 3, and each array must have length equal to the first dimension of pixel_mask.
bad_bit_value (int, default: None ) –

Value corresponding to bad_bits, as defined by user in _aperture_photometry(). If creating quality mask for PSF photmetry, this should be None.
psf_flux (ndarray, default: None ) –

PSF flux time-series from _psf_photometry(). If creating quality mask for aperture photmetry, this should be None.

Returns:

lc_quality ( ndarray ) –

Array of lightcurve quality flags with length [ntimes].

create_lc_quality_mask

create_lc_quality_mask(
    spoc_quality: ndarray,
    lc_quality: ndarray,
    bad_spoc_bits: Union[list[int], str] = "default",
    bad_lc_bits: Union[list[int], str] = "default",
)

Combines SPOC quality flags and tess_asteroids lightcurve quality flags to create a boolean quality mask that can be applied to the aperture or PSF lightcurve.

Parameters:

spoc_quality (ndarray) –

Array of SPOC quality flags.
lc_quality (ndarray) –

Array of tess_asteroids lightcurve quality flags, as defined by _create_lc_quality(). This must have the same length as spoc_quality.
bad_spoc_bits (list or str, default: 'default' ) –
Defines SPOC bits corresponding to bad quality data. Can be one of:
- "default" - mask bits defined by default_bad_spoc_bits.
- "all" - mask all data with a SPOC quality flag.
- "none" - mask no data.
- list - mask custom bits provided in list.
More information about the SPOC quality flags can be found in Section 9 of the TESS Science Data Products Description Document.
bad_lc_bits (list or str, default: 'default' ) –
Defines bits corresponding to bad quality data from _create_lc_quality(). Can be one of:
- "default" - mask bits defined by default_bad_lc_bits.
- "all" - mask all data with a quality flag.
- "none" - mask no data.
- list - mask custom bits provided in list.

Returns:

quality_mask ( ndarray ) –

A boolean mask with the same length as spoc_quality and lc_quality. True indicates a good quality cadence and False indicates a bad quality cadence.

to_fits

to_fits(
    file_type: str,
    save: bool = False,
    overwrite: bool = True,
    outdir: str = "",
    file_name: Optional[str] = None,
    **kwargs,
)

Convert the moving TPF or lightcurve data to FITS format. This function creates the self.tpf_hdulist or self.lc_hdulist attribute, which can be optionally saved to a file.

Parameters:

file_type (str) –

Type of file to be converted to FITS. One of [tpf, lc].
save (bool, default: False ) –

If True, write the HDUList to a file.
overwrite (bool, default: True ) –

If save, this determines whether to overwrite an existing file with the same name.
outdir (str, default: '' ) –

If save, this is the directory into which the file will be saved.
file_name (str, default: None ) –

If save, this is the filename that will be used. Format must be '.fits'. If no filename is given, a default one will be generated.

animate_tpf

animate_tpf(
    show_aperture: bool = True,
    show_ephemeris: bool = True,
    step: Optional[int] = None,
    save: bool = False,
    outdir: str = "",
    file_name: Optional[str] = None,
    **kwargs,
)

Plot animation of TPF data with optional information overlay.

Parameters:

show_aperture (bool, default: True ) –

If True, the aperture used for photometry is displayed in the animation.
show_ephemeris (bool, default: True ) –

If True, the predicted position of the target is included in the animation.
step (int or None, default: None ) –

Spacing between frames, i.e. plot every nth frame. If None, the spacing will be determined such that about 50 frames are shown. Showing more frames will increase the runtime and, if save, the file size.
save (bool, default: False ) –

If True, save the animation.
outdir (str, default: '' ) –

If save, this is the directory into which the file will be saved.
file_name (str or None, default: None ) –

If save, this is the filename that will be used. Format must be '.gif'. If no filename is given, a default one will be generated.
kwargs –

Keyword arguments passed to utils.animate_cube such as interval, repeat_delay, cnorm, vmin, vmax.

Returns:

animation ( html ) –

If in a notebook environment, the animation is returned in HTML format for display purposes.

plot_lc

plot_lc(
    lc: Optional[dict] = None,
    method: str = "all",
    bad_spoc_bits: Union[list[int], str] = "default",
    bad_ap_bits: Union[list[int], str] = "default",
    bad_psf_bits: Union[list[int], str] = "default",
    plot_err: bool = False,
    plot_bad_quality: bool = True,
    xlim: Optional[tuple] = None,
    ylim: Optional[tuple] = None,
    save: bool = False,
    outdir: str = "",
    file_name: Optional[str] = None,
)

Plot aperture and/or PSF lightcurves, with options to customise and save.

Parameters:

lc (dict, default: None ) –

A dictionary containing aperture and PSF photometry. This must have the same structure as that produced by self.to_lightcurve(). If None, self.lc will be used by default.
method (str, default: 'all' ) –

Lightcurve to plot. One of [all, aperture, psf].
bad_spoc_bits (list or str, default: 'default' ) –
Defines SPOC bits corresponding to bad quality data. Can be one of:
- "default" - mask bits defined by default_bad_spoc_bits.
- "all" - mask all data with a SPOC quality flag.
- "none" - mask no data.
- list - mask custom bits provided in list.
More information about the SPOC quality flags can be found in Section 9 of the TESS Science Data Products Description Document.
bad_ap_bits (Union[list[int], str], default: 'default' ) –
Defines bits corresponding to bad quality data for aperture/psf photometry, as defined by _create_lc_quality(). Can be one of:
- "default" - mask bits defined by default_bad_lc_bits.
- "all" - mask all data with a quality flag.
- "none" - mask no data.
- list - mask custom bits provided in list.
plot_err (bool, default: False ) –

If True, plot errorbars on lightcurve.
plot_bad_quality (bool, default: True ) –

If True, include data flagged as bad quality in the plot.
xlim (Optional[tuple], default: None ) –

(min, max) axes limits.
save (bool, default: False ) –

If True, save the figure.
outdir (str, default: '' ) –

If save, this is the directory into which the file will be saved.
file_name (str or None, default: None ) –

If save, this is the filename that will be used. If no filename is given, a default one will be generated.

Returns:

fig ( Figure ) –

Matplotlib figure object.

MovingTPF

MovingTPF

from_name staticmethod

make_tpf

make_lc

get_data

reshape_data

background_correction

create_aperture

create_pixel_quality

to_lightcurve

_create_lc_quality

create_lc_quality_mask

to_fits

animate_tpf

plot_lc

`MovingTPF`

from_name `staticmethod`