Base class for Psf Matching; should not be called directly
Notes
-----
PsfMatchTask is a base class that implements the core functionality for matching the
Psfs of two images using a spatially varying Psf-matching `lsst.afw.math.LinearCombinationKernel`.
The Task requires the user to provide an instance of an `lsst.afw.math.SpatialCellSet`,
filled with `lsst.ip.diffim.KernelCandidate` instances, and a list of `lsst.afw.math.Kernels`
of basis shapes that will be used for the decomposition. If requested, the Task
also performs background matching and returns the differential background model as an
`lsst.afw.math.Kernel.SpatialFunction`.
Invoking the Task
-----------------
As a base class, this Task is not directly invoked. However, ``run()`` methods that are
implemented on derived classes will make use of the core ``_solve()`` functionality,
which defines a sequence of `lsst.afw.math.CandidateVisitor` classes that iterate
through the KernelCandidates, first building up a per-candidate solution and then
building up a spatial model from the ensemble of candidates. Sigma clipping is
performed using the mean and standard deviation of all kernel sums (to reject
variable objects), on the per-candidate substamp diffim residuals
(to indicate a bad choice of kernel basis shapes for that particular object),
and on the substamp diffim residuals using the spatial kernel fit (to indicate a bad
choice of spatial kernel order, or poor constraints on the spatial model). The
``_diagnostic()`` method logs information on the quality of the spatial fit, and also
modifies the Task metadata.
.. list-table:: Quantities set in Metadata
:header-rows: 1
* - Parameter
- Description
* - ``spatialConditionNum``
- Condition number of the spatial kernel fit
* - ``spatialKernelSum``
- Kernel sum (10^{-0.4 * ``Delta``; zeropoint}) of the spatial Psf-matching kernel
* - ``ALBasisNGauss``
- If using sum-of-Gaussian basis, the number of gaussians used
* - ``ALBasisDegGauss``
- If using sum-of-Gaussian basis, the deg of spatial variation of the Gaussians
* - ``ALBasisSigGauss``
- If using sum-of-Gaussian basis, the widths (sigma) of the Gaussians
* - ``ALKernelSize``
- If using sum-of-Gaussian basis, the kernel size
* - ``NFalsePositivesTotal``
- Total number of diaSources
* - ``NFalsePositivesRefAssociated``
- Number of diaSources that associate with the reference catalog
* - ``NFalsePositivesRefAssociated``
- Number of diaSources that associate with the source catalog
* - ``NFalsePositivesUnassociated``
- Number of diaSources that are orphans
* - ``metric_MEAN``
- Mean value of substamp diffim quality metrics across all KernelCandidates,
for both the per-candidate (LOCAL) and SPATIAL residuals
* - ``metric_MEDIAN``
- Median value of substamp diffim quality metrics across all KernelCandidates,
for both the per-candidate (LOCAL) and SPATIAL residuals
* - ``metric_STDEV``
- Standard deviation of substamp diffim quality metrics across all KernelCandidates,
for both the per-candidate (LOCAL) and SPATIAL residuals
Debug variables
---------------
The `lsst.pipe.base.cmdLineTask.CmdLineTask` command line task interface supports a
flag -d/--debug to import @b debug.py from your PYTHONPATH. The relevant contents of debug.py
for this Task include:
.. code-block:: py
import sys
import lsstDebug
def DebugInfo(name):
di = lsstDebug.getInfo(name)
if name == "lsst.ip.diffim.psfMatch":
# enable debug output
di.display = True
# display mask transparency
di.maskTransparency = 80
# show all the candidates and residuals
di.displayCandidates = True
# show kernel basis functions
di.displayKernelBasis = False
# show kernel realized across the image
di.displayKernelMosaic = True
# show coefficients of spatial model
di.plotKernelSpatialModel = False
# show fixed and spatial coefficients and coefficient histograms
di.plotKernelCoefficients = True
# show the bad candidates (red) along with good (green)
di.showBadCandidates = True
return di
lsstDebug.Info = DebugInfo
lsstDebug.frame = 1
Note that if you want additional logging info, you may add to your scripts:
.. code-block:: py
import lsst.log.utils as logUtils
logUtils.traceSetAt("ip.diffim", 4)
Definition at line 527 of file psfMatch.py.