SourceDetectionTask

SourceDetectionTask Detect positive and negative sources on an exposure and return a new table.SourceCatalog

Python API summary

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

Create the detection task. Most arguments are simply passed onto pipe.base.Task...

attributeconfig

Access configuration fields and retargetable subtasks.

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

Run source detection and create a SourceCatalog 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 lsst.pipe.base.cmdLineTask.cmdLineTask command line task interface supports a flag -d 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