Skip to content

Localize

Bases: object

__init__(time, flux, flux_err, tces, id, ra_targ, dec_targ, wcs, epoch, mission=None, ra_bonus=None, dec_bonus=None, prf=None, headers=None, **mission_keywords)

Initialize the Localize object.

Parameters:

Name Type Description Default
time ndarray

1D array of time values in BJD.

 required
flux ndarray

3D flux cube with shape (n_time, n_rows, n_cols).

 required
flux_err ndarray

3D array of per-pixel uncertainties matching flux.

 required
tces DataFrame

DataFrame containing Threshold Crossing Event (TCE) information. Must contain the columns period, t0, and tdur. The period and tdur values must be in days, and t0 must be in BJD.

 required
id str

Target identifier. Do not include the mission prefix (TIC/KIC/etc.).

 required
ra_targ float

J2000 right ascension of the target, in degrees.

 required
dec_targ float

J2000 declination of the target, in degrees.

 required
wcs WCS

WCS solution for pixel-to-sky transformations.

 required
epoch Time

Epoch of the input coordinates.

 required
mission str

Mission name (e.g., 'kepler', 'tess').

 None
ra_bonus float

J2000 right ascension of a source different from the nominal mission target, in degrees.

 None
dec_bonus float

J2000 declination of a source different from the nominal mission target, in degrees.

 None
prf object

Precomputed PRF model.

 None
headers list of astropy.io.fits.Header

FITS headers from the original FITS file. Each entry corresponds to the header of a single HDU.

 None
**mission_keywords

Additional mission-specific keyword arguments stored directly in the instance dictionary. Common entries include sector/quarter, channel, CCD, camera, and other instrument metadata required for PRF evaluation.

 {}

Raises:

Type Description
ValueError

If flux is not 3D, if the length of time does not match the first axis of flux, or if tces does not contain the required columns.
TypeError

If tces is not a pandas DataFrame.

from_tpf_info(filename, tces, id, mission, ra_bonus=None, dec_bonus=None) staticmethod

Create a Localize object from a Kepler or TESS Target Pixel File (TPF).

Parameters:

Name Type Description Default
filename str

Path to the TPF FITS file.

 required
tces DataFrame

DataFrame containing Threshold Crossing Event (TCE) information associated with the target.

 required
id str

Identifier for the target.

 required
mission str

Name of the mission ('kepler' or 'tess').

 required
ra_bonus float

J2000 right ascension of a source different from the nominal mission target, in degrees.

 None
dec_bonus float

J2000 declination of a source different from the nominal mission target, in degrees.

 None

Returns:

Type Description
Localize

Initialized Localize object containing the data and metadata extracted from the TPF.

build_design_matrix(order=3, spacing_mult=3.0, tdur_frac=3.0, transit_method='box', batman_kws=None)

Construct the full design matrix.

Parameters:

Name Type Description Default
order int

Order of the spline used to model short-term variability. Default is 3.

 3
spacing_mult float

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

 3.0
tdur_frac float

Factor used to determine the width of the box-shaped transit model. The transit mask extends to tdur / tdur_frac from the transit center. Default is 3.0.

 3.0
transit_method str

Method used to generate the transit component. Options are "box" and "batman". Default is "box".

 'box'
batman_kws list of dict

List of dictionaries containing additional arguments passed to the batman transit model. One dictionary is required for each TCE when transit_method="batman".

 None

Raises:

Type Description
ValueError

If transit_method is not "box" or "batman", or if transit_method="batman" and batman_kws is not provided.

Attributes:

Name Type Description
valid_tces ndarray

Indices of TCEs in self.tces that produce non-zero transit models and are included as columns in the design matrix.
tce_mapping dict

Mapping from TCE indices in the self.tces DataFrame to their corresponding column indices in the design matrix.
design_matrix ndarray or None

Final design matrix combining transit, polynomial, and spline components. Set to None if no valid transits are found.

solve_transit_weights()

Solve for the spatial transit depth maps for all TCEs.

Attributes:

Name Type Description
self.transit_weights list of numpy.ndarray

List of 2D transit depth maps, one per TCE.
self.transit_weights_err list of numpy.ndarray

List of 2D 1-sigma uncertainty maps corresponding to each transit depth map.

fit_to_heatmap(model_func=None, which_tce=None, method='prf', initial_loc=None, **fit_kw)

Fit a model to the per-pixel transit depth heatmap.

Parameters:

Name Type Description Default
model_func callable

Custom residual function used when method="custom".

 None
which_tce int

Index of the TCE to fit. For method="prf", if None, a joint PRF fit is performed across all valid TCEs.

 None
method str

Fitting method. Must be "prf", "2dgaussian", or "custom".

 'prf'
initial_loc tuple of float

Initial guess for the centroid position as (col, row) in pixel coordinates. If None, the position is initialized using ra_bonus and dec_bonus if provided, otherwise ra_targ and dec_targ.

 None
**fit_kw

Additional keyword arguments passed to the custom model.

 {}

Returns:

Name Type Description
result ModelResult or MinimizerResult

Full fit result object.
fit_metrics dict

Dictionary containing the best-fit centroid position and corresponding 1-sigma uncertainties. Keys are "centerx", "centery", "sigmax", and "sigmay".

Raises:

Type Description
ValueError

If an unsupported fitting method is provided, if which_tce is required but not provided, or if a required argument for the selected fitting method is missing.
KeyError

If which_tce does not correspond to a valid TCE for the current quarter or sector.
RuntimeError

If an unexpected error occurs during fitting.

get_offset(fit_metrics)

Compute the centroid offset in units of sigma.

Parameters:

Name Type Description Default
fit_metrics dict

Dictionary containing the fitted centroid positions and their uncertainties. Must contain "centerx", "centery", "sigmax", and "sigmay".

 required

Returns:

Name Type Description
nsigma float

Radial offset between the fitted centroid and the expected source position, expressed in units of the propagated positional uncertainty.
dist float

Euclidean distance between the fitted centroid and the expected source position in pixels.
sigma_dist float

Propagated 1-sigma uncertainty on the radial distance in pixels.
mah_dist float

Mahalanobis distance between the fitted centroid and the expected source position.

Raises:

Type Description
KeyError

If a required key is missing from fit_metrics.

plot_heatmap(metrics, which_tce, savefig=False, save_directory='.')

Generate a localization report plot for a given TCE.

Parameters:

Name Type Description Default
metrics dict

Dictionary containing the fitted centroid positions and their uncertainties. Must contain "centerx", "centery", "sigmax", and "sigmay".

 required
which_tce int

Index of the TCE in self.tces to visualize.

 required
savefig bool

If True, save the figure to disk. Default is False.

 False
save_directory str

Directory where the figure will be saved. Default is the current directory.

 '.'

Raises:

Type Description
KeyError

If which_tce does not correspond to a valid TCE for the current quarter or sector.