Revise id_type behavior in jplhorizons.

Rename 'majorbody' to '', in better alignment with the API.

Set default to `None`, but preserve the current behavior as a 'smallbody'.  In the future, replace this with ''.

Raise a deprecation warning if 'majorbody' or `None` are used.

Author: mkelley

CHANGES.rst

@@ -34,6 +34,16 @@ jplhorizons
   Included in this update, the default reference system is changed from
   J2000 to ICRF, following API documentation. [#2154]
 
+- Query `id_type` behavior and options are changing:
+  - `'majorbody'` has been renamed to `''` (empty string) to represent the
+    Horizons default behavior. The Horizons default to search major bodies
+    first, then fall back to a small body search.  Horizons does not have
+    a major body only search.
+  - The default behavior was `'smallbody'` but this will be changed to the
+    Horizons default in a future version.
+  - Deprecation warnings are raised if `id_type` is `'majorbody'` or
+    was not specified by the user.
+
 Infrastructure, Utility and Other Changes and Additions
 -------------------------------------------------------
 

astroquery/jplhorizons/core.py

@@ -12,6 +12,7 @@
 from astropy.table import Table, Column
 from astropy.io import ascii
 from astropy.time import Time
+from astropy.utils.exceptions import AstropyDeprecationWarning
 
 # 3. local imports - use relative imports
 # commonly required local imports shown below as example
@@ -35,7 +36,7 @@ class HorizonsClass(BaseQuery):
     TIMEOUT = conf.timeout
 
     def __init__(self, id=None, location=None, epochs=None,
-                 id_type='smallbody'):
+                 id_type=None):
         """Instantiate JPL query.
 
         Parameters
@@ -64,11 +65,19 @@ def __init__(self, id=None, location=None, epochs=None,
             element and vector queries. If no epochs are provided, the current
             time is used.
         id_type : str, optional
-            Identifier type, options: ``'smallbody'``, ``'majorbody'`` (planets
-            but also anything that is not a small body), ``'designation'``,
-            ``'name'``, ``'asteroid_name'``, ``'comet_name'``, ``'id'``
-            (Horizons id number), or ``'smallbody'`` (find the closest match
-            under any id_type), default: ``'smallbody'``
+            Controls Horizons's object selection for ``id``
+            [HORIZONSDOC_SELECTION]_ .  Options: ``'majorbody'`` (DEPRECATED,
+            use ``''``), ``'designation'`` (small body designation), ``'name'``
+            (asteroid or comet name), ``'asteroid_name'``, ``'comet_name'``,
+            ``'id'`` (Horizons ID number), ``'smallbody'`` (asteroid and comet
+            search), or ``''`` (empty string; first search search planets,
+            natural satellites, spacecraft, and special cases, then small
+            bodies).
+
+        References
+        ----------
+
+        .. [HORIZONSDOC_SELECTION] https://ssd.jpl.nasa.gov/?horizons_doc#selection (retrieved 2021 Sep 23).
 
 
         Examples
@@ -101,8 +110,18 @@ def __init__(self, id=None, location=None, epochs=None,
         self.epochs = epochs
 
         # check for id_type
-        if id_type not in ['smallbody', 'majorbody',
-                           'designation', 'name',
+        if id_type is None:
+            warnings.warn('id_type was not specified, defaulting to a '
+            '"smallbody" search.  This behavior is deprecated and will be '
+            'changed to "" (empty string / Horizons default) in the future.',
+            AstropyDeprecationWarning)
+            id_type = 'smallbody'
+        elif id_type == 'majorbody':
+            warnings.warn('id_type "majorbody" is deprecated and will be '
+            'removed.  For the equivalent search behavior, use "" (empty '
+            'string).', AstropyDeprecationWarning)
+            id_type = ''
+        if id_type not in ['', 'smallbody', 'designation', 'name',
                            'asteroid_name', 'comet_name', 'id']:
             raise ValueError('id_type ({:s}) not allowed'.format(id_type))
         self.id_type = id_type

astroquery/jplhorizons/tests/test_jplhorizons.py

@@ -6,9 +6,10 @@
 from collections import OrderedDict
 
 from numpy.ma import is_masked
-from ...utils.testing_tools import MockResponse
 from astropy.tests.helper import assert_quantity_allclose
+from astropy.utils.exceptions import AstropyDeprecationWarning
 
+from ...utils.testing_tools import MockResponse
 from ... import jplhorizons
 
 # files in data/ for different query types
@@ -218,3 +219,18 @@ def test_no_H(patch_request):
     """testing missing H value (also applies for G, M1, k1, M2, k2)"""
     res = jplhorizons.Horizons(id='1935 UZ').ephemerides()[0]
     assert 'H' not in res
+
+
+def test_id_type_deprecation():
+    """Test deprecation warnings based on issue 1742.
+
+    Remove when id_type behavior is changed.
+
+    https://github.com/astropy/astroquery/pull/1742
+
+    """
+    with pytest.warns(AstropyDeprecationWarning):
+        res = jplhorizons.Horizons(id='Ceres')
+
+    with pytest.warns(AstropyDeprecationWarning):
+        res = jplhorizons.Horizons(id='Ceres', id_type='majorbody')

astroquery/jplhorizons/tests/test_jplhorizons_remote.py

@@ -15,6 +15,7 @@ def test_ephemerides_query(self):
         # check values of Ceres for a given epoch
         # orbital uncertainty of Ceres is basically zero
         res = jplhorizons.Horizons(id='Ceres', location='500',
+                                   id_type='smallbody',
                                    epochs=2451544.5).ephemerides()[0]
 
         assert res['targetname'] == "1 Ceres (A801 AA)"
@@ -152,7 +153,7 @@ def test_ephemerides_query_five(self):
 
     def test_ephemerides_query_six(self):
         # tests optional constrains for ephemerides queries
-        obj = jplhorizons.Horizons(id='3552',
+        obj = jplhorizons.Horizons(id='3552', id_type='smallbody',
                                    location='I33',
                                    epochs={'start': '2018-05-01',
                                            'stop': '2018-08-01',
@@ -169,13 +170,14 @@ def test_ephemerides_query_six(self):
 
     def test_ephemerides_query_raw(self):
         res = (jplhorizons.Horizons(id='Ceres', location='500',
-                                    epochs=2451544.5).
+                                    id_type='smallbody', epochs=2451544.5).
                ephemerides(get_raw_response=True))
 
         assert len(res) >= 15400
 
     def test_elements_query(self):
         res = jplhorizons.Horizons(id='Ceres', location='500@10',
+                                   id_type='smallbody',
                                    epochs=[2451544.5,
                                            2451545.5]).elements()[0]
 
@@ -204,6 +206,7 @@ def test_elements_query(self):
 
     def test_elements_query_two(self):
         obj = jplhorizons.Horizons(id='Ceres', location='500@10',
+                                   id_type='smallbody',
                                    epochs=[2451544.5,
                                            2451545.5])
 
@@ -219,6 +222,7 @@ def test_elements_query_two(self):
 
     def test_elements_query_raw(self):
         res = jplhorizons.Horizons(id='Ceres', location='500@10',
+                                   id_type='smallbody',
                                    epochs=2451544.5).elements(
                                        get_raw_response=True)
 
@@ -228,6 +232,7 @@ def test_vectors_query(self):
         # check values of Ceres for a given epoch
         # orbital uncertainty of Ceres is basically zero
         res = jplhorizons.Horizons(id='Ceres', location='500@10',
+                                   id_type='smallbody',
                                    epochs=2451544.5).vectors()[0]
 
         assert res['targetname'] == "1 Ceres (A801 AA)"
@@ -251,6 +256,7 @@ def test_vectors_query(self):
 
     def test_vectors_query_raw(self):
         res = jplhorizons.Horizons(id='Ceres', location='500@10',
+                                   id_type='smallbody',
                                    epochs=2451544.5).vectors(
                                        get_raw_response=True)
 
@@ -259,20 +265,20 @@ def test_vectors_query_raw(self):
     def test_unknownobject(self):
         try:
             jplhorizons.Horizons(id='spamspamspameggsspam', location='500',
-                                 epochs=2451544.5).ephemerides()
+                                 id_type='', epochs=2451544.5).ephemerides()
         except ValueError:
             pass
 
     def test_multipleobjects(self):
         try:
-            jplhorizons.Horizons(id='73P', location='500',
+            jplhorizons.Horizons(id='73P', location='500', id_type='smallbody',
                                  epochs=2451544.5).ephemerides()
         except ValueError:
             pass
 
     def test_uri(self):
         target = jplhorizons.Horizons(id='3552', location='500',
-                                      epochs=2451544.5)
+                                      id_type='smallbody', epochs=2451544.5)
         assert target.uri is None
 
         target.ephemerides()
@@ -299,10 +305,12 @@ def test__userdefinedlocation_ephemerides_query(self):
 
         am_res = jplhorizons.Horizons(id='Ceres',
                                       location='688',
+                                      id_type='smallbody',
                                       epochs=2451544.5).ephemerides()[0]
 
         user_res = jplhorizons.Horizons(id='Ceres',
                                         location=anderson_mesa,
+                                        id_type='smallbody',
                                         epochs=2451544.5).ephemerides()[0]
 
         assert_quantity_allclose([am_res['RA'], am_res['DEC']],
@@ -321,7 +329,8 @@ def test_majorbody(self):
         quantities = ('1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,'
                       '21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,'
                       '38,39,40,41,42,43')
-        target = jplhorizons.Horizons(id='301', location='688', epochs=epochs)
+        target = jplhorizons.Horizons(id='301', location='688', epochs=epochs,
+                                      id_type='')
         eph = target.ephemerides(quantities=quantities)
         assert len(eph) == 2
 
@@ -342,6 +351,7 @@ def test_airmass(self):
 
         # verify data['a-mass'].filled(99) works:
         target = jplhorizons.Horizons('Ceres', location='I41',
+                                      id_type='smallbody',
                                       epochs=[2458300.5])
         eph = target.ephemerides(quantities='1,8')
         assert len(eph) == 1
@@ -352,7 +362,8 @@ def test_airmass(self):
 
     def test_vectors_aberrations(self):
         """Check functionality of `aberrations` options"""
-        obj = jplhorizons.Horizons(id='1', epochs=2458500, location='500@0')
+        obj = jplhorizons.Horizons(id='1', epochs=2458500, location='500@0',
+                                   id_type='smallbody')
 
         vec = obj.vectors(aberrations='geometric')
         assert_quantity_allclose(vec['x'][0], -2.086487005013347)
@@ -364,7 +375,8 @@ def test_vectors_aberrations(self):
         assert_quantity_allclose(vec['x'][0], -2.086576286974797)
 
     def test_vectors_delta_T(self):
-        obj = jplhorizons.Horizons(id='1', epochs=2458500, location='500@0')
+        obj = jplhorizons.Horizons(id='1', epochs=2458500, location='500@0',
+                                   id_type='smallbody')
 
         vec = obj.vectors(delta_T=False)
         assert 'delta_T' not in vec.columns
@@ -373,7 +385,8 @@ def test_vectors_delta_T(self):
         assert_quantity_allclose(vec['delta_T'][0], 69.184373)
 
     def test_ephemerides_extraprecision(self):
-        obj = jplhorizons.Horizons(id='1', epochs=2458500, location='G37')
+        obj = jplhorizons.Horizons(id='1', epochs=2458500, location='G37',
+                                   id_type='smallbody')
 
         vec_simple = obj.ephemerides(extra_precision=False)
         vec_highprec = obj.ephemerides(extra_precision=True)