`utils`

utils

Utility functions

target_observability

target_observability(
    target: str,
    sector: Optional[int] = None,
    return_ephem: bool = False,
)

Determine if a target has been observed by TESS and, if so, during which sector/camera/CCD. This function will also give an estimate of the length of time, in days, for which the target was observed on each sector/camera/CCD.

Parameters:

target (str) –

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

TESS sector number. If you want to know whether your target was observed during a specific sector, set this parameter. If None, all available sectors will be checked.
return_ephem (bool, default: False ) –

If True, this will return the full ephemeris of the target in addition to the observability summary.

Returns:

obs ( DataFrame ) –
A summary of the TESS observations of the target. There is one entry for each unique combination of sector/camera/CCD. The DataFrame has the following columns:
- 'sector', 'camera', 'ccd': sector/camera/CCD target was observed in.
- 'dur': approximate duration for which target was observed in this sector/camera/CCD, in days.
df_ephem ( DataFrame ) –

If return_ephem = True, the ephemeris will also be returned. This includes the pixel 'row' and 'column' of the target over time.

calculate_TESSmag

calculate_TESSmag(
    flux: Union[float, ndarray],
    flux_err: Union[float, ndarray],
    flux_fraction: Union[float, ndarray],
)

Calculate TESS magnitude from a flux and a zero-point magnitude. The equation was taken from the TESS Instrument Handbook 2018 (see also Fausnaugh et al. 2021).

This function assumes that the background flux has been perfectly removed, i.e. the only flux is that from the target. It can account for flux outside of the aperture via flux_fraction.

Parameters:

flux (float or ndarray) –

Target flux, in electrons/second.
flux_err (float or ndarray) –

Error on target flux, in electrons/second.
flux_fraction (float or ndarray) –

Fraction of target flux inside aperture. Must satisfy: 0 < flux_fraction <= 1.

Returns:

mag ( float or ndarray ) –

TESS magnitude.
mag_err ( float or ndarray ) –

Error on TESS magnitude.

compute_moments

compute_moments(
    flux: ndarray,
    mask: Optional[ndarray] = None,
    second_order: bool = True,
    return_err: bool = False,
)

Computes first and second order moments of a 2d distribution over time using a coordinate grid with the same shape as flux (nt, nrows, ncols). First order moments (X,Y) are the centroid positions. The X,Y centroids are in the range [0, ncols), [0, nrows), respectively i.e. they are zero-indexed. Second order moments (X2, Y2, XY) represent the spatial spread of the distribution.

Parameters:

flux (ndarray) –

3D array with flux values as (nt, nrows, ncols).
mask (Optional[ndarray], default: None ) –

Mask to select pixels used for computing moments. Shape could be 3D (nt, nrows, ncols) or 2D (nrows, ncols). If a 2D mask is given, it is used for all frames.
second_order (bool, default: True ) –

If True, returns first and second order moments, else returns only first order moments.
return_err (bool, default: False ) –

If True, returns error on first order moments.

Returns:

X, Y, XERR, YERR, X2, Y2, XY: ndarrays –

First (X, Y) and second (X2, Y2, XY) order moments, plus error on first order moments (XERR, YERR). If second_order is False, X2/Y2/XY are not returned. If return_err is False, XERR/YERR are not returned. Each array has shape (nt).

plot_img_aperture

plot_img_aperture(
    img: ndarray,
    aperture_mask: Optional[ndarray] = None,
    cbar: bool = True,
    ax: Optional[Axes] = None,
    corner: Tuple[int, int] = (0, 0),
    marker: Optional[Tuple[float, float]] = None,
    title: str = "",
    vmin: Optional[float] = None,
    vmax: Optional[float] = None,
    cnorm: Optional[Normalize] = None,
)

Plots an image with an optional aperture mask.

This function displays an image, optionally overlaying an aperture mask, and provides several customization options such as color scaling, title, and axis control.

Parameters:

img (2D array) –

The image data to be plotted, typically a 2D array or matrix representing pixel values.
aperture_mask (2D array, default: None ) –

A binary mask (same shape as img) indicating the aperture region to be overlaid on the image.
cbar (bool, default: True ) –

Whether to display a color bar alongside the plot.
ax (Axes, default: None ) –

The axes object where the plot will be drawn. If not provided, a new axes will be created.
corner (list of two ints, default: [0, 0] ) –

The (row, column) coordinates of the lower left corner of the image.
marker (tuple of float, default: None ) –

The (row, column) coordinates at which to plot a marker in the figure. This can be used to plot the position of the moving object.
title (str, default: "" ) –

Title of the plot. If None, no title will be shown.
vmin (float, default: None ) –

Minimum value for color scale. If None, the 3%-percentile is used.
vmax (float, default: None ) –

Maximum value for color scale. If None, the 97%-percentile is used.
cnorm (optional, default: None ) –

Color matplotlib normalization object (e.g. astropy.visualization.simple_norm). If provided, then vmax and vmin are not used.

Returns:

ax ( Axes ) –

The axes object containing the plot.

animate_cube

animate_cube(
    cube: ndarray,
    aperture_mask: Optional[ndarray] = None,
    corner: Union[Tuple, ndarray] = (0, 0),
    ephemeris: Optional[ndarray] = None,
    cadenceno: Optional[ndarray] = None,
    time: Optional[ndarray] = None,
    interval: int = 200,
    repeat_delay: int = 1000,
    step: int = 1,
    vmin: Optional[float] = None,
    vmax: Optional[float] = None,
    cnorm: bool = False,
    suptitle: str = "",
)

Creates an animated visualization of a 3D image cube, with an optional aperture mask and other customization options.

This function animates the slices of a 3D image cube, optionally overlaying an aperture mask, and provides controls for animation speed, title, and tracking information.

Parameters:

cube (3D array) –

A 3D array representing the image cube (e.g., a stack of 2D images over time).
aperture_mask (2D or 3D array, default: None ) –

A binary mask (same shape or a 2D slice of cube) to overlay on each frame of the animation. If a 2D mask is passed, it will be repeated for all times.
corner (list of two ints or 2D array, default: [0, 0] ) –

The (row, column) coordinates of the lower left corner of the image.
ephemeris (2D array, default: None ) –

A 2D array of object positions (row, column) to be displayed on the plot. For proper display of object position, if corner is [0, 0] then ephemeris needs to be relative to corner. If corner is provided, ephemeris needs to be absolute. If None, no tracking information is shown.
cadenceno (int, default: None ) –

The cadence number of the frames, used for information display.
time (array - like, default: None ) –

Array of time values corresponding to the slices in the cube.
interval (int, default: 200 ) –

The time interval (in milliseconds) between each frame of the animation.
repeat_delay (int, default: 1000 ) –

The time delay (in milliseconds) before the animation restarts once it finishes.
step (int, default: 1 ) –

Spacing between frames, i.e. plot every nth frame.
vmin (float, default: None ) –

Minimum value for color scale. If None, the 3%-percentile is used.
vmax (float, default: None ) –

Maximum value for color scale. If None, the 97%-percentile is used.
cnorm (optional, default: False ) –

Whether to use asinh color normalization (from astropy.visualization.simple_norm). This can be useful for cases when the moving object is too faint compared to other features in the background. If provided, then vmax and vmin are not used.
suptitle (str, default: "" ) –

A string to be used as the super title of the animation. It can be used to provide additional context or information about the animated data, for example the target name or observing sector/camera/ccd.

Returns:

ani ( FuncAnimation ) –

The animation object that can be displayed or saved.