`MovingTPF`

MovingTPF

MovingTPF(
    target: str,
    ephem: DataFrame,
    time_scale: str = "tdb",
    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'].
- 'time' : float in format (JD - 2457000). See also time_scale 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.
time_scale (str, default: 'tdb' ) –
Time scale of input ephem['time']. One of ['tdb', 'utc']. Default is 'tdb'.
- If 'tdb', the input ephem['time'] must be in TDB measured at the solar system barycenter from the TESS FFI header. This is the scale used for the 'TSTART'/'TSTOP' keywords in SPOC FFI headers and the 'TIME' column in SPOC TPFs and LCFs.
- If 'utc', the input ephem['time'] must be in UTC 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}.
- '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.

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'].
- 'time' : float with units (JD - 2457000) in UTC 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.

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 = "aperture",
    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: 'aperture' ) –

Method to extract lightcurve. One of [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 a 3D pixel quality mask. The mask is a bit-wise combination of the following flags (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 linear model, value was infilled. 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).

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.

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.

MovingTPF

MovingTPF

from_name staticmethod

make_tpf

make_lc

get_data

reshape_data

background_correction

create_aperture

create_pixel_quality

to_lightcurve

to_fits

animate_tpf

`MovingTPF`

from_name `staticmethod`