Skip to content

Commit 2922473

Browse files
bsipoczbsipocz
authored
Merge pull request #1965 from tinumide/jplhorizons-doc-cleanup
Jplhorizons, Jplsbdb, Jplspec documentation cleanup
2 parents ffb6c52 + 3ce2ae3 commit 2922473

File tree

3 files changed

+224
-201
lines changed

3 files changed

+224
-201
lines changed

‎docs/jplhorizons/jplhorizons.rst

Lines changed: 73 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,3 @@
1-
.. doctest-skip-all
2-
31
.. _astroquery.jplhorizons:
42

53
***********************************************************************************
@@ -35,7 +33,7 @@ identical to the one presented here.
3533
In order to query information for a specific Solar System body, a
3634
``Horizons`` object has to be instantiated:
3735

38-
.. code-block:: python
36+
.. doctest-remote-data::
3937

4038
>>> from astroquery.jplhorizons import Horizons
4139
>>> obj = Horizons(id='Ceres', location='568', epochs=2458133.33546)
@@ -63,16 +61,18 @@ uses the coordinates of the `Statue of Liberty
6361
<https://www.google.com/maps/place/Statue+of+Liberty+National+Monument/@40.6892534,-74.0466891,17z/data=!3m1!4b1!4m5!3m4!1s0x89c25090129c363d:0x40c6a5770d25022b!8m2!3d40.6892494!4d-74.0445004>`_
6462
as the observer's location:
6563

64+
.. doctest-remote-data::
65+
6666
>>> statue_of_liberty = {'lon': -74.0466891,
6767
... 'lat': 40.6892534,
6868
... 'elevation': 0.093}
6969
>>> obj = Horizons(id='Ceres',
7070
... location=statue_of_liberty,
7171
... epochs=2458133.33546)
72+
>>> print(obj)
7273
JPLHorizons instance "Ceres"; location={'lon': -74.0466891, 'lat': 40.6892534, 'elevation': 0.093}, epochs=[2458133.33546], id_type=None
7374

7475

75-
7676
``epochs`` is either a scalar or list of Julian dates (floats or strings) in the
7777
case of discrete epochs, or, in the case of a range of epochs, a dictionary that
7878
has to include the keywords ``start``, ``stop`` (both using the following format
@@ -105,10 +105,11 @@ In the case of ambiguities in the name resolution, a list of matching objects
105105
will be provided. In order to select an object from this list, provide the
106106
respective id number or record number as ``id`` and use ``id_type=None``:
107107

108-
.. code-block:: python
108+
.. doctest-remote-data::
109109

110110
>>> from astroquery.jplhorizons import Horizons
111111
>>> print(Horizons(id='Encke').ephemerides())
112+
Traceback (most recent call last):
112113
...
113114
ValueError: Ambiguous target name; provide unique id:
114115
Record # Epoch-yr Primary Desig >MATCH NAME<
@@ -118,7 +119,7 @@ respective id number or record number as ``id`` and use ``id_type=None``:
118119
90000035 1796 2P Encke
119120
90000036 1805 2P Encke
120121
... ... ... ...
121-
>>> print(Horizons(id='90000034', id_type=None).ephemerides())
122+
>>> print(Horizons(id='90000034', id_type=None).ephemerides()) # doctest: +IGNORE_OUTPUT
122123
targetname datetime_str datetime_jd ... RA_3sigma DEC_3sigma
123124
--- --- d ... arcsec arcsec
124125
---------- ------------------------ ----------------- ... --------- ----------
@@ -141,30 +142,30 @@ for a given observer location (``location``) and epoch or range of epochs
141142
(``epochs``) in the form of an astropy table. The following example queries the
142143
ephemerides of asteroid (1) Ceres for a range of dates as seen from Mauna Kea:
143144

144-
.. code-block:: python
145+
.. doctest-remote-data::
145146

146147
>>> from astroquery.jplhorizons import Horizons
147148
>>> obj = Horizons(id='Ceres', location='568',
148149
... epochs={'start':'2010-01-01', 'stop':'2010-03-01',
149150
... 'step':'10d'})
150151
>>> eph = obj.ephemerides()
151152
>>> print(eph)
152-
targetname datetime_str datetime_jd ... GlxLat RA_3sigma DEC_3sigma
153-
--- --- d ... deg arcsec arcsec
154-
---------- ----------------- ----------- ... --------- --------- ----------
155-
1 Ceres 2010-Jan-01 00:00 2455197.5 ... 24.120057 0.0 0.0
156-
1 Ceres 2010-Jan-11 00:00 2455207.5 ... 20.621496 0.0 0.0
157-
1 Ceres 2010-Jan-21 00:00 2455217.5 ... 17.229529 0.0 0.0
158-
1 Ceres 2010-Jan-31 00:00 2455227.5 ... 13.97264 0.0 0.0
159-
1 Ceres 2010-Feb-10 00:00 2455237.5 ... 10.877201 0.0 0.0
160-
1 Ceres 2010-Feb-20 00:00 2455247.5 ... 7.976737 0.0 0.0
153+
targetname datetime_str datetime_jd ... alpha_true PABLon PABLat
154+
--- --- d ... deg deg deg
155+
----------------- ----------------- ----------- ... ---------- -------- ------
156+
1 Ceres (A801 AA) 2010-Jan-01 00:00 2455197.5 ... 12.3609 238.2494 4.5532
157+
1 Ceres (A801 AA) 2010-Jan-11 00:00 2455207.5 ... 14.1057 241.3339 4.2832
158+
1 Ceres (A801 AA) 2010-Jan-21 00:00 2455217.5 ... 15.7313 244.3394 4.0089
159+
1 Ceres (A801 AA) 2010-Jan-31 00:00 2455227.5 ... 17.2067 247.2518 3.7289
160+
1 Ceres (A801 AA) 2010-Feb-10 00:00 2455237.5 ... 18.5029 250.0576 3.4415
161+
1 Ceres (A801 AA) 2010-Feb-20 00:00 2455247.5 ... 19.5814 252.7383 3.1451
161162

162163

163164
The following fields are available for each ephemerides query:
164165

165166
.. code-block:: python
166167
167-
>>> print(eph.columns)
168+
>>> print(eph.columns) # doctest: +REMOTE_DATA
168169
<TableColumns names=('targetname','datetime_str','datetime_jd','H','G','solar_presence','flags','RA','DEC','RA_app','DEC_app','RA_rate','DEC_rate','AZ','EL','AZ_rate','EL_rate','sat_X','sat_Y','sat_PANG','siderealtime','airmass','magextinct','V','surfbright','illumination','illum_defect','sat_sep','sat_vis','ang_width','PDObsLon','PDObsLat','PDSunLon','PDSunLat','SubSol_ang','SubSol_dist','NPole_ang','NPole_dist','EclLon','EclLat','r','r_rate','delta','delta_rate','lighttime','vel_sun','vel_obs','elong','elongFlag','alpha','lunar_elong','lunar_illum','sat_alpha','sunTargetPA','velocityPA','OrbPlaneAng','constellation','TDB-UT','ObsEclLon','ObsEclLat','NPole_RA','NPole_DEC','GlxLon','GlxLat','solartime','earth_lighttime','RA_3sigma','DEC_3sigma','SMAA_3sigma','SMIA_3sigma','Theta_3sigma','Area_3sigma','RSS_3sigma','r_3sigma','r_rate_3sigma','SBand_3sigma','XBand_3sigma','DoppDelay_3sigma','true_anom','hour_angle','alpha_true','PABLon','PABLat')>
169170
170171
The values in these columns are the same as those defined in the Horizons
@@ -214,24 +215,24 @@ Horizons) and for a given epoch or a range of epochs (``epochs``) in the form of
214215
an astropy table. The following example queries the osculating elements of
215216
asteroid (433) Eros for a given date relative to the Sun:
216217

217-
.. code-block:: python
218+
.. doctest-remote-data::
218219

219220
>>> from astroquery.jplhorizons import Horizons
220221
>>> obj = Horizons(id='433', location='500@10',
221222
... epochs=2458133.33546)
222223
>>> el = obj.elements()
223224
>>> print(el)
224-
targetname datetime_jd ... Q P
225-
--- d ... AU d
226-
------------------ ------------- ... ------------- ------------
227-
433 Eros (A898 PA) 2458133.33546 ... 1.78244263804 642.93873484
225+
targetname datetime_jd ... Q P
226+
--- d ... AU d
227+
------------------ ------------- ... ----------------- -----------------
228+
433 Eros (A898 PA) 2458133.33546 ... 1.782442696867877 642.9387350660577
228229

229230

230231
The following fields are queried:
231232

232233
.. code-block:: python
233234
234-
>>> print(el.columns)
235+
>>> print(el.columns) # doctest: +REMOTE_DATA
235236
<TableColumns names=('targetname','datetime_jd','datetime_str','H','G','e','q','incl','Omega','w','Tp_jd','n','M','nu','a','Q','P')>
236237
237238
Optional parameters of :meth:`~astroquery.jplhorizons.HorizonsClass.elements`
@@ -257,36 +258,34 @@ the form of an astropy table. The following example queries the state
257258
vector of asteroid 2012 TC4 as seen from Goldstone for a range of
258259
epochs:
259260

260-
.. code-block:: python
261+
.. doctest-remote-data::
261262

262263
>>> from astroquery.jplhorizons import Horizons
263264
>>> obj = Horizons(id='2012 TC4', location='257',
264265
... epochs={'start':'2017-10-01', 'stop':'2017-10-02',
265266
... 'step':'10m'})
266267
>>> vec = obj.vectors()
267268
>>> print(vec)
268-
targetname datetime_jd ... range range_rate
269-
--- d ... AU AU / d
270-
---------- ------------- ... --------------- -----------------
271-
(2012 TC4) 2458027.5 ... 0.0429332099306 -0.00408018711862
272-
(2012 TC4) 2458027.50694 ... 0.0429048742906 -0.00408040726527
273-
(2012 TC4) 2458027.51389 ... 0.0428765385796 -0.00408020747595
274-
(2012 TC4) 2458027.52083 ... 0.0428482057142 -0.0040795878561
275-
(2012 TC4) 2458027.52778 ... 0.042819878607 -0.00407854931543
276-
(2012 TC4) 2458027.53472 ... 0.0427915601617 -0.0040770935665
277-
... ... ... ... ...
278-
(2012 TC4) 2458028.45833 ... 0.0392489462501 -0.00405496595173
279-
(2012 TC4) 2458028.46528 ... 0.03922077771 -0.00405750632914
280-
(2012 TC4) 2458028.47222 ... 0.039192592935 -0.00405964084539
281-
(2012 TC4) 2458028.47917 ... 0.039164394759 -0.00406136516755
282-
(2012 TC4) 2458028.48611 ... 0.0391361860433 -0.00406267574646
283-
(2012 TC4) 2458028.49306 ... 0.0391079696711 -0.0040635698239
284-
(2012 TC4) 2458028.5 ... 0.0390797485422 -0.00406404543822
269+
targetname datetime_jd ... range range_rate
270+
--- d ... AU AU / d
271+
---------- ----------------- ... ------------------- ---------------------
272+
(2012 TC4) 2458027.5 ... 0.04293321014985829 -0.004080187136570278
273+
(2012 TC4) 2458027.506944444 ... 0.04290487450966027 -0.004080407283352606
274+
(2012 TC4) 2458027.513888889 ... 0.04287653879860514 -0.004080207494158422
275+
(2012 TC4) 2458027.520833333 ... 0.04284820593301306 -0.004079587874430119
276+
... ... ... ... ...
277+
(2012 TC4) 2458028.479166667 ... 0.03916439496172948 -0.004061365183433081
278+
(2012 TC4) 2458028.486111111 ... 0.03913618624590608 -0.004062675762467314
279+
(2012 TC4) 2458028.493055556 ... 0.03910796987365932 -0.004063569840032833
280+
(2012 TC4) 2458028.5 ... 0.03907974874463358 -0.004064045454467904
285281
Length = 145 rows
286282

283+
287284
The following fields are queried:
288285

289-
>>> print(vec.columns)
286+
.. code-block:: python
287+
288+
>>> print(vec.columns) # doctest: +REMOTE_DATA
290289
<TableColumns names=('targetname','datetime_jd','datetime_str','H','G','x','y','z','vx','vy','vz','lighttime','range','range_rate')>
291290
292291
@@ -314,20 +313,21 @@ We provide some examples to illustrate how to use them based on the following
314313
JPL Horizons ephemerides query of near-Earth asteroid (3552) Don Quixote since
315314
its year of Discovery:
316315

317-
.. code-block:: python
316+
.. doctest-remote-data::
318317

319318
>>> from astroquery.jplhorizons import Horizons
320319
>>> obj = Horizons(id='3552', location='568',
321320
... epochs={'start':'2010-01-01', 'stop':'2019-12-31',
322321
... 'step':'1y'})
323322
>>> eph = obj.ephemerides()
324323

324+
325325
As we have seen before, we can display a truncated version of table
326326
``eph`` by simply using
327327

328328
.. code-block:: python
329329
330-
>>> print(eph)
330+
>>> print(eph) # doctest: +REMOTE_DATA
331331
targetname datetime_str ... PABLon PABLat
332332
--- --- ... deg deg
333333
-------------------------- ----------------- ... -------- --------
@@ -356,16 +356,17 @@ We can get at list of all the columns in this table with:
356356

357357
.. code-block:: python
358358
359-
>>> print(eph.columns)
359+
>>> print(eph.columns) # doctest: +REMOTE_DATA
360360
<TableColumns names=('targetname','datetime_str','datetime_jd','H','G','solar_presence','flags','RA','DEC','RA_app','DEC_app','RA_rate','DEC_rate','AZ','EL','AZ_rate','EL_rate','sat_X','sat_Y','sat_PANG','siderealtime','airmass','magextinct','V','surfbright','illumination','illum_defect','sat_sep','sat_vis','ang_width','PDObsLon','PDObsLat','PDSunLon','PDSunLat','SubSol_ang','SubSol_dist','NPole_ang','NPole_dist','EclLon','EclLat','r','r_rate','delta','delta_rate','lighttime','vel_sun','vel_obs','elong','elongFlag','alpha','lunar_elong','lunar_illum','sat_alpha','sunTargetPA','velocityPA','OrbPlaneAng','constellation','TDB-UT','ObsEclLon','ObsEclLat','NPole_RA','NPole_DEC','GlxLon','GlxLat','solartime','earth_lighttime','RA_3sigma','DEC_3sigma','SMAA_3sigma','SMIA_3sigma','Theta_3sigma','Area_3sigma','RSS_3sigma','r_3sigma','r_rate_3sigma','SBand_3sigma','XBand_3sigma','DoppDelay_3sigma','true_anom','hour_angle','alpha_true','PABLon','PABLat')>
361361
362+
362363
We can address each column individually by indexing it using its name as
363364
provided in this list. For instance, we can get all RAs for Don Quixote by using
364365

365366
.. code-block:: python
366367
367-
>>> print(eph['RA'])
368-
RA
368+
>>> print(eph['RA']) # doctest: +REMOTE_DATA
369+
RA
369370
deg
370371
---------
371372
345.50204
@@ -385,27 +386,28 @@ We can select several columns at a time, for instance RA and DEC for each epoch
385386

386387
.. code-block:: python
387388
388-
>>> print(eph['datetime_str', 'RA', 'DEC'])
389-
datetime_str RA DEC
390-
--- deg deg
391-
----------------- --------- --------
392-
2010-Jan-01 00:00 345.50204 13.43621
393-
2011-Jan-01 00:00 78.77158 61.48831
394-
2012-Jan-01 00:00 119.85659 54.21955
395-
2013-Jan-01 00:00 136.60021 45.82409
396-
2014-Jan-01 00:00 147.44947 37.79876
397-
2015-Jan-01 00:00 156.58967 29.23058
398-
2016-Jan-01 00:00 166.32129 18.48174
399-
2017-Jan-01 00:00 180.6992 1.20453
400-
2018-Jan-01 00:00 232.11974 -37.9554
401-
2019-Jan-01 00:00 16.1066 45.50296
389+
>>> print(eph['datetime_str', 'RA', 'DEC']) # doctest: +REMOTE_DATA
390+
datetime_str RA DEC
391+
--- deg deg
392+
----------------- --------- --------
393+
2010-Jan-01 00:00 345.50204 13.43621
394+
2011-Jan-01 00:00 78.77158 61.48831
395+
2012-Jan-01 00:00 119.85659 54.21955
396+
2013-Jan-01 00:00 136.60021 45.8241
397+
2014-Jan-01 00:00 147.44947 37.79876
398+
2015-Jan-01 00:00 156.58967 29.23058
399+
2016-Jan-01 00:00 166.32129 18.48174
400+
2017-Jan-01 00:00 180.6992 1.20453
401+
2018-Jan-01 00:00 232.11974 -37.9554
402+
2019-Jan-01 00:00 16.1066 45.50296
402403
403404
404405
We can use the same representation to do math with these columns. For instance,
405406
let's calculate the total rate of the object by summing 'RA_rate' and 'DEC_rate'
406407
in quadrature:
407408

408-
.. code-block:: python
409+
410+
.. doctest-remote-data::
409411

410412
>>> import numpy as np
411413
>>> print(np.sqrt(eph['RA_rate']**2 + eph['DEC_rate']**2))
@@ -418,7 +420,7 @@ in quadrature:
418420
14.775809055378625
419421
11.874886005626538
420422
7.183281978025435
421-
7.295600209387093
423+
7.295600636473737
422424
94.84824546372009
423425
23.952470898018017
424426

@@ -436,7 +438,7 @@ h`` - arcseconds per hour:
436438

437439
.. code-block:: python
438440
439-
>>> print(eph['RA_rate'])
441+
>>> print(eph['RA_rate']) # doctest: +REMOTE_DATA
440442
RA_rate
441443
arcsec / h
442444
----------
@@ -447,15 +449,15 @@ h`` - arcseconds per hour:
447449
-12.107
448450
-9.32616
449451
-5.80004
450-
3.115853
452+
3.115854
451453
85.22719
452454
19.02548
453455
454456
455457
The unit of this column can be easily converted to any other unit describing the
456458
same dimensions. For instance, we can turn ``RA_rate`` into ``arcsec / s``:
457459

458-
.. code-block:: python
460+
.. doctest-remote-data::
459461

460462
>>> eph['RA_rate'].convert_unit_to('arcsec/s')
461463
>>> print(eph['RA_rate'])
@@ -469,7 +471,7 @@ same dimensions. For instance, we can turn ``RA_rate`` into ``arcsec / s``:
469471
-0.0033630555555555553
470472
-0.0025905999999999998
471473
-0.0016111222222222222
472-
0.0008655147222222222
474+
0.0008655150000000001
473475
0.023674219444444443
474476
0.005284855555555556
475477

@@ -493,9 +495,10 @@ Horizons server can be obtained from the
493495
:class:`~astroquery.jplhorizons.HorizonsClass` object after a query has been
494496
performed (before the query only ``None`` would be returned):
495497

496-
>>> print(obj.uri)
498+
>>> print(obj.uri) # doctest: +REMOTE_DATA
497499
https://ssd.jpl.nasa.gov/api/horizons.api?format=text&EPHEM_TYPE=OBSERVER&QUANTITIES=%271%2C2%2C3%2C4%2C5%2C6%2C7%2C8%2C9%2C10%2C11%2C12%2C13%2C14%2C15%2C16%2C17%2C18%2C19%2C20%2C21%2C22%2C23%2C24%2C25%2C26%2C27%2C28%2C29%2C30%2C31%2C32%2C33%2C34%2C35%2C36%2C37%2C38%2C39%2C40%2C41%2C42%2C43%27&COMMAND=%223552%22&SOLAR_ELONG=%220%2C180%22&LHA_CUTOFF=0&CSV_FORMAT=YES&CAL_FORMAT=BOTH&ANG_FORMAT=DEG&APPARENT=AIRLESS&REF_SYSTEM=ICRF&EXTRA_PREC=NO&CENTER=%27568%27&START_TIME=%222010-01-01%22&STOP_TIME=%222019-12-31%22&STEP_SIZE=%221y%22&SKIP_DAYLT=NO
498500

501+
499502
If your query failed, it might be useful for you to put the URI into a web
500503
browser to get more information why it failed. Please note that ``uri`` is an
501504
attribute of :class:`~astroquery.jplhorizons.HorizonsClass` and not the results
@@ -558,7 +561,7 @@ astropy's `~astropy.coordinates`:
558561
For example, get the barycentric coordinates of Jupiter as an astropy
559562
`~astropy.coordinates.SkyCoord` object:
560563

561-
.. code-block:: python
564+
.. doctest-remote-data::
562565

563566
>>> from astropy.coordinates import SkyCoord
564567
>>> from astropy.time import Time
@@ -575,12 +578,10 @@ For example, get the barycentric coordinates of Jupiter as an astropy
575578

576579

577580

578-
579581
Acknowledgements
580582
================
581583

582-
This submodule makes use of the `JPL Horizons
583-
<https://ssd.jpl.nasa.gov/horizons/>`_ system.
584+
This submodule makes use of the `JPL Horizons <https://ssd.jpl.nasa.gov/horizons/>`_ system.
584585

585586
The development of this submodule is in part funded through NASA PDART Grant No.
586587
80NSSC18K0987 to the `sbpy project <http://sbpy.org>`_.

0 commit comments

Comments
 (0)