Numpydoc conversion of meas_algorithms through makeCoaddApCorrMap.py

lsst · Jan 8, 2021 · 15d457a · 15d457a
1 parent 2b8c1f5
commit 15d457a
Show file tree

Hide file tree

Showing 6 changed files with 174 additions and 168 deletions.
diff --git a/doc/lsst.meas.algorithms/tasks/lsst.meas.algorithms.IngestGaiaReferenceTask.rst b/doc/lsst.meas.algorithms/tasks/lsst.meas.algorithms.IngestGaiaReferenceTask.rst
@@ -0,0 +1,31 @@
+.. lsst-task-topic:: lsst.meas.algorithms.IngestGaiaReferenceTask
+
+#######################
+IngestGaiaReferenceTask
+#######################
+
+``IngestGaiaReferenceTask`` acts as a special-cased version of the refcat ingester for Gaia DR2.
+
+.. _lsst.meas.algorithms.IngestGaiaReferenceTask-api:
+
+Python API summary
+==================
+
+.. lsst-task-api-summary:: lsst.meas.algorithms.IngestGaiaReferenceTask
+
+.. _lsst.meas.algorithms.IngestGaiaReferenceTask-subtasks:
+
+Retargetable subtasks
+=====================
+
+.. lsst-task-config-subtasks:: lsst.meas.algorithms.IngestGaiaReferenceTask
+
+.. _lsst.meas.algorithms.IngestGaiaReferenceTask-configs:
+
+Configuration fields
+====================
+
+.. lsst-task-config-fields:: lsst.meas.algorithms.IngestGaiaReferenceTask
+
+.. _lsst.meas.algorithms.IngestGaiaReferenceTask-examples:
+
diff --git a/doc/lsst.meas.algorithms/tasks/lsst.meas.algorithms.InstallGaussianPsfTask.rst b/doc/lsst.meas.algorithms/tasks/lsst.meas.algorithms.InstallGaussianPsfTask.rst
@@ -0,0 +1,39 @@
+.. lsst-task-topic:: lsst.meas.algorithms.InstallGaussianPsfTask
+
+######################
+InstallGaussianPsfTask
+######################
+
+``InstallGaussianPsfTask`` installs a Gaussian PSF model in an exposure.
+
+.. _lsst.meas.algorithms.InstallGaussianPsfTask-summary:
+
+Processing summary
+==================
+
+``InstallGaussianPsfTask`` installs a Gaussian PSF model in an exposure, creating a new PSF with the same sigma and width if a PSF already exists for the exposure. If there is not a PSF model for the exposure, the sigma and width are taken from the config.
+.. _lsst.meas.algorithms.InstallGaussianPsfTask-api:
+
+Python API summary
+==================
+
+.. lsst-task-api-summary:: lsst.meas.algorithms.InstallGaussianPsfTask
+
+.. _lsst.meas.algorithms.InstallGaussianPsfTask-examples:
+
+Examples
+========
+
+.. code-block:: python
+    from lsst.afw.image import ExposureF
+    from lsst.meas.algorithms.installGaussianPsf import InstallGaussianPsfTask, FwhmPerSigma
+
+    exposure = ExposureF(100, 100)
+    task = InstallGaussianPsfTask()
+    task.run(exposure=exposure)
+
+     # This particular exposure had no PSF model to begin with, so the new PSF model
+     # uses the config's FWHM. However, measured FWHM is based on the truncated
+     # PSF image, so it does not exactly match the input
+     measFwhm = exposure.getPsf().computeShape().getDeterminantRadius() * FwhmPerSigma
+     assert abs(measFwhm - task.config.fwhm) < 1e-3
diff --git a/doc/lsst.meas.algorithms/tasks/lsst.meas.algorithms.LoadReferenceObjectsTask.rst b/doc/lsst.meas.algorithms/tasks/lsst.meas.algorithms.LoadReferenceObjectsTask.rst
@@ -0,0 +1,78 @@
+.. lsst-task-topic:: lsst.meas.algorithms.LoadReferenceObjectsTask
+
+########################
+LoadReferenceObjectsTask
+########################
+
+Implementations must subclass this class, override the loadSkyCircle method, and will typically override the value of ConfigClass with a task-specific config class.
+
+``LoadReferenceObjectsTask`` acts as an abstract base class for tasks that load objects from a reference catalog in a particluar region of sky.
+
+.. _lsst.meas.algorithms.LoadReferenceObjectsTask-api:
+
+Python API summary
+==================
+
+.. lsst-task-api-summary:: lsst.meas.algorithms.LoadReferenceObjectsTask
+
+.. _lsst.meas.algorithms.LoadReferenceObjectsTask-subtasks:
+
+Retargetable subtasks
+=====================
+
+.. lsst-task-config-subtasks:: lsst.meas.algorithms.LoadReferenceObjectsTask
+
+.. _lsst.meas.algorithms.LoadReferenceObjectsTask-configs:
+
+Configuration fields
+====================
+
+.. lsst-task-config-fields:: lsst.meas.algorithms.LoadReferenceObjectsTask
+
+.. _lsst.meas.algorithms.LoadReferenceObjectsTask-indepth
+
+In Depth
+========
+
+Catalog Schema
+--------------
+
+    - ``coord``: ICRS position of star on sky (an ``lsst.geom.SpherePoint``)
+    - ``centroid``: position of star on an exposure, if relevant (an ``lsst.afw.Point2D``)
+    - ``hasCentroid``: is centroid usable? (a Flag)
+    - ``<referenceFilterName>_flux``: brightness in the specified reference catalog filter (nJy)
+        Note: you can use astropy.units to convert from AB Magnitude to nJy: `u.Magnitude(value, u.ABmag).to_value(u.nJy)`
+    - ``<referenceFilterName>_fluxErr`` (optional): brightness standard deviation (nJy); omitted if no data is available; possibly nan if data is available for some objects but not others
+    - ``camFlux``: brightness in default camera filter (nJy); omitted if `defaultFilter` not specified
+    - ``camFluxErr``: brightness standard deviation for default camera filter; omitted if `defaultFilter` not specified or standard deviation not available that filter
+    - ``<cameraFilterName>_camFlux``: brightness in specified camera filter (nJy)
+    - ``<cameraFilterName>_camFluxErr`` (optional): brightness standard deviation in specified camera filter (nJy); omitted if no data is available;
+        possibly nan if data is available for some objects but not others
+    - ``photometric`` (optional): is the object usable for photometric calibration? (a Flag)
+    - ``resolved`` (optional): is the object spatially resolved? (a Flag)
+    - ``variable`` (optional): does the object have variable brightness? (a Flag)
+    - ``coord_raErr``: uncertainty in `coord` along the direction of right ascension (radian, an Angle) = uncertainty in ra * cos(dec); nan if unknown
+    - ``coord_decErr``: uncertainty in `coord` along the direction of declination (radian, an Angle);
+        nan if unknown
+
+The following are optional; fields should only be present if the information is available for at least some objects.
+    Numeric values are `nan` if unknown:
+
+    - ``epoch``: date of observation as TAI MJD (day)
+    - ``pm_ra``: proper motion along the direction of right ascension (rad/year, an Angle) = dra/dt * cos(dec)
+    - ``pm_dec``: proper motion along the direction of declination (rad/year, and Angle)
+    - ``pm_raErr``: uncertainty in `pm_ra` (rad/year)
+    - ``pm_decErr``: uncertainty in `pm_dec` (rad/year)
+    - ``pm_ra_dec_Cov``: covariance between pm_ra and pm_dec (rad2/year2)
+    - ``pm_flag``: set if proper motion, error or covariance is bad
+    - ``parallax``: parallax (rad, an Angle)
+    - ``parallaxErr``: uncertainty in `parallax` (rad)
+    - ``parallax_flag``: set if parallax value or parallaxErr is bad
+    - ``coord_ra_pm_ra_Cov``: covariance between coord_ra and pm_ra (rad2/year)
+    - ``coord_ra_pm_dec_Cov``: covariance between coord_ra and pm_dec (rad2/year)
+    - ``coord_ra_parallax_Cov``: covariance between coord_ra and parallax (rad2/year)
+    - ``coord_dec_pm_ra_Cov``: covariance between coord_dec and pm_ra (rad2/year)
+    - ``coord_dec_pm_dec_Cov``: covariance between coord_dec and pm_dec (rad2/year)
+    - ``coord_dec_parallax_Cov``: covariance between coord_dec and parallax (rad2/year)
+    - ``pm_ra_parallax_Cov``: covariance between pm_ra and parallax (rad2/year)
+    - ``pm_dec_parallax_Cov``: covariance between pm_dec and parallax (rad2/year)
diff --git a/python/lsst/meas/algorithms/installGaussianPsf.py b/python/lsst/meas/algorithms/installGaussianPsf.py
@@ -32,7 +32,8 @@
 
 
 class InstallGaussianPsfConfig(pexConfig.Config):
-    """!Config for InstallGaussianPsfTask"""
+    """Config for InstallGaussianPsfTask
+    """
     fwhm = pexConfig.Field(
         dtype=float,
         default=1.5 * FwhmPerSigma,
@@ -51,84 +52,24 @@ def validate(self):
             raise RuntimeError("width=%s must be odd" % (self.width,))
 
 
-## @addtogroup LSST_task_documentation
-## @{
-## @page InstallGaussianPsfTask
-## @ref InstallGaussianPsfTask_ "InstallGaussianPsfTask"
-## @copybrief InstallGaussianPsfTask
-## @}
-
 class InstallGaussianPsfTask(pipeBase.Task):
-    r"""!Install a Gaussian PSF model in an exposure
-
-    @anchor InstallGaussianPsfTask_
-
-    @section pipe_tasks_installGaussianPsf_Contents  Contents
-
-     - @ref pipe_tasks_installGaussianPsf_Purpose
-     - @ref pipe_tasks_installGaussianPsf_Initialize
-     - @ref pipe_tasks_installGaussianPsf_IO
-     - @ref pipe_tasks_installGaussianPsf_Config
-     - @ref pipe_tasks_installGaussianPsf_Metadata
-     - @ref pipe_tasks_installGaussianPsf_Debug
-     - @ref pipe_tasks_installGaussianPsf_Example
-
-    @section pipe_tasks_installGaussianPsf_Purpose  Description
-
-    Install a Gaussian PSF model in an exposure.
+    r"""Install a Gaussian PSF model in an exposure.
     If the exposure already has a PSF model then the new model
     has the same sigma and size (width and height in pixels) of the existing model.
-    If the exposure does not have a PSF model then the PSF sigma and size
-    are taken from the config.
-
-    At present the produced model is always circularly symmetric, but it is planned
-    to change this to an elliptical PSF model (only for the case that the exposure
-    already has a PSF model), once the necessary PSF object is available.
-
-    A variant of this task may someday exist to estimate the PSF
-    from the pixel data if no PSF model is present.
-
-    @section pipe_tasks_installGaussianPsf_Initialize  Task initialisation
-
-    @copydoc \_\_init\_\_
-
-    @section pipe_tasks_installGaussianPsf_IO  Invoking the Task
-
-    The main method is `run`.
-
-    @section pipe_tasks_installGaussianPsf_Config  Configuration parameters
-
-    See @ref InstallGaussianPsfConfig
-
-    @section pipe_tasks_installGaussianPsf_Debug  Debug variables
-
-    This task has no debug display
-
-    @section pipe_tasks_installGaussianPsf_Example  A complete example of using InstallGaussianPsfTask
-
-        from lsst.afw.image import ExposureF
-        from lsst.meas.algorithms.installGaussianPsf import InstallGaussianPsfTask, FwhmPerSigma
-
-        exposure = ExposureF(100, 100)
-        task = InstallGaussianPsfTask()
-        task.run(exposure=exposure)
-
-        # This particular exposure had no PSF model to begin with, so the new PSF model
-        # uses the config's FWHM. However, measured FWHM is based on the truncated
-        # PSF image, so it does not exactly match the input
-        measFwhm = exposure.getPsf().computeShape().getDeterminantRadius() * FwhmPerSigma
-        assert abs(measFwhm - task.config.fwhm) < 1e-3
     """
     ConfigClass = InstallGaussianPsfConfig
     _DefaultName = "installSimplePsfModel"
 
     def run(self, exposure):
-        """!Set exposure's PSF to a simple PSF model
+        """Set exposure's PSF to a simple PSF model
 
         The sigma and width of the new simple PSF model matches the sigma and width of the current model,
         if any, else the config parameters are used.
 
-        @param[in,out] exposure  exposure to which to replace or add the PSF model
+        Parameters
+        ----------
+        exposure : `lsst.afw.image.Exposure`
+            Exposure in which to replace or add the PSF model.
         """
         if exposure.hasPsf():
             psfModel = exposure.getPsf()

diff --git a/python/lsst/meas/algorithms/loadReferenceObjects.py b/python/lsst/meas/algorithms/loadReferenceObjects.py
@@ -816,102 +816,8 @@ def validate(self):
                                                  self, msg)
 
 
-# The following comment block adds a link to this task from the Task Documentation page.
-## @addtogroup LSST_task_documentation
-## @{
-## @page LoadReferenceObjectsTask
-## @ref LoadReferenceObjectsTask_ "LoadReferenceObjectsTask"
-## @copybrief LoadReferenceObjectsTask
-## @}
-
-
 class LoadReferenceObjectsTask(pipeBase.Task, metaclass=abc.ABCMeta):
-    r"""!Abstract base class to load objects from reference catalogs
-
-    @anchor LoadReferenceObjectsTask_
-
-    @section meas_algorithms_loadReferenceObjects_Contents Contents
-
-     - @ref meas_algorithms_loadReferenceObjects_Purpose
-     - @ref meas_algorithms_loadReferenceObjects_Initialize
-     - @ref meas_algorithms_loadReferenceObjects_IO
-     - @ref meas_algorithms_loadReferenceObjects_Schema
-     - @ref meas_algorithms_loadReferenceObjects_Config
-
-    @section meas_algorithms_loadReferenceObjects_Purpose  Description
-
-    Abstract base class for tasks that load objects from a reference catalog
-    in a particular region of the sky.
-
-    Implementations must subclass this class, override the loadSkyCircle method,
-    and will typically override the value of ConfigClass with a task-specific config class.
-
-    @section meas_algorithms_loadReferenceObjects_Initialize   Task initialisation
-
-    @copydoc \_\_init\_\_
-
-    @section meas_algorithms_loadReferenceObjects_IO       Invoking the Task
-
-    @copydoc loadPixelBox
-
-    @section meas_algorithms_loadReferenceObjects_Schema       Schema of the reference object catalog
-
-    Reference object catalogs are instances of lsst.afw.table.SimpleCatalog with the following schema
-    (other fields may also be present).
-    The units use astropy quantity conventions, so a 2 suffix means squared.
-    See also makeMinimalSchema.
-    - coord: ICRS position of star on sky (an lsst.geom.SpherePoint)
-    - centroid: position of star on an exposure, if relevant (an lsst.afw.Point2D)
-    - hasCentroid: is centroid usable? (a Flag)
-    - *referenceFilterName*_flux: brightness in the specified reference catalog filter (nJy)
-        Note: you can use astropy.units to convert from AB Magnitude to nJy:
-            `u.Magnitude(value, u.ABmag).to_value(u.nJy)`
-    - *referenceFilterName*_fluxErr (optional): brightness standard deviation (nJy);
-        omitted if no data is available; possibly nan if data is available for some objects but not others
-    - camFlux: brightness in default camera filter (nJy); omitted if defaultFilter not specified
-    - camFluxErr: brightness standard deviation for default camera filter;
-        omitted if defaultFilter not specified or standard deviation not available that filter
-    - *cameraFilterName*_camFlux: brightness in specified camera filter (nJy)
-    - *cameraFilterName*_camFluxErr (optional): brightness standard deviation
-        in specified camera filter (nJy); omitted if no data is available;
-        possibly nan if data is available for some objects but not others
-    - photometric (optional): is the object usable for photometric calibration? (a Flag)
-    - resolved (optional): is the object spatially resolved? (a Flag)
-    - variable (optional): does the object have variable brightness? (a Flag)
-    - coord_raErr: uncertainty in `coord` along the direction of right ascension (radian, an Angle)
-                    = uncertainty in ra * cos(dec); nan if unknown
-    - coord_decErr: uncertainty in `coord` along the direction of declination (radian, an Angle);
-        nan if unknown
-
-    The following are optional; fields should only be present if the
-    information is available for at least some objects.
-    Numeric values are `nan` if unknown:
-    - epoch: date of observation as TAI MJD (day)
-
-    - pm_ra: proper motion along the direction of right ascension (rad/year, an Angle) = dra/dt * cos(dec)
-    - pm_dec: proper motion along the direction of declination (rad/year, and Angle)
-    - pm_raErr: uncertainty in `pm_ra` (rad/year)
-    - pm_decErr: uncertainty in `pm_dec` (rad/year)
-    - pm_ra_dec_Cov: covariance between pm_ra and pm_dec (rad2/year2)
-    - pm_flag: set if proper motion, error or covariance is bad
-
-    - parallax: parallax (rad, an Angle)
-    - parallaxErr: uncertainty in `parallax` (rad)
-    - parallax_flag: set if parallax value or parallaxErr is bad
-
-    - coord_ra_pm_ra_Cov: covariance between coord_ra and pm_ra (rad2/year)
-    - coord_ra_pm_dec_Cov: covariance between coord_ra and pm_dec (rad2/year)
-    - coord_ra_parallax_Cov: covariance between coord_ra and parallax (rad2/year)
-    - coord_dec_pm_ra_Cov: covariance between coord_dec and pm_ra (rad2/year)
-    - coord_dec_pm_dec_Cov: covariance between coord_dec and pm_dec (rad2/year)
-    - coord_dec_parallax_Cov: covariance between coord_dec and parallax (rad2/year)
-    - pm_ra_parallax_Cov: covariance between pm_ra and parallax (rad2/year)
-    - pm_dec_parallax_Cov: covariance between pm_dec and parallax (rad2/year)
-
-    @section meas_algorithms_loadReferenceObjects_Config       Configuration parameters
-
-    See @ref LoadReferenceObjectsConfig for a base set of configuration parameters.
-    Most subclasses will add configuration variables.
+    r"""Abstract base class to load objects from reference catalogs
     """
     ConfigClass = LoadReferenceObjectsConfig
     _DefaultName = "LoadReferenceObjects"
@@ -1046,7 +952,9 @@ def _trimToBBox(refCat, bbox, wcs):
         wcs : `lsst.afw.geom.SkyWcs`
             WCS; used to convert sky coordinates to pixel positions.
 
-        @return a catalog of reference objects in bbox, with centroid and hasCentroid fields set
+        Returns
+        -------
+        A catalog of reference objects in bbox, with centroid and hasCentroid fields set
         """
         afwTable.updateRefCentroids(wcs, refCat)
         centroidKey = afwTable.Point2DKey(refCat.schema["centroid"])

diff --git a/python/lsst/meas/algorithms/makeCoaddApCorrMap.py b/python/lsst/meas/algorithms/makeCoaddApCorrMap.py
@@ -29,11 +29,20 @@
 def makeCoaddApCorrMap(catalog, coaddBox, coaddWcs, weightFieldName="weight"):
     """Construct an ApCorrMap for a coadd
 
-    @param catalog: Table of coadd inputs (lsst.afw.table.ExposureCatalog)
-    @param coaddBox: Bounding box for coadd (lsst.geom.Box2I)
-    @param coaddWcs: Wcs for coadd
-    @param weightFieldName: name of weight field in catalog
-    @return aperture corrections
+    Parameters
+    ----------
+    catalog: `lsst.afw.table.ExposureCatalog`
+        A table of coadd inputs
+    coaddBox : `lsst.geom.Box2I`
+        Bounding box for coadd
+    coaddWcs : `lsst.afw.geom.SkyWcs
+        Wcs for coadd
+    weightFieldName : `str`
+        Name of the weight field in the catalog
+
+    Returns
+    -------
+    Aperture corrections
     """
 
     # Assemble the BoundedFields for each type