Merge pull request #367 from lsst/u/parejkoj/detection-docs

u/parejkoj/detection: add notes about background-subtraction dependency to detection task

doc/lsst.meas.algorithms/tasks/lsst.meas.algorithms.SourceDetectionTask.rst

@@ -5,8 +5,9 @@ SourceDetectionTask
 ###################
 
 `SourceDetectionTask` detects positive and negative sources on an exposure and produces a `lsst.afw.table.SourceCatalog` of detected sources.
+This task expects the image to have been background subtracted first, for example via :lsst-task:`~lsst.meas.algorithms.subtractBackground.SubtractBackgroundTask`.
+Running detection on images with a non-zero-centered background may result in a single source detected on the entire image containing thousands of peaks, or other pathological outputs.
 This task convolves the image with a Gaussian approximation to the PSF, matched to the sigma of the input exposure, because this is separable and fast.
-The PSF would have to be very non-Gaussian or non-circular for this approximation to have a significant impact on the signal-to-noise of the detected sources.
 
 .. _lsst.meas.algorithms.SourceDetectionTask-api:
 

python/lsst/meas/algorithms/detection.py

@@ -170,11 +170,10 @@ def setDefaults(self):
 class SourceDetectionTask(pipeBase.Task):
     """Detect peaks and footprints of sources in an image.
 
-    This task convolves the image with a Gaussian approximation to the PSF,
-    matched to the sigma of the input exposure, because this is separable and
-    fast. The PSF would have to be very non-Gaussian or non-circular for this
-    approximation to have a significant impact on the signal-to-noise of the
-    detected sources.
+    This task expects the image to have been background subtracted first.
+    Running detection on images with a non-zero-centered background may result
+    in a single source detected on the entire image containing thousands of
+    peaks, or other pathological outputs.
 
     Parameters
     ----------
@@ -189,8 +188,11 @@ class SourceDetectionTask(pipeBase.Task):
 
     Notes
     -----
-    This task can add fields to the schema, so any code calling this task must
-    ensure that these columns are indeed present in the input match list.
+    This task convolves the image with a Gaussian approximation to the PSF,
+    matched to the sigma of the input exposure, because this is separable and
+    fast. The PSF would have to be very non-Gaussian or non-circular for this
+    approximation to have a significant impact on the signal-to-noise of the
+    detected sources.
     """
     ConfigClass = SourceDetectionConfig
     _DefaultName = "sourceDetection"