astro query:docs

- Index
- Modules

### Navigation

- next »
- « previous |
- astroquery v0.4.11 »
- JPL SBDB Queries (`astroquery.jplsbdb`/astroquery.solarsystem.jpl.sbdb)

# 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', '263'), ('fullname', '3552 Don Quixote (1983 SA)'),
    ('des', '3552'), ('prefix', None)])), ('signature', OrderedDict([('source', 'NASA/JPL Small-Body Database (SBDB) API'), ('version', '1.2')])),
    ('orbit', OrderedDict([('source', 'JPL'), ('cov_epoch', Unit("2.45756e+06 d")), ('moid_jup', Unit("0.44 AU")), ('t_jup', '2.314'),
    ('condition_code', '0'), ('not_valid_before', None), ('rms', '0.46'), ('model_pars', []), ('orbit_id', '263'), ('producer', 'Otto Matic'),
    ('first_obs', '1983-09-10'), ('soln_date', '2021-01-25 05:31:27'), ('two_body', None), ('epoch', Unit("2.459e+06 d")), ('elements', OrderedDict([('e', '0.709'),
    ('e_sig', '2.7e-08'), ('a', Unit("4.26 AU")), ('a_sig', Unit("2e-08 AU")), ('q', Unit("1.24 AU")), ('q_sig', Unit("1.2e-07 AU")), ('i', Unit("31.1 deg")),
    ('i_sig', Unit("5.3e-06 deg")), ('om', Unit("350 deg")), ('om_sig', Unit("9.4e-06 deg")), ('w', Unit("316 deg")), ('w_sig', Unit("9.3e-06 deg")),
    ('ma', Unit("84.5 deg")), ('ma_sig', Unit("3.9e-06 deg")), ('tp', Unit("2.45825e+06 d")), ('tp_sig', Unit("3.1e-05 d")), ('per', Unit("3210 d")),
    ('per_sig', Unit("2.3e-05 d")), ('n', Unit("0.112 deg / d")), ('n_sig', Unit("8.1e-10 deg / d")), ('ad', Unit("7.28 AU")), ('ad_sig', Unit("3.5e-08 AU"))])),
    ('equinox', 'J2000'), ('data_arc', '13645'), ('not_valid_after', None), ('n_del_obs_used', None), ('sb_used', 'SB431-N16'), ('n_obs_used', '1322'),
    ('comment', None), ('pe_used', 'DE431'), ('last_obs', '2021-01-18'), ('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: 263
    | +-- fullname: 3552 Don Quixote (1983 SA)
    | +-- des: 3552
    | +-- prefix: None
    +-+ signature:
    | +-- source: NASA/JPL Small-Body Database (SBDB) API
    | +-- version: 1.2
    +-+ orbit:
    | +-- source: JPL
    | +-- cov_epoch: 2.45756e+06 d
    | +-- moid_jup: 0.44 AU
    | +-- t_jup: 2.314
    | +-- condition_code: 0
    | +-- not_valid_before: None
    | +-- rms: 0.46
    | +-- model_pars: []
    | +-- orbit_id: 263
    | +-- producer: Otto Matic
    | +-- first_obs: 1983-09-10
    | +-- soln_date: 2021-01-25 05:31:27
    | +-- two_body: None
    | +-- epoch: 2.459e+06 d
    | +-+ elements:
    | | +-- e: 0.709
    | | +-- e_sig: 2.7e-08
    | | +-- a: 4.26 AU
    | | +-- a_sig: 2e-08 AU
    | | +-- q: 1.24 AU
    | | +-- q_sig: 1.2e-07 AU
    | | +-- i: 31.1 deg
    | | +-- i_sig: 5.3e-06 deg
    | | +-- om: 350 deg
    | | +-- om_sig: 9.4e-06 deg
    | | +-- w: 316 deg
    | | +-- w_sig: 9.3e-06 deg
    | | +-- ma: 84.5 deg
    | | +-- ma_sig: 3.9e-06 deg
    | | +-- tp: 2.45825e+06 d
    | | +-- tp_sig: 3.1e-05 d
    | | +-- per: 3210 d
    | | +-- per_sig: 2.3e-05 d
    | | +-- n: 0.112 deg / d
    | | +-- n_sig: 8.1e-10 deg / d
    | | +-- ad: 7.28 AU
    | | +-- ad_sig: 3.5e-08 AU
    | +-- equinox: J2000
    | +-- data_arc: 13645
    | +-- not_valid_after: None
    | +-- n_del_obs_used: None
    | +-- sb_used: SB431-N16
    | +-- n_obs_used: 1322
    | +-- comment: None
    | +-- pe_used: DE431
    | +-- last_obs: 2021-01-18
    | +-- 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']
    <Quantity 0.428 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'))
    64027888.6596 km

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

### Name Search

The SBDB API provides a name search tool that enables the listing of existing target names using a wildcard symbol (`'*'`). For instance, if you are interested in all NEOs with designations starting with “2018 AA”, you would use the following query:

    >>> sbdb = SBDB.query('2018 AA*', neo_only=True)

Note that in case of a name search not the entire output is queries per target, but only a list of objects matching this pattern:

    >>> sbdb['list']
    OrderedDict({'name': ['(2018 AA4)', '(2018 AA12)', '(2018 AA74)'], 'pdes': ['2018 AA4', '2018 AA12', '2018 AA74']})

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

## Troubleshooting

If you are repeatedly getting failed queries, or bad/out-of-date results, try clearing your cache:

    >>> from astroquery.jplsbdb import SBDB
    >>> SBDB.clear_cache()

If this function is unavailable, upgrade your version of astroquery. The `clear_cache` function was introduced in version 0.4.7.dev8479.

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