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.fetch_known_packed_designations(force_download=False)

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

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

This then returns a dictionary of all known packed 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:

{‘00001’: ‘00001’, ‘I01A00A’: ‘00001’, ‘I99O00F’: ‘00001’, ‘J43X00B’: ‘00001’, ‘00002’: ‘00002’, ‘I02F00A’: ‘00002’, …}

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

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.35412, 243.13746, 1.69615, 'Palomar Mountain', '675')

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

kete.mpc.normalize_names(dataset, col='MPC_packed_name', name_lookup=None)

Given a Pandas Dataframe containing packed MPC names, alter the names to be the up to date MPC designation.

Parameters:

dataset – A pandas dataframe which contains a column of packed MPC names.
col (str) – The column of the dataset which contains the packed MPC names.
name_lookup – Dictionary mapping old names to current names, if None is provided, this will use fetch_known_packed_designations().

kete.mpc.pack_comet_designation(unpacked)

Accepts an unpacked MPC provisional designation and returns a packed provisional designation.

See https://www.minorplanetcenter.net/iau/info/PackedDes.html for more details.

>>> kete.mpc.pack_comet_designation("C/2020 F3")
'CK20F030'

>>> kete.mpc.pack_comet_designation("1P/Halley")
'0001P'

Parameters:: unpacked (str) – An unpacked MPC comet designation of an object.

kete.mpc.pack_designation(unpacked)

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 (str) – An unpacked designation to be packed into either a permanent or provisional designation.

kete.mpc.pack_permanent_designation(unpacked)

Convert an MPC asteroid number into an MPC 5 character packed designation.

>>> kete.mpc.pack_permanent_designation('3140113')
'~AZaz'
>>> kete.mpc.pack_permanent_designation('21P')
'0021P'
>>> kete.mpc.pack_permanent_designation('Saturn V')
'S005S'

Parameters:: unpacked (str) – A string to convert to an MPC permanent designation.

kete.mpc.pack_provisional_designation(unpacked)

Accepts an unpacked MPC provisional designation and returns a packed provisional designation.

See https://www.minorplanetcenter.net/iau/info/PackedDes.html for more details.

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

Parameters:: unpacked (str) – An unpacked provisional MPC designation of an object.

kete.mpc.pack_satellite_designation(unpacked)

Accepts an unpacked MPC planetary satellite designation and returns a packed designation.

See https://www.minorplanetcenter.net/iau/info/PackedDes.html for more details.

>>> kete.mpc.pack_satellite_designation("Jupiter XIII")
'J013S'

Parameters:: unpacked (str) – An unpacked satellite MPC designation of an object.

kete.mpc.table_to_states(orbit_dataframe)

Given a dataframe provided by fetch_known_orbit_data() above, load all states.

import kete

# Load all MPC orbits
orbits = kete.mpc.fetch_known_orbit_data()

# Subset the table to be only NEOs
neos = kete.population.neo(orbits.peri_dist, orbits.ecc)
neo_subset = orbits[neos]

# load the state object from this table
state = kete.mpc.table_to_states(neo_subset)

Parameters:: orbit_dataframe – Pandas Dataframe as provided by the fetch_known_orbit_data function.

kete.mpc.unpack_comet_designation(packed)

Accepts a packed MPC comet designation and returns an unpacked provisional designation.

See https://www.minorplanetcenter.net/iau/info/PackedDes.html for more details.

>>> kete.mpc.unpack_comet_designation("CI70Q010")
'C/1870 Q1'

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

kete.mpc.unpack_designation(packed)

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 (str) – A packed 5, 7, or 8 character MPC designation of an object.

kete.mpc.unpack_permanent_designation(designation)

Convert an MPC 5 character permanent designation into an unpacked representation.

>>> kete.mpc.unpack_permanent_designation("~AZaz")
'3140113'
>>> kete.mpc.unpack_permanent_designation("C3456")
'123456'
>>> kete.mpc.unpack_permanent_designation("0021P")
'21P'
>>> kete.mpc.unpack_permanent_designation("J005S")
'Jupiter V'

Parameters:: designation (str) – A 5 character permanent designation to convert to unpack.

kete.mpc.unpack_provisional_designation(packed)

Accepts a packed MPC provisional designation and returns an unpacked provisional designation.

See https://www.minorplanetcenter.net/iau/info/PackedDes.html for more details.

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

Parameters:: packed (str) – A packed 7 character provisional MPC designation of an object.

kete.mpc.unpack_satellite_designation(packed)

Accepts a packed MPC satellite designation and returns an unpacked designation.

See https://www.minorplanetcenter.net/iau/info/PackedDes.html for more details.

>>> kete.mpc.unpack_satellite_designation("J013S")
'Jupiter XIII'

Parameters:: packed (str) – A packed 5 character satellite MPC designation of an object.

IPAC - IRSA

kete.irsa.IRSA_column_data(table_name, base_url='https://irsa.ipac.caltech.edu', auth=None)

Retrieve the column data for a specified IRSA 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.

kete.irsa.annotate_plot(wcs, ra, dec=None, text=None, px_gap=70, length=50, lw=1, c='red', text_color='White', style='+', text_dx=0, text_dy=0, text_fs=None)

Add an annotation for a point in a FITS plot, this requires a world coordinate system (wcs) as returned by the plotting function above.

Parameters:

wcs – An Astropy World Coordinate system from the image.
ra – The RA in degrees, can be a Vector, if so then dec is ignored.
dec – The DEC in degrees.
text – Optional text to display.
px_gap – How many pixels should the annotation be offset from the specified RA/DEC.
length – Length of the bars in pixels.
lw – Line width of the marker.
c – Color of the marker, uses matplotlib colors.
text_color – If text is provided, this defines the text color.
style – Style of marker, this can be either “o”, “+”, or “L”.
text_dx – Offset of the text x location in pixels.
text_dy – Offset of the text y location in pixels.
text_fs – Text font size.

kete.irsa.plot_fits_image(fit, percentiles=(0.1, 99.95), power_stretch=0.5, cmap='gray')

Plot a FITS image, returning a WCS object which may be used to plot future points correctly onto the current image.

This estimates the standard deviation, subtracts the median, and scales the displayed image by number of standard deviations from the median value.

This returns the WCS which is constructed during the plotting process.

This will use the existing matplotlib plotting axis if available.

Parameters:

fit – Fits file from Astropy.
percentiles – Statistical percentile limit for which data to plot. By default this is set to 0.1% and 99.95%. If this is set to None, then this uses Astropy’s ZScaleInterval.
power_stretch – The scaling of the intensity of the plot is a power law, this defines the power of that power law. By default plots are sqrt scaled. If this is set to 1, then this becomes a linear scaling.
cmap – Color map to use for the plot.

kete.irsa.query_irsa_tap(query, upload_table=None, base_url='https://irsa.ipac.caltech.edu', auth=None, timeout=None, verbose=False)

Query IRSA’s 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.irsa.IRSA_column_data(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.irsa.query_irsa_tap(query, upload_table=data)

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

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 to not respond within this time.
verbose – Print status responses as they are fetched from IRSA.

kete.irsa.zoom_plot(wcs, ra, dec=None, zoom=100)

Given a WCS, zoom the current plot to the specified RA/Dec.

Parameters:

wcs – An Astropy World Coordinate system from the image.
ra – The RA in degrees, can be a Vector, if so then dec is ignored.
dec – The DEC in degrees.
zoom – Optional zoom region in pixels

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.

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)

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.