Skip to content

Utils

get_p_tdur_t0(tce)

Extract the orbital period, transit duration, and transit epoch (t0) from a TCE NumPy array.

Parameters:

Name Type Description Default
tce Series

Row from a TCE DataFrame containing the columns period, tdur, and t0. period and tdur are in days, and t0 is in BJD.

required

Returns:

Type Description
tuple[float, float, float]

A tuple containing the period, transit duration, and transit epoch (t0), in that order.

create_spline_design_matrix(time, tdur, order=3, spacing_mult=3.0)

Construct a piecewise spline design matrix.

Parameters:

Name Type Description Default
time ndarray

One-dimensional array of time values.

required
tdur float

Transit duration in the same units as time. Used to set the spline knot spacing.

required
order int

Order of the spline. Default is 3 for cubic splines.

3
spacing_mult float

Multiplier applied to the transit duration to set the spline knot spacing. Default is 3.0.

3.0

Returns:

Type Description
ndarray

Spline design matrix evaluated at the normalized time values.

create_polynomial_design_matrix(time)

Construct a piecewise quadratic polynomial design matrix.

Parameters:

Name Type Description Default
time ndarray

One-dimensional array of time values.

required

Returns:

Type Description
numpy.ndarray :

Piecewise polynomial design matrix with separate quadratic trends for each continuous time segment.

coords_to_pixels(wcs, ra, dec)

Convert sky coordinates (RA, Dec) to detector pixel coordinates.

Parameters:

Name Type Description Default
wcs WCS

World Coordinate System transformation object.

required
ra float

Right ascension in degrees.

required
dec float

Declination in degrees.

required

Returns:

Type Description
tuple[float, float]

Pixel column and row coordinates corresponding to the input sky coordinates.

query_vizier_background(ra_targ, dec_targ, tpf_shape, mission, radius=60)

Query background sources from Vizier

Parameters:

Name Type Description Default
ra_targ float

Target right ascension in degrees.

required
dec_targ float

Target declination in degrees.

required
tpf_shape tuple

Shape of the target pixel file (e.g., (n_rows, n_cols)), used to estimate the search radius.

required
radius float

Search radius in arcseconds. Used when mission is not specified and pixel size is unknown (default 60).

60
mission string

Mission name. If mission is 'tess' or 'kepler', search radius is based on tpf_shape rather than radius.

required

Returns:

Name Type Description
query_result Table or None

Table of sources from Gaia DR3 within the search radius, including 'ID', 'Gmag', 'pmra', 'pmdec', 'RA_ICRS', 'DE_ICRS'. Returns None if no sources found.

propagate_query(query_result, wcs, epoch)

Propagate Gaia query coordinates to a given epoch and convert to pixel coordinates.

Parameters:

Name Type Description Default
query_result dict or Table

Source data containing at least: - 'RA_ICRS', 'DE_ICRS' in degrees - 'pmRA', 'pmDE' in mas/yr

required
wcs WCS

World Coordinate System transformation object.

required
epoch Time

Observation epoch to propagate coordinates to.

required

Returns:

Name Type Description
coord_bkgd SkyCoord

Sky coordinates of catalog sources propagated to the observation epoch.

pix_bkgd tuple[ndarray, ndarray]

Pixel coordinates of the sources as arrays of column and row positions.

prf_residual(params, prf, data, data_err, origin, shape)

Compute the flattened, uncertainty-weighted residual for PRF fitting.

Parameters:

Name Type Description Default
params Parameters

Fit parameters containing 'amplitude', 'centerx', and 'centery'.

required
prf lkprf PRF model

PRF model object used to evaluate the expected spatial flux distribution. For example, a KeplerPRF or TESSPRF object.

required
data ndarray

2D array of observed pixel values.

required
data_err ndarray

2D array of per-pixel uncertainties.

required
origin tuple[float, float]

CCD reference position as (row_origin, col_origin).

required
shape tuple[int, int]

Shape of the image stamp as (n_rows, n_cols).

required

Returns:

Type Description
ndarray

Flattened array of finite, uncertainty-weighted residuals.

Raises:

Type Description
ValueError

If no finite residuals can be calculated from the input pixels.

all_prf_residual(params, prf, data, data_err, origin, shape, valid_tces, tce_mapping)

Compute concatenated, uncertainty-weighted residuals for multiple TCEs.

Parameters:

Name Type Description Default
params Parameters

Fit parameters containing centerx, centery, and amplitude_i for each TCE index i.

required
prf lkprf PRF model

PRF model object used to evaluate the expected spatial flux distribution, such as a KeplerPRF or TESSPRF object.

required
data ndarray

Array of 2D pixel data for each TCE with shape (n_tces, n_rows, n_cols).

required
data_err ndarray

Array of per-pixel uncertainties with the same shape as data.

required
origin tuple[float, float]

CCD reference position as (row_origin, col_origin).

required
shape tuple[int, int]

Shape of the image stamp as (n_rows, n_cols).

required
valid_tces ndarray

Indices of TCEs that produce non-zero transit models and are included in the fit.

required
tce_mapping dict[int, int]

Mapping from the original TCE index to its column index in data and data_err.

required

Returns:

Type Description
ndarray

Flattened array of finite, concatenated residuals across all valid TCEs.

Raises:

Type Description
ValueError

If no valid residuals can be calculated for any TCE.

quarters_prf_residual(params, prf_list, data_list, data_err_list, wcs_list, origin_list, shape_list, tce_mapping_list, valid_idxs, which_tce)

Compute concatenated, uncertainty-weighted residuals for a TCE across multiple quarters or sectors.

Parameters:

Name Type Description Default
params Parameters

Fit parameters containing centerra, centerdec, and amplitude_i for each valid quarter or sector.

required
prf_list list

List of lkprf PRF model objects, one for each observation.

required
data_list list[ndarray]

List of transit depth maps for each observation.

required
data_err_list list[ndarray]

List of per-pixel uncertainties corresponding to data_list.

required
wcs_list list[WCS]

List of WCS objects used to convert sky coordinates to pixel coordinates for each observation.

required
origin_list list[tuple[float, float]]

List of CCD reference positions as (row_origin, col_origin) for each observation.

required
shape_list list[tuple[int, int]]

List of image stamp shapes as (n_rows, n_cols).

required
tce_mapping_list list[dict[int, int]]

List of mappings from TCE indices to their corresponding columns in the transit depth maps.

required
valid_idxs list[int]

Indices of observations containing the TCE being fitted.

required
which_tce int

Index of the TCE being fitted.

required

Returns:

Type Description
ndarray

Flattened array of finite, concatenated residuals across all valid observations.

Raises:

Type Description
ValueError

If no valid residuals can be calculated for any observation.