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)
estimateVariancePlane(vplane1, vplane2, ...)	Estimate the variance planes.
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.

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, vplane2numpy.ndarray of float

Variance planes of the original (before pre-convolution or matching) exposures.

varMean1, varMean2float

Replacement average values for non-finite vplane1 and vplane2 values respectively.

c1ft, c2ftnumpy.ndarray of complex

The overall convolution that includes the matching and the afterburner in frequency space. The result of either computeScoreCorrection or computeDiffimCorrection.

Returns

vplaneDnumpy.ndarray of float

The variance plane of the difference/score images.

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

shapesone or more tuple of int

Shapes of the arrays. All must have the same dimensionality. At least one shape must be provided.

Returns

None.

Notes

For each dimension, gets the smallest even number greater than or equal to N1+N2-1 where N1 and N2 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

corrftnumpy.ndarray

The frequency space representation of the correction calculated by computeCorrection. Shape must be self.freqSpaceShape.

psfOldnumpy.ndarray

The psf of the difference image to be corrected.

Returns

correctedPsflsst.meas.algorithms.KernelPsf

The corrected psf, same shape as psfOld, sum normed to 1.

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

corrftnumpy.ndarray

The frequency space representation of the correction calculated by computeCorrection. Shape must be self.freqSpaceShape.

imgOldnumpy.ndarray

The difference image to be corrected.

Returns

imgNewnumpy.ndarray

The corrected image, same size as the input.

computeDiffimCorrection(kappa, svar, tvar)

Compute the Lupton decorrelation post-convolution kernel for decorrelating an image difference, based on the PSF-matching kernel.

Parameters

kappanumpy.ndarray of float

A matching kernel 2-d numpy.array derived from Alard & Lupton PSF matching.

svarfloat > 0.

Average variance of science image used for PSF matching.

tvarfloat > 0.

Average variance of the template (matched) image used for PSF matching.

Returns

corrftnumpy.ndarray of float

The frequency space representation of the correction. The array is real (dtype float). Shape is self.freqSpaceShape.

cnft, crftnumpy.ndarray of complex

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.

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

kappanumpy.ndarray

A matching kernel 2-d numpy.array derived from Alard & Lupton PSF matching.

svarfloat

Average variance of science image used for PSF matching (before pre-convolution).

tvarfloat

Average variance of the template (matched) image used for PSF matching.

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

Returns

corrftnumpy.ndarray of float

The frequency space representation of the correction. The array is real (dtype float). Shape is self.freqSpaceShape.

cnft, crftnumpy.ndarray of complex

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.

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, vplane2numpy.ndarray of float

Variance planes of the original (before pre-convolution or matching) exposures.

c1ft, c2ftnumpy.ndarray of complex

The overall convolution that includes the matching and the afterburner in frequency space. The result of either computeScoreCorrection or computeDiffimCorrection.

Returns

vplaneDnumpy.ndarray of float

The estimated variance plane of the difference/score image as a weighted sum of the input variances.

Notes

See DMTN-179 Section 5 about the variance plane calculations.

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

Anumpy.ndarray

An array to copy from.

newShapetuple of int

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

Returns

Rnumpy.ndarray

The padded or unpadded array with shape of newShape and the same dtype as A.

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

scienceExposurelsst.afw.image.Exposure

The original science exposure (before pre-convolution, if preConvMode==True).

templateExposurelsst.afw.image.Exposure

The original template exposure warped, but not psf-matched, to the science exposure.

subtractedExposurelsst.afw.image.Exposure

the subtracted exposure produced by ip_diffim.ImagePsfMatchTask.subtractExposures(). The subtractedExposure must inherit its PSF from exposure, see notes below.

psfMatchingKernellsst.afw.detection.Psf

An (optionally spatially-varying) PSF matching kernel produced by ip_diffim.ImagePsfMatchTask.subtractExposures().

preConvKernellsst.afw.math.Kernel, optional

If not None, then the scienceExposure was pre-convolved with (the reflection of) this kernel. Must be normalized to sum to 1. Allowed only if templateMatched==True and preConvMode==True. Defaults to the PSF of the science exposure at the image center.

xcenfloat, optional

X-pixel coordinate to use for computing constant matching kernel to use If None (default), then use the center of the image.

ycenfloat, optional

Y-pixel coordinate to use for computing constant matching kernel to use If None (default), then use the center of the image.

svarfloat, optional

Image variance for science image If None (default) then compute the variance over the entire input science image.

tvarfloat, optional

Image variance for template image If None (default) then compute the variance over the entire input template image.

templateMatchedbool, optional

If True, the template exposure was matched (convolved) to the science exposure. See also notes below.

preConvModebool, 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.

Returns

resultlsst.pipe.base.Struct

• correctedExposure : the decorrelated diffim

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) If preConvKernel is not specified, the PSF of scienceExposure is assumed as pre-convolution kernel.

The subtractedExposure is NOT updated. The returned correctedExposure 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 the scienceExposure by psfMatchingKernel during image differencing. Otherwise the scienceExposure was matched (convolved) by psfMatchingKernel. 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 of scienceExposure and templateExposure. The image plane of subtractedExposure must be at the photometric level set by the AL PSF matching in ImagePsfMatchTask.subtractExposures. The assumptions about the photometric level are controlled by the templateMatched 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.