Ctrl+K

exofop.download

exofop.download#

This sub-package provides functionality for downloading data from the ExoFOP website.

Outline#

exofop.download.SystemDownloaderclass

A class for downloading data related to individual stellar systems from ExoFOP.

exofop.download.ExoFOPAuthenticatorclass

A class for handling authentication with and cookie storage for the ExoFOP server.

exofop.download.TagDownloaderclass

A class for downloading data using ExoFOP tags.

exofop.download.Systemclass

A class representing an ExoFOP system identifier, e.g. a TIC ID or a TOI ID.

exofop.download.TICclass

A class representing a TIC ID.

exofop.download.TOIclass

A class representing a TOI ID.

exofop.download.OverviewTableAccessorclass

A class for providing tables from ExoFOP for a given target.

Example

The following is a basic example of how to use the class exofop.download.SystemDownloader to download data from ExoFOP:

>>> from exofop.download import System, SystemDownloader
>>> system = System("TIC 123456789")
>>> system_loader = SystemDownloader(
...     system=system,
...     data_dir="path/to/directory/to/store/downloaded/tags",
... )
>>> tags = system_loader.time_series.tags
>>> system_loader.download(tags[:5])

For a more detailed introduction, consult the tutorial Download tags from ExoFOP.

Classes#

class exofop.download.ExoFOPAuthenticator(username: str | None = None, cookies_dir: str | None = None, buffer_hours: int = 1, credential_file_path: str | None = None, number_of_cookie_jars: int = 3)[source]#

Bases: object

A class for managing sessions and login to ExoFOP using httpx.

Parameters:

username (str, optional) – The ExoFOP username. If not provided, user will be prompted to enter.

username#

The ExoFOP username used for login.

Type:

str

Examples

>>> authenticator = ExoFOPAuthenticator(username="lovelace")
Please enter your login credentials:
Username: myusername  # Username is printed
Password:             # Password is prompted
Login was successful. # Or 'Login was not successful'
BASE_URL = 'https://exofop.ipac.caltech.edu'#

Base URL for the ExoFOP website.

property cookies#

Serve cookies from the cookie_jar_shelf.

login(password: str | None = None) → bool[source]#

Login to ExoFOP and return True if successful.

Parameters:

password (str, optional) – The ExoFOP password. If not provided, user will be prompted to enter. For security reasons, it is strongly recommended not to hardcode or directly pass your password to this function. Instead, only enter your password when prompted.

Return type:

None

Examples

>>> session = ExoFOPAuthenticator(username="lovelace")
>>> session.login()
Please enter your login credentials:
Username: myusername  # Username is printed
Password:             # Password is prompted
Login was successful. # Or 'Login was not successful'
class exofop.download.OverviewTableAccessor(table_loader: ExofopTable, target: str, target_dir: str = '.')[source]#

Bases: object

A class for providing tables from ExoFOP for a given target.

property table: Table#

The table containing the data for the given target.

property tags: ndarray#

The list of tags contained in the table for the given target.

class exofop.download.System(name: str | None = None, tic: str | int | TIC | None = None, toi: str | int | float | TOI | None = None, complete: bool = False)[source]#

Bases: object

System class for handling and validating TIC and TOI IDs.

name#

The name of the system.

Type:

str

tic#

The TIC ID of the system.

Type:

TIC

toi#

The TOI ID of the system.

Type:

TOI

Examples

Initialize System with a TIC ID or TOI ID by explicitly providing a name and a TIC or TOI ID

>>> s = System(name="cool_system", tic="254113311", toi=None)

As the first argument is name, we can also hand IDs using the prefixes ‘TIC’ or ‘TOI’.

>>> s = System(name="TOI-1130")  # Indicate TOI ID with prefix 'TOI'
>>> s = System("TIC_254113311")  # Indicate TIC ID with prefix 'TIC'

Less recommended way, as it requires an extra lookup

>>> System(name="1130")
System(name=1130, tic=TIC_254113311 toi=TOI1130)

Initialize System with a TIC ID or TOI ID and autocomplete

>>> System(name="cool_system", tic="254113311", complete=True)
System(name=cool_system, tic=TIC_254113311 toi=TOI1130)

Get target ID, which can be used to query ExoFOP time series data

>>> System(toi="TOI-1130").target
'TOI1130'
>>> System(tic="TIC_254113311").target
'254113311'
autocomplete() → bool[source]#

Autocomplete the system by inferring the missing TIC or TOI ID from the provided one.

exists(overview_table: DataFrame | None = None) → bool[source]#

Check if the system exists in the overview table.

get_tic() → TIC[source]#

Get the TIC ID of the system.

get_toi() → TOI[source]#

Get the TOI ID of the system.

is_complete() → bool[source]#

Check if the system is complete, i.e., if both TIC and TOI IDs are provided.

is_consistent() → bool[source]#

Check if both TIC and TOI IDs are referring to the same system.

lookup(overview_table: DataFrame | None = None) → DataFrame[source]#

Look up the system in the overview table.

property target: str#

The target ID of the system. This is either the TIC or TOI ID.

class exofop.download.SystemDownloader(system: System, data_dir: str = '.', target_dir=None, add_exofop_subdir: bool = False, authenticator: ExoFOPAuthenticator | None = None, downloader: AsyncDownloader | None = None, max_concurrent_downloads=2, timeout=5, max_retries=1)[source]#

Bases: TagDownloader

A class for downloading data related to individual stellar systems from ExoFOP.

Parameters:

  • system (exofop.download.identifiers.System) – The system identifier for the given system.

  • data_dir (str, optional) – The directory where downloaded and extracted files will be stored. Default is the current directory.

  • target_dir (str, optional) – The target directory where downloaded and extracted files will be stored. Default is None.

  • add_exofop_subdir (bool, optional) – Whether to add a subdirectory for ExoFOP data. Default is False.

  • authenticator (exofop.download.authenticator.ExoFOPAuthenticator, optional) – An instance of ExoFOPAuthenticator for authentication to ExoFOP. Default is None.

  • downloader (AsyncDownloader, optional) – An instance of AsyncDownloader for handling asynchronous file downloads. Default is None.

  • max_concurrent_downloads (int, optional) – The maximum number of concurrent downloads. Default is 2.

  • timeout (int, optional) – Timeout in seconds for each download. Default is 5.

  • max_retries (int, optional) – The maximum number of retries for each download. Default is 1.

time_series#

The time series table for the given system.

Type:

OverviewTableAccessor

spectroscopy#

The spectroscopy table for the given system.

Type:

OverviewTableAccessor

imaging#

The imaging table for the given system.

Type:

OverviewTableAccessor

stellar_parameters#

The stellar parameters table for the given system.

Type:

OverviewTableAccessor

nearby_target#

The nearby target table for the given system.

Type:

OverviewTableAccessor

stellar_companions#

The stellar companions table for the given system.

Type:

OverviewTableAccessor

Examples

>>> system_loader = SystemDownloader(
...     data_dir=data_dir,
...     system=System('TIC_254113311'),
...     max_retries=0
... )

Lets say we want to download the time series observations. We will first see what observations are available:

>>> tab = system_loader.time_series.table

Then we can download the tags that we are interested in:

>>> tags = system_loader.time_series.tags
>>> system_loader.download(tags[[1, 3]])

To download all time series data for a given system:

>>> system_loader.download_time_series()
download(tags, output_dir: str | None = None, unzip=True)[source]#

Download all all files specified by the given tags.

Parameters:

  • tags (list[str]) – The list of tags for the files to be downloaded.

  • output_dir (Optional[str]) – The directory where the downloaded files should be stored. Default is None.

  • unzip (bool) – Whether to unzip the downloaded files. Default is True.

Returns:

counts – A Counter object containing the number of files with each download status.

Return type:

Counter[DownloadStatus]

download_imaging(output_dir: str | None = None, unzip: bool = True) → Counter[DownloadStatus][source]#

Download all imaging tables for the given system.

Convenience method for downloading all imaging tables for the given system, and optionally unzipping the downloaded files.

Parameters:

  • output_dir (Optional[str]) – The directory where the downloaded files should be stored. Default is None.

  • unzip (bool) – Whether to unzip the downloaded files. Default is True.

download_spectroscopy(output_dir: str | None = None, unzip: bool = True) → Counter[DownloadStatus][source]#

Download all spectroscopy tables for the given system.

Convenience method for downloading all spectroscopy tables for the given system, and optionally unzipping the downloaded files.

Parameters:

  • output_dir (Optional[str]) – The directory where the downloaded files should be stored. Default is None.

  • unzip (bool) – Whether to unzip the downloaded files. Default is True.

download_time_series(output_dir: str | None = None, unzip: bool = True) → Counter[DownloadStatus][source]#

Download all time series observations tables for the given system.

Convenience method for downloading all time series observations tables for the given system, and optionally unzipping the downloaded files.

Parameters:

  • output_dir (Optional[str]) – The directory where the downloaded files should be stored. Default is None.

  • unzip (bool) – Whether to unzip the downloaded files. Default is True.

classmethod from_username(username: str, system: System, data_dir: str = '.', target_dir=None, add_exofop_subdir: bool = False, downloader: AsyncDownloader | None = None, max_concurrent_downloads=5, timeout=100)[source]#
property light_curve#

The light curve table for the given system. Alternative name for time_series.

See also

time_series

OverviewTableAccessor The light curve table for the given system.

unzip_downloaded_files(output_dir: str | None = None) → None[source]#

Unzip all downloaded files for the given system.

Unzip all downloaded files for the given system and move the extracted contents to the output path.

Parameters:

output_dir (Optional[str]) – The path to the folder where the extracted contents should be moved. Default is None.

class exofop.download.TIC(tic_id: str | int | TIC)[source]#

Bases: object

TESSS Input Catalogue (TIC) class for handling and validating TIC IDs.

Parameters:

tic_id (Union[str, int]) – The TIC ID to initialize the TIC object.

Examples

Initialize TIC with a valid TIC ID

>>> tic = TIC(123456789)
>>> tic.id
'123456789'

Initialize TIC with a valid TIC ID as a string

>>> tic_str = TIC('231663901')
>>> tic_str.to_toi()
TOI(101)

Initialize TIC with an invalid TIC ID (raises InvalidTICError)

>>> invalid_tic = TIC('invalid_id')  
Traceback (most recent call last):
InvalidTICError: Invalid TIC ID: `invalid_id` ...

Alternatively, you can use the exists method to check if a TIC ID is valid

>>> TIC('123456789').exists()
False
exists(overview_table: DataFrame | None = None) → bool[source]#

Check if the system exists in the overview table.

property id: str#

The TESSS Input Catalogue (TIC) ID.

This is a string of 9 digits, e.g., “123456789”.

lookup(overview_table: DataFrame | None = None) → DataFrame[source]#

Look up the system in the overview table.

to_toi(overview_table: DataFrame | None = None) → TOI[source]#

Convert TIC to TOI ID.

class exofop.download.TOI(toi_id: str | int | float | TOI)[source]#

Bases: object

TESS Objects of Interest (TOI) class for handling and validating TOI IDs.

Parameters:

toi_id (Union[str, int]) – The TOI ID to initialize the TOI object.

Examples

Initialize TOI with a valid TOI ID

>>> toi = TOI(1234)
>>> toi.id
'TOI1234'

Initialize TOI with a valid TOI ID as a string

>>> toi_str = TOI('1234')
>>> toi_str.to_tic()
TIC(90504905)

Initialize TOI with an invalid TOI ID (raises InvalidTOIError)

>>> invalid_tic = TOI('invalid_id')  
Traceback (most recent call last):
InvalidTOIError: Invalid TOI ID: `invalid_id` ...

Alternatively, you can use the exists method to check if a TOI ID is valid

>>> TOI('101').exists()
True
exists(overview_table: DataFrame | None = None) → bool[source]#

Check if the system exists in the overview table.

property id: str#

The TESS Objects of Interest (TOI) ID.

lookup(overview_table: DataFrame | None = None) → DataFrame[source]#

Look up the system in the overview table.

property planet: str#

The planet number of the TESS Objects of Interest (TOI) ID.

property system: str#

TOI ID of the system without the planet number.

to_tic(overview_table: DataFrame | None = None) → TIC[source]#

Convert TOI to TIC ID.

class exofop.download.TagDownloader(target_dir: str = '.', authenticator: ExoFOPAuthenticator | None = None, downloader: AsyncDownloader | None = None, max_concurrent_downloads=2, timeout=5, max_retries=1)[source]#

Bases: object

TagDownloader is a class for downloading files associated with a list of ExoFOP tags.

Parameters:

  • target_dir (str, optional) – The target directory where downloaded and extracted files will be stored. Default is the current directory.

  • authenticator (exofop.download.authenticator.ExoFOPAuthenticator, optional) – An instance of ExoFOPAuthenticator for authentication to ExoFOP. Default is None.

  • downloader (AsyncDownloader, optional) – An instance of AsyncDownloader for handling asynchronous file downloads. Default is None.

  • max_concurrent_downloads (int, optional) – The maximum number of concurrent downloads. Default is 5.

  • timeout (int, optional) – Timeout in seconds for each download. Default is 100.

Examples

>>> data_dir = '/path/to/data'
>>> os.makedirs(data_dir, exist_ok=True)
>>> tdl = TagDownloader(target_dir=data_dir)
>>> tdl.download_tags(tags=['5903'])
>>> tdl.unzip_downloaded_files()

Examples

>>> data_dir='/path/to/data'
>>> authenticator = ExoFOPAuthenticator(username="lovelace")
>>> os.makedirs(data_dir, exist_ok=True)
>>> tdl = TagDownloader(target_dir=data_dir, authenticator=authenticator)
>>> tdl.download_tags(tags=['5734', '5903'])
>>> tdl.unzip_downloaded_files()

Notes

After downloading the tags 5734 and 5904, the directory structure looks as follows:

target_dir/
├── 5734/
├── 5903/
├── zip/
│   ├── 5734.zip
│   ├── 5903.zip

For more information on the ExoFOP API see: https://exofop.ipac.caltech.edu/tess/Introduction_to_ExoFOP_php_functions.php

BASE_URL = 'https://exofop.ipac.caltech.edu'#
property client_kwargs: dict#

Return the client kwargs for the downloader.

This includes a set of cookies if an authenticator is provided.

delete_zip_folder() → None[source]#

Delete the .zip folder and all files inside it.

Examples

>>> tag_downloader.delete_zip_folder()
download_tags(tags: ndarray | list | str | int, download_directory: str | None = None) → Counter[DownloadStatus][source]#
async download_tags_async(tags: ndarray | list | str | int, download_directory: str | None = None) → Counter[DownloadStatus][source]#
unzip_downloaded_files(output_dir: str | None = None) → None[source]#

Unzip all .zip files in the given folder and move the extracted contents to the output path.

Parameters:

output_dir (Optional, str) – The path to the folder where the extracted contents should be moved.

Examples

>>> downloader.unzip_downloaded_files()
Contents