Improve documentation in response to PR comments.

Document 'outputPrefix'.
Relabeled docstring 'Inputs'->'Parameters'.

Updated README to note that the requirement is `pipe_base` not `pipe_tasks`.

Whitespace fixes.

README.md

@@ -4,7 +4,7 @@ and validate the astrometric and photometric repeatability of the results.
 
 Pre-requisites: install and declare the following
 
-1. `pipe_tasks` from the LSST DM stack (note that pipe_tasks is included with lsst_apps, which is the usual thing to install)
+1. `pipe_base` from the LSST DM stack (note that `pipe_base` is included with `lsst_apps`, which is the usual thing to install)
 2. `obs_decam` from https://github.com/lsst/obs_decam
 3. `obs_cfht` from https://github.com/lsst/obs_cfht
 4. `validation_data_cfht` from https://github.com/lsst/validation_data_cfht

python/lsst/validate/drp/base.py

@@ -1,5 +1,3 @@
-#!/usr/bin/env python
-
 # LSST Data Management System
 # Copyright 2008-2016 AURA/LSST.
 #
@@ -27,6 +25,12 @@ class ValidateError(Exception):
     """Base classes for exceptions in validate_drp."""
     pass
 
+
 class ValidateErrorNoStars(ValidateError):
-    """Base classes for exceptions in validate_drp."""
+    """To be returned by tests that find no stars satisfying a set of criteria.
+
+    Some example cases that might return such an error:
+    1. There are no stars between 19-21 arcmin apart.
+    2. There are no stars in the given magnitude range.
+    """
     pass

python/lsst/validate/drp/calcSrd.py

@@ -1,5 +1,3 @@
-#!/usr/bin/env python
-
 # LSST Data Management System
 # Copyright 2008-2016 AURA/LSST.
 #
@@ -372,8 +370,8 @@ def matchVisitComputeDistance(visit_obj1, ra_obj1, dec_obj1,
     For each visit shared between visit_obj1 and visit_obj2,
     calculate the spherical distance between the obj1 and obj2.
 
-    Inputs
-    ------
+    Parameters
+    ----------
     visit_obj1 : scalar, list, or numpy.array of int or str
         List of visits for object 1.
     ra_obj1 : scalar, list, or numpy.array of float
@@ -455,7 +453,7 @@ def calcAMx(groupView, D=5, width=2, magRange=None,
 
     Raises
     ------
-    ValidateError if `x` isn't in `getAstrometricSpec` values of [1,2,3]
+    ValueError if `x` isn't in `getAstrometricSpec` values of [1,2,3]
 
     Notes
     -----

python/lsst/validate/drp/check.py

@@ -1,5 +1,3 @@
-#!/usr/bin/env python
-
 # LSST Data Management System
 # Copyright 2008-2016 AURA/LSST.
 #
@@ -32,8 +30,8 @@
 def isExtended(source, extendedKey, extendedThreshold=1.0):
     """Is the source extended attribute above the threshold.
 
-    Inputs
-    ------
+    Parameters
+    ----------
     cat : collection with a .get method
         for `extendedKey`
     extendedKey
@@ -49,8 +47,8 @@ def magNormDiff(cat):
     """Calculate the normalized mag/mag_err difference from the mean for a
     set of observations of an objection.
 
-    Inputs
-    ------
+    Parameters
+    ----------
     cat : collection with a .get method
          for flux, flux+"-"
 
@@ -70,8 +68,8 @@ def magNormDiff(cat):
 def positionRms(cat):
     """Calculate the RMS for RA, Dec for a set of observations an object.
 
-    Inputs
-    ------
+    Parameters
+    ----------
     cat -- collection with a .get method
          for 'coord_ra', 'coord_dec' that returns radians.
 
@@ -98,8 +96,8 @@ def checkAstrometry(mag, mmagrms, dist, match,
                     medianRef=100, matchRef=500):
     """Print out the astrometric scatter for all stars, and for good stars.
 
-    Inputs
-    ------
+    Parameters
+    ----------
     mag : list or numpy.array
         Average magnitudes of each star
     mmagrms ; list or numpy.array
@@ -150,8 +148,8 @@ def checkPhotometry(mag, mmagrms, dist, match,
                     medianRef=100, matchRef=500):
     """Print out the astrometric scatter for all stars, and for good stars.
 
-    Inputs
-    ------
+    Parameters
+    ----------
     mag : list or numpy.array
         Average magnitudes of each star
     mmagrms ; list or numpy.array

python/lsst/validate/drp/io.py

@@ -1,5 +1,3 @@
-#!/usr/bin/env python
-
 # LSST Data Management System
 # Copyright 2008-2016 AURA/LSST.
 #
@@ -25,11 +23,12 @@
 import json
 import numpy as np
 
+
 def saveKpmToJson(KpmStruct, filename):
-    """Save Kpm `lsst.pipe.base.Struct` to JSON file.
+    """Save KPM `lsst.pipe.base.Struct` to JSON file.
 
-    Inputs
-    ------
+    Parameters
+    ----------
     KpmStruct : lsst.pipe.base.Struct
         Information to serialize in JSON.
     filename : str
@@ -39,7 +38,7 @@ def saveKpmToJson(KpmStruct, filename):
     --------
     >>> foo = {'a': b}
     >>> outfile = 'tmp.json'
-    >>> saveKpmToJson(bar, outfile)
+    >>> saveKpmToJson(foo, outfile)
 
     Notes
     -----

python/lsst/validate/drp/plot.py

@@ -1,5 +1,3 @@
-#!/usr/bin/env python
-
 # LSST Data Management System
 # Copyright 2008-2016 AURA/LSST.
 #
@@ -51,11 +49,13 @@ def plotOutlinedLines(ax, x1, x2, x1_color=color['all'], x2_color=color['bright'
 
 
 def plotAstrometry(mag, mmagerr, mmagrms, dist, match, good_mag_limit=19.5,
-                   plotBase=""):
+                   outputPrefix=""):
     """Plot angular distance between matched sources from different exposures.
 
-    Inputs
-    ------
+    Creates a file containing the plot with a filename beginning with `outputPrefix`.
+
+    Parameters
+    ----------
     mag : list or numpy.array
         Average Magnitude
     mmagerr : list or numpy.array
@@ -66,6 +66,12 @@ def plotAstrometry(mag, mmagerr, mmagrms, dist, match, good_mag_limit=19.5,
         Separation from reference [mas]
     match : int
         Number of stars matched.
+    good_mag_limit : float, optional
+        Minimum average brightness (in magnitudes) for a star to be considered.
+    outputPrefix : str, optional
+        Prefix to use for filename of plot file.  Will also be used in plot titles.
+        E.g., outputPrefix='Cfht_output_r_' will result in a file named
+           'Cfht_output_r_check_astrometry.png'
     """
 
     bright, = np.where(np.asarray(mag) < good_mag_limit)
@@ -100,8 +106,8 @@ def plotAstrometry(mag, mmagerr, mmagrms, dist, match, good_mag_limit=19.5,
     ax[1].legend(loc='upper left')
     plotOutlinedLines(ax[1], dist_median, bright_dist_median)
 
-    plt.suptitle("Astrometry Check : %s" % plotBase.rstrip('_'), fontsize=30)
-    plotPath = plotBase+"check_astrometry.png"
+    plt.suptitle("Astrometry Check : %s" % outputPrefix.rstrip('_'), fontsize=30)
+    plotPath = outputPrefix+"check_astrometry.png"
     plt.savefig(plotPath, format="png")
 
 
@@ -144,11 +150,11 @@ def plotMagerrFit(*args, **kwargs):
 
 
 def plotPhotometry(mag, mmagerr, mmagrms, dist, match, good_mag_limit=19.5,
-                   plotBase=""):
+                   outputPrefix=""):
     """Plot photometric RMS for matched sources.
 
-    Inputs
-    ------
+    Parameters
+    ----------
     mag : list or numpy.array
         Average Magnitude
     mmagerr : list or numpy.array
@@ -159,6 +165,10 @@ def plotPhotometry(mag, mmagerr, mmagrms, dist, match, good_mag_limit=19.5,
         Separation from reference [mas]
     match : int
         Number of stars matched.
+    outputPrefix : str, optional
+        Prefix to use for filename of plot file.  Will also be used in plot titles.
+        E.g., outputPrefix='Cfht_output_r_' will result in a file named
+           'Cfht_output_r_check_photometry.png'
     """
 
     bright, = np.where(np.asarray(mag) < good_mag_limit)
@@ -220,13 +230,28 @@ def plotPhotometry(mag, mmagerr, mmagrms, dist, match, good_mag_limit=19.5,
     plotMagerrFit(mag[w], mmagerr[w], mmagerr[w], ax=ax[1][1])
     ax[1][1].legend(loc='upper left')
 
-    plt.suptitle("Photometry Check : %s" % plotBase.rstrip('_'), fontsize=30)
-    plotPath = plotBase+"check_photometry.png"
+    plt.suptitle("Photometry Check : %s" % outputPrefix.rstrip('_'), fontsize=30)
+    plotPath = outputPrefix+"check_photometry.png"
     plt.savefig(plotPath, format="png")
 
 
-def plotPA1(pa1, plotBase=""):
-    """Plot the results of calculating the LSST SRC requirement PA1."""
+def plotPA1(pa1, outputPrefix=""):
+    """Plot the results of calculating the LSST SRC requirement PA1.
+
+    Creates a file containing the plot with a filename beginning with `outputPrefix`.
+
+    Parameters
+    ----------
+    pa1 : pipeBase.Struct
+        Must contain:
+        rms, iqr, magMean, magDiffs
+        rmsUnits, iqrUnits, magDiffsUnits
+    outputPrefix : str, optional
+        Prefix to use for filename of plot file.  Will also be used in plot titles.
+        E.g., outputPrefix='Cfht_output_r_' will result in a file named
+           'Cfht_output_r_AM1_D_5_arcmin_17.0-21.5.png'
+        for an AMx.name=='AM1' and AMx.magRange==[17, 21.5]
+    """
     diffRange = (-100, +100)
 
     fig = plt.figure(figsize=(18, 12))
@@ -259,8 +284,8 @@ def plotPA1(pa1, plotBase=""):
     for label in ax2.get_yticklabels():
         label.set_visible(False)
 
-    plt.suptitle("PA1: %s" % plotBase.rstrip('_'))
-    plotPath = "%s%s" % (plotBase, "PA1.png")
+    plt.suptitle("PA1: %s" % outputPrefix.rstrip('_'))
+    plotPath = "%s%s" % (outputPrefix, "PA1.png")
     plt.savefig(plotPath, format="png")
 
 
@@ -273,19 +298,22 @@ def plotAM2(*args, **kwargs):
 def plotAM3(*args, **kwargs):
     return plotAMx(*args, x=3, **kwargs)
 
-def plotAMx(AMx, plotBase=""):
+def plotAMx(AMx, outputPrefix=""):
     """Plot a histogram of the RMS in relative distance between pairs of stars.
 
-    Inputs
-    ------
+    Creates a file containing the plot with a filename beginning with `outputPrefix`.
+
+    Parameters
+    ----------
     AMx : pipeBase.Struct
         Must contain:
         AMx, rmsDistMas, fractionOver, annulus, magRange, x, level,
         AMx_spec, AFx_spec, ADx_spec
-
-    Outputs
-    -------
-    Plot file prefixed with plotBase.
+    outputPrefix : str, optional
+        Prefix to use for filename of plot file.  Will also be used in plot titles.
+        E.g., outputPrefix='Cfht_output_r_' will result in a file named
+           'Cfht_output_r_AM1_D_5_arcmin_17.0-21.5.png'
+        for an AMx.name=='AM1' and AMx.magRange==[17, 21.5]
     """
 
     percentOver = 100*AMx.fractionOver
@@ -315,7 +343,7 @@ def plotAMx(AMx, plotBase=""):
 
     ax1.legend(loc='upper right', fontsize=16)
 
-    figName = plotBase+'%s_D_%d_%s_%.1f-%.1f.png' % \
+    figName = outputPrefix+'%s_D_%d_%s_%.1f-%.1f.png' % \
               (AMx.name, int(sum(AMx.annulus)/2), AMx.DUnits.upper(), AMx.magRange[0], AMx.magRange[1])
 
     plt.savefig(figName, dpi=300)

python/lsst/validate/drp/print.py

@@ -1,5 +1,3 @@
-#!/usr/bin/env python
-
 # LSST Data Management System
 # Copyright 2008-2016 AURA/LSST.
 #
@@ -25,8 +23,7 @@
 from .srdSpec import srdSpec
 
 def printPA1(PA1):
-    """Print the calculated PA1 from the LSST SRD.  
-    """
+    """Print the calculated PA1 from the LSST SRD."""
     print("PA1(RMS) = %4.2f+-%4.2f %s" % (PA1.rms, PA1.rmsStd, PA1.rmsUnits))
     print("PA1(IQR) = %4.2f+-%4.2f %s" % (PA1.iqr, PA1.iqrStd, PA1.iqrUnits))
 
@@ -35,15 +32,15 @@ def printPA2(pa2):
     """Print the calculated PA2 from the LSST SRD."""
     for level in ('minimum', 'design', 'stretch'):
         print("%-7s: PF1=%2d%s of diffs more than PA2 = %4.2f %s (target is < %2.0f %s)" %
-              (level, pa2.PF1[level], pa2.pf1Units, pa2.getDict()[level], pa2.pa2Units, 
+              (level, pa2.PF1[level], pa2.pf1Units, pa2.getDict()[level], pa2.pa2Units,
                srdSpec.PA2[level], srdSpec.pa2Units))
 
 
 def printAMx(AMx):
     """Print the Astrometric performance.
 
-    Inputs
-    ------
+    Parameters
+    ----------
     AMx : pipeBase.Struct
         Must contain:
         AMx, fractionOver, annulus, magRange, x, level,
@@ -56,7 +53,7 @@ def printAMx(AMx):
     print("%s goals" % AMx.level.upper())
     print("For stars from %.2f < mag < %.2f" % (AMx.magRange[0], AMx.magRange[1]))
     print("from D = [%.2f, %.2f] %s, %s=%.2f %s (target is < %.0f %s)." %
-          (AMx.annulus[0], AMx.annulus[1], AMx.annulusUnits, 
+          (AMx.annulus[0], AMx.annulus[1], AMx.annulusUnits,
            AMx.name, AMx.AMx, AMx.amxUnits, AMx.AMx_spec, AMx.amxUnits))
     print("  %.2f%% of sample deviates by >%.0f %s (target is < %.0f%%)" %
           (percentOver, AMx.ADx_spec+AMx.AMx_spec, AMx.adxUnits, AMx.AFx_spec))

python/lsst/validate/drp/srdSpec.py

@@ -1,5 +1,3 @@
-#!/usr/bin/env python
-
 # LSST Data Management System
 # Copyright 2008-2016 AURA/LSST.
 #
@@ -24,8 +22,6 @@
 
 import lsst.pipe.base as pipeBase
 
-from .base import ValidateError
-
 srdSpec = pipeBase.Struct(
     levels=("design", "minimum", "stretch"),
     PA2={"design": 15, "minimum": 15, "stretch": 10}, pa2Units='mmag',
@@ -47,8 +43,8 @@
 def getAstrometricSpec(x=None, level='design'):
     """Return SRD specification for given astrometric test.
 
-    Inputs
-    ------
+    Parameters
+    ----------
     x : int
         One of [1,2,3].
     level : str
@@ -61,7 +57,7 @@ def getAstrometricSpec(x=None, level='design'):
 
     Raises:
     -------
-    ValidateError if `x` isn't in `getAstrometricSpec`
+    ValueError if `x` isn't in `getAstrometricSpec`
     """
 
     if x == 1:
@@ -77,6 +73,6 @@ def getAstrometricSpec(x=None, level='design'):
         AFx = srdSpec.AF3[level]
         ADx = srdSpec.AD3[level]
     else:
-        raise ValidateError("Unknown astrometric test specification: %s" % str(x))
+        raise ValueError("Unknown astrometric test specification: %s" % str(x))
 
     return AMx, AFx, ADx