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
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, background=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?

excludeMaskPlanes

Default
[]
Field type

str ListField

Mask planes to exclude when detecting sources.

includeThresholdMultiplier

Default
1.0
Field type

float RangeField

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

Default
True
Field type

bool Field

Grow pixels as isotropically as possible? If False, use a Manhattan metric instead.

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
'pixel_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 meaning of thresholdValue.

thresholdValue

Default
5.0
Field type

float RangeField

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

  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