`BackgroundCube`

BackgroundCube

Bases: object

Class for creating TESS Full Frame Image background cubes to train a deep learning model that predicts the scatter light.

It uses tesscube to retrieve FFI cubes from MAST/AWS, does spatia binning to downsize the 2k x 2k image, e.g. to 128 x 128 pixels. It uses tessvectors to obtain Earth/Moon angles/distances with respect to each TESS camera and creates a pixel map for each object angle and distance with the same resolution as the downsize FFI cube.

Package the data into local files or returns batches fot ML training.

Parameters:

sector (int, default: 1 ) –

TESS sector number. Must be between 1 and 100. Default is 1.
camera (int, default: 1 ) –

TESS camera number. Must be between 1 and 4. Default is 1.
ccd (int, default: 1 ) –

TESS CCD number. Must be between 1 and 4. Default is 1.
img_bin (int, default: 16 ) –

Binning factor for spatial downsampling of the FFI image. Must be a divisor of 2048. Default is 16. #
downsize (str, default: 'binning' ) –

Method for spatial downsampling. Options are 'binning' (median binning) or 'sparse' (select sparse pixels). Default is "binning".

init

__init__(
    sector: int = 1,
    camera: int = 1,
    ccd: int = 1,
    img_bin: int = 16,
    downsize: str = "binning",
)

plot_dark_frame

plot_dark_frame(mask_straps: bool = False)

Displays diagnostic plots of the darkest frame and associated masks.

Shows the darkest FFI frame, the generated star mask, and optionally the strap mask.

Parameters:

mask_straps (bool, default: False ) –

If True, also fetches and plots the strap mask. Requires the _get_straps_mask method to have been called or will call it. Default is False.

get_scatter_light_cube

get_scatter_light_cube(
    plot: bool = False,
    mask_straps: bool = True,
    frames: Optional[Tuple] = None,
    rolling: bool = True,
    errors: bool = True,
)

Computes the scattered light cube by processing FFIs.

This method orchestrates the process of: 1. Identifying dark frames (_get_dark_frame_idx). 2. Creating a star mask (_get_star_mask). 3. Optionally creating a strap mask (_get_straps_mask). 4. Defining background pixels (excluding stars and optionally straps). 5. Calculating the static scene by median-combining dark frames (_get_static_scene). 6. Iterating through FFIs (all or a specified range): - Fetching FFI data. - Applying the background pixel mask (masking stars/straps). - Subtracting the static scene. - Downsampling the result using the specified downsize method ('binning' or 'sparse'). 7. Storing the final scattered light cube.

Parameters:

plot (bool, default: False ) –

If True, displays the diagnostic dark frame plots after mask creation. Default is False.
mask_straps (bool, default: True ) –

If True, masks out pixels corresponding to CCD straps in addition to stars. Default is False.
frames (Optional[Tuple], default: None ) –

Specifies a range of frame indices to process. Can be: - (N,): Process frames from 0 up to (but not including) N. - (start, stop): Process frames from index start up to stop. - (start, stop, step): Process frames from start to stop with step. If None, processes all frames. Default is None.
rolling (bool, default: True ) –

If True, pooling downsizing will be done with an iterative rolling windown and stride that will match the output desired shape, this will make the downsizing step slower. If False, pooling downsizing will use fixed window and stride.
errors (bool, default: True ) –

Retrieve and propagate errors

get_vector_maps

get_vector_maps(ang_size: bool = True)

Generates pixel-wise maps of Earth and Moon positions and sizes.

Fetches spacecraft orientation and Earth/Moon position vectors using tessvectors. Then, for both Earth and Moon, it calls _get_object_vectors to compute 3D maps (time, row, col) representing the distance/angular size, altitude, and azimuth for each pixel in the downsampled grid over time. Also stores the boresight vectors for reference.

Parameters:

ang_size (bool, default: True ) –

If True, the 'dist' maps and vectors represent angular size (degrees). If False, they represent physical distance ([m] for maps). Default is True.

bin_time_axis

bin_time_axis(bin_size: float = 2.5)

Performs temporal binning on the calculated data cubes and vectors.

If self.time_bin is greater than 1, this method bins the time axis of scatter_cube, time, cadenceno, and all Earth/Moon vector maps and boresight vectors by taking the mean or median within each time bin.

Parameters:

bin_size (float, default: 2.5 ) –

Bin size for time axis in units of hours (e.g. 2.5 hours).

save_to_fits

save_to_fits(
    out_file: Optional[str] = None, binned: bool = True
)

Saves the downsize version of the scatter light cube as a FITS file similar to the MAST FFI cubes.

Parameters:

out_file (Optional[str], default: None ) –

Path to the output .npz file. If None, a default filename is generated based on sector, camera, ccd, and binning factor, saved in the current directory. Default is None.

Returns:

hdul ( HDUList object ) –

Header unit list with data and metadata

save_to_npz

save_to_npz(
    out_file: Optional[str] = None, save_maps: bool = False
)

Saves the processed background data to a NumPy .npz file.

Parameters:

out_file (Optional[str], default: None ) –

Path to the output .npz file. If None, a default filename is generated based on sector, camera, ccd, and binning factor, saved in the current directory. Default is None.
save_maps (bool, default: False ) –

If True, saves the detailed pixel-wise maps for Earth and Moon angles/distances alongside the scatter cube and boresight vectors. If False, saves only the scatter cube, time, cadence, and boresight vectors (smaller file size). Default is False.

animate_data

animate_data(
    data: str = "sl",
    step: int = 10,
    file_name: Optional[str] = None,
    save: bool = False,
)

Creates and optionally saves an animation of the processed data cubes.

Generates an animation showing the time evolution of either the scattered light cube or one of the Earth/Moon angle/distance maps.

Parameters:

data (str, default: 'sl' ) –

Which data cube to animate. Options are: - 'sl': Scattered light cube (scatter_cube). - 'earth_alt': Earth altitude map (earth_maps['alt']). - 'earth_az': Earth azimuth map (earth_maps['az']). - 'earth_dist': Earth distance/angular size map (earth_maps['dist']). - 'moon_alt', 'moon_az', 'moon_dist': Corresponding Moon maps. Default is "sl".
step (int, default: 10 ) –

Frame step for the animation (e.g., step=10 shows every 10th frame). Default is 10.
file_name (Optional[str], default: None ) –

Filename for saving the animation as a GIF. If None and save is True, a default filename is generated. Default is None.
save (bool, default: False ) –

If True, saves the animation to the specified file_name (or default). If False, attempts to display the animation directly (requires IPython). Default is False.

Returns:

HTML or None –

If save is False and IPython is available, returns an HTML object for displaying the animation. Otherwise returns None.