Horizons

Functions for interacting with the Horizons API.

class jorbit.utils.horizons.HorizonsQueryConfig

Bases: NamedTuple

Configuration for Horizons API queries.

ASTROMETRY_COLUMNS = ['JD_UTC', 'twilight_flag', 'moon_flag', 'RA', 'DEC', 'V', 'S-brt', 'RA_3sigma', 'DEC_3sigma', 'SMAA_3sigma', 'SMIA_3sigma', 'Theta_3sigma', 'Area_3sigma', '_']

ASTROQUERY_MAX_TIMESTEPS = 25

HORIZONS_API_URL = 'https://ssd.jpl.nasa.gov/api/horizons_file.api'

MAX_TIMESTEPS = 10000

VECTOR_COLUMNS = ['JD_TDB', 'Cal', 'x', 'y', 'z', 'vx', 'vy', 'vz', 'LT', 'RG', 'RR', '_']

jorbit.utils.horizons.get_observer_positions(times, observatories, de_ephemeris_version)

A wrapper to retrieve the barycentric positions of an observer from the Horizons API.

Parameters:

• times (Time) – The times for the query. Can be a single Time, or a Time object with length > 1. If length < 50, positions will be retrieved using astroquery, otherwise a manual API query will be used. Note that length must be < 10,000.

• observatories (str | list[str]) – The observatory name for the query. If ‘@’ is included in the query, it’s assumed to be a Horizons-interpretable code. Otherwise it will be compared to the list of observatory names in the jorbit.data.observatory_codes module and mapped to its appropriate code.

• de_ephemeris_version (str) – The DE ephemeris version to use for the query. This is something of a hack- Horizons is using something like DE440 by default, so if you want the observer’s position while assuming a different ephemeris (e.g. you’re pretending the Earth is in a different location than Horizons thinks it is), you need to correct for the shift. This will apply a translation to align the Earth-Moon barycenter between the requested ephemeris and DE440; it will not perform any rotations or higher-order corrections. Accepts ‘440’ or ‘430’.

Returns:

The barycentric positions of the observer in AU.

Return type:

Array

jorbit.utils.horizons.horizons_bulk_astrometry_query(target, center, times, skip_daylight=False, disable_astroquery=False)

The main query function for our retrieval of astrometry from the Horizons API.

This function creates the appropriate query string, executes the query, and parses the response into a DataFrame. If we’re requesting a small number of timesteps, it’ll use astroquery to retrieve the data, which allows for easy caching. However, if we’re requesting > 50 unique timesteps, astroquery will fail, so we instead fall back to a manual API query. These results will not be cached.

Note: The Horizons API has a hard limit of 10,000 timesteps per query.

Parameters:

• target (str) – The target object identifier. Must be a packed MPC designation with length 5 for numbered objects or 7 for provisional designations.

• center (str) – The center object identifier.

• times (Time) – The times for the query. Note it just needs to be an Astropy Time object- we’ll handle the different tdb/utc conversions internally.

• skip_daylight (bool) – Whether to skip daylight in the query.

• disable_astroquery (bool) – Whether to disable the astroquery default for small searches.

Returns:

A pandas DataFrame containing the astrometry data.

Return type:

DataFrame

jorbit.utils.horizons.horizons_bulk_vector_query(target, center, times, disable_astroquery=False)

The main query function for our retrieval of vectors from the Horizons API.

This function creates the appropriate query string, executes the query, and parses the response into a DataFrame. If we’re requesting a small number of timesteps, it’ll use astroquery to retrieve the data, which allows for easy caching. However, if we’re requesting > 50 unique timesteps, astroquery will fail, so we instead fall back to a manual API query. These results will not be cached.

Note: The Horizons API has a hard limit of 10,000 timesteps per query.

Parameters:

• target (str) – The target object identifier. Must be a packed MPC designation with length 5 for numbered objects or 7 for provisional designations.

• center (str) – The center object identifier.

• times (Time) – The times for the query. Note it just needs to be an Astropy Time object- we’ll handle the different tdb/utc conversions internally.

• disable_astroquery (bool) – Whether to disable the astroquery default for small searches.

Returns:

A pandas DataFrame containing the vector data.

Return type:

DataFrame

jorbit.utils.horizons.horizons_query_context(query_string)

Creates and manages the query content in memory.

Return type:

StringIO

Parameters:

query_string (str)

jorbit.utils.horizons.horizons_query_string(target, center, query_type, times, skip_daylight=False)

Constructs the query string for the Horizons API.

Parameters:

• target (str) – The target object identifier.

• center (str) – The center object identifier.

• query_type (str) – The type of query, either ‘VECTOR’ or ‘OBSERVER’.

• times (Time) – The times for the query. Note it just needs to be an Astropy Time object- we’ll handle the different tdb/utc conversions internally.

• skip_daylight (bool) – Whether to skip daylight in the query.

Returns:

The constructed query string.

Return type:

str

jorbit.utils.horizons.make_horizons_request(query_content)

Makes the HTTP request to Horizons API.

Parameters:

query_content (StringIO) – The query content to send in the request.

Returns:

The response text from the Horizons API.

Return type:

str

Raises:

ValueError – If the request fails.

jorbit.utils.horizons.parse_horizons_response(response_text, columns, skip_empty=False)

Parses the Horizons API response into a DataFrame.

Parameters:

• response_text (str) – The response text from the Horizons API.

• columns (list[str]) – The column names for the DataFrame.

• skip_empty (bool) – Whether to skip empty lines in the response.

Returns:

The parsed DataFrame.

Return type:

DataFrame