Interface

Below are APIs to external organizations and web interfaces. These are provided primarily to make it easier to fetch data from these various sources for analysis with kete.

Minor Planet Center (MPC)

kete.mpc.fetch_known_comet_orbit_data(force_download=False)

Download the orbital elements for comets from the MPC at the specified URL.

This returns a list of dict, one for each orbital element fetched from the MPC. Object names are set to the packed normalized MPC representation.

kete.mpc.fetch_known_designations(force_download=False)

Download the most recent copy of the MPCs known ID mappings in their unpacked format.

This download only occurs the first time this function is called.

This then returns a dictionary of all known unpacked IDs to a single ID which is the one that the MPC specifies as their default.

For example, here are the first two objects which are returned:

{‘1’: ‘1’, ‘A801 AA’: ‘1’, ‘A899 OF’: ‘1’, ‘1943 XB’: ‘1’, ‘2’: ‘2’, ‘A802 FA’: ‘2’, …}

Ceres has 4 entries, which all map to ‘1’.

kete.mpc.fetch_known_orbit_data(url=None, force_download=False)

Download the orbital elements from the MPC at the specified URL.

Object names are set to the packed normalized MPC representation.

This loads the *.json.gz files located in the Orbits category located at https://minorplanetcenter.net/data

This doesn’t work with the comet file on the MPC website as they have a different file format, see the function fetch_known_comet_orbit_data.

Example URLS:

Full MPCORB data for all asteroids in the MPC database

https://minorplanetcenter.net/Extended_Files/mpcorb_extended.json.gz

NEAs

https://minorplanetcenter.net/Extended_Files/nea_extended.json.gz

PHAs

https://minorplanetcenter.net/Extended_Files/pha_extended.json.gz

Latest DOU MPEC

https://minorplanetcenter.net/Extended_Files/daily_extended.json.gz

Orbits for TNOs, Centaurs, and SDOs

https://minorplanetcenter.net/Extended_Files/distant_extended.json.gz

Orbits for asteroids with e> 0.5 and q > 6 AU

https://minorplanetcenter.net/Extended_Files/unusual_extended.json.gz

kete.mpc.find_obs_code(site)

kete.mpc.pack_designation(desig)

Accepts either a unpacked provisional designation or permanent designation and returns the packed representation.

>>> kete.mpc.pack_designation("1998 SQ108")
'J98SA8Q'

>>> kete.mpc.pack_designation("3140113")
'~AZaz'

Parameters:: unpacked – An unpacked designation to be packed into either a permanent or provisional designation.

kete.mpc.unpack_designation(desig)

Accepts either a packed provisional designation or permanent designation and returns the unpacked representation.

>>> kete.mpc.unpack_designation("J98SA8Q")
'1998 SQ108'

>>> kete.mpc.unpack_designation("~AZaz")
'3140113'

Parameters:: packed – A packed 5, 7, or 8 character MPC designation of an object.

TAP Queries

Query tools for TAP services such as IRSA

kete.tap.TAP_SERVERS = {'CADC': 'https://ws.cadc-ccda.hia-iha.nrc-cnrc.gc.ca/argus/async', 'GAIA': 'https://gaia.aip.de/tap/async', 'IRSA': 'https://irsa.ipac.caltech.edu/TAP/async', 'MAST': 'https://mast.stsci.edu/vo-tap/api/v0.1/caom/async'}

Defined TAP servers for easy lookup.

If you have a TAP compliant server that you would like to add to this list, please submit a github issue with the URL.

kete.tap.query_tap(query, upload_table=None, service='IRSA', auth=None, timeout=None, verbose=False, cache=True, update_cache=False)

Query TAP service, optionally upload a table which will be included in the query data. The pandas dataframe table will be labeled as my_table and columns in the query can be used like so:

import kete
import pandas as pd

# Column names cannot match the column names in the IRSA table you are querying
# 0 has been added to the end of these column names to satisfy this constraint.

data = pd.DataFrame([['foo', 56823.933738, 186.249070833, 22.8977],
                    ['bar', 55232.963786, 49.14175, 21.63811111]],
                    columns=['name', 'mjd0', 'ra0', 'dec0'])

jd = kete.Time.from_mjd(56823.933738).jd

# This time corresponds to this phase:
phase = kete.wise.mission_phase_from_jd(jd)

# Single source table on IRSA is then: phase.source_table

# The columns of data available in this source table are
column_information = kete.tap.tap_column_info(phase.source_table)

# Note that lots of information is available in column_information

# Now select which columns we want IRSA to return.
# Using TAP_UPLOAD.my_table.name we can get back the column of data we sent
columns_to_fetch = "TAP_UPLOAD.my_table.name, mjd, ra, dec"

query = (f"select {columns_to_fetch} from {phase.source_table} where " +
        "CONTAINS(POINT('J2000',ra,dec)," +
        "         CIRCLE('J2000'," +
        "                TAP_UPLOAD.my_table.ra0," +
        "                TAP_UPLOAD.my_table.dec0," +
        "                0.01)" +
        "         )=1 " +
        " and (((mjd - mjd0) < 0.0001) " +
        " and ((mjd0 - mjd) < 0.0001))")

result = kete.tap.query_tap(query, upload_table=data)

This is a blocking operation using TAP Async queries. This submits the query, receives a response from the TAP service containing a URL, then queries that URL for job status. This continues until the job either completes or errors.

By default, queries are cached, and any calls of this function with the same parameters will return the cached results. This may be disabled with the cache keywords, additionally the cache can be forcibly updated using update_cache.

Parameters:

query – An SQL text query.
upload_table – An optional pandas dataframe.
service – The URL or known name of the TAPS service to query, this defaults to IRSA.
auth – An optional (username, password), this may be used to access restricted data.
timeout – Timeout for web queries. This will raise an exception if the servers do not respond within this time.
verbose – Print status responses as they are fetched from the TAP service.
cache – Bool to indicate whether or not the query should be cached.
update_cache – If cache=True, then this value can specify if the cache will be forcibly updated. IE: previous query results are ignored and resubmitted to the TAP service.

kete.tap.tap_column_info(table_name, service='IRSA', auth=None)

Retrieve the column data for a specified TAP table.

This will return a dataframe containing the column properties of the target table.

Parameters:

table_name – The name of the table to query the columns of.
service – The URL or known name of the TAPS service to query, this defaults to IRSA.
auth – An optional (username, password), this may be used to access restricted data.

JPL Horizons

Interface functions and classes to JPL Horizons web services.

class kete.horizons.HorizonsProperties(desig, group=None, epoch=None, eccentricity=None, inclination=None, lon_of_ascending=None, peri_arg=None, peri_dist=None, peri_time=None, h_mag=None, vis_albedo=None, diameter=None, moid=None, g_phase=None, arc_len=None, covariance_params=None, covariance_matrix=None, covariance_epoch=None)

Horizons object properties Physical, orbital, and observational properties of a solar system object as recorded in JPL Horizons.

alternate_desigs: Alternate designations for this object.

arc_len: Arc length in days.

desig: The MPC designation of the object.

diameter: Diameter in km.

eccentricity: Eccentricity.

elements: Cometary orbital elements.

epoch: Epoch of the orbital elements (JD, TDB).

static fetch(name, update_name=True, update_cache=False, exact_name=False)

Fetch an object from JPL Horizons.

Parameters:

name (str) – Name of the object to fetch.
update_name (bool) – If true, replace name with the name that horizons uses for the object.
update_cache (bool) – If true, the current cache contents are ignored, and new values are saved after querying horizons.
exact_name (bool) – If true, it is assumed that an exact designation in the format of horizons has been provided.

g_phase: G phase parameter.

group: Optional group name.

h_mag: H magnitude.

inclination: Inclination in degrees.

json

Raw SBDB JSON response parsed into a Python dict.

Raises ValueError if no JSON is found.

lon_of_ascending: Longitude of ascending node in degrees.

moid: MOID to Earth in AU.

non_grav: Non-gravitational force model from Horizons, if available.

peri_arg: Argument of perihelion in degrees.

peri_dist: Perihelion distance in AU.

peri_time: Time of perihelion (JD, TDB).

raw_json: Raw JSON response from SBDB, if fetched via API.

sample(n_samples, seed=None)

Sample the covariance matrix for this object, returning n_samples of states and non-gravitational models, which may be used to propagate the orbit in time.

This uses the full covariance matrix in order to correctly sample the object’s orbit with all correlations, including correlations with the non-gravitational forces.

Parameters:

n_samples – The number of samples to take of the covariance.
seed – An optional random seed for reproducibility.

state: Convert the orbital elements of the object to a State.

uncertain_state

The uncertain orbit state, constructed from the Horizons covariance.

Returns None if no covariance was provided.

vis_albedo: Visible albedo (0-1).

kete.horizons.fetch(name, update_name=True, update_cache=False, exact_name=False)

Fetch an object from JPL Horizons.

Parameters:

name (str) – Name of the object to fetch.
update_name (bool) – If true, replace name with the name that horizons uses for the object.
update_cache (bool) – If true, the current cache contents are ignored, and new values are saved after querying horizons.
exact_name (bool) – If true, it is assumed that an exact designation in the format of horizons has been provided.

kete.horizons.fetch_known_orbit_data(update_cache=False)

Fetch the known orbit data from JPL Horizons for all known asteroids and comets.

This gets loaded as a pandas table, and if the file already exists in cache, then the contents of this file are returned by default.

The constructed pandas table may be turned into states using the table_to_states() function.

Parameters:: update_cache – Force download a new file from JPL Horizons, this can be used to update the orbit fits which are currently saved.

kete.horizons.fetch_spice_kernel(name, jd_start, jd_end, exact_name=False, update_cache=False, apparition_year=None, cache_dir='kernels')

Download a SPICE kernel from JPL Horizons and save it directly into the Cache.

from kete import horizons, Time
jd_start = Time.from_ymd(1900, 1, 1)
jd_end = Time.from_ymd(2100, 1, 1)
horizons.fetch_spice_kernel("10p", jd_start, jd_end)

Parameters:

name – Name or integer id value of the object.
jd_start (Time | float) – Start date of the SPICE kernel to download.
jd_end (Time | float) – End date of the SPICE kernel to download.
exact_name (bool) – If the specified name is the exact name in Horizons, this can help for comet fragments.
update_cache (bool) – If the current state of the cache should be ignored and the file re-downloaded.
apparition_year (int | None) – If the object is a comet, retrieve the orbit fit which is previous to this specified year. If this is not provided, then default to the most recent epoch of orbit fit. Ex: apparition_year=1980 will return the closest epoch before 1980.
cache_dir (str) – The directory in the cache where the file will be saved. This is used to separate the planet SPICE kernels from the other cache files.