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:

kete.mpc.find_obs_code(name)

Search known observatory codes, if a single matching observatory is found, this will return the [lat, lon, altitude, description, obs code] in degrees and km as appropriate.

>>> kete.mpc.find_obs_code("Palomar Mountain")
[33.35411714, -116.86254, 1.69606288, 'Palomar Mountain', '675']
Parameters:

name (str) – Name of the observatory, this can be a partial name, or obs code.

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.query_tap(query, upload_table=None, base_url='https://irsa.ipac.caltech.edu/TAP/async', 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.

  • base_url – The URL 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, base_url='https://irsa.ipac.caltech.edu/TAP/async', 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.

  • base_url – The URL 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=None)

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

arc_len

If the object was previously known, this lists the length of time of the observations of the object in days.

covariance

Covariance values in the orbit fit.

desig

The MPC designation of the object.

property desigs: list[str]

List of alternate designations for this object.

First designation in this list is the Horizons preferred designation.

diameter

The diameter of the object in km.

eccentricity

The eccentricity of the orbit.

elements

Cometary orbital elements.

epoch

The epoch during which the orbital elements listed are accurate, in JD, TDB.

fetch(update_name=True, cache=True, update_cache=False, exact_name=False)

Fetch object properties from JPL Horizons service.

This does a best effort to fill in the values from horizons, but some values may be missing. The keyword arguments in this function allow to fill in defaults when the specified values cannot be found from horizons.

Parameters:

  • name – Name of the object to fetch.

  • update_name – If this is true, replace name with the name that horizons uses for the object.

  • cache – If this is true, the results are cached, and no query to horizons takes place if the object is already in the local cache.

  • update_cache – If this is true, the current cache contents are ignored, and new values are saved after querying horizons.

  • exact_name – If this is true, it is assumed that an exact designation in the format of horizons has been provided. This is particularly useful for comets which have fragments, as these objects are difficult to query since there are several names which have matches on substrings.

g_phase

The g parameter of the object.

group

An optional group name to associate the object with a group.

h_mag

The H magnitude of the object.

inclination

The inclination of the orbit in degrees.

property json: dict

JSON Representation of the object as queried from horizons.

This will by default come directly from the cached results, but will query if the object is not found.

static load(filename)

Load the horizons query from a file.

lon_of_ascending

The longitudinal node of the orbit in degrees.

moid

The minimum orbital intersection distance between the object and Earth in AU.

property non_grav: NonGravModel

The non-gravitational forces model from the values returned from horizons.

peri_arg

The argument of perihelion in degrees.

peri_dist

The perihelion distance in AU.

peri_time

The time of perihelion in JD, TDB scaled time.

sample(n_samples)

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.

save(filename)

Save the horizons query to a file.

state

Convert the orbital elements of the object to a State.

vis_albedo

The visible albedo of the object, between 0 and 1.

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.