JPL SBDB Queries (astroquery.jplsbdb/astroquery.solarsystem.jpl.sbdb)

Overview

The SBDBClass class provides an interface to the Small-Body Database Browser (SBDB) maintained by the JPL Solar System Dynamics group.

The SBDB provides detailed information on a specific known small body, including it’s orbit, close approaches with major planets, available radar observations, detailed information on virtual impactors, discovery circumstances, and a few select physical properties.

This module enables the query of these information for an individual object into a formatted OrderedDict structure using units and ndarray objects where possible. It furthermore provides the means to query a list of objects based on their primary designation and using a wildcard symbol. This module uses the SBDB API as described in the SBDB API documentation and hence closely follows the definitions in that document with some simplifications.

Because of its relevance to Solar System science, this service can also be accessed from the topical submodule astroquery.solarsystem.jpl. The functionality of that service is identical to the one presented here.

Example

The most simple query to obtain information for a specific Solar System small-body works as follows:

>>> from astroquery.jplsbdb import SBDB
>>> sbdb = SBDB.query('3552')
>>> print(sbdb)
OrderedDict([('object', OrderedDict([('shortname', '3552 Don Quixote'), ('neo', True), ('orbit_class', OrderedDict([('name', 'Amor'), ('code', 'AMO')])), ('pha', False), ('spkid', '2003552'), ('kind', 'an'), ('orbit_id', '188'), ('fullname', '3552 Don Quixote (1983 SA)'), ('des', '3552'), ('prefix', None)])), ('signature', OrderedDict([('source', 'NASA/JPL Small-Body Database (SBDB) API'), ('version', '1.0')])), ('orbit', OrderedDict([('source', 'JPL'), ('cov_epoch', Unit("2.45657e+06 d")), ('moid_jup', Unit("0.441 AU")), ('t_jup', '2.315'), ('condition_code', '0'), ('not_valid_before', None), ('rms', '0.51'), ('model_pars', []), ('orbit_id', '188'), ('producer', 'Otto Matic'), ('first_obs', '1983-09-10'), ('soln_date', '2018-07-06 06:55:08'), ('two_body', None), ('epoch', Unit("2.4582e+06 d")), ('elements', OrderedDict([('e', '0.709'), ('e_sig', '4.8e-08'), ('a', Unit("4.26 AU")), ('a_sig', Unit("2.3e-08 AU")), ('q', Unit("1.24 AU")), ('q_sig', Unit("2e-07 AU")), ('i', Unit("31.1 deg")), ('i_sig', Unit("1.1e-05 deg")), ('om', Unit("350 deg")), ('om_sig', Unit("1e-05 deg")), ('w', Unit("316 deg")), ('w_sig', Unit("1.1e-05 deg")), ('ma', Unit("355 deg")), ('ma_sig', Unit("3.9e-06 deg")), ('tp', Unit("2.45825e+06 d")), ('tp_sig', Unit("3.5e-05 d")), ('per', Unit("3210 d")), ('per_sig', Unit("2.6e-05 d")), ('n', Unit("0.112 deg / d")), ('n_sig', Unit("9.2e-10 deg / d")), ('ad', Unit("7.27 AU")), ('ad_sig', Unit("4e-08 AU"))])), ('equinox', 'J2000'), ('data_arc', '12717'), ('not_valid_after', None), ('n_del_obs_used', None), ('sb_used', 'SB431-N16'), ('n_obs_used', '869'), ('comment', None), ('pe_used', 'DE431'), ('last_obs', '2018-07-05'), ('moid', Unit("0.334 AU")), ('n_dop_obs_used', None)]))])

This function orders the parsed data into a dictionary. This representation of the results is convenient but not easy to read for a human. schematic() will use the output dictionary and transform it into a human-readable schematic. Please consult the Data Output section of the SBDB API documentation to learn more about the meaning of the different output fields:

>>> print(SBDB.schematic(sbdb))
+-+ object:
| +-- shortname: 3552 Don Quixote
| +-- neo: True
| +-+ orbit_class:
| | +-- name: Amor
| | +-- code: AMO
| +-- pha: False
| +-- spkid: 2003552
| +-- kind: an
| +-- orbit_id: 188
| +-- fullname: 3552 Don Quixote (1983 SA)
| +-- des: 3552
| +-- prefix: None
+-+ signature:
| +-- source: NASA/JPL Small-Body Database (SBDB) API
| +-- version: 1.0
+-+ orbit:
| +-- source: JPL
| +-- cov_epoch: 2.45657e+06 d
| +-- moid_jup: 0.441 AU
| +-- t_jup: 2.315
| +-- condition_code: 0
| +-- not_valid_before: None
| +-- rms: 0.51
| +-- model_pars: []
| +-- orbit_id: 188
| +-- producer: Otto Matic
| +-- first_obs: 1983-09-10
| +-- soln_date: 2018-07-06 06:55:08
| +-- two_body: None
| +-- epoch: 2.4582e+06 d
| +-+ elements:
| | +-- e: 0.709
| | +-- e_sig: 4.8e-08
| | +-- a: 4.26 AU
| | +-- a_sig: 2.3e-08 AU
| | +-- q: 1.24 AU
| | +-- q_sig: 2e-07 AU
| | +-- i: 31.1 deg
| | +-- i_sig: 1.1e-05 deg
| | +-- om: 350 deg
| | +-- om_sig: 1e-05 deg
| | +-- w: 316 deg
| | +-- w_sig: 1.1e-05 deg
| | +-- ma: 355 deg
| | +-- ma_sig: 3.9e-06 deg
| | +-- tp: 2.45825e+06 d
| | +-- tp_sig: 3.5e-05 d
| | +-- per: 3210 d
| | +-- per_sig: 2.6e-05 d
| | +-- n: 0.112 deg / d
| | +-- n_sig: 9.2e-10 deg / d
| | +-- ad: 7.27 AU
| | +-- ad_sig: 4e-08 AU
| +-- equinox: J2000
| +-- data_arc: 12717
| +-- not_valid_after: None
| +-- n_del_obs_used: None
| +-- sb_used: SB431-N16
| +-- n_obs_used: 869
| +-- comment: None
| +-- pe_used: DE431
| +-- last_obs: 2018-07-05
| +-- moid: 0.334 AU
| +-- n_dop_obs_used: None

The schematic shows the different levels in the dictionary. Note that schematic() actually only returns a string; in order to display it properly, it has to be passed to a print function. schematic() can also be applied to individual items of the dictionary, e.g., print(sbdb['orbit']).

In this example, there are three top-level items (object, orbit, signature), each of which is an OrderedDict itself, containing additional information: object contains general object information on the object’s dynamical type and identifiers, whereas orbit contains detailed information on the target’s orbit. signature simply provides information on SBDB and the API version used.

orbit contains a number of items describing the target’s orbit. In order to use one of these items, you can access it like any dictionary item:

>>> sbdb['orbit']['moid_jup']
0.441 AU

Note that many of the items in the output dictionary are associated with units which can be readily used for transformations. For instance, if you are interested in the minimum orbit intersection distance of the target with respect to Jupiter (moid_jup) expressed in km instead of au, you can use:

>>> print(sbdb['orbit']['moid_jup'].to('km'))
65972660.9787

The vast majority of parameter names are identical to those used in the SBDB API documentation, please refer to this document for exact definitions.

The most significant difference between data obtained through SBDBClass and directly through the SBDB API is the formatting. Where possible and useful, dictionary style formatting has been replaced with ndarray structure to make the data easier to access (see e.g., sbdb['orbit']['elements'] in the above example).

Customizing your Query

The default query() offers only a limited amount of target information. The full potential of the SBDB API can be tapped using the optional parameters of query(). The following listing shows the optional parameters of query() and how they translate to the SBDB API. Note that most options are or boolean nature and can be triggered by simply assigning True to them.

  • id_type: available options ['search', 'spk', 'des'] translate into the different SBDB API search modes [sstr, spk, des]; the default search mode is 'search'

  • neo_only: outputs only information for Near-Earth Objects (NEOs); corresponds to SBDB API option neo; default value: False

  • alternate_id: provides information on alternate ids, for instance in the case of double designations; True activates the SBDB API options alt-des and alt-spk; default value: False

  • full_precision: enables full precision output; corresponds to SBDB API option full_prec; default value: False

  • solution_epoch: outputs the orbit data at the JPL orbit-solution epoch instead of the standard Minor Planet Center epoch; corresponds to SBDB API option soln_epoch; default value: False

  • covariance: outputs the orbital covariance (if available) in the form specified: 'mat' in full matrix form, 'vec' in upper-triangular vector-stored form, 'src' in upper-triangular vector-stored square-root form; corresponds to SBDB API option cov; default value: None (no output)

  • validity: output not_valid_before and not_valid_after validity ranges for the orbit in Julian Date format; True corresponds to SBDB API nv_fmt='jd'; default value: False

  • alternate_orbit: output information on alternate orbits (e.g., in the case of comets); corresponds to SBDB API alt-orbits; default value: False

  • phys: output available information on physical properties; corresponds to SBDB API phys-par; default value: False

  • close_approach: output information on close approaches with major bodies; True corresponds to SBDB API ca-data='true' together with ca-time='both', ca-tunc='both', ca-unc='true'; default value: False

  • radar: output information on radar observations; True corresponds to radar-obs='true' together with r-name='true', r-observer='true', and r-notes='true'; default value: False

  • virtual-impactor: output information on virtual impactor status; corresponds to SBDB API vi-data; default value: False

  • discovery: output information on discovery circumstance; True corresponds to SBDB API discovery='true' and raw-citation='true'; default value: False

Acknowledgements

This submodule makes use of the JPL Horizons system.

The development of this submodule is funded through NASA PDART Grant No. 80NSSC18K0987 to the sbpy project.

Reference/API

astroquery.jplsbdb Package

JPLSBDB

author

Michael Mommert (mommermiscience@gmail.com)

Classes

SBDBClass()

A class for querying the JPL Small-Body Database Browser service.

Conf()

Configuration parameters for astroquery.jplsbdb.