SourceDetectionTask

SourceDetectionTask detects positive and negative sources on an exposure and produces a lsst.afw.table.SourceCatalog of detected sources. 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.

Python API summary

from lsst.meas.algorithms.detection import SourceDetectionTask
classSourceDetectionTask(schema=None, **kwds)

Detect peaks and footprints of sources in an image...

attributeconfig

Access configuration fields and retargetable subtasks.

methodrun(table, exposure, doSmooth=True, sigma=None, clearMask=True, expId=None)

Detect sources and return catalog(s) of detections...

See also

See the SourceDetectionTask API reference for complete details.

Retargetable subtasks

background

Default
lsst.meas.algorithms.subtractBackground.SubtractBackgroundTask
Field type
ConfigurableField
Background re-estimation; ignored if reEstimateBackground false

tempLocalBackground

Default
lsst.meas.algorithms.subtractBackground.SubtractBackgroundTask
Field type
ConfigurableField
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

Default
lsst.meas.algorithms.subtractBackground.SubtractBackgroundTask
Field type
ConfigurableField
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

Default
0.0
Field type
float Field
Fiddle factor to add to the background; debugging only

combinedGrow

Default
True
Field type
bool Field
Grow all footprints at the same time? This allows disconnected footprints to merge.

doTempLocalBackground

Default
True
Field type
bool Field
Enable temporary local background subtraction? (see tempLocalBackground)

doTempWideBackground

Default
False
Field type
bool Field
Do temporary wide (large-scale) background subtraction before footprint detection?

includeThresholdMultiplier

Default
1.0
Field type
float RangeField
Range
[0.0,inf)
Include threshold relative to thresholdValue

isotropicGrow

Default
False
Field type
bool Field
Pixels should be grown as isotropically as possible (slower)

minPixels

Default
1
Field type
int RangeField
Range
[0,inf)
detected sources with fewer than the specified number of pixels will be ignored

nPeaksMaxSimple

Default
1
Field type
int Field
The maximum number of peaks in a Footprint before trying to replace its peaks using the temporary local background

nSigmaForKernel

Default
7.0
Field type
float Field
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

Default
2.4
Field type
float Field
Grow detections by nSigmaToGrow * [PSF RMS width]; if 0 then do not grow

reEstimateBackground

Default
True
Field type
bool Field
Estimate the background again after final source detection?

returnOriginalFootprints

Default
False
Field type
bool Field
Grow detections to set the image mask bits, but return the original (not-grown) footprints

statsMask

Default
['BAD', 'SAT', 'EDGE', 'NO_DATA']
Field type
str ListField
Mask planes to ignore when calculating statistics of image (for thresholdType=stdev)

thresholdPolarity

Default
'positive'
Field type
str ChoiceField
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
'stdev'
Field type
str ChoiceField
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 desired flavor of Threshold

thresholdValue

Default
5.0
Field type
float RangeField
Range
[0.0,inf)
Threshold for 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.fpSets.numPos,
result.fpSets.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

  1. If True, display the exposure of afwDisplay.Display’s frame 0. Positive detections in blue, negative detections in cyan.
  2. If display > 1, display the convolved exposure on frame 1