add docs

python/lsst/meas/algorithms/computeExPsf.py

@@ -1,3 +1,24 @@
+# This file is part of meas_algorithms.
+#
+# Developed for the LSST Data Management System.
+# This product includes software developed by the LSST Project
+# (https://www.lsst.org).
+# See the COPYRIGHT file at the top-level directory of this distribution
+# for details of code ownership.
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
 from lsst.pex.config import Config, Field
 from lsst.pipe.base import Task
 import treecorr
@@ -26,29 +47,35 @@ class ComputeExPsfConfig(Config):
 class ComputeExPsfTask(Task):
     """Compute Ex for PSF.
 
-    TO DO: more explanations.
+    Compute scalar correlation function from
+    PSF ellipticity residuals to compute TEx
+    metrics.
 
     Parameters
     ----------
     de1: `numpy.array`
-        TO DO.
+        PSF ellipticity residuals component 1.
     de2: `numpy.array`
-        TO DO.
+        PSF ellipticity residuals component 2.
     ra: `numpy.array`
-        TO DO.
+        Right ascension coordinate.
     dec: `numpy.array`
-        TO DO.
+        Declination coordinate.
     units: `str`
-        TO DO.
+        In which units are ra and dec. units supported
+        are the same as the one in treecorr.
 
     Returns
     -------
     kk_E1: `float`
-        TO DO.
+        <de1 de1> scalar correlation function, compute
+        in an angular bin define in ComputeExPsfConfig.
     kk_E2: `float`
-        TO DO.
+        <de2 de2> scalar correlation function, compute
+        in an angular bin define in ComputeExPsfConfig.
     kk_Ex: `float`
-        TO DO.
+        <de1 de2> scalar cross-correlation function, compute
+        in an angular bin define in ComputeExPsfConfig.
     """
 
     ConfigClass = ComputeExPsfConfig

tests/test_computeExPsf.py

@@ -67,8 +67,57 @@ def generate_gaussian_random_field(
     seed=42,
     input_coord=None,
 ):
-    """
-    TO DO.
+    """Generate a Gaussian Random Field.
+
+    Function to generate a Gaussian Random Field.
+    Help for unit test and generate spatial correlated
+    function and have an analytical 2-point correlation
+    to compared with (Gaussian here).
+
+    Parameters
+    ----------
+    xmin: `int`
+        Min value in x direction.
+        Default: ``0``
+    xmax: `int`
+        Max value in x direction.
+        Default: ``2000``
+    ymin: `int`
+        Min value in y direction.
+        Default: ``0``
+    ymax: `int`
+        Max value in y direction.
+        Default: ``2000``
+    npoints: `int`
+        Number of data points generated.
+        Default: ``10000``
+    nmax: `int`
+        Max number of data points generated using
+        `np.random.multivariate_normal`. If
+        npoints>nmax, a GP will be used in addition.
+        Default: ``1000``
+    std: `float`
+        Amplitude of the gaussian random field.
+        Default: ``1.0``
+    correlation_length: `float`
+        Correlation length of the gaussian random field.
+        Default: ``10.0``
+    white_noise: `float`
+        Noise added to the gaussian random field.
+        Default: ``1.0``
+    seed: `int`
+        Seed of the random generator.
+        Default: ``42``
+    input_coord: `np.array`
+        Take a input coord to generate the Gaussian Random field
+        Default: ``None``
+
+    Returns
+    -------
+    coord: `np.array`
+        2D coordinate of the gaussian random field
+    z: `np.array`
+        Scalar value of the gaussian random field
     """
     np.random.seed(seed)
 
@@ -169,6 +218,10 @@ def test_comp_ex_psf(self):
         task = ComputeExPsfTask(config)
         kk_E1, kk_E2, kk_Ex = task.run(self.de1, self.de2, ra, dec, units="arcmin")
 
+        # At small scale, expect the scalar two-point correlation function
+        # to be close to the input variance for de1 and de2. Cross correlation
+        # between de1 and de2 should be zeros are they are 2 indendant field.
+
         np.testing.assert_allclose(kk_E1, 1.0, atol=2e-1)
         np.testing.assert_allclose(kk_E2, 1.0, atol=2e-1)
         np.testing.assert_allclose(kk_Ex, 0.0, atol=1e-1)
@@ -177,6 +230,9 @@ def test_comp_ex_psf(self):
         config.thetaMin = 600.0
         config.thetaMax = 1000.0
 
+        # At large scale, expect the scalar two-point correlation function to
+        # be all close to 0.
+
         task = ComputeExPsfTask(config)
         kk_E1, kk_E2, kk_Ex = task.run(self.de1, self.de2, ra, dec, units="arcmin")