Updated docstrings following review

python/lsst/pipe/tasks/calibrate.py

@@ -257,7 +257,8 @@ class CalibrateConfig(pipeBase.PipelineTaskConfig, pipelineConnections=Calibrate
     )
     setPrimaryFlags = pexConfig.ConfigurableField(
         target=SetPrimaryFlagsTask,
-        doc="Set flags for primary source classification in single frame processing"
+        doc=("Set flags for primary source classification in single frame "
+             "processing. True if sources are not sky sources and not a parent.")
     )
     doApCorr = pexConfig.Field(
         dtype=bool,

python/lsst/pipe/tasks/setPrimaryFlags.py

@@ -34,13 +34,28 @@ class SetPrimaryFlagsConfig(Config):
 
 
 class SetPrimaryFlagsTask(Task):
+    """Add isPrimaryKey to a given schema.
+
+    Parameters
+    ----------
+    schema : `lsst.afw.table.Schema`
+        The input schema.
+    isSingleFrame : `bool`
+        Flag specifying if task is operating with single frame imaging.
+    kwargs :
+        Keyword arguments passed to the task.
+    """
+
     ConfigClass = SetPrimaryFlagsConfig
 
     def __init__(self, schema, isSingleFrame=False, **kwargs):
         Task.__init__(self, **kwargs)
         self.schema = schema
         self.isSingleFrame = isSingleFrame
         if not self.isSingleFrame:
+            primaryDoc = ("true if source has no children and is in the inner region of a coadd patch "
+                          "and is in the inner region of a coadd tract "
+                          "and is not \"detected\" in a pseudo-filter (see config.pseudoFilterList)")
             self.isPatchInnerKey = self.schema.addField(
                 "detect_isPatchInner", type="Flag",
                 doc="true if source is in the inner region of a coadd patch",
@@ -49,9 +64,6 @@ def __init__(self, schema, isSingleFrame=False, **kwargs):
                 "detect_isTractInner", type="Flag",
                 doc="true if source is in the inner region of a coadd tract",
             )
-            primaryDoc = ("true if source has no children and is in the inner region of a coadd patch "
-                          "and is in the inner region of a coadd tract "
-                          "and is not \"detected\" in a pseudo-filter (see config.pseudoFilterList)")
         else:
             primaryDoc = "true if source has no children and is not a sky source"
         self.isPrimaryKey = self.schema.addField(
@@ -61,20 +73,33 @@ def __init__(self, schema, isSingleFrame=False, **kwargs):
 
     def run(self, sources, skyMap=None, tractInfo=None, patchInfo=None,
             includeDeblend=True):
-        """Set is-primary and related flags on sources
-
-        @param[in,out] sources   a SourceTable
-            - reads centroid fields and an nChild field
-            - writes is-patch-inner, is-tract-inner and is-primary flags
-        @param[in] skyMap   sky tessellation object (subclass of lsst.skymap.BaseSkyMap)
-        @param[in] tractInfo   tract object (subclass of lsst.skymap.TractInfo)
-        @param[in] patchInfo   patch object (subclass of lsst.skymap.PatchInfo)
-        @param[in] includeDeblend   include deblend information in isPrimary?
+        """Set is-patch-inner, is-tract-inner and is-primary flags on sources.
+        For coadded imaging, the is-primary flag returns True when an object
+        has no children, is in the inner region of a coadd patch, is in the
+        inner region of a coadd trach, and is not detected in a pseudo-filter
+        (e.g., a sky_object).
+        For single frame imaging, the is-primary flag returns True when a
+        source has no children and is not a sky source.
+
+        Parameters
+        ----------
+        sources : `lsst.afw.table.SourceCatalog`
+            A sourceTable. Reads in centroid fields and an nChild field.
+            Writes is-patch-inner, is-tract-inner, and is-primary flags.
+        skyMap : `lsst.skymap.BaseSkyMap`
+            Sky tessellation object
+        tractInfo : `lsst.skymap.TractInfo`
+            Tract object
+        patchInfo : `lsst.skymap.PatchInfo`
+            Patch object
+        includeDeblend : `bool`
+            Include deblend information in isPrimary?
         """
         nChildKey = None
         if includeDeblend:
             nChildKey = self.schema.find(self.config.nChildKeyName).key
 
+        # coadd case
         if not self.isSingleFrame:
             # set inner flags for each source and set primary flags for sources with no children
             # (or all sources if deblend info not available)
@@ -121,12 +146,13 @@ def run(self, sources, skyMap=None, tractInfo=None, patchInfo=None,
 
                     source.setFlag(self.isPrimaryKey, isPatchInner and isTractInner and not isPseudo)
 
+        # single frame case
         else:
             hasSkySources = True if "sky_source" in sources.schema else False
             for source in sources:
-                if nChildKey is None or source.get(nChildKey) == 0:
-                    if hasSkySources:
-                        if not source["sky_source"]:
-                            source.setFlag(self.isPrimaryKey, True)
-                    else:
-                        source.setFlag(self.isPrimaryKey, True)
+                hasNoChildren = True if nChildKey is None or source.get(nChildKey) == 0 else False
+                isSkySource = False
+                if hasSkySources:
+                    if source["sky_source"]:
+                        isSkySource = True
+                source.setFlag(self.isPrimaryKey, hasNoChildren and not isSkySource)

tests/test_isPrimaryFlag.py

@@ -43,7 +43,8 @@ def tearDown(self):
         del self.exposure
 
     def testIsPrimaryFlag(self):
-        """Tests detect_isPrimary column gets added when run.
+        """Tests detect_isPrimary column gets added when run, and that sources
+        labelled as detect_isPrimary are not sky sources and have no children.
         """
         charImConfig = CharacterizeImageConfig()
         charImTask = CharacterizeImageTask(config=charImConfig)
@@ -56,9 +57,9 @@ def testIsPrimaryFlag(self):
         outputCat = calibResults.outputCat
         self.assertTrue("detect_isPrimary" in outputCat.schema.getNames())
         # make sure all sky sources are flagged as not primary
-        self.assertTrue(sum((outputCat["detect_isPrimary"]) & (outputCat["sky_source"])) == 0)
+        self.assertEqual(sum((outputCat["detect_isPrimary"]) & (outputCat["sky_source"])), 0)
         # make sure all parent sources are flagged as not primary
-        self.assertTrue(sum((outputCat["detect_isPrimary"]) & (outputCat["deblend_nChild"] > 0)) == 0)
+        self.assertEqual(sum((outputCat["detect_isPrimary"]) & (outputCat["deblend_nChild"] > 0)), 0)
 
 
 class MemoryTester(lsst.utils.tests.MemoryTestCase):