MakeKernelTask¶
MakeKernelTask creates a PSF-matching kernel for two images.
Description¶
Build a Psf-matching kernel using two input images, either as MaskedImages or Exposures.
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 _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
-
class
MakeKernelTask(*args, **kwargs) Construct a kernel for PSF matching two exposures
...
- attributeconfig
Access configuration fields and retargetable subtasks.
-
method
run(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
- Field type
Initial detections used to feed stars to kernel fitting
selectMeasurement¶
- Default
- Field type
Initial measurements used to feed stars to kernel fitting
Configuration fields¶
afwBackgroundConfig¶
- Data type
lsst.meas.algorithms.subtractBackground.SubtractBackgroundConfig- Field type
Controlling the Afw background fitting
badMaskPlanes¶
- Mask planes to ignore when calculating diffim statistics
Options: NO_DATA EDGE SAT BAD CR INTRP
calculateKernelUncertainty¶
- 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¶
- 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¶
- Rejects KernelCandidates yielding bad difference image quality.
Used by BuildSingleKernelVisitor, AssessSpatialKernelVisitor. Represents average over pixels of (image/sqrt(variance)).
candidateResidualStdMax¶
- Rejects KernelCandidates yielding bad difference image quality.
Used by BuildSingleKernelVisitor, AssessSpatialKernelVisitor. Represents stddev over pixels of (image/sqrt(variance)).
checkConditionNumber¶
- 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
strChoiceField(optional)- Choices
'SVD'Use singular values
'EIGENVALUE'Use eigen values (faster)
NoneField is optional
Use singular values (SVD) or eigen values (EIGENVALUE) to determine condition number
constantVarianceWeighting¶
- Use constant variance weighting in single kernel fitting?
In some cases this is better for bright star residuals.
fitForBackground¶
Include terms (including kernel cross terms) for background in ip_diffim
fwhmExposureBuffer¶
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¶
Grid size to compute the average PSF FWHM in an exposure
iterateSingleKernel¶
- 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
strChoiceField(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
NoneField is optional
Type of basis set for PSF matching kernel.
kernelSize¶
- Number of rows/columns in the convolution kernel; should be odd-valued.
Modified by kernelSizeFwhmScaling if scaleByFwhm = true
kernelSizeFwhmScaling¶
Multiplier of the largest AL Gaussian basis sigma to get the kernel bbox (pixel) size.
kernelSizeMax¶
Maximum kernel bbox (pixel) size.
kernelSizeMin¶
Minimum kernel bbox (pixel) size.
kernelSumClipping¶
Do sigma clipping on the ensemble of kernel sums
maxConditionNumber¶
Maximum condition number for a well conditioned matrix
maxKsumSigma¶
- Maximum allowed sigma for outliers from kernel sum distribution.
Used to reject variable objects from the kernel model
maxSpatialConditionNumber¶
Maximum condition number for a well conditioned spatial matrix
maxSpatialIterations¶
Maximum number of iterations for rejecting bad KernelCandidates in spatial fitting
nStarPerCell¶
Maximum number of KernelCandidates in each SpatialCell to use in the spatial fitting. Set to -1 to use all candidates in each cell.
numPrincipalComponents¶
- Number of principal components to use for Pca basis, including the
mean kernel if requested.
scaleByFwhm¶
Scale kernelSize, alardGaussians by input Fwhm
singleKernelClipping¶
Do sigma clipping on each raw kernel candidate
sizeCellX¶
Size (rows) in pixels of each SpatialCell for spatial modeling
sizeCellY¶
Size (columns) in pixels of each SpatialCell for spatial modeling
spatialBgOrder¶
Spatial order of differential background variation
spatialKernelClipping¶
Do sigma clipping after building the spatial model
spatialKernelOrder¶
Spatial order of convolution kernel variation
spatialModelType¶
- Default
'chebyshev1'- Field type
strChoiceField(optional)- Choices
'chebyshev1'Chebyshev polynomial of the first kind
'polynomial'Standard x,y polynomial
NoneField is optional
Type of spatial functions for kernel and background
subtractMeanForPca¶
Subtract off the mean feature before doing the Pca
useAfwBackground¶
Use afw background subtraction instead of ip_diffim
useBicForKernelBasis¶
Use Bayesian Information Criterion to select the number of bases going into the kernel
useCoreStats¶
- 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¶
- 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
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:
- display
bool Enable debug display output.
- maskTransparency
float Transparency of mask planes in the output display.
- displayCandidates
bool Show all the candidates and residuals.
- displayKernelBasis
bool Show kernel basis functions.
- displayKernelMosaic
bool Show kernel realized across the image.
- plotKernelSpatialModel
bool Show coefficients of spatial model.
- showBadCandidates
bool Show the bad candidates (red) along with good (green).
- displayTemplate
bool Show full (remapped) template.
- displaySciIm
bool Show science image to match to.
- displaySpatialCells
bool Show spatial cells.
- displayDiffIm
bool Show difference image.