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 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.
Python API summary¶
from lsst.meas.algorithms.detection import SourceDetectionTask
-
class
SourceDetectionTask(schema=None, **kwds) Detect peaks and footprints of sources in an image
...
- attributeconfig
Access configuration fields and retargetable subtasks.
-
method
run(table, exposure, doSmooth=True, sigma=None, clearMask=True, expId=None, background=None) Detect sources and return catalog(s) of detections
...
See also
See the SourceDetectionTask API reference for complete details.
Retargetable subtasks¶
background¶
Background re-estimation; ignored if reEstimateBackground false
tempLocalBackground¶
A local (small-scale), temporary background estimation step run between detecting above-threshold regions and detecting the peaks within them; used to avoid detecting spuerious peaks in the wings.
tempWideBackground¶
A wide (large-scale) background estimation and removal before footprint and peak detection. It is added back into the image after detection. The purpose is to suppress very large footprints (e.g., from large artifacts) that the deblender may choke on.
Configuration fields¶
adjustBackground¶
Fiddle factor to add to the background; debugging only
combinedGrow¶
Grow all footprints at the same time? This allows disconnected footprints to merge.
doTempLocalBackground¶
Enable temporary local background subtraction? (see tempLocalBackground)
doTempWideBackground¶
Do temporary wide (large-scale) background subtraction before footprint detection?
excludeMaskPlanes¶
Mask planes to exclude when detecting sources.
includeThresholdMultiplier¶
- Default
1.0- Field type
- Range
[0.0,inf)
Multiplier on thresholdValue for whether a source is included in the output catalog. For example, thresholdValue=5, includeThresholdMultiplier=10, thresholdType=’pixel_stdev’ results in a catalog of sources at >50 sigma with the detection mask and footprints including pixels >5 sigma.
isotropicGrow¶
Grow pixels as isotropically as possible? If False, use a Manhattan metric instead.
minPixels¶
- Default
1- Field type
- Range
[0,inf)
detected sources with fewer than the specified number of pixels will be ignored
nPeaksMaxSimple¶
The maximum number of peaks in a Footprint before trying to replace its peaks using the temporary local background
nSigmaForKernel¶
Multiple of PSF RMS size to use for convolution kernel bounding box size; note that this is not a half-size. The size will be rounded up to the nearest odd integer
nSigmaToGrow¶
Grow detections by nSigmaToGrow * [PSF RMS width]; if 0 then do not grow
reEstimateBackground¶
Estimate the background again after final source detection?
returnOriginalFootprints¶
Grow detections to set the image mask bits, but return the original (not-grown) footprints
statsMask¶
Mask planes to ignore when calculating statistics of image (for thresholdType=stdev)
thresholdPolarity¶
- Default
'positive'- Field type
- Choices
'positive'detect only positive sources
'negative'detect only negative sources
'both'detect both positive and negative sources
Specifies whether to detect positive, or negative sources, or both.
thresholdType¶
- Default
'pixel_stdev'- Field type
- Choices
'variance'threshold applied to image variance
'stdev'threshold applied to image std deviation
'value'threshold applied to image value
'pixel_stdev'threshold applied to per-pixel std deviation
Specifies the meaning of thresholdValue.
thresholdValue¶
- Default
5.0- Field type
- Range
[0.0,inf)
Threshold for detecting footprints; exact meaning and units depend on thresholdType.
Examples¶
This code is in measAlgTasks.py in the examples directory, and can be run as e.g.
examples/measAlgTasks.py --doDisplay
The example also runs the SingleFrameMeasurementTask; see meas_algorithms_measurement_Example for more explanation.
Import the task (there are some other standard imports; read the file if you’re confused)
from lsst.meas.algorithms.detection import SourceDetectionTask
We need to create our task before processing any data as the task constructor can add an extra column to the schema, but first we need an almost-empty Schema
schema = afwTable.SourceTable.makeMinimalSchema()
after which we can call the constructor:
config = SourceDetectionTask.ConfigClass()
config.thresholdPolarity = "both"
config.background.isNanSafe = True
config.thresholdValue = 3
detectionTask = SourceDetectionTask(config=config, schema=schema)
We’re now ready to process the data (we could loop over multiple exposure/catalogues using the same task objects). First create the output table:
table = afwTable.SourceTable.make(schema)
And process the image
result = detectionTask.run(table, exposure)
(You may not be happy that the threshold was set in the config before creating the Task rather than being set separately for each exposure. You can reset it just before calling the run method if you must, but we should really implement a better solution).
We can then unpack the results:
sources = result.sources
print("Found %d sources (%d +ve, %d -ve)" % (len(sources), result.numPos,
result.numNeg))
Debugging¶
The pipetask run command-line interface
supports a flag --debug to to import debug.py from your PYTHONPATH; see
lsstDebug for more about debug.py files.
The available variables in SourceDetectionTask are:
display
If True, display the exposure of afwDisplay.Display’s frame 0. Positive detections in blue, negative detections in cyan.
If display > 1, display the convolved exposure on frame 1