Docstring updates in ip_diffim, mostly a subset of DM-17458 todos.

(cherry picked from commit f3ee5b4)

python/lsst/ip/diffim/diffimTools.py

@@ -63,13 +63,13 @@ def makePoissonNoiseImage(im):
     Parameters
     ----------
     im : `lsst.afw.image.Image`
-        image; the output image has the same dimensions and shape
+        image; the output image has the same dtype, dimensions and shape
         and its expectation value is the value of ``im`` at each pixel
 
     Returns
     -------
     noiseIm : `lsst.afw.image.Image`
-        TODO: DM-17458
+        Newly constructed image instance, same type as ``im``.
 
     Notes
     -----
@@ -109,29 +109,53 @@ def fakeCoeffs():
 def makeFakeKernelSet(sizeCell=128, nCell=3,
                       deltaFunctionCounts=1.e4, tGaussianWidth=1.0,
                       addNoise=True, bgValue=100., display=False):
-    """TODO: DM-17458
+    """Generate test template and science images with sources
+    giving a kernel candidate list.
 
     Parameters
     ----------
     sizeCell : `int`, optional
-        TODO: DM-17458
+        Side of the square spatial cells in pixels.
     nCell : `int`, optional
-        TODO: DM-17458
+        Number of adjacent spatial cells in both direction in both images.
     deltaFunctionCounts : `float`, optional
-        TODO: DM-17458
+        Flux value for the template image sources.
     tGaussianWidth : `float`, optional
-        TODO: DM-17458
+        Sigma of the generated Gaussian PSF sources in the template image.
     addNoise : `bool`, optional
-        TODO: DM-17458
+        If `True`, Poisson noise is added to both the generated template
+        and science images.
     bgValue : `float`, optional
-        TODO: DM-17458
+        Background level to be added to the generated science image.
     display : `bool`, optional
-        TODO: DM-17458
+        If `True` displays the generated template and science images by
+        `lsst.afw.display.Display`.
+
+    Notes
+    -----
+    - The generated images consist of adjacent ``nCell x nCell`` cells, each
+      of pixel size ``sizeCell x sizeCell``.
+    - The sources in the science image is generated by convolving the
+      template by `sKernel`. `sKernel` is a spatial `LinearCombinationKernel`
+      of hard wired kernel bases functions. The linear combination has first
+      order polynomial spatial dependence with polynomial parameters from ``fakeCoeffs()``.
+    - The template image sources are generated in the center of each spatial
+      cell from one pixel, set to `deltaFunctionCounts` counts, then convolving
+      by a 2D Gaussian with sigma of `tGaussianWidth` along each axis.
 
     Returns
     -------
-    TODO: DM-17458
-        TODO: DM-17458
+    tMi : `lsst.afw.image.MaskedImage`
+        Generated template image.
+    sMi : `lsst.afw.image.MaskedImage`
+        Generated science image.
+    sKernel : `lsst.afw.math.LinearCombinationKernel`
+        The spatial kernel used to generate the sources in the science image.
+    kernelCellSet : `lsst.afw.math.SpatialCellSet`
+        Cell set of `lsst.ip.diffim.KernelCandidate` instances of
+        around all the generated sources in the science image.
+    configFake : `lsst.ip.diffim.ImagePsfMatchConfig`
+        Config instance used in the image generation.
     """
     from . import imagePsfMatch
     configFake = imagePsfMatch.ImagePsfMatchConfig()

python/lsst/ip/diffim/getTemplate.py

@@ -222,11 +222,11 @@ def run(self, exposure, sensorRef, templateIdList):
         ----------
         exposure :  `lsst.afw.image.Exposure`
             exposure (unused)
-        sensorRef : TYPE
-            a Butler data reference
-        templateIdList : TYPE
-            list of data ids, which should contain a single item.
-            If there are multiple items, only the first is used.
+        sensorRef : `lsst.daf.persistence.ButlerDataRef`
+            Data reference of the calexp(s) to subtract from.
+        templateIdList : `lsst.daf.persistence.ButlerDataRef`
+            Data reference of the template calexp to be subtraced.
+            Can be incomplete, fields are initialized from `sensorRef`.
 
         Returns
         -------

python/lsst/ip/diffim/imagePsfMatch.py

@@ -874,7 +874,7 @@ def _buildCellSet(self, templateMaskedImage, scienceMaskedImage, candidateList):
 
         Returns
         -------
-        kernelCellSet :
+        kernelCellSet : `lsst.afw.math.SpatialCellSet`
             a SpatialCellSet for use with self._solve
         """
         if not candidateList:

python/lsst/ip/diffim/makeKernelBasisList.py

@@ -31,30 +31,37 @@
 
 def makeKernelBasisList(config, targetFwhmPix=None, referenceFwhmPix=None,
                         basisDegGauss=None, metadata=None):
-    """Generate the appropriate Kernel basis based on the Config
+    """Generate the delta function or Alard-Lupton kernel bases depending on the Config.
+    Wrapper to call either `lsst.ip.diffim.makeDeltaFunctionBasisList` or
+    `lsst.ip.diffim.generateAlardLuptonBasisList`.
 
     Parameters
     ----------
-    config : TODO: DM-17458
-        TODO: DM-17458
-    targetFwhmPix : TODO: DM-17458, optional
-        TODO: DM-17458
-    referenceFwhmPix : TODO: DM-17458, optional
-        TODO: DM-17458
-    basisDegGauss : TODO: DM-17458, optional
-        TODO: DM-17458
-    metadata : TODO: DM-17458, optional
-        TODO: DM-17458
+    config : `lsst.ip.diffim.PsfMatchConfigAL`
+        Configuration object.
+    targetFwhmPix : `float`, optional
+        Passed on to `lsst.ip.diffim.generateAlardLuptonBasisList`. Not used otherwise.
+    referenceFwhmPix : `float`, optional
+        Passed on to `lsst.ip.diffim.generateAlardLuptonBasisList`. Not used otherwise.
+    basisDegGauss : list of `int`, optional
+        Passed on to `lsst.ip.diffim.generateAlardLuptonBasisList`. Not used otherwise.
+    metadata : `lsst.daf.base.PropertySet`, optional
+        Passed on to `lsst.ip.diffim.generateAlardLuptonBasisList`. Not used otherwise.
 
     Returns
     -------
-    TODO: DM-17458
-        TODO: DM-17458
+    basisList: `list` of `lsst.afw.math.kernel.FixedKernel`
+        List of basis kernels.
+
+    Notes
+    -----
+    See `lsst.ip.diffim.generateAlardLuptonBasisList` and
+    `lsst.ip.diffim.makeDeltaFunctionBasisList` for more information.
 
     Raises
     ------
     ValueError
-        TODO: DM-17458
+        If ``config.kernelBasisSet`` has an invalid value (not "alard-lupton" or "delta-function").
     """
     if config.kernelBasisSet == "alard-lupton":
         return generateAlardLuptonBasisList(config, targetFwhmPix=targetFwhmPix,
@@ -70,33 +77,66 @@ def makeKernelBasisList(config, targetFwhmPix=None, referenceFwhmPix=None,
 
 def generateAlardLuptonBasisList(config, targetFwhmPix=None, referenceFwhmPix=None,
                                  basisDegGauss=None, metadata=None):
-    """Generate an Alard-Lupton kernel basis based upon the Config and
-    the input FWHM of the science and template images
+    """Generate an Alard-Lupton kernel basis list based upon the Config and
+    the input FWHM of the science and template images.
 
     Parameters
     ----------
-    config : TODO: DM-17458
-        TODO: DM-17458
+    config : `lsst.ip.diffim.PsfMatchConfigAL`
+        Configuration object for the Alard-Lupton algorithm.
     targetFwhmPix : `float`, optional
-        TODO: DM-17458
+        Fwhm width (pixel) of the template exposure characteristic psf.
+        This is the _target_ that will be matched to the science exposure.
     referenceFwhmPix : `float`, optional
-        TODO: DM-17458
-    basisDegGauss : TODO: DM-17458, optional
-        TODO: DM-17458
-    metadata : TODO: DM-17458, optional
-        TODO: DM-17458
+        Fwhm width (pixel) of the science exposure characteristic psf.
+    basisDegGauss : list of `int`, optional
+        Polynomial degree of each Gaussian (sigma) basis. If None, defaults to `config.alardDegGauss`.
+    metadata : `lsst.daf.base.PropertySet`, optional
+        If specified, object to collect metadata fields about the kernel basis list.
 
     Returns
     -------
-    TYPE
-        TODO: DM-17458
+    basisList : list of `lsst.afw.math.kernel.FixedKernel`
+        List of basis kernels. For each degree value ``n`` in ``config.basisDegGauss`` (n+2)(n+1)/2 kernels
+        are generated and appended to the list in the order of the polynomial parameter number.
+        See `lsst.afw.math.polynomialFunction2D` documentation for more details.
+
+    Notes
+    -----
+    The polynomial functions (``f``) are always evaluated in the -1.0, +1.0 range in both x, y directions, 
+    edge to edge, with ``f(0,0)`` evaluated at the kernel center pixel, ``f(-1.0,-1.0)`` at the kernel 
+    ``(0,0)`` pixel. They are not scaled by the sigmas of the Gaussians.
+
+    Base Gaussian widths (sigmas in pixels) of the kernels are determined as:
+        - If not all fwhm parameters are provided or ``config.scaleByFwhm==False``
+          then ``config.alardNGauss`` and  ``config.alardSigGauss`` are used.
+        - If ``targetFwhmPix<referenceFwhmPix`` (normal convolution):
+          First sigma ``Sig_K`` is determined to satisfy: ``Sig_reference**2 = Sig_target**2 + Sig_K**2``.
+          If it's larger than ``config.alardMinSig * config.alardGaussBeta``, make it the
+          second kernel. Else make it the smallest kernel, unless only 1 kernel is asked for.
+        - If ``referenceFwhmPix < targetFwhmPix`` (deconvolution):
+          Define the progression of Gaussians using a
+          method to derive a deconvolution sum-of-Gaussians from it's
+          convolution counterpart. [1]_ Only use 3 since the algorithm
+          assumes 3 components.
+
+    References
+    ----------
+
+    .. [1] Ulmer, W.: Inverse problem of linear combinations of Gaussian convolution kernels
+       (deconvolution) and some applications to proton/photon dosimetry and image
+       processing. http://iopscience.iop.org/0266-5611/26/8/085002  Equation 40
 
     Raises
     ------
     RuntimeError
-        TODO: DM-17458
+        - if ``config.kernelBasisSet`` is not equal to "alard-lupton"
     ValueError
-        TODO: DM-17458
+        - if ``config.kernelSize`` is even
+        - if the number of Gaussians and the number of given
+          sigma values are not equal or
+        - if the number of Gaussians and the number of given
+          polynomial degree values are not equal
     """
 
     if config.kernelBasisSet != "alard-lupton":