ImagePsfMatchTask¶

ImagePsfMatchTask creates a PSF-matching kernel for two images.

Description¶

Build a Psf-matching kernel using two input images, either as MaskedImages (in which case they need to be astrometrically aligned) or Exposures (in which case astrometric alignment will happen by default but may be turned off). This requires a list of input Sources which may be provided by the calling Task; if not, the Task will perform a coarse source detection and selection for this purpose. Sources are vetted for signal-to-noise and masked pixels (in both the template and science image), and substamps around each acceptable source are extracted and used to create an instance of KernelCandidate. Each KernelCandidate is then placed within a SpatialCellSet, which is used by an ensemble of CandidateVisitor instances to build the Psf-matching kernel. These visitors include, in the order that they are called: BuildSingleKernelVisitor, KernelSumVisitor, BuildSpatialKernelVisitor, and AssessSpatialKernelVisitor.

Upon initialization, the kernel configuration is defined by self.config.kernel.active. The task creates an Warper from the subConfig self.config.kernel.active.warpingConfig. A schema for the selection and measurement of candidate KernelCandidates is defined, and used to initize subTasks selectDetection (for candidate detection) and selectMeasurement(for candidate measurement).

Sigma clipping of KernelCandidates is performed as follows:

BuildSingleKernelVisitor, using the substamp diffim residuals from the per-source kernel fit, if PsfMatchConfig.singleKernelClipping is True
KernelSumVisitor, using the mean and standard deviation of the kernel sum from all candidates, if PsfMatchConfig.kernelSumClipping is True
AssessSpatialKernelVisitor, using the substamp diffim ressiduals from the spatial kernel fit, if PsfMatchConfig.spatialKernelClipping is True

The actual solving for the kernel (and differential background model) happens in lsst.ip.diffim.PsfMatchTask._solve. This involves a loop over the SpatialCellSet that first builds the per-candidate matching kernel for the requested number of KernelCandidates per cell (PsfMatchConfig.nStarPerCell). The quality of this initial per-candidate difference image is examined, using moments of the pixel residuals in the difference image normalized by the square root of the variance(i.e. sigma); ideally this should follow a normal (0, 1) distribution, but the rejection thresholds are set by the config (PsfMatchConfig.candidateResidualMeanMax and PsfMatchConfig.candidateResidualStdMax). All candidates that pass this initial build are then examined en masse to find the mean/stdev of the kernel sums across all candidates. Objects that are significantly above or below the mean, typically due to variability or sources that are saturated in one image but not the other, are also rejected.This threshold is defined by PsfMatchConfig.maxKsumSigma. Finally, a spatial model is built using all currently-acceptable candidates, and the spatial model used to derive a second set of (spatial) residuals which are again used to reject bad candidates, using the same thresholds as above.

Invoking the Task¶

There is no run() method for this Task. Instead there are 4 methods that may be used to invoke the Psf-matching. These are matchMaskedImages, subtractMaskedImages, matchExposures, and subtractExposures.

The methods that operate on MaskedImage require that the images already be astrometrically aligned, and are the same shape. The methods that operate on Exposure allow for the input images to be misregistered and potentially be different sizes; by default a LanczosWarpingKernel is used to perform the astrometric alignment. The methods that “match” images return a Psf-matched image, while the methods that “subtract” images return a Psf-matched and template subtracted image.

See each method’s returned Struct for more details.

Python API summary¶

from lsst.ip.diffim.imagePsfMatch import ImagePsfMatchTask

classImagePsfMatchTask(*args, **kwargs): Psf-match two MaskedImages or Exposures using the sources in the images...

attributeconfig: Access configuration fields and retargetable subtasks.

Retargetable subtasks¶

selectDetection¶

Default: lsst.meas.algorithms.detection.SourceDetectionTask
Field type: ConfigurableField

Initial detections used to feed stars to kernel fitting

selectMeasurement¶

Default: lsst.meas.base.sfm.SingleFrameMeasurementTask
Field type: ConfigurableField

Initial measurements used to feed stars to kernel fitting

Configuration fields¶

autoPadPsfTo¶

Default: 1.4
Field type: float RangeField
Range: [1.0,2.0)

Minimum Science Psf dimensions as a fraction of matching kernel dimensions. If the dimensions of the Psf to be matched are less than the matching kernel dimensions * autoPadPsfTo, pad Science Psf to this size. Ignored if doAutoPadPsf=False.

doAutoPadPsf¶

Default: True
Field type: bool Field

If too small, automatically pad the science Psf? Pad to smallest dimensions appropriate for the matching kernel dimensions, as specified by autoPadPsfTo. If false, pad by the padPsfBy config.

kernel¶

Default

'AL'

Field type

Single-selection ConfigChoiceField

Choices

'AL': lsst.ip.diffim.psfMatch.PsfMatchConfigAL

kernel type

padPsfBy¶

Default: 0
Field type: int Field

Pixels (even) to pad Science Psf by before matching. Ignored if doAutoPadPsf=True

Debugging¶

The pipetask command line interface supports a --debug flag to import debug.py from your PYTHONPATH; see lsstDebug for more about debug.py files. The available variables in ImagePsfMatchTask include:

displaybool: Enable debug display output.
maskTransparencyfloat: Transparency of mask planes in the output display.
displayCandidatesbool: Show all the candidates and residuals.
displayKernelBasisbool: Show kernel basis functions.
displayKernelMosaicbool: Show kernel realized across the image.
plotKernelSpatialModelbool: Show coefficients of spatial model.
showBadCandidatesbool: Show the bad candidates (red) along with good (green).
displayTemplatebool: Show full (remapped) template.
displaySciImbool: Show science image to match to.
displaySpatialCellsbool: Show spatial cells.
displayDiffImbool: Show difference image.

Navigation