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.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.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.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.

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

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.

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_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.