DynamicDetectionTask

class lsst.meas.algorithms.DynamicDetectionTask(*args, **kwargs)

Bases: SourceDetectionTask

Detection of sources on an image with a dynamic threshold

We first detect sources using a lower threshold than normal (see config parameter prelimThresholdFactor) in order to identify good sky regions (configurable skyObjects). Then we perform forced PSF photometry on those sky regions. Using those PSF flux measurements and estimated errors, we set the threshold so that the stdev of the measurements matches the median estimated error.

Besides the usual initialisation of configurables, we also set up the forced measurement which is deliberately not represented in this Task’s configuration parameters because we’re using it as part of the algorithm and we don’t want to allow it to be modified.

Methods Summary

calculateThreshold(exposure, seed[, sigma, ...])	Calculate new threshold
detectFootprints(exposure[, doSmooth, ...])	Detect footprints with a dynamic threshold
tweakBackground(exposure, bgLevel[, bgList])	Modify the background by a constant value

Methods Documentation

calculateThreshold(exposure, seed, sigma=None, minFractionSourcesFactor=1.0, isBgTweak=False, nPixMaskErode=None, maxMaskErodeIter=10)

Calculate new threshold

This is the main functional addition to the vanilla SourceDetectionTask.

We identify sky objects and perform forced PSF photometry on them. Using those PSF flux measurements and estimated errors, we set the threshold so that the stdev of the measurements matches the median estimated error.

Parameters

exposurelsst.afw.image.Exposure

Exposure on which we’re detecting sources.

seedint

RNG seed to use for finding sky objects.

sigmafloat, optional

Gaussian sigma of smoothing kernel; if not provided, will be deduced from the exposure’s PSF.

minFractionSourcesFactorfloat

Change the fraction of required sky sources from that set in self.config.minFractionSources by this factor. NOTE: this is intended for use in the background tweak pass (the detection threshold is much lower there, so many more pixels end up marked as DETECTED or DETECTED_NEGATIVE, leaving less room for sky object placement).

isBgTweakbool

Set to True for the background tweak pass (for more helpful log messages).

nPixMaskErodeint, optional

Number of pixels by which to erode the detection masks on each iteration of best-effort sky object placement.

maxMaskErodeIterint, optional

Maximum number of iterations for the detection mask erosion.

Returns

resultlsst.pipe.base.Struct

Result struct with components:

multiplicative

Multiplicative factor to be applied to the configured detection threshold (float).

additive

Additive factor to be applied to the background level (float).

Raises

InsufficientSourcesError

Raised if the number of good sky sources found is less than the minimum fraction (self.config.minFractionSources``*``minFractionSourcesFactor) of the number requested (self.skyObjects.config.nSources).

detectFootprints(exposure, doSmooth=True, sigma=None, clearMask=True, expId=None, background=None, backgroundToPhotometricRatio=None)

Detect footprints with a dynamic threshold

This varies from the vanilla detectFootprints method because we do detection three times: first with a high threshold to detect “bright” (both positive and negative, the latter to identify very over-subtracted regions) sources for which we grow the DETECTED and DETECTED_NEGATIVE masks significantly to account for wings. Second, with a low threshold to mask all non-empty regions of the image. These two masks are combined and used to identify regions of sky uncontaminated by objects. A final round of detection is then done with the new calculated threshold.

Parameters

exposurelsst.afw.image.Exposure

Exposure to process; DETECTED{,_NEGATIVE} mask plane will be set in-place.

doSmoothbool, optional

If True, smooth the image before detection using a Gaussian of width sigma.

sigmafloat, optional

Gaussian Sigma of PSF (pixels); used for smoothing and to grow detections; if None then measure the sigma of the PSF of the exposure.

clearMaskbool, optional

Clear both DETECTED and DETECTED_NEGATIVE planes before running detection.

expIdint, optional

Exposure identifier, used as a seed for the random number generator. If absent, the seed will be the sum of the image.

backgroundlsst.afw.math.BackgroundList, optional

Background that was already subtracted from the exposure; will be modified in-place if reEstimateBackground=True.

backgroundToPhotometricRatiolsst.afw.image.Image, optional

Unused; if set will Raise.

Returns

resultslsst.pipe.base.Struct

The results Struct contains:

positive

Positive polarity footprints. (lsst.afw.detection.FootprintSet or None)

negative

Negative polarity footprints. (lsst.afw.detection.FootprintSet or None)

numPos

Number of footprints in positive or 0 if detection polarity was negative. (int)

numNeg

Number of footprints in negative or 0 if detection polarity was positive. (int)

background

Re-estimated background. None or the input background if reEstimateBackground==False. (lsst.afw.math.BackgroundList)

factor

Multiplication factor applied to the configured detection threshold. (float)

prelim

Results from preliminary detection pass. (lsst.pipe.base.Struct)

tweakBackground(exposure, bgLevel, bgList=None)

Modify the background by a constant value

Parameters

exposurelsst.afw.image.Exposure

Exposure for which to tweak background.

bgLevelfloat

Background level to remove

bgListlsst.afw.math.BackgroundList, optional

List of backgrounds to append to.

Returns

bglsst.afw.math.BackgroundMI

Constant background model.