Add more test docstrings and other doc fixes

docs/index.rst

@@ -191,7 +191,7 @@ Required data files are:
 
 ::
 
-  $SKA/data/agasc/miniagasc.h5
+  $SKA/data/agasc/proseco_agasc_1p7.h5
   $SKA/data/mica/archive/aca_dark/<YYYYddd>/image.fits
   $SKA/data/mica/archive/aca_dark/<YYYYddd>/properties.json
 

proseco/core.py

@@ -1132,16 +1132,16 @@ def add_agasc_id(self, agasc_id):
 
     def add_fake_constellation(self, n_stars=8, size=1500, mag=7.0, **attrs):
         """
-        Add a fake constellation of up to 8 stars consisting of a cross and square
+        Add a fake constellation of up to 8 stars consisting of a cross and square::
 
                 *
               *   *
             *       *
               *   *
                 *
 
-        yangs = [1,  0, -1,  0, 0.5,  0.5, -0.5, -0.5] * size
-        zangs = [0,  1,  0, -1, 0.5, -0.5,  0.5, -0.5] * size
+          yangs = [1,  0, -1,  0, 0.5,  0.5, -0.5, -0.5] * size
+          zangs = [0,  1,  0, -1, 0.5, -0.5,  0.5, -0.5] * size
 
         Additional star table attributes can be specified as keyword args.  All
         attributes are broadcast as needed.
@@ -1163,7 +1163,7 @@ def add_fake_constellation(self, n_stars=8, size=1500, mag=7.0, **attrs):
         :param n_stars: number of stars (default=8, max=8)
         :param size: size of constellation [arcsec] (default=2000)
         :param mag: star magnitudes (default=7.0)
-        :param **attrs: other star table attributes
+        :param \**attrs: other star table attributes
         """
         if n_stars > 8:
             raise ValueError('max value of n_stars is 8')
@@ -1196,7 +1196,7 @@ def add_fake_star(self, **star):
         primary inputs unless explicitly provided.  All the rest will be set
         to default "good"" values that will preclude initial exclusion of the star.
 
-        :param **star: keyword arg attributes corresponding to StarTable columns
+        :param \**star: keyword arg attributes corresponding to StarTable columns
         """
         names = ['id', 'ra', 'dec', 'yang', 'zang', 'row', 'col', 'mag', 'mag_err',
                  'POS_ERR', 'PM_RA', 'PM_DEC', 'MAG_ACA',

proseco/tests/test_acq.py

@@ -82,22 +82,26 @@ def add_spoiler(stars, acq, dyang, dzang, dmag, mag_err=0.05):
 
 
 def test_get_p_man_err():
-    # P_man_errs is a table that defines the probability of a maneuver error being
-    # within a defined lo/hi bin [arcsec] given a maneuver angle [deg] within a
-    # bin range.  The first two columns specify the maneuver error bins and the
-    # subsequent column names give the maneuver angle bin in the format
-    # <angle_lo>-<angle_hi>.  The source table does not include the row for
-    # the 0-60 man err case: this is generated automatically from the other
-    # values so the sum is 1.0.
-    #
-    # man_err_lo man_err_hi 0-5 5-20 20-40 40-60 60-80 80-100 100-120 120-180
-    # ---------- ---------- --- ---- ----- ----- ----- ------ ------- -------
-    #         60         80 0.0  0.2   0.5   0.6   1.6    4.0     8.0     8.0
-    #         80        100 0.0  0.1   0.2   0.3   0.5    1.2     2.4     2.4
-    #        100        120 0.0  0.0   0.1   0.2   0.3    0.8     0.8     0.8
-    #        120        140 0.0  0.0  0.05  0.05   0.2    0.4     0.4     0.4
-    #        140        160 0.0  0.0  0.05  0.05   0.2    0.2     0.2     0.4
+    """Test the get_p_man_err function.
+
+    P_man_errs is a table that defines the probability of a maneuver error being
+    within a defined lo/hi bin [arcsec] given a maneuver angle [deg] within a
+    bin range.  The first two columns specify the maneuver error bins and the
+    subsequent column names give the maneuver angle bin in the format
+    <angle_lo>-<angle_hi>.  The source table does not include the row for
+    the 0-60 man err case: this is generated automatically from the other
+    values so the sum is 1.0.
+    ::
+
+       man_err_lo man_err_hi 0-5 5-20 20-40 40-60 60-80 80-100 100-120 120-180
+       ---------- ---------- --- ---- ----- ----- ----- ------ ------- -------
+               60         80 0.0  0.2   0.5   0.6   1.6    4.0     8.0     8.0
+               80        100 0.0  0.1   0.2   0.3   0.5    1.2     2.4     2.4
+              100        120 0.0  0.0   0.1   0.2   0.3    0.8     0.8     0.8
+              120        140 0.0  0.0  0.05  0.05   0.2    0.4     0.4     0.4
+              140        160 0.0  0.0  0.05  0.05   0.2    0.2     0.2     0.4
 
+    """
     assert get_p_man_err(man_err=30, man_angle=0) == 1.0
     assert get_p_man_err(60, 0) == 1.0  # Exactly 60 is in 0-60 bin
     assert get_p_man_err(60.00001, 0) == 0.0  # Just over 60 in 60-80 bin
@@ -110,12 +114,14 @@ def test_get_p_man_err():
 
 
 def test_bin2x2():
+    """Test the bin2x2 function"""
     arr = bin2x2(np.arange(16).reshape(4, 4))
     assert arr.shape == (2, 2)
     assert np.all(arr == [[10, 18], [42, 50]])
 
 
 def test_get_image_props():
+    """Test the get_image_props function"""
     c_row = 10
     c_col = 20
     bgd = 40
@@ -131,6 +137,7 @@ def test_get_image_props():
 
 
 def setup_get_imposter_stars(val):
+    """Setup for testing with the get_imposter_stars function."""
     bgd = 40
     dark = np.full((100, 100), fill_value=bgd, dtype=float)
     box_size = ACABox(6 * 5)
@@ -144,7 +151,7 @@ def setup_get_imposter_stars(val):
 
 def test_get_imposters_3500():
     """
-    Three nearby hits don't make the cut
+    Test three nearby hits that don't make the cut.
     """
     imposters = setup_get_imposter_stars(3500)
     assert len(imposters) == 1
@@ -157,6 +164,9 @@ def test_get_imposters_3500():
 
 
 def test_get_imposters_5000():
+    """
+    Test get_imposters with an imposter of 5000.
+    """
     imposters = setup_get_imposter_stars(5000)
     assert len(imposters) == 2
     imp = imposters[1]
@@ -421,11 +431,14 @@ def test_get_acq_catalog_19387():
 
 def test_get_acq_catalog_21007():
     """Put it all together.  Regression test for selected stars.
-    From ipython:
-    >>> from proseco.acq import AcqTable
-    >>> acqs = get_acq_catalog(21007)
-    >>> TEST_COLS = ('idx', 'slot', 'id', 'yang', 'zang', 'halfw')
-    >>> repr(acqs.cand_acqs[TEST_COLS]).splitlines()
+
+    From ipython::
+
+      >>> from proseco.acq import AcqTable
+      >>> acqs = get_acq_catalog(21007)
+      >>> TEST_COLS = ('idx', 'slot', 'id', 'yang', 'zang', 'halfw')
+      >>> repr(acqs.cand_acqs[TEST_COLS]).splitlines()
+
     """
     acqs = get_acq_catalog(**OBS_INFO[21007])
 
@@ -468,7 +481,9 @@ def test_get_acq_catalog_21007():
 
 def test_box_strategy_20603():
     """Test for PR #32 that doesn't allow p_acq to be reduced below 0.1.
+
     The idx=8 (mag=10.50) star was previously selected with 160 arsec box.
+
     """
     acqs = get_acq_catalog(**OBS_INFO[20603])
 
@@ -509,9 +524,11 @@ def test_box_strategy_20603():
 
 
 def test_make_report(tmpdir):
-    """
-    Test making an acquisition report.  Use a big-box dither here
-    to test handling of that in report (after passing through pickle).
+    """Test making an acquisition report.
+
+    Use a big-box dither here to test handling of that in report (after passing
+    through pickle).
+
     """
     obsid = 19387
     kwargs = OBS_INFO[obsid].copy()
@@ -546,8 +563,10 @@ def test_make_report(tmpdir):
 
 
 def test_cand_acqs_include_exclude():
-    """
-    Test include and exclude stars.  This uses a catalog with 11 stars:
+    """Test include and exclude stars.
+
+    This uses a catalog with 11 stars:
+
     - 8 bright stars from 7.0 to 7.7 mag, where the 7.0 is EXCLUDED
     - 2 faint (but OK) stars 10.0, 10.1 where the 10.0 is INCLUDED
     - 1 very faint (bad) stars 12.0 mag is INCLUDED
@@ -559,6 +578,7 @@ def test_cand_acqs_include_exclude():
     Finally, starting from the catalog chosen with the include/exclude
     constraints applied, remove those constraints and re-optimize.
     This must come back to the original catalog of the 8 bright stars.
+
     """
     stars = StarsTable.empty()
 

proseco/tests/test_core.py

@@ -205,6 +205,9 @@ def test_calc_spoiler_impact_21068():
 
 
 def test_mag_err_clip():
+    """
+    Test clipping magnitudes
+    """
     # Clipping case for star
     s1 = StarsTable.from_agasc_ids(att=[6.88641501, 16.8899464, 0],
                                    agasc_ids=[154667024])

proseco/tests/test_fid.py

@@ -45,7 +45,7 @@ def test_get_fid_position():
 
 
 def test_get_initial_catalog():
-    # Basic catalog with no stars in field.  Standard 2-4-5 config.
+    """Test basic catalog with no stars in field using standard 2-4-5 config."""
     exp = ['<FidTable length=6>',
            '  id    yang     zang     row     col     mag   spoiler_score  idx   slot',
            'int64 float64  float64  float64 float64 float64     int64     int64 int64',
@@ -104,8 +104,10 @@ def test_n_fid():
 
 @pytest.mark.parametrize('dither_z', [8, 64])
 def test_fid_spoiling_acq(dither_z):
-    """
+    """Test fid spoiling acq.
+
     Check fid spoiling acq:
+
     - 20" (4 pix) positional err on fid light
     - 4 pixel readout halfw for fid light
     - 2 pixel PSF of fid light that could creep into search box
@@ -117,6 +119,7 @@ def test_fid_spoiling_acq(dither_z):
     positions of ACIS-S 2, 4, 5 but offset by 82, 149 and 151 arcsec + dither.
     Only ACIS-S-5 is allowed, so we end up with the first fid set using
     1, 3, 5, 6, which is 1, 5, 6.
+
     """
     dither_y = 8
     stars = StarsTable.empty()
@@ -172,6 +175,7 @@ def test_dither_as_sequence():
 
 
 def test_fid_spoiler_score():
+    """Test computing the fid spoiler score."""
     dither_y = 8
     dither_z = 64
     stars = StarsTable.empty()
@@ -189,12 +193,14 @@ def test_fid_spoiler_score():
 
 
 def test_big_sim_offset():
+    """Test of an observation with a big SIM offset"""
     fids = get_fid_catalog(**mod_std_info(stars=StarsTable.empty(), sim_offset=300000))
     names = ['id', 'yang', 'zang', 'row', 'col', 'mag', 'spoiler_score', 'idx']
     assert all(name in fids.colnames for name in names)
 
 
 def test_fid_hot_pixel_reject():
+    """Test hot pixel rejecting a fid"""
     lim = FID.hot_pixel_spoiler_limit
     dark = DARK40.copy()
     for fid_id, off, dc in [(1, 8.0, lim * 1.05),  # spoiler,

proseco/tests/test_guide.py

@@ -61,6 +61,9 @@ def test_common_column_obsid_19904():
 
 
 def test_box_mag_spoiler():
+    """
+    Test spoiling.
+    """
     # Manipulate a spoiler star in this test to first not be a spoiler
     att = (0, 0, 0)
     agasc_ids = [688522000, 688523960, 611190016, 139192, 688522008]
@@ -85,6 +88,9 @@ def test_box_mag_spoiler():
 
 
 def test_region_contrib():
+    """
+    Regression test of stars rejected by contributing starlight to readout region.
+    """
     att = (8, 47, 0)
     date = '2018:001'
     agasc_ids = [425740488, 425864552, 426263240, 425736928, 426255616, 426253528, 426253768]
@@ -149,13 +155,19 @@ def test_avoid_trap():
 
 @pytest.mark.skipif('not HAS_SC_ARCHIVE', reason='Test requires starcheck archive')
 def test_big_dither():
+    """
+    Regression test of a catalog with big dither.
+    """
     # Obsid 20168
     selected = get_guide_catalog(obsid=20168, n_guide=5)
     expected = [977409032, 977930352, 977414712, 977416336, 977405808]
     assert selected['id'].tolist() == expected
 
 
 def test_check_pixmag_offset():
+    """
+    Test the check_pixmag_offset function.
+    """
     APL = AcaPsfLibrary()
 
     # Then use one star and test with various pixels
@@ -330,6 +342,7 @@ def test_guides_include_exclude():
 
 dither_cases = [(8, 8), (64, 8), (8, 64), (20, 20), (30, 20)]
 
+
 def test_guides_include_bad():
     """
     Test include stars for guide where star is bad for some reason.
@@ -366,6 +379,7 @@ def test_guides_include_bad():
         get_guide_catalog(**STD_INFO, stars=stars, include_ids=20)
     assert 'cannot include star id=20' in str(err)
 
+
 @pytest.mark.parametrize('dither', dither_cases)
 def test_edge_star(dither):
     """