API Reference
Main Dataset Classes
ExoTools - Tools for working with exoplanet data.
- class exotools.PlanetarySystemsDataset(dataset_tag=None, storage=None)[source]
Bases:
BaseDatasetDataset class for accessing and managing confirmed exoplanets data.
This class provides functionality to download, store, and retrieve data about known exoplanets from the NASA Exoplanet Archive. It also supports integration with Gaia stellar data and can generate star system representations that combine exoplanet and stellar information.
Initialize a PlanetarySystemsDataset instance.
- Parameters:
dataset_tag (str | None) – Tag to identify this specific dataset instance, it will be used as a postfix for all the storage keys.
storage (BaseStorage | None) – Storage backend for persisting dataset information. Defaults to in-memory storage.
- load_known_exoplanets_dataset(with_gaia_star_data=False, with_name=None)[source]
Load previously stored known exoplanets dataset.
Attempts to load known exoplanets data from the configured storage backend, optionally including associated Gaia stellar data.
- Parameters:
- Returns:
Database object containing the loaded exoplanets data, or None if no data is found in storage.
- Raises:
Various exceptions may be raised by the underlying storage backend if the –
load operation fails for reasons other than missing data. –
- Return type:
ExoDB | None
- load_star_system_dataset(with_name=None)[source]
Load previously stored star system dataset.
Attempts to load a reduced representation of star systems from the configured storage backend. If the reduced dataset doesn’t exist, it will attempt to compute it from the full exoplanet and Gaia datasets.
- Parameters:
with_name (str | None) – A distinctive name to give the dataset, it will be used as a postfix for the artifact name.
- Returns:
Database object containing star system data, or None if the required data is not found in storage.
- Raises:
Various exceptions may be raised by the underlying storage backend if the –
load operation fails for reasons other than missing data. –
- Return type:
StarSystemDB | None
- load_gaia_dataset_of_known_exoplanets(with_name=None)[source]
Load previously stored Gaia data for known exoplanets’ host stars.
Attempts to load Gaia stellar data associated with known exoplanets from the configured storage backend.
- Parameters:
with_name (str | None) – A distinctive name to give the dataset, it will be used as a postfix for the artifact name.
- Returns:
Database object containing Gaia stellar data, or None if no data is found in storage.
- Raises:
Various exceptions may be raised by the underlying storage backend if the –
load operation fails for reasons other than missing data. –
- Return type:
GaiaDB | None
- download_known_exoplanets(with_gaia_star_data=False, limit=None, columns=None, where=None, with_name=None, store=True)[source]
Download known exoplanets data from NASA Exoplanet Archive.
Retrieves data about confirmed exoplanets and optionally their host stars’ Gaia data, and stores it in the configured storage backend.
- Parameters:
with_gaia_star_data (bool) – Whether to also download Gaia data for the host stars. Default is False.
limit (int | None) – Maximum number of exoplanets to retrieve. Default is None (no limit).
columns (Sequence[str] | None) – Specific columns to retrieve. Default is None (all available columns).
where (dict[str, Any | list[Any]] | None) – Additional filters to apply to the data.
with_name (str | None) – A distinctive name to give the dataset, it will be used as a postfix for the artifact name.
store (bool) – Whether to store the downloaded data in the storage backend. Default is True.
- Returns:
Database object containing the downloaded exoplanets data.
- Raises:
Various exceptions may be raised by the underlying downloader if the –
download fails. –
- Return type:
- class exotools.CandidateExoplanetsDataset(dataset_tag=None, storage=None)[source]
Bases:
BaseDatasetDataset class for accessing and managing candidate exoplanets data.
This class provides functionality to download, store, and retrieve candidate exoplanets data from the NASA Exoplanet Archive. It handles the retrieval and storage of exoplanet candidates that have not yet been confirmed as actual exoplanets.
Initialize a CandidateExoplanetsDataset instance.
- Parameters:
dataset_tag (str | None) – Tag to identify this specific dataset instance, it will be used as a postfix for all the storage keys.
storage (BaseStorage | None) – Storage backend for persisting dataset information. Defaults to in-memory storage.
- load_candidate_exoplanets_dataset(with_name=None)[source]
Load previously stored candidate exoplanets dataset, with an optional distinctive name. Attempts to load candidate exoplanets data from the configured storage backend.
- Returns:
Database object containing the loaded candidate exoplanets data, or None if no data is found in storage.
- Raises:
Various exceptions may be raised by the underlying storage backend if the –
load operation fails for reasons other than missing data. –
- Parameters:
with_name (str | None)
- Return type:
CandidateDB | None
- download_candidate_exoplanets(limit=None, with_name=None, store=True)[source]
Retrieves candidate exoplanets data from NASA Exoplanet Archive and optionally stores it in the configured storage backend.
- Parameters:
- Returns:
Database object containing the downloaded candidate exoplanets data.
- Raises:
Various exceptions may be raised by the underlying downloader if the –
download fails. –
- Return type:
- class exotools.TicCatalogDataset(dataset_tag=None, storage=None)[source]
Bases:
BaseDatasetDataset class for accessing and managing TESS (Transiting Exoplanet Survey Satellite) catalog data.
This class provides functionality to download, store, and retrieve TESS observation metadata and TIC (TESS Input Catalog) target information. It interfaces with the MAST archive to retrieve TESS-related data.
- Parameters:
dataset_tag (str | None) – Tag to identify this specific dataset instance, it will be used as a postfix for all the storage keys.
storage (BaseStorage | None) – Storage backend for persisting dataset information. Defaults to in-memory storage.
- classmethod authenticate_casjobs(username, password)[source]
Authenticate with the MAST CasJobs service using the provided username and password. Authentication is required for querying the TIC
Create an account at https://mastweb.stsci.edu/mcasjobs/CreateAccount.aspx
- download_tic_targets(limit=None, star_mass_range=None, priority_threshold=None, with_name=None, store=False)[source]
Searches the TESS Input Catalog for targets matching the given criteria and optionally stores the results in the configured storage backend.
- Parameters:
limit (int | None) – Maximum number of targets to retrieve. Default is None (no limit).
star_mass_range (tuple[float, float] | None) – Range of stellar masses to filter by, specified as (min_mass, max_mass) in solar masses. Default is None (no filtering).
priority_threshold (float | None) – Minimum priority value for targets. Default is None (no filtering).
with_name (str | None) – A distinctive name to give the dataset, it will be used as a postfix for the artifact name.
store (bool) – Whether to store the search results in the storage backend. Default is False.
- Returns:
Database object containing the search results.
- Return type:
- Raises:
ValueError – If username and password were not provided during initialization.
Various exceptions may be raised by the underlying downloader if the –
download fails. –
- download_tic_targets_by_ids(tic_ids, with_name=None, store=True)[source]
Download TIC target information for specific TIC IDs.
Retrieves detailed information for the specified TIC IDs from the TESS Input Catalog and optionally stores it in the configured storage backend.
- Parameters:
- Returns:
Database object containing the downloaded TIC target information.
- Return type:
- Raises:
ValueError – If username and password were not provided during initialization.
Various exceptions may be raised by the underlying downloader if the –
download fails. –
- load_tic_target_dataset(with_name=None)[source]
Load previously stored TIC target dataset.
Attempts to load TIC target data from the configured storage backend. This loads data that was previously stored via the search_tic_targets method.
- Parameters:
with_name (str | None) – A distinctive name to give the dataset, it will be used as a postfix for the artifact name.
- Returns:
- Database object containing the loaded TIC target data,
or None if no data is found in storage.
- Return type:
Optional[TicDB]
- Raises:
Various exceptions may be raised by the underlying storage backend if the –
load operation fails for reasons other than missing data. –
- class exotools.GaiaParametersDataset(dataset_tag=None, storage=None)[source]
Bases:
BaseDataset- Parameters:
dataset_tag (str | None)
storage (BaseStorage | None)
- class exotools.TicObservationsDataset(dataset_tag=None, storage=None)[source]
Bases:
BaseDataset- Parameters:
dataset_tag (str | None)
storage (BaseStorage | None)
- classmethod authenticate_mast(mast_token)[source]
Authenticate with the MAST archive using the provided MAST token. Get a MAST token from https://auth.mast.stsci.edu/tokens
- Parameters:
mast_token (str) – MAST token for authentication.
- download_observation_metadata(targets_tic_id, with_name=None, store=True)[source]
Download TESS observation metadata for specified TIC IDs.
Retrieves observation metadata for the given TIC IDs from the MAST archive and optionally stores it in the configured storage backend.
- Parameters:
- Returns:
Database object containing the downloaded observation metadata.
- Return type:
- Raises:
Various exceptions may be raised by the underlying downloader if the –
download fails. –
- load_observation_metadata(with_name=None)[source]
Load previously stored TESS observation metadata.
Attempts to load TESS observation metadata from the configured storage backend.
- Parameters:
with_name (str | None) – A distinctive name to give the dataset, it will be used as a postfix for the artifact name.
- Returns:
- Database object containing the loaded observation metadata,
or None if no data is found in storage.
- Return type:
Optional[TicObsDB]
- Raises:
Various exceptions may be raised by the underlying storage backend if the –
load operation fails for reasons other than missing data. –
- class exotools.LightcurveDataset(lc_storage_path, dataset_tag=None, override_existing=False, verbose=False)[source]
Bases:
BaseDatasetDataset class for accessing and managing astronomical lightcurve data.
This class provides functionality to download, store, and retrieve lightcurve data from various astronomical sources, primarily TESS (Transiting Exoplanet Survey Satellite). Unlike other datasets that use the BaseStorage interface, lightcurves are stored directly as FITS files in the filesystem.
Initialize a LightcurveDataset instance.
- Parameters:
lc_storage_path (Path) – Base directory where lightcurve files will be stored.
dataset_tag (str | None) – Tag to identify this specific dataset instance, it will be used as a postfix for the storage directory.
override_existing (bool) – Whether to overwrite existing lightcurve files when downloading. Default is False.
verbose (bool) – Whether to output detailed progress information during downloads. Default is False.
- download_lightcurves_from_tic_db(tic_obs_db, with_name=None)[source]
Download lightcurves for targets in a TESS metadata database.
For each observation in the provided TESS metadata database, downloads the corresponding lightcurve FITS file and stores it in the configured directory. Files are organized in subdirectories by TIC ID.
- Parameters:
- Returns:
Database object containing information about the downloaded lightcurves, or None if no lightcurves were downloaded.
- Raises:
Various exceptions may be raised by the underlying downloader if the –
download fails. –
- Return type:
LightcurveDB | None
- load_lightcurve_dataset(with_name=None)[source]
Load previously downloaded lightcurve files.
Scans the configured directory for lightcurve FITS files and creates a database object to access them.
- Parameters:
with_name (str | None) – A distinctive name to give the dataset, it will be used as a postfix for the artifact name.
- Returns:
Database object containing information about the available lightcurves, or None if no lightcurve files were found.
- Return type:
LightcurveDB | None
Database Classes
Database classes for exotools.
- class exotools.db.ExoDB(exoplanets_dataset)[source]
Bases:
PsDB- Parameters:
exoplanets_dataset (QTable)
- class exotools.db.GaiaDB(gaia_dataset)[source]
Bases:
BaseDB- Parameters:
gaia_dataset (QTable)
- static impute_radius(dataset)[source]
Creates a new column “radius” as the average of the available estimations. Fixes nan values where possible
- static compute_mean_temperature(dataset)[source]
Creates a new column “teff_mean” as the average of the available estimations.
- static compute_habitable_zone(dataset)[source]
https://www.planetarybiology.com/calculating_habitable_zone.html Whitmire, Daniel; Reynolds, Ray, (1996). Circumstellar habitable zones: astronomical considerations. In: Doyle, Laurence (ed.). Circumstellar Habitable Zones, 117-142. Travis House Publications, Menlo Park.
- class exotools.db.StarSystemDB(transit_dataset)[source]
Bases:
ExoDB- Parameters:
transit_dataset (QTable)
- get_star_system_from_star_name(star_name)[source]
- Parameters:
star_name (str)
- Return type:
StarSystem | None
- get_star_system_from_tic_id(tic_id)[source]
- Parameters:
tic_id (int)
- Return type:
StarSystem | None
- class exotools.db.LightcurveDB(dataset)[source]
Bases:
BaseDBDtypes:
obs_id int64 tic_id int64 path object ——————
- load_by_tic(tic_id, start_time_at_zero=False, load_in_jd_time=False)[source]
- Parameters:
- Return type:
list[LightCurvePlus] | None
- load_stitched_by_tic(tic_id, start_time_at_zero=False, load_in_jd_time=False)[source]
- Parameters:
- Return type:
LightCurvePlus | None
- load_by_obs_id(obs_id, start_time_at_zero=False, load_in_jd_time=False)[source]
- Parameters:
- Return type:
LightCurvePlus | None
- load_collections_by_tics(tic_ids, load_in_jd_time=False)[source]
- Parameters:
- Return type:
list[LightCurveCollection | None]
- load_stitched_by_tics(tic_ids, load_in_jd_time=False)[source]
- Parameters:
- Return type:
list[LightCurvePlus | None]
- load_by_obs_ids(obs_ids, load_in_jd_time=False)[source]
- Parameters:
- Return type:
list[LightCurvePlus | None]
- Parameters:
dataset (QTable)
- class exotools.db.LightCurvePlus(lightcurve, obs_id=None)[source]
Bases:
object- Parameters:
lightcurve (LightCurve)
obs_id (int | None)
- property elapsed_time: ndarray
Days since first cadence (relative timeline), independent of BJDREF*.
- get_transit_first_index(planet)[source]
Get the index of the first transit in the light curve time series.
- get_transit_mask(planet, duration_increase_percent=0)[source]
- Parameters:
- Return type:
Returns: a boolean array were 1 corresponds to planet transits
- find_time_gaps_i(greater_than_median=10.0)[source]
Find time gaps in the lightcurve based on time step analysis.
Identifies locations where the time difference between consecutive points exceeds the median time step by a specified factor, indicating data gaps or interruptions in observations.
- Parameters:
greater_than_median (float) – Threshold multiplier for gap detection. Gaps are identified where time_diff > median_time_step * greater_than_median.
- Returns:
List of index tuples (i, i+1) where each tuple represents the indices immediately before and after a detected gap. The gap occurs between time[i] and time[i+1].
- Return type:
- find_time_gaps_x(greater_than_median=10.0)[source]
Find time gaps in the lightcurve and return actual time values.
Identifies locations where the time difference between consecutive points exceeds the median time step by a specified factor, returning the actual time values at gap boundaries rather than indices.
- Parameters:
greater_than_median (float) – Threshold multiplier for gap detection. Gaps are identified where time_diff > median_time_step * greater_than_median.
- Returns:
List of time value tuples (t1, t2) where each tuple represents the actual time values immediately before and after a detected gap. The gap occurs between time t1 and time t2.
- Return type:
See also
find_time_gaps_i: Returns the same gaps as index pairs instead of time values.
- find_contiguous_time_i(greater_than_median=10.0)[source]
Find contiguous time intervals in the lightcurve based on time step analysis.
Identifies regions where time differences between consecutive points remain below the threshold, indicating continuous observation periods without significant gaps.
- Parameters:
greater_than_median (float) – Threshold multiplier for gap detection. Contiguous intervals are where time_diff <= median_time_step * greater_than_median.
- Returns:
List of index tuples (start, end) where each tuple represents the start and end indices (inclusive) of a contiguous time interval.
- Return type:
- find_contiguous_time_x(greater_than_median=10.0)[source]
Find contiguous time intervals in the lightcurve and return actual time values.
Identifies regions where time differences between consecutive points remain below the threshold, returning the actual time values at the boundaries of contiguous intervals.
- Parameters:
greater_than_median (float) – Threshold multiplier for gap detection. Contiguous intervals are where time_diff <= median_time_step * greater_than_median.
- Returns:
List of time value tuples (t_start, t_end) where each tuple represents the actual time values at the start and end of a contiguous interval.
- Return type:
- to_jd_time()[source]
Convert the light curve time to plain Julian Date (JD) representation in place.
JD is the continuous count of days since 4713 BCE (noon), independent of location; the scale (UTC, TT, TDB, …) is tracked separately. This method puts the times in format=”jd” while preserving the existing time scale and reference frame.
When your times are already barycentric (e.g., TESS BJD_TDB), converting to JD does not change the numeric values—it only standardizes the representation.
Examples
Suppose your first cadence is BJD_TDB = 2458354.123456: >>> lc.time.format, lc.time.scale (‘jd’, ‘tdb’) >>> lc.time[0].value 2458354.123456 >>> lc.to_jd_time().lc.time[0].value # still JD in TDB scale 2458354.123456
- Returns:
Returns self for method chaining.
- Return type:
Self
- to_btjd_time()[source]
Convert the light curve time to BTJD (Barycentric TESS Julian Date) in place.
BTJD is a TESS-specific convenience: BTJD ≡ BJD_TDB − (BJDREFI + BJDREFF). For standard SPOC products, (BJDREFI, BJDREFF) = (2457000, 0), so BTJD = BJD_TDB − 2457000. This keeps the barycentric reference and the TDB time scale, but shifts the zero-point so numbers are ~10^3 instead of ~2.4×10^6.
Examples
>>> # Starting from BJD_TDB = 2458354.123456 (TESS Year 1) >>> lc.to_btjd_time().lc.time[0].value 1354.123456 # 2458354.123456 - 2457000.0
>>> # Converting back to BJD_TDB (see to_bjd_time) restores the 2.458e6 magnitude. >>> lc.to_bjd_time().lc.time[0].value 2458354.123456
- Returns:
Returns self for method chaining.
- Return type:
Self
- to_bjd_time()[source]
Convert the light curve time to Barycentric Julian Date (BJD_TDB) in place.
BJD is simply JD evaluated at the Solar System Barycenter (SSB). For TESS, timestamps are already referenced to the SSB with TIMESYS=’TDB’ and TIMEREF=’SOLARSYSTEM’, so BJD_TDB is the physically correct absolute time. Numerically, BJD_TDB equals JD in the TDB scale when the reference location is barycentric.
This method ensures the output is BJD_TDB (absolute, not offset), which is what you want for comparing absolute epochs (e.g., transit mid-times) across sectors or with literature ephemerides.
Examples
>>> # From BTJD back to absolute BJD_TDB: >>> lc.to_btjd_time().lc.time[0].value 1354.123456 >>> lc.to_bjd_time().lc.time[0].value 2458354.123456 # adds back (BJDREFI + BJDREFF) = 2457000.0
>>> # If already BJD_TDB, calling again is a no-op: >>> lc.time.format, lc.time.scale ('jd', 'tdb') >>> lc.to_bjd_time().lc.time.format 'jd'
- Returns:
Returns self for method chaining.
- Return type:
Self
Star System Types
Star system types and data structures.
- class exotools.db.star_system.Star(star_name, data)[source]
Bases:
UncertainDataSource- property tic_id
- property radius: UncertainValue[Quantity]
- property mass: UncertainValue[Quantity]
- class exotools.db.star_system.Planet(name, data)[source]
Bases:
UncertainDataSource- property radius: UncertainValue[Quantity]
- property mass: UncertainValue[Quantity]
- property density: UncertainValue[Quantity]
- property eccentricity: UncertainValue[float]
- property orbital_period: UncertainValue[Quantity]
- property parameter_of_periastron: UncertainValue[Quantity]
- property orbital_inclination: UncertainValue[Quantity]
- property semimajor_axis: UncertainValue[Quantity]
- property transit_midpoint: UncertainValue[Time]
- property transit_duration: UncertainValue[Quantity]
- property transit_depth: UncertainValue[float]
- property impact_parameter: UncertainValue[float]
- property radius_to_stellar_ratio: UncertainValue[float]
- property semimajor_axis_to_stellar_ratio: UncertainValue[float]