MakeKernelTask

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

Python API summary

from lsst.ip.diffim.makeKernel import MakeKernelTask
classMakeKernelTask(*args, **kwargs)

Construct a kernel for PSF matching two exposures...

attributeconfig

Access configuration fields and retargetable subtasks.

methodrun(template, science, kernelSources, preconvolved=False)

Solve for the kernel and background model that best match two Exposures evaluated at the given source locations...

See also

See the MakeKernelTask API reference for complete details.

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

afwBackgroundConfig

Data type

lsst.meas.algorithms.subtractBackground.SubtractBackgroundConfig

Field type

ConfigField

Controlling the Afw background fitting

badMaskPlanes

Default
('NO_DATA', 'EDGE', 'SAT')
Field type

str ListField

Mask planes to ignore when calculating diffim statistics

Options: NO_DATA EDGE SAT BAD CR INTRP

calculateKernelUncertainty

Default
False
Field type

bool Field

Calculate kernel and background uncertainties for each kernel candidate?

This comes from the inverse of the covariance matrix. Warning: regularization can cause problems for this step.

candidateCoreRadius

Default
3
Field type

int Field

Radius for calculation of stats in ‘core’ of KernelCandidate diffim.

Total number of pixels used will be (2*radius)**2. This is used both for ‘core’ diffim quality as well as ranking of KernelCandidates by their total flux in this core

candidateResidualMeanMax

Default
0.25
Field type

float Field

Rejects KernelCandidates yielding bad difference image quality.

Used by BuildSingleKernelVisitor, AssessSpatialKernelVisitor. Represents average over pixels of (image/sqrt(variance)).

candidateResidualStdMax

Default
1.5
Field type

float Field

Rejects KernelCandidates yielding bad difference image quality.

Used by BuildSingleKernelVisitor, AssessSpatialKernelVisitor. Represents stddev over pixels of (image/sqrt(variance)).

checkConditionNumber

Default
False
Field type

bool Field

Test for maximum condition number when inverting a kernel matrix.

Anything above maxConditionNumber is not used and the candidate is set as BAD. Also used to truncate inverse matrix in estimateBiasedRisk. However, if you are doing any deconvolution you will want to turn this off, or use a large maxConditionNumber

conditionNumberType

Default
'EIGENVALUE'
Field type

str ChoiceField (optional)

Choices
'SVD'

Use singular values

'EIGENVALUE'

Use eigen values (faster)

None

Field is optional

Use singular values (SVD) or eigen values (EIGENVALUE) to determine condition number

constantVarianceWeighting

Default
True
Field type

bool Field

Use constant variance weighting in single kernel fitting?

In some cases this is better for bright star residuals.

detectionConfig

Data type

lsst.ip.diffim.psfMatch.DetectionConfig

Field type

ConfigField

Controlling the detection of sources for kernel building

fitForBackground

Default
False
Field type

bool Field

Include terms (including kernel cross terms) for background in ip_diffim

fwhmExposureBuffer

Default
0.05
Field type

float Field

Fractional buffer margin to be left out of all sides of the image during constructionof grid to compute average PSF FWHM in an exposure

fwhmExposureGrid

Default
10
Field type

int Field

Grid size to compute the average PSF FWHM in an exposure

iterateSingleKernel

Default
False
Field type

bool Field

Remake KernelCandidate using better variance estimate after first pass?

Primarily useful when convolving a single-depth image, otherwise not necessary.

kernel

Default
'AL'
Field type

Single-selection ConfigChoiceField

Choices
'AL'

lsst.ip.diffim.psfMatch.PsfMatchConfigAL

'DF'

lsst.ip.diffim.psfMatch.PsfMatchConfigDF

kernel type

kernelBasisSet

Default
'alard-lupton'
Field type

str ChoiceField (optional)

Choices
'alard-lupton'

Alard-Lupton sum-of-gaussians basis set, * The first term has no spatial variation * The kernel sum is conserved * You may want to turn off ‘usePcaForSpatialKernel’

'delta-function'

Delta-function kernel basis set, * You may enable the option useRegularization * You should seriously consider usePcaForSpatialKernel, which will also enable kernel sum conservation for the delta function kernels

None

Field is optional

Type of basis set for PSF matching kernel.

kernelSize

Default
21
Field type

int Field

Number of rows/columns in the convolution kernel; should be odd-valued.

Modified by kernelSizeFwhmScaling if scaleByFwhm = true

kernelSizeFwhmScaling

Default
6.0
Field type

float Field

Multiplier of the largest AL Gaussian basis sigma to get the kernel bbox (pixel) size.

kernelSizeMax

Default
35
Field type

int Field

Maximum kernel bbox (pixel) size.

kernelSizeMin

Default
21
Field type

int Field

Minimum kernel bbox (pixel) size.

kernelSumClipping

Default
True
Field type

bool Field

Do sigma clipping on the ensemble of kernel sums

maxConditionNumber

Default
50000000.0
Field type

float Field

Maximum condition number for a well conditioned matrix

maxKsumSigma

Default
3.0
Field type

float Field

Maximum allowed sigma for outliers from kernel sum distribution.

Used to reject variable objects from the kernel model

maxSpatialConditionNumber

Default
10000000000.0
Field type

float Field

Maximum condition number for a well conditioned spatial matrix

maxSpatialIterations

Default
3
Field type

int Field

Maximum number of iterations for rejecting bad KernelCandidates in spatial fitting

nStarPerCell

Default
5
Field type

int Field

Maximum number of KernelCandidates in each SpatialCell to use in the spatial fitting. Set to -1 to use all candidates in each cell.

numPrincipalComponents

Default
5
Field type

int Field

Number of principal components to use for Pca basis, including the

mean kernel if requested.

scaleByFwhm

Default
True
Field type

bool Field

Scale kernelSize, alardGaussians by input Fwhm

singleKernelClipping

Default
True
Field type

bool Field

Do sigma clipping on each raw kernel candidate

sizeCellX

Default
128
Field type

int Field

Size (rows) in pixels of each SpatialCell for spatial modeling

sizeCellY

Default
128
Field type

int Field

Size (columns) in pixels of each SpatialCell for spatial modeling

spatialBgOrder

Default
1
Field type

int Field

Spatial order of differential background variation

spatialKernelClipping

Default
True
Field type

bool Field

Do sigma clipping after building the spatial model

spatialKernelOrder

Default
2
Field type

int Field

Spatial order of convolution kernel variation

spatialModelType

Default
'chebyshev1'
Field type

str ChoiceField (optional)

Choices
'chebyshev1'

Chebyshev polynomial of the first kind

'polynomial'

Standard x,y polynomial

None

Field is optional

Type of spatial functions for kernel and background

subtractMeanForPca

Default
True
Field type

bool Field

Subtract off the mean feature before doing the Pca

useAfwBackground

Default
False
Field type

bool Field

Use afw background subtraction instead of ip_diffim

useBicForKernelBasis

Default
False
Field type

bool Field

Use Bayesian Information Criterion to select the number of bases going into the kernel

useCoreStats

Default
False
Field type

bool Field

Use the core of the footprint for the quality statistics, instead of the entire footprint.

WARNING: if there is deconvolution we probably will need to turn this off

usePcaForSpatialKernel

Default
False
Field type

bool Field

Use Pca to reduce the dimensionality of the kernel basis sets.

This is particularly useful for delta-function kernels. Functionally, after all Cells have their raw kernels determined, we run a Pca on these Kernels, re-fit the Cells using the eigenKernels and then fit those for spatial variation using the same technique as for Alard-Lupton kernels. If this option is used, the first term will have no spatial variation and the kernel sum will be conserved.

warpingConfig

Data type

lsst.afw.math._warper.WarperConfig

Field type

ConfigField

Config for warping exposures to a common alignment

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