DecorrelateALKernelTask¶
- class lsst.ip.diffim.DecorrelateALKernelTask(*args, **kwargs)¶
Bases:
Task
Decorrelate the effect of convolution by Alard-Lupton matching kernel in image difference
Methods Summary
calculateVariancePlane
(vplane1, vplane2, ...)Full propagation of the variance planes of the original exposures.
computeCommonShape
(*shapes)Calculate the common shape for FFT operations.
computeCorrectedDiffimPsf
(corrft, psfOld)Compute the (decorrelated) difference image's new PSF.
computeCorrectedImage
(corrft, imgOld)Compute the decorrelated difference image.
computeDiffimCorrection
(kappa, svar, tvar)Compute the Lupton decorrelation post-convolution kernel for decorrelating an image difference, based on the PSF-matching kernel.
computeScoreCorrection
(kappa, svar, tvar, ...)Compute the correction kernel for a score image.
computeVarianceMean
(exposure)Empty (clear) the metadata for this Task and all sub-Tasks.
estimateVariancePlane
(vplane1, vplane2, ...)Estimate the variance planes.
Get metadata for all tasks.
Get the task name as a hierarchical name including parent task names.
getName
()Get the name of the task.
Get a dictionary of all tasks as a shallow copy.
makeField
(doc)Make a
lsst.pex.config.ConfigurableField
for this task.makeSubtask
(name, **keyArgs)Create a subtask as a new instance as the
name
attribute of this task.padCenterOriginArray
(A, newShape[, useInverse])Zero pad an image where the origin is at the center and replace the origin to the corner as required by the periodic input of FFT.
run
(scienceExposure, templateExposure, ...)Perform decorrelation of an image difference or of a score difference exposure.
timer
(name[, logLevel])Context manager to log performance data for an arbitrary block of code.
Methods Documentation
- calculateVariancePlane(vplane1, vplane2, varMean1, varMean2, c1ft, c2ft)¶
Full propagation of the variance planes of the original exposures.
The original variance planes of independent pixels are convolved with the image space square of the overall kernels.
- Parameters:
- vplane1, vplane2
numpy.ndarray
offloat
Variance planes of the original (before pre-convolution or matching) exposures.
- varMean1, varMean2
float
Replacement average values for non-finite
vplane1
andvplane2
values respectively.- c1ft, c2ft
numpy.ndarray
ofcomplex
The overall convolution that includes the matching and the afterburner in frequency space. The result of either
computeScoreCorrection
orcomputeDiffimCorrection
.
- vplane1, vplane2
- Returns:
- vplaneD
numpy.ndarray
offloat
The variance plane of the difference/score images.
- vplaneD
Notes
See DMTN-179 Section 5 about the variance plane calculations.
Infs and NaNs are allowed and kept in the returned array.
- computeCommonShape(*shapes)¶
Calculate the common shape for FFT operations. Set
self.freqSpaceShape
internally.- Parameters:
- Returns:
- None.
Notes
For each dimension, gets the smallest even number greater than or equal to
N1+N2-1
whereN1
andN2
are the two largest values. In case of only one shape given, rounds up to even each dimension value.
- computeCorrectedDiffimPsf(corrft, psfOld)¶
Compute the (decorrelated) difference image’s new PSF.
- Parameters:
- corrft
numpy.ndarray
The frequency space representation of the correction calculated by
computeCorrection
. Shape must beself.freqSpaceShape
.- psfOld
numpy.ndarray
The psf of the difference image to be corrected.
- corrft
- Returns:
- correctedPsf
lsst.meas.algorithms.KernelPsf
The corrected psf, same shape as
psfOld
, sum normed to 1.
- correctedPsf
Notes
There is no algorithmic guarantee that the corrected psf can meaningfully fit to the same size as the original one.
- computeCorrectedImage(corrft, imgOld)¶
Compute the decorrelated difference image.
- Parameters:
- corrft
numpy.ndarray
The frequency space representation of the correction calculated by
computeCorrection
. Shape must beself.freqSpaceShape
.- imgOld
numpy.ndarray
The difference image to be corrected.
- corrft
- Returns:
- imgNew
numpy.ndarray
The corrected image, same size as the input.
- imgNew
- computeDiffimCorrection(kappa, svar, tvar)¶
Compute the Lupton decorrelation post-convolution kernel for decorrelating an image difference, based on the PSF-matching kernel.
- Parameters:
- kappa
numpy.ndarray
offloat
A matching kernel 2-d numpy.array derived from Alard & Lupton PSF matching.
- svar
float
> 0. Average variance of science image used for PSF matching.
- tvar
float
> 0. Average variance of the template (matched) image used for PSF matching.
- kappa
- Returns:
- corrft
numpy.ndarray
offloat
The frequency space representation of the correction. The array is real (dtype float). Shape is
self.freqSpaceShape
.- cnft, crft
numpy.ndarray
ofcomplex
The overall convolution (pre-conv, PSF matching, noise correction) kernel for the science and template images, respectively for the variance plane calculations. These are intermediate results in frequency space.
- corrft
Notes
The maximum correction factor converges to
sqrt(tvar/svar)
towards high frequencies. This should be a plausible value.
- computeScoreCorrection(kappa, svar, tvar, preConvArr)¶
Compute the correction kernel for a score image.
- Parameters:
- kappa
numpy.ndarray
A matching kernel 2-d numpy.array derived from Alard & Lupton PSF matching.
- svar
float
Average variance of science image used for PSF matching (before pre-convolution).
- tvar
float
Average variance of the template (matched) image used for PSF matching.
- preConvArr
numpy.ndarray
The pre-convolution kernel of the science image. It should be the PSF of the science image or an approximation of it. It must be normed to sum 1.
- kappa
- Returns:
- corrft
numpy.ndarray
offloat
The frequency space representation of the correction. The array is real (dtype float). Shape is
self.freqSpaceShape
.- cnft, crft
numpy.ndarray
ofcomplex
The overall convolution (pre-conv, PSF matching, noise correction) kernel for the science and template images, respectively for the variance plane calculations. These are intermediate results in frequency space.
- corrft
Notes
To be precise, the science image should be _correlated_ by
preConvArray
but this does not matter for this calculation.cnft
,crft
contain the scaling factor as well.
- computeVarianceMean(exposure)¶
- static estimateVariancePlane(vplane1, vplane2, c1ft, c2ft)¶
Estimate the variance planes.
The estimation assumes that around each pixel the surrounding pixels’ sigmas within the convolution kernel are the same.
- Parameters:
- vplane1, vplane2
numpy.ndarray
offloat
Variance planes of the original (before pre-convolution or matching) exposures.
- c1ft, c2ft
numpy.ndarray
ofcomplex
The overall convolution that includes the matching and the afterburner in frequency space. The result of either
computeScoreCorrection
orcomputeDiffimCorrection
.
- vplane1, vplane2
- Returns:
- vplaneD
numpy.ndarray
offloat
The estimated variance plane of the difference/score image as a weighted sum of the input variances.
- vplaneD
Notes
See DMTN-179 Section 5 about the variance plane calculations.
- getFullMetadata() TaskMetadata ¶
Get metadata for all tasks.
- Returns:
- metadata
TaskMetadata
The keys are the full task name. Values are metadata for the top-level task and all subtasks, sub-subtasks, etc.
- metadata
Notes
The returned metadata includes timing information (if
@timer.timeMethod
is used) and any metadata set by the task. The name of each item consists of the full task name with.
replaced by:
, followed by.
and the name of the item, e.g.:topLevelTaskName:subtaskName:subsubtaskName.itemName
using
:
in the full task name disambiguates the rare situation that a task has a subtask and a metadata item with the same name.
- getFullName() str ¶
Get the task name as a hierarchical name including parent task names.
- Returns:
- fullName
str
The full name consists of the name of the parent task and each subtask separated by periods. For example:
The full name of top-level task “top” is simply “top”.
The full name of subtask “sub” of top-level task “top” is “top.sub”.
The full name of subtask “sub2” of subtask “sub” of top-level task “top” is “top.sub.sub2”.
- fullName
- getName() str ¶
Get the name of the task.
- Returns:
- taskName
str
Name of the task.
- taskName
See also
getFullName
Get the full name of the task.
- getTaskDict() dict[str, weakref.ReferenceType[lsst.pipe.base.task.Task]] ¶
Get a dictionary of all tasks as a shallow copy.
- Returns:
- taskDict
dict
Dictionary containing full task name: task object for the top-level task and all subtasks, sub-subtasks, etc.
- taskDict
- classmethod makeField(doc: str) ConfigurableField ¶
Make a
lsst.pex.config.ConfigurableField
for this task.- Parameters:
- doc
str
Help text for the field.
- doc
- Returns:
- configurableField
lsst.pex.config.ConfigurableField
A
ConfigurableField
for this task.
- configurableField
Examples
Provides a convenient way to specify this task is a subtask of another task.
Here is an example of use:
class OtherTaskConfig(lsst.pex.config.Config): aSubtask = ATaskClass.makeField("brief description of task")
- makeSubtask(name: str, **keyArgs: Any) None ¶
Create a subtask as a new instance as the
name
attribute of this task.- Parameters:
- name
str
Brief name of the subtask.
- **keyArgs
Extra keyword arguments used to construct the task. The following arguments are automatically provided and cannot be overridden:
config
.parentTask
.
- name
Notes
The subtask must be defined by
Task.config.name
, an instance ofConfigurableField
orRegistryField
.
- static padCenterOriginArray(A, newShape: tuple, useInverse=False)¶
Zero pad an image where the origin is at the center and replace the origin to the corner as required by the periodic input of FFT. Implement also the inverse operation, crop the padding and re-center data.
- Parameters:
- A
numpy.ndarray
An array to copy from.
- newShape
tuple
ofint
The dimensions of the resulting array. For padding, the resulting array must be larger than A in each dimension. For the inverse operation this must be the original, before padding size of the array.
- useInversebool, optional
Selector of forward, add padding, operation (False) or its inverse, crop padding, operation (True).
- A
- Returns:
- R
numpy.ndarray
The padded or unpadded array with shape of
newShape
and the same dtype as A.
- R
Notes
For odd dimensions, the splitting is rounded to put the center pixel into the new corner origin (0,0). This is to be consistent e.g. for a dirac delta kernel that is originally located at the center pixel.
- run(scienceExposure, templateExposure, subtractedExposure, psfMatchingKernel, preConvKernel=None, xcen=None, ycen=None, svar=None, tvar=None, templateMatched=True, preConvMode=False, **kwargs)¶
Perform decorrelation of an image difference or of a score difference exposure.
Corrects the difference or score image due to the convolution of the templateExposure with the A&L PSF matching kernel. See [DMTN-021, Equation 1](http://dmtn-021.lsst.io/#equation-1) and [DMTN-179](http://dmtn-179.lsst.io/) for details.
- Parameters:
- scienceExposure
lsst.afw.image.Exposure
The original science exposure (before pre-convolution, if
preConvMode==True
).- templateExposure
lsst.afw.image.Exposure
The original template exposure warped, but not psf-matched, to the science exposure.
- subtractedExposure
lsst.afw.image.Exposure
the subtracted exposure produced by
ip_diffim.ImagePsfMatchTask.subtractExposures()
. ThesubtractedExposure
must inherit its PSF fromexposure
, see notes below.- psfMatchingKernel
lsst.afw.detection.Psf
An (optionally spatially-varying) PSF matching kernel produced by
ip_diffim.ImagePsfMatchTask.subtractExposures()
.- preConvKernel
lsst.afw.math.Kernel
, optional If not
None
, then thescienceExposure
was pre-convolved with (the reflection of) this kernel. Must be normalized to sum to 1. Allowed only iftemplateMatched==True
andpreConvMode==True
. Defaults to the PSF of the science exposure at the image center.- xcen
float
, optional X-pixel coordinate to use for computing constant matching kernel to use If
None
(default), then use the center of the image.- ycen
float
, optional Y-pixel coordinate to use for computing constant matching kernel to use If
None
(default), then use the center of the image.- svar
float
, optional Image variance for science image If
None
(default) then compute the variance over the entire input science image.- tvar
float
, optional Image variance for template image If
None
(default) then compute the variance over the entire input template image.- templateMatched
bool
, optional If True, the template exposure was matched (convolved) to the science exposure. See also notes below.
- preConvMode
bool
, optional If True,
subtractedExposure
is assumed to be a likelihood difference image and will be noise corrected as a likelihood image.- **kwargs
Additional keyword arguments propagated from DecorrelateALKernelSpatialTask.
- scienceExposure
- Returns:
- result
lsst.pipe.base.Struct
correctedExposure
: the decorrelated diffim
- result
Notes
If
preConvMode==True
,subtractedExposure
is assumed to be a score image and the noise correction for likelihood images is applied. The resulting image is an optimal detection likelihood image when the templateExposure has noise. (See DMTN-179) IfpreConvKernel
is not specified, the PSF ofscienceExposure
is assumed as pre-convolution kernel.The
subtractedExposure
is NOT updated. The returnedcorrectedExposure
has an updated but spatially fixed PSF. It is calculated as the center of image PSF corrected by the center of image matching kernel.If
templateMatched==True
, the templateExposure was matched (convolved) to thescienceExposure
bypsfMatchingKernel
during image differencing. Otherwise thescienceExposure
was matched (convolved) bypsfMatchingKernel
. In either case, note that the original template and science images are required, not the psf-matched version.This task discards the variance plane of
subtractedExposure
and re-computes it from the variance planes ofscienceExposure
andtemplateExposure
. The image plane ofsubtractedExposure
must be at the photometric level set by the AL PSF matching inImagePsfMatchTask.subtractExposures
. The assumptions about the photometric level are controlled by thetemplateMatched
option in this task.Here we currently convert a spatially-varying matching kernel into a constant kernel, just by computing it at the center of the image (tickets DM-6243, DM-6244).
We are also using a constant accross-the-image measure of sigma (sqrt(variance)) to compute the decorrelation kernel.
TODO DM-23857 As part of the spatially varying correction implementation consider whether returning a Struct is still necessary.