JPL Horizons Queries (astroquery.jplhorizons/astroquery.solarsystem.jpl.horizons)¶
Overview¶
The HorizonsClass class provides an
interface to services provided by the Solar System Dynamics group at
the Jet Propulation Laboratory.
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.
In order to query information for a specific Solar System body, a
Horizons object has to be instantiated:
>>> from astroquery.jplhorizons import Horizons
>>> obj = Horizons(id='Ceres', location='568', epochs=2458133.33546)
>>> print(obj)
JPLHorizons instance "Ceres"; location=568, epochs=[2458133.33546], id_type=smallbody
id refers to the target identifier and is mandatory; the exact
string will be used in the query to the Horizons system.
location means either the observer’s location (e.g., Horizons
ephemerides query) or the body relative to which orbital elements are
provided (e.g., Horizons orbital elements or vectors query); the same
codes as used by Horizons are used here, which includes MPC
Observatory codes. The default is location=None, which uses a
geocentric location for ephemerides queries and the Sun as central body
for orbital elements and state vector queries. User-defined
topocentric locations for ephemerides queries can be provided, too, in
the form of a dictionary. The dictionary has to be formatted as
follows: {'lon': longitude in degrees (East positive, West
negative), 'lat': latitude in degrees (North positive, South
negative), 'elevation': elevation in km above the reference
ellipsoid}. In addition, 'body' can be set to the Horizons body ID
of the central body if different from Earth; by default, it is
assumed that this location is on Earth if it has not been specifically
set. The following example uses the coordinates of the Statue of
Liberty
as the observer’s location:
>>> statue_of_liberty = {'lon': -74.0466891,
... 'lat': 40.6892534,
... 'elevation': 0.093}
>>> obj = Horizons(id='Ceres',
... location=statue_of_liberty,
... epochs=2458133.33546)
JPLHorizons instance "Ceres"; location={'lon': -74.0466891, 'lat': 40.6892534, 'elevation': 0.093}, epochs=[2458133.33546], id_type=smallbody
epochs is either a scalar or list of Julian Dates (floats or
strings) in the case of discrete epochs, or, in the case of a range of
epochs, a dictionary that has to include the keywords start,
stop (both using the following format “YYYY-MM-DD [HH:MM:SS]”),
and step (e.g., '1m' for one minute, '3h'``three hours,
``'10d' for ten days). Note that all input epochs, both calendar
dates/times and Julian Dates, refer to UTC. By default,
epochs=None, which uses the current date and time.
id_type describes what type of target identifier has been provided
in order to minimize the risk of confusion when identifying the
target: smallbody (default; refers to an asteroid or comet),
majorbody (planets or satellites), designation (any type of
asteroid or comet designation), name (any type of target name),
asteroid_name (name of an asteroid), or comet_name (name of a
comet). In order to minimize confusion, try to be as specific as
possible; namely, in the case of comets, make use of comet_name
(e.g., “Halley”) and designation (e.g., “73P”). In the case of
ambiguities in the name resolving, a list of matching objects will be
provided. In order to select an object from this list, provide the
respective id number or record number as id and use id_type=id:
>>> from astroquery.jplhorizons import Horizons
>>> print(Horizons(id='Encke').ephemerides())
...
ValueError: Ambiguous target name; provide unique id:
Record # Epoch-yr Primary Desig >MATCH NAME<
-------- -------- ------------- -------------------------
9134 4822 P-L Encke
900034 1786 2P Encke
900035 1796 2P Encke
900036 1805 2P Encke
... ... ... ...
>>> print(Horizons(id='900034', id_type='id').ephemerides())
targetname datetime_str datetime_jd ... RA_3sigma DEC_3sigma
--- --- d ... arcsec arcsec
---------- ------------------------ ----------------- ... --------- ----------
2P/Encke 2018-Jan-17 05:06:07.709 2458135.712589224 ... -- --
Querying JPL Horizons¶
The JPL Horizons system provides ephemerides, orbital elements, and state vectors for almost all known Solar System bodies. These queries are provided through three functions:
ephemerides() returns
ephemerides for a given observer location (location) and epoch or
range of epochs (epochs) in the form of an astropy table. The
following example queries the ephemerides of asteroid (1) Ceres for
a range of dates as seen from Maunakea:
>>> from astroquery.jplhorizons import Horizons
>>> obj = Horizons(id='Ceres', location='568',
... epochs={'start':'2010-01-01', 'stop':'2010-03-01',
... 'step':'10d'})
>>> eph = obj.ephemerides()
>>> print(eph)
targetname datetime_str datetime_jd ... GlxLat RA_3sigma DEC_3sigma
--- --- d ... deg arcsec arcsec
---------- ----------------- ----------- ... --------- --------- ----------
1 Ceres 2010-Jan-01 00:00 2455197.5 ... 24.120057 0.0 0.0
1 Ceres 2010-Jan-11 00:00 2455207.5 ... 20.621496 0.0 0.0
1 Ceres 2010-Jan-21 00:00 2455217.5 ... 17.229529 0.0 0.0
1 Ceres 2010-Jan-31 00:00 2455227.5 ... 13.97264 0.0 0.0
1 Ceres 2010-Feb-10 00:00 2455237.5 ... 10.877201 0.0 0.0
1 Ceres 2010-Feb-20 00:00 2455247.5 ... 7.976737 0.0 0.0
The following fields are available for each ephemerides query:
>>> print(eph.columns)
<TableColumns names=('targetname','datetime_str','datetime_jd','H','G','solar_presence','flags','RA','DEC','RA_rate','DEC_rate','AZ','EL','airmass','magextinct','V','surfbright','illumination','EclLon','EclLat','r','r_rate','delta','delta_rate','lighttime','elong','elongFlag','alpha','sunTargetPA','velocityPA','ObsEclLon','ObsEclLat','GlxLon','GlxLat','RA_3sigma','DEC_3sigma')>
The values in these columns are the same as those defined in the
Horizons Definition of Observer Table Quantities; names have been
simplified in a few cases. Quantities H and G are the target’s
Solar System absolute magnitude and photometric phase curve slope,
respectively. In the case of comets, H and G are replaced by M1,
M2, k1, k2, and phasecoeff; please refer to the Horizons
documentation for definitions.
Optional parameters of
ephemerides() are
corresponding to optional features of the Horizons system:
airmass_lessthan sets an upper limit to airmass,
solar_elongation enables the definition of a solar elongation
range, max_hour_angle sets a cutoff of the hour angle,
skip_daylight=True reject epochs during daylight, rate_cutoff
allows to reject targets with sky motion rates higher than provided
(in units of arcsec/h), refraction accounts for refraction in the
computation of the ephemerides (disabled by default), and
refsystem defines the coordinate reference system used (J2000 by
default).. For comets, the options closest_apparation and
no_fragments are available, which select the closest apparition in
time and reject fragments, respectively. Note that these options
should only be used for comets and will crash the query for other
object types. Furthermore, get_query_payload=True skips the query
and only returns the query payload, whereas get_raw_response=True
the raw query response instead of the astropy table returns.
ephemerides() queries by
default all available quantities from the JPL Horizons servers. This
might take a while. If you are only interested in a subset of the
available quantities, you can query only those. The corresponding
optional parameter to be set is quantities. This parameter uses
the same numerical codes as JPL Horizons defined in the JPL Horizons
User Manual Definition of Observer Table Quantities. For
instance, if you only want to query astrometric RA and Dec, you can
use quantities=1; if you only want the heliocentric and geocentric
distances, you can use quantities='19,20' (note that in this case
a string with comma-separated codes has to be provided).
elements() returns orbital
elements relative to some Solar System body (location, referred to as
“CENTER” in Horizons) and for a given epoch or a range of epochs
(epochs) in the form of an astropy table. The following example
queries the osculating elements of asteroid (433) Eros for a given
data relative to the Sun:
>>> from astroquery.jplhorizons import Horizons
>>> obj = Horizons(id='433', location='500@10',
... epochs=2458133.33546)
>>> el = obj.elements()
>>> print(el)
targetname datetime_jd ... Q P
--- d ... AU d
------------------ ------------- ... ------------- ------------
433 Eros (1898 DQ) 2458133.33546 ... 1.78244263804 642.93873484
The following fields are queried:
>>> print(el.columns)
<TableColumns names=('targetname','datetime_jd','datetime_str','H','G','e','q','incl','Omega','w','Tp_jd','n','M','nu','a','Q','P')>
Optional parameters of
elements() include
refsystem, which defines the coordinate reference system used
(J2000 by default), refplane which defines the reference plane of
the orbital elements queried, and tp_type, which switches between
a relative and absolute representation of the time of perihelion
passage. For comets, the options closest_apparation and
no_fragments are available, which select the closest apparition in
time and reject fragments, respectively. Note that these options
should only be used for comets and will crash the query for other
object types. Furthermore,``get_query_payload=True``, which skips the
query and only returns the query payload, and
get_raw_response=True, which returns the raw query response
instead of the astropy table, are available.
vectors() returns the
state vector of the target body in cartesian coordinates relative to
some Solar System body (location, referred to as “CENTER” in
Horizons) and for a given epoch or a range of epochs (epochs) in
the form of an astropy table. The following example queries the state
vector of asteroid 2012 TC4 as seen from Goldstone for a range of
epochs:
>>> from astroquery.jplhorizons import Horizons
>>> obj = Horizons(id='2012 TC4', location='257',
... epochs={'start':'2017-10-01', 'stop':'2017-10-02',
... 'step':'10m'})
>>> vec = obj.vectors()
>>> print(vec)
targetname datetime_jd ... range range_rate
--- d ... AU AU / d
---------- ------------- ... --------------- -----------------
(2012 TC4) 2458027.5 ... 0.0429332099306 -0.00408018711862
(2012 TC4) 2458027.50694 ... 0.0429048742906 -0.00408040726527
(2012 TC4) 2458027.51389 ... 0.0428765385796 -0.00408020747595
(2012 TC4) 2458027.52083 ... 0.0428482057142 -0.0040795878561
(2012 TC4) 2458027.52778 ... 0.042819878607 -0.00407854931543
(2012 TC4) 2458027.53472 ... 0.0427915601617 -0.0040770935665
... ... ... ... ...
(2012 TC4) 2458028.45833 ... 0.0392489462501 -0.00405496595173
(2012 TC4) 2458028.46528 ... 0.03922077771 -0.00405750632914
(2012 TC4) 2458028.47222 ... 0.039192592935 -0.00405964084539
(2012 TC4) 2458028.47917 ... 0.039164394759 -0.00406136516755
(2012 TC4) 2458028.48611 ... 0.0391361860433 -0.00406267574646
(2012 TC4) 2458028.49306 ... 0.0391079696711 -0.0040635698239
(2012 TC4) 2458028.5 ... 0.0390797485422 -0.00406404543822
Length = 145 rows
The following fields are queried:
>>> print(vec.columns)
<TableColumns names=('targetname','datetime_jd','datetime_str','H','G','x','y','z','vx','vy','vz','lighttime','range','range_rate')>
Similar to the other HorizonsClass functions,
optional parameters of vectors() are
get_query_payload=True, which skips the query and only returns the
query payload, and get_raw_response=True, which returns the raw
query response instead of the astropy table. For comets, the options
closest_apparation and no_fragments are available, which select
the closest apparition in time and reject fragments,
respectively. Note that these options should only be used for comets
and will crash the query for other object types.
How to Use the Query Tables¶
astropy table created by the query functions are extremely versatile and easy to use. Since all query functions return the same type of table, they can all be used in the same way.
We provide some examples to illustrate how to use them based on the following JPL Horizons ephemerides query of near-Earth asteroid (3552) Don Quixote since its year of Discovery:
>>> from astroquery.jplhorizons import Horizons
>>> obj = Horizons(id='3552', location='568',
... epochs={'start':'2010-01-01', 'stop':'2019-12-31',
... 'step':'1y'})
>>> eph = obj.ephemerides()
As we have seen before, we can display a truncated version of table
eph by simply using
>>> print(eph)
targetname datetime_str ... RA_3sigma DEC_3sigma
--- --- ... arcsec arcsec
-------------------------- ----------------- ... --------- ----------
3552 Don Quixote (1983 SA) 1983-Jan-01 00:00 ... 0.159 0.141
3552 Don Quixote (1983 SA) 1984-Jan-01 00:00 ... 0.187 0.231
3552 Don Quixote (1983 SA) 1985-Jan-01 00:00 ... 0.138 0.147
3552 Don Quixote (1983 SA) 1986-Jan-01 00:00 ... 0.117 0.123
3552 Don Quixote (1983 SA) 1987-Jan-01 00:00 ... 0.106 0.104
3552 Don Quixote (1983 SA) 1988-Jan-01 00:00 ... 0.095 0.089
... ... ... ... ...
3552 Don Quixote (1983 SA) 2013-Jan-01 00:00 ... 0.106 0.107
3552 Don Quixote (1983 SA) 2014-Jan-01 00:00 ... 0.095 0.092
3552 Don Quixote (1983 SA) 2015-Jan-01 00:00 ... 0.083 0.079
3552 Don Quixote (1983 SA) 2016-Jan-01 00:00 ... 0.07 0.067
3552 Don Quixote (1983 SA) 2017-Jan-01 00:00 ... 0.061 0.062
3552 Don Quixote (1983 SA) 2018-Jan-01 00:00 ... 0.126 0.089
3552 Don Quixote (1983 SA) 2019-Jan-01 00:00 ... 0.174 0.174
Length = 37 rows
Please note the formatting of this table, which is done automatically. Above the dashes in the first two lines, you have the column name and its unit. Every column is assigned a unit from astropy units. We will learn later how to use these units.
Columns¶
We can get at list of all the columns in this table with
>>> print(eph.columns)
<TableColumns names=('targetname','datetime_str','datetime_jd','H','G','solar_presence','flags','RA','DEC','RA_rate','DEC_rate','AZ','EL','airmass','magextinct','V','surfbright','illumination','EclLon','EclLat','r','r_rate','delta','delta_rate','lighttime','elong','elongFlag','alpha','sunTargetPA','velocityPA','ObsEclLon','ObsEclLat','GlxLon','GlxLat','RA_3sigma','DEC_3sigma')>
We can address each column individually by indexing it using its name as provided in this list. For instance, we can get all RAs for Don Quixote by using
>>> print(eph['RA'])
RA
deg
---------
209.43762
357.85696
86.22996
122.10393
137.91137
148.42444
...
136.60019
147.44945
156.58965
166.32128
180.69918
232.11974
16.10662
Length = 37 rows
This column is formatted like the entire table; it has a column name and a unit. We can select several columns at a time, for instance RA and DEC for each epoch
>>> print(eph['datetime_str', 'RA', 'DEC'])
datetime_str RA DEC
--- deg deg
----------------- --------- ---------
1983-Jan-01 00:00 209.43762 -25.92118
1984-Jan-01 00:00 357.85696 28.74791
1985-Jan-01 00:00 86.22996 60.90524
1986-Jan-01 00:00 122.10393 53.19306
1987-Jan-01 00:00 137.91137 44.95184
1988-Jan-01 00:00 148.42444 37.01774
... ... ...
2013-Jan-01 00:00 136.60019 45.82408
2014-Jan-01 00:00 147.44945 37.79874
2015-Jan-01 00:00 156.58965 29.23058
2016-Jan-01 00:00 166.32128 18.48173
2017-Jan-01 00:00 180.69918 1.20453
2018-Jan-01 00:00 232.11974 -37.95539
2019-Jan-01 00:00 16.10662 45.50296
Length = 37 rows
We can use the same representation to do math with these columns. For instance, let’s calculate the total rate of the object by calculating the geometric mean of ‘RA_rate’ and ‘DEC_rate’:
>>> import numpy as np
>>> print(np.sqrt(eph['RA_rate']**2 + eph['DEC_rate']**2))
dRA*cosD
------------------
58.69696313151559
51.59679292260421
25.793090188451636
20.994411962530627
17.258738465267385
14.376579229218054
11.73881436960752
...
17.679841379965037
14.775806762375074
11.874884148540735
7.183280208160058
7.2955985010416375
94.84821056509183
23.952455011994072
Please note that the column is wrong (it uses the title of the first column used), and that there is no unit (this will be fixed with the use of astropy QTables in the future).
Units¶
Columns have units assigned to them. For instance, the RA column has
the unit deg assigned to it, i.e., degrees. More complex units are
available, too, e.g., the RA_rate column is expressed in arcsec /
h - arcseconds per hour:
>>> print(eph['RA_rate'])
RA_rate
arcsec / h
----------
44.35495
49.20015
-24.5561
-20.0651
-15.0293
-11.6761
...
-15.5509
-12.107
-9.32616
-5.80004
3.115849
85.2272
19.02546
Length = 37 rows
The unit of this column can be easily converted to any other unit
describing the same dimensions. For instance, we can turn RA_rate
into arcsec / s:
>>> eph['RA_rate'].convert_unit_to('arcsec/s')
>>> print(eph['RA_rate'])
RA_rate
arcsec / s
----------------------
0.012320819444444445
0.013666708333333333
-0.006821138888888889
-0.005573638888888889
-0.004174805555555556
-0.003243361111111111
...
-0.004319694444444445
-0.0033630555555555553
-0.0025905999999999998
-0.0016111222222222222
0.0008655136111111111
0.02367422222222222
0.00528485
Length = 37 rows
Please refer to the astropy table and astropy units documentations for more information.
Hints and Tricks¶
Checking the original JPL Horizons output¶
For all query types, the query URI (the URI is what you would put into
the URL field of your web browser) that is used to request the data
from the JPL Horizons server can be obtained from the
HorizonsClass object after a query
has been performed (before the query only None would be returned):
>>> print(obj.uri)
https://ssd.jpl.nasa.gov/horizons_batch.cgi?batch=1&TABLE_TYPE=VECTORS&OUT_UNITS=AU-D&COMMAND=%222012+TC4%3B%22&CENTER=%27257%27&CSV_FORMAT=%22YES%22&REF_PLANE=ECLIPTIC&REF_SYSTEM=J2000&TP_TYPE=ABSOLUTE&LABELS=YES&OBJ_DATA=YES&START_TIME=2017-10-01&STOP_TIME=2017-10-02&STEP_SIZE=10m
If your query failed, it might be useful for you to put the URI into a
web browser to get more information why it failed. Please note that
uri is an attribute of
HorizonsClass and not the results
table.
Date Formats¶
JPL Horizons puts somewhat strict guidelines on the date formats:
individual epochs have to be provided as Julian Dates, whereas epoch
ranges have to be provided as ISO dates (YYYY-MM-DD HH-MM UT). If you
have your epoch dates in one of these formats but you need the other
format, make use of astropy.time.Time for the conversion. An
example is provided here:
>>> from astropy.time import Time
>>> mydate_fromiso = Time('2018-07-23 15:55:23') # pass date as string
>>> print(mydate_fromiso.jd) # convert Time object to Julian Date
2458323.163460648
>>> mydate_fromjd = Time(2458323.163460648, format='jd')
>>> print(mydate_fromjd.iso) # convert Time object to ISO
2018-07-23 15:55:23.000
astropy.time.Time allows you to convert dates across a wide
range of formats. Please note that when reading in Julian Dates, you
have to specify the date format as 'jd', as the integer passed to
Time is ambiguous.
Keep Queries Short¶
Keep in mind that queries are sent as URIs to the Horizons server. If you query a large number of epochs (in the form of a list), this list might be truncated as URIs are typically expected to be shorter than 2,000 symbols and your results might be compromised. If your query URI is longer than this limit, a warning is given. In that case, please try using a range of dates instead of a list of individual dates.
Acknowledgements¶
This submodule makes use of the JPL Horizons system.
The development of this submodule is in part funded through NASA PDART Grant No. 80NSSC18K0987 to the sbpy project.
Reference/API¶
astroquery.jplhorizons Package¶
JPLHorizons¶
| author: | Michael Mommert (mommermiscience@gmail.com) |
|---|
Classes¶
HorizonsClass([id, location, epochs, id_type]) |
A class for querying the JPL Horizons service. |
Conf |
Configuration parameters for astroquery.jplhorizons. |