lsst.ip.diffim g47cf500ddd+fc5bbe81e9
Loading...
Searching...
No Matches
Public Member Functions | Public Attributes | Static Public Attributes | Protected Member Functions | Static Protected Attributes | List of all members
lsst.ip.diffim.psfMatch.PsfMatchTask Class Reference
Inheritance diagram for lsst.ip.diffim.psfMatch.PsfMatchTask:
lsst.ip.diffim.makeKernel.MakeKernelTask lsst.ip.diffim.modelPsfMatch.ModelPsfMatchTask

Public Member Functions

 __init__ (self, *args, **kwargs)
 

Public Attributes

 kConfig
 
 useRegularization
 
 hMat
 

Static Public Attributes

 ConfigClass = PsfMatchConfig
 

Protected Member Functions

 _diagnostic (self, kernelCellSet, spatialSolution, spatialKernel, spatialBg)
 
 _displayDebug (self, kernelCellSet, spatialKernel, spatialBackground)
 
 _createPcaBasis (self, kernelCellSet, nStarPerCell, ps)
 
 _buildCellSet (self, *args)
 
 _solve (self, kernelCellSet, basisList, returnOnExcept=False)
 

Static Protected Attributes

str _DefaultName = "psfMatch"
 

Detailed Description

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 ``pipetask`` command line interface supports a
flag --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.utils.logging as logUtils
    logUtils.trace_set_at("lsst.ip.diffim", 4)

Definition at line 529 of file psfMatch.py.

Constructor & Destructor Documentation

◆ __init__()

lsst.ip.diffim.psfMatch.PsfMatchTask.__init__ (   self,
args,
**  kwargs 
)
Create the psf-matching Task

Parameters
----------
*args
    Arguments to be passed to ``lsst.pipe.base.task.Task.__init__``
**kwargs
    Keyword arguments to be passed to ``lsst.pipe.base.task.Task.__init__``

Notes
-----
The initialization sets the Psf-matching kernel configuration using the value of
self.config.kernel.active.  If the kernel is requested with regularization to moderate
the bias/variance tradeoff, currently only used when a delta function kernel basis
is provided, it creates a regularization matrix stored as member variable
self.hMat.

Reimplemented in lsst.ip.diffim.makeKernel.MakeKernelTask, and lsst.ip.diffim.modelPsfMatch.ModelPsfMatchTask.

Definition at line 635 of file psfMatch.py.

Member Function Documentation

◆ _buildCellSet()

lsst.ip.diffim.psfMatch.PsfMatchTask._buildCellSet (   self,
args 
)
protected
Fill a SpatialCellSet with KernelCandidates for the Psf-matching process;
override in derived classes

Reimplemented in lsst.ip.diffim.modelPsfMatch.ModelPsfMatchTask, and lsst.ip.diffim.makeKernel.MakeKernelTask.

Definition at line 875 of file psfMatch.py.

◆ _createPcaBasis()

lsst.ip.diffim.psfMatch.PsfMatchTask._createPcaBasis (   self,
  kernelCellSet,
  nStarPerCell,
  ps 
)
protected
Create Principal Component basis

If a principal component analysis is requested, typically when using a delta function basis,
perform the PCA here and return a new basis list containing the new principal components.

Parameters
----------
kernelCellSet : `lsst.afw.math.SpatialCellSet`
    a SpatialCellSet containing KernelCandidates, from which components are derived
nStarPerCell : `int`
    the number of stars per cell to visit when doing the PCA
ps : `lsst.daf.base.PropertySet`
    input property set controlling the single kernel visitor

Returns
-------
nRejectedPca : `int`
    number of KernelCandidates rejected during PCA loop
spatialBasisList : `list` of `lsst.afw.math.kernel.FixedKernel`
    basis list containing the principal shapes as Kernels

Raises
------
RuntimeError
    If the Eigenvalues sum to zero.

Definition at line 808 of file psfMatch.py.

◆ _diagnostic()

lsst.ip.diffim.psfMatch.PsfMatchTask._diagnostic (   self,
  kernelCellSet,
  spatialSolution,
  spatialKernel,
  spatialBg 
)
protected
Provide logging diagnostics on quality of spatial kernel fit

Parameters
----------
kernelCellSet : `lsst.afw.math.SpatialCellSet`
    Cellset that contains the KernelCandidates used in the fitting
spatialSolution : `lsst.ip.diffim.SpatialKernelSolution`
    KernelSolution of best-fit
spatialKernel : `lsst.afw.math.LinearCombinationKernel`
    Best-fit spatial Kernel model
spatialBg : `lsst.afw.math.Function2D`
    Best-fit spatial background model

Reimplemented in lsst.ip.diffim.modelPsfMatch.ModelPsfMatchTask.

Definition at line 664 of file psfMatch.py.

◆ _displayDebug()

lsst.ip.diffim.psfMatch.PsfMatchTask._displayDebug (   self,
  kernelCellSet,
  spatialKernel,
  spatialBackground 
)
protected
Provide visualization of the inputs and ouputs to the Psf-matching code

Parameters
----------
kernelCellSet : `lsst.afw.math.SpatialCellSet`
    The SpatialCellSet used in determining the matching kernel and background
spatialKernel : `lsst.afw.math.LinearCombinationKernel`
    Spatially varying Psf-matching kernel
spatialBackground : `lsst.afw.math.Function2D`
    Spatially varying background-matching function

Definition at line 754 of file psfMatch.py.

◆ _solve()

lsst.ip.diffim.psfMatch.PsfMatchTask._solve (   self,
  kernelCellSet,
  basisList,
  returnOnExcept = False 
)
protected
Solve for the PSF matching kernel

Parameters
----------
kernelCellSet : `lsst.afw.math.SpatialCellSet`
    a SpatialCellSet to use in determining the matching kernel
     (typically as provided by _buildCellSet)
basisList : `list` of `lsst.afw.math.kernel.FixedKernel`
    list of Kernels to be used in the decomposition of the spatially varying kernel
    (typically as provided by makeKernelBasisList)
returnOnExcept : `bool`, optional
    if True then return (None, None) if an error occurs, else raise the exception

Returns
-------
psfMatchingKernel : `lsst.afw.math.LinearCombinationKernel`
    Spatially varying Psf-matching kernel
backgroundModel : `lsst.afw.math.Function2D`
    Spatially varying background-matching function

Raises
------
RuntimeError :
    If unable to determine PSF matching kernel and ``returnOnExcept==False``.

Definition at line 881 of file psfMatch.py.

Member Data Documentation

◆ _DefaultName

str lsst.ip.diffim.psfMatch.PsfMatchTask._DefaultName = "psfMatch"
staticprotected

Definition at line 633 of file psfMatch.py.

◆ ConfigClass

lsst.ip.diffim.psfMatch.PsfMatchTask.ConfigClass = PsfMatchConfig
static

Definition at line 632 of file psfMatch.py.

◆ hMat

lsst.ip.diffim.psfMatch.PsfMatchTask.hMat

Definition at line 662 of file psfMatch.py.

◆ kConfig

lsst.ip.diffim.psfMatch.PsfMatchTask.kConfig

Definition at line 654 of file psfMatch.py.

◆ useRegularization

lsst.ip.diffim.psfMatch.PsfMatchTask.useRegularization

Definition at line 657 of file psfMatch.py.


The documentation for this class was generated from the following file: