Merge pull request #337 from mkelley/data-doc-updates-2022.05

Documentation enhancements

docs/index.rst

@@ -59,10 +59,12 @@ Data Structures: Orbits, Ephemerides, Observations, and Physical Properties
 ---------------------------------------------------------------------------
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
+   :glob:
 
    sbpy/data/index.rst
    sbpy/data/fieldnames.rst
+   sbpy/data/*
 
 Photometry and Spectroscopy
 ---------------------------

docs/sbpy/data/dataclass.rst

@@ -1,8 +1,8 @@
 .. _data containers:
 
-===============
-Data Containers
-===============
+=======================================
+Data Containers (`sbpy.data.DataClass`)
+=======================================
 
 `sbpy` relies heavily on the use of `~sbpy.data.DataClass` data
 containers that are used to encapsulate data and to propagate them

docs/sbpy/data/fieldnames.rst

@@ -1,8 +1,9 @@
 
 .. _field name list:
 
-sbpy Field Names
-================
+===================================
+Data Container Field Name Reference
+===================================
 
 The following table lists field names that are recognized by `sbpy`
 when accessing `~sbpy.data.DataClass` objects, i.e.,

docs/sbpy/data/index.rst

@@ -26,11 +26,11 @@ Content
 .. toctree::
    :maxdepth: 2
 
-   dataclass.rst	     
+   dataclass.rst
    ephem.rst
    obs.rst
    orbit.rst
-   phys.rst	      
+   phys.rst
    names.rst
 
 

docs/sbpy/data/names.rst

@@ -1,13 +1,17 @@
-=============
- Using Names
-=============
+===========================================
+Small-Body Name Parsing (`sbpy.data.Names`)
+===========================================
 
 `~sbpy.data.Names` is different from the other classes in `~sbpy.data`
 in that it does not use `~sbpy.data.DataClass` as a base class. Instead,
 `~sbpy.data.Names` does not contain any data, it merely serves as an
 umbrella for functions to identify asteroid and comet names, numbers,
 and designations.
 
+
+Cometary and Asteroidal Name Parsing
+------------------------------------
+
 In order to distinguish if a string designates a comet or an asteroid,
 you can use the following code:
 
@@ -22,23 +26,59 @@ strings and find patterns that agree with asteroid and comet names,
 numbers, and designations. There are separate tasks to identify
 asteroid and comet identifiers:
 
-    >>> Names.parse_asteroid('(228195) 6675 P-L') # doctest: +SKIP
+    >>> Names.parse_asteroid('(228195) 6675 P-L')
     {'number': 228195, 'desig': '6675 P-L'}
-    >>> Names.parse_asteroid('C/2001 A2-A (LINEAR)') # doctest: +SKIP
-    ... sbpy.data.names.TargetNameParseError: C/2001 A2-A (LINEAR) does not appear to be an asteroid identifier
-    >>> Names.parse_comet('12893') # doctest: +SKIP
-    ... sbpy.data.names.TargetNameParseError: 12893 does not appear to be a comet name
-    >>> Names.parse_comet('73P-C/Schwassmann Wachmann 3 C') # doctest: +SKIP
+    >>> Names.parse_comet('73P-C/Schwassmann Wachmann 3 C')
     {'type': 'P', 'number': 73, 'fragment': 'C', 'name': 'Schwassmann Wachmann 3 C'}
 
-In order to be able to distinguish between asteroid and comet
-identifiers, `sbpy` follows the MPC guideline in that it requires
-comet identifiers to include the comet type in either in combination
-with a number (e.g., ``'259P'``), a name (e.g., ``'P/Halley'``), or
-both (e.g., ``'2P/Encke'``). For instance, the identifier ``'Halley'``
-would be identified as an asteroid, as it lacks a comet type
-identifier. Hence, some caution is advised when using these routines -
-identification might not be unambiguous.
+These methods will raise exceptions when the name cannot be parsed as expected:
+
+    >>> Names.parse_asteroid('C/2001 A2-A (LINEAR)')
+    Traceback (most recent call last):
+    ...
+    sbpy.data.names.TargetNameParseError: C/2001 A2-A (LINEAR) does not appear to be an asteroid identifier
+    >>> Names.parse_comet('12893')
+    Traceback (most recent call last):
+    ...
+    sbpy.data.names.TargetNameParseError: 12893 does not appear to be a comet name
+
+In order to be able to distinguish between asteroid and comet identifiers,
+`sbpy` follows the MPC guideline in that it requires comet identifiers to
+include the comet type in either in combination with a number (e.g.,
+``'259P'``), a name (e.g., ``'P/Halley'``), or both (e.g., ``'2P/Encke'``). For
+instance, the identifier ``'Halley'`` would be identified as an asteroid, as it
+lacks a comet type identifier. Hence, some caution is advised when using these
+routines - identification might not be unambiguous.
+
+
+A/ objects: asteroids in cometary orbits
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Small bodies designated with an A/ prefix have cometary orbits, but appear
+asteroidal [MPEC2018H54]_.  ``sbpy`` considers them to be asteroids:
+
+    >>> Names.asteroid_or_comet('A/2018 V3')
+    'asteroid'
+
+
+Interstellar objects
+^^^^^^^^^^^^^^^^^^^^
+
+Interstellar object designations, which start with an I/, do not
+give any insight into the nature of the object.  For example, 1I/ʻOumuamua was
+asteroidal in appearance but 2I/Borisov was cometary.  ``sbpy`` raises an
+exception for I/ objects:
+
+    >>> Names.asteroid_or_comet('1I/ʻOumuamua')
+    Traceback (most recent call last):
+      File "<stdin>", line 1, in <module>
+      File "/disks/data0/astro/Projects/sbpy/sbpy/data/names.py", line 597, in asteroid_or_comet
+        raise TargetNameParseError('Target nature unclear.')
+    sbpy.data.names.TargetNameParseError: Target nature unclear.
+
+
+.. [MPEC2018H54] Williams, G. V. 2018.  A/ Objects.  MPEC 2018-H54.  https://minorplanetcenter.net/mpec/K18/K18H54.html
+
 
 Sorting names with a natural sort order
 ---------------------------------------
@@ -62,6 +102,7 @@ comparisons are made whenever possible:
     >>> sorted(comets, key=natural_sort_key)
     ['2P/Encke', '9P/Tempel 1', '10P/Tempel 2', '101P/Chernykh']
 
+
 Packed Numbers and Designations
 -------------------------------
 

docs/sbpy/data/obs.rst

@@ -1,12 +1,12 @@
-===========
- Using Obs
-===========
+============================================
+Observational Data Objects (`sbpy.data.Obs`)
+============================================
 
 `~sbpy.data.Obs` objects mostly share their functionality with
 `~sbpy.data.Ephem`, but there are some unique features tailored to observational data.
 
-For instance, this class allows you to query observations reported to
-the Minor Planet Center for a given target:
+For instance, this class allows you to query observations reported to the Minor
+Planet Center for a given target via `astroquery.mpc.MPCClass.get_observations`:
 
     >>> from sbpy.data import Obs
     >>> data = Obs.from_mpc('2019 AA', id_type='asteroid designation') # doctest: +REMOTE_DATA

docs/sbpy/data/orbit.rst

@@ -1,6 +1,6 @@
-=============
- Using Orbit
-=============
+======================================
+Orbit Data Objects (`sbpy.data.Orbit`)
+======================================
 
 Orbit Queries
 =============

docs/sbpy/data/phys.rst

@@ -1,6 +1,6 @@
-============
- Using Phys
-============
+========================================
+Physical Data Objects (`sbpy.data.Phys`)
+========================================
 
 `~sbpy.data.Phys` is designed to contain and query physical properties for
 small bodies; functions to query these properties are
@@ -17,13 +17,13 @@ small number of asteroids:
     >>> phys = Phys.from_sbdb(['Ceres', '12893', '3552'])  # doctest: +REMOTE_DATA
     >>> phys['targetname', 'H', 'diameter'] # doctest: +SKIP
     <QTable length=3>
-	    targetname            H    diameter
-					  km
-	      str26            float64 float64
+            targetname            H    diameter
+                                 mag      km   
+              str26            float64 float64 
     -------------------------- ------- --------
-		       1 Ceres    3.34    939.4
-     12893 Mommert (1998 QS55)    13.9    5.214
-    3552 Don Quixote (1983 SA)    12.9     19.0
+             1 Ceres (A801 AA)    3.56    939.4
+     12893 Mommert (1998 QS55)   13.98    5.214
+    3552 Don Quixote (1983 SA)   12.96     19.0
 
 
 Please note that the SBDB database is not complete with respect to