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...

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

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

Navigation