lsst.ip.diffim  20.0.0-7-gcda7bf1+ddb9d7f898
Public Member Functions | Static Public Member Functions | Public Attributes | Static Public Attributes | List of all members
lsst.ip.diffim.zogy.ZogyTask Class Reference
Inheritance diagram for lsst.ip.diffim.zogy.ZogyTask:

Public Member Functions

def computeCommonShape (self, *shapes)
 
def padAndFftImage (self, imgArr)
 
def inverseFftAndCropImage (self, imgArr, origSize, filtInf=None, filtNaN=None, dtype=None)
 
def prepareFullExposure (self, exposure1, exposure2, correctBackground=False)
 
def prepareSubExposure (self, bbox1=None, bbox2=None, psf1=None, psf2=None, sig1=None, sig2=None)
 
def checkCentroids (self, psfArr1, psfArr2)
 
def calculateFourierDiffim (self, psf1, im1, varPlane1, F1, varMean1, psf2, im2, varPlane2, F2, varMean2, calculateScore=True)
 
def makeDiffimSubExposure (self, ftDiff)
 
def run (self, exposure1, exposure2, calculateScore=True)
 

Static Public Member Functions

def padCenterOriginArray (A, newShape, useInverse=False, dtype=None)
 
def computePsfAtCenter (exposure)
 
def subtractImageMean (image, mask, statsControl)
 
def pixelSpaceSquare (D)
 
def getCentroid (A)
 
def calculateMaskPlane (mask1, mask2, effPsf1=None, effPsf2=None)
 
def makeKernelPsfFromArray (A)
 

Public Attributes

 freqSpaceShape
 
 statsControl
 
 F1
 
 F2
 
 psfShape1
 
 psfShape2
 
 imgShape
 
 fullExp1
 
 fullExp2
 
 fftFullIm1
 
 fftVarPl1
 
 fftFullIm2
 
 fftVarPl2
 
 subExpPsf1
 
 subExpPsf2
 
 subExpVar1
 
 subExpVar2
 
 psfFft1
 
 psfFft2
 
 subExposure1
 
 subExposure2
 

Static Public Attributes

 ConfigClass = ZogyConfig
 

Detailed Description

Task to perform ZOGY proper image subtraction. See module-level documentation for
additional details.

Definition at line 110 of file zogy.py.

Member Function Documentation

◆ calculateFourierDiffim()

def lsst.ip.diffim.zogy.ZogyTask.calculateFourierDiffim (   self,
  psf1,
  im1,
  varPlane1,
  F1,
  varMean1,
  psf2,
  im2,
  varPlane2,
  F2,
  varMean2,
  calculateScore = True 
)
Convolve and subtract two images in Fourier space.

Calculate the ZOGY proper difference image, score image and their PSFs.
All input and output arrays are in Fourier space.

Parameters
----------
psf1, psf2, im1, im2, varPlane1, varPlane2 : `numpy.ndarray` of `numpy.complex`,
shape ``self.freqSpaceShape``
    Psf, image and variance plane arrays respectively.
    All arrays must be already in Fourier space.

varMean1, varMean2: `numpy.float` > 0.
    Average per-pixel noise variance in im1, im2 respectively. Used as weighing
    of input images. Must be greater than zero.

F1, F2 : `numpy.float` > 0.
    Photometric scaling of the images. See eqs. (5)--(9)

calculateScore : `bool`, optional
    If True (default), calculate and return the detection significance (score) image.
    Otherwise, these return fields are `None`.

Returns
-------
result : `pipe.base.Struct`
    All arrays are in Fourier space and have shape ``self.freqSpaceShape``.
    - ``Fd`` : `float`
Photometric level of ``D``.
    - ``D`` : `numpy.ndarray` of `numpy.complex`
The difference image.
    - ``varplaneD`` : `numpy.ndarray` of `numpy.complex`
Variance plane of ``D``.
    - ``Pd`` : `numpy.ndarray` of `numpy.complex`
PSF of ``D``.
    - ``S`` : `numpy.ndarray` of `numpy.complex` or `None`
Significance (score) image.
    - ``varplaneS`` : `numpy.ndarray` of `numpy.complex` or `None`
Variance plane of ``S``.
    - ``Ps`` : `numpy.ndarray` of `numpy.complex`
PSF of ``S``.

Notes
-----
All array inputs and outputs are Fourier-space images with size of
`self.freqSpaceShape` in this method.

``varMean1``, ``varMean2`` quantities are part of the noise model and not to be confused
with the variance of image frequency components or with ``varPlane1``, ``varPlane2`` that
are the Fourier transform of the variance planes.

Definition at line 577 of file zogy.py.

◆ calculateMaskPlane()

def lsst.ip.diffim.zogy.ZogyTask.calculateMaskPlane (   mask1,
  mask2,
  effPsf1 = None,
  effPsf2 = None 
)
static
Calculate the mask plane of the difference image.

Parameters
----------
mask1, maks2 : `lsst.afw.image.Mask`
    Mask planes of the two exposures.


Returns
-------
diffmask : `lsst.afw.image.Mask`
    Mask plane for the subtraction result.

Notes
-----
TODO DM-25174 : Specification of effPsf1, effPsf2 are not yet supported.

Definition at line 688 of file zogy.py.

◆ checkCentroids()

def lsst.ip.diffim.zogy.ZogyTask.checkCentroids (   self,
  psfArr1,
  psfArr2 
)
Check whether two PSF array centroids' distance is within tolerance.

Parameters
----------
psfArr1, psfArr2 : `numpy.ndarray` of `float`
    Input PSF arrays to check.

Returns
-------
None

Raises
------
ValueError:
    Centroid distance exceeds `config.maxPsfCentroidDist` pixels.

Definition at line 552 of file zogy.py.

◆ computeCommonShape()

def lsst.ip.diffim.zogy.ZogyTask.computeCommonShape (   self,
shapes 
)
Calculate the common shape for FFT operations.

Set ``self.freqSpaceShape`` internally.

Parameters
----------
shapes : one 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.

Definition at line 196 of file zogy.py.

◆ computePsfAtCenter()

def lsst.ip.diffim.zogy.ZogyTask.computePsfAtCenter (   exposure)
static
Computes the PSF image at the bbox center point.

This may be at a fractional pixel position.

Parameters
----------
exposure : `lsst.afw.image.Exposure`
    Exposure with psf.

Returns
-------
psfImg : `lsst.afw.image.Image`
    Calculated psf image.

Definition at line 294 of file zogy.py.

◆ getCentroid()

def lsst.ip.diffim.zogy.ZogyTask.getCentroid (   A)
static
Calculate the centroid coordinates of a 2D array.

Parameters
----------
A : 2D `numpy.ndarray` of `float`
    The input array. Must not be all exact zero.

Notes
-----
Calculates the centroid as if the array represented a 2D geometrical shape with
weights per cell, allowing for "negative" weights. If sum equals to exact (float) zero,
calculates centroid of absolute value array.

The geometrical center is defined as (0,0), independently of the array shape.
For an odd dimension, this is the center of the center pixel,
for an even dimension, this is between the two center pixels.

Returns
-------
ycen, xcen : `tuple` of `float`

Definition at line 518 of file zogy.py.

◆ inverseFftAndCropImage()

def lsst.ip.diffim.zogy.ZogyTask.inverseFftAndCropImage (   self,
  imgArr,
  origSize,
  filtInf = None,
  filtNaN = None,
  dtype = None 
)
Inverse FFT and crop padding from image array.

Parameters
----------
imgArr : `numpy.ndarray` of `numpy.complex`
    Fourier space array representing a real image.

origSize : `tuple` of `int`
    Original unpadded shape tuple of the image to be cropped to.

filtInf, filtNan : `numpy.ndarray` of bool or int, optional
    If specified, they are used as index arrays for ``result`` to set values to
    `numpy.inf` and `numpy.nan` respectively at these positions.

dtype : `numpy.dtype`, optional
    Dtype of result array to cast return values to implicitly. This is to
    spare one array copy operation at reducing double precision to single.
    If `None` result inherits dtype of `imgArr`.

Returns
-------
result : `numpy.ndarray` of `dtype`

Definition at line 260 of file zogy.py.

◆ makeDiffimSubExposure()

def lsst.ip.diffim.zogy.ZogyTask.makeDiffimSubExposure (   self,
  ftDiff 
)
Wrap array results into Exposure objects.

Parameters
----------
ftDiff : `lsst.pipe.base.Struct`
    Result struct by `calculateFourierDiffim`.

Returns
-------
resultName : `lsst.pipe.base.Struct`
    - ``diffSubExp`` : `lsst.afw.image.Exposure`
The difference (sub)exposure. The exposure is calibrated
in its pixel values, and has a constant `PhotoCalib` object of 1.
    - ``scoreSubExp`` : `lsst.afw.image.Exposure` or `None`
The score (sub)exposure if it was calculated.

Definition at line 735 of file zogy.py.

◆ makeKernelPsfFromArray()

def lsst.ip.diffim.zogy.ZogyTask.makeKernelPsfFromArray (   A)
static
Create a non spatially varying PSF from a `numpy.ndarray`.

Parameters
----------
A : `numpy.ndarray`
    2D array to use as the new psf image. The pixels are copied.

Returns
-------
psfNew : `lsst.meas.algorithms.KernelPsf`
    The constructed PSF.

Definition at line 718 of file zogy.py.

◆ padAndFftImage()

def lsst.ip.diffim.zogy.ZogyTask.padAndFftImage (   self,
  imgArr 
)
Prepare and forward FFT an image array.

Parameters
----------
imgArr : `numpy.ndarray` of `float`
    Original array. In-place modified as `numpy.nan` and `numpy.inf` are replaced by
    array mean.

Returns
-------
result : `lsst.pipe.base.Struct`
    - ``imFft`` : `numpy.ndarray` of `numpy.complex`.
FFT of image.
    - ``filtInf``, ``filtNaN`` : `numpy.ndarray` of `bool`

Notes
-----
Save location of non-finite values for restoration, and replace them
with image mean values. Re-center and zero pad array by `padCenterOriginArray`.

Definition at line 229 of file zogy.py.

◆ padCenterOriginArray()

def lsst.ip.diffim.zogy.ZogyTask.padCenterOriginArray (   A,
  newShape,
  useInverse = False,
  dtype = None 
)
static
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` 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.
useInverse : bool, optional
    Selector of forward, add padding, operation (False)
    or its inverse, crop padding, operation (True).
dtype: `numpy.dtype`, optional
    Dtype of output array. Values must be implicitly castable to this type.
    Use to get expected result type, e.g. single float (nympy.float32).
    If not specified, dtype is inherited from ``A``.

Returns
-------
R : `numpy.ndarray`
    The padded or unpadded array with shape of `newShape` and dtype of ``dtype``.

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.


Raises
------
ValueError : ``newShape`` dimensions must be greater than or equal to the
    dimensions of ``A`` for the forward operation and less than or equal to
    for the inverse operation.

Definition at line 128 of file zogy.py.

◆ pixelSpaceSquare()

def lsst.ip.diffim.zogy.ZogyTask.pixelSpaceSquare (   D)
static
Square the argument in pixel space.

Parameters
----------
D : 2D `numpy.ndarray` of `numpy.complex`
    Fourier transform of a real valued array.

Returns
-------
R : `numpy.ndarray` of `numpy.complex`

Notes
-----
``D`` is to be inverse Fourier transformed, squared and then
forward Fourier transformed again, i.e. an autoconvolution in Fourier space.
This operation is not distributive over multiplication.
``pixelSpaceSquare(A*B) != pixelSpaceSquare(A)*pixelSpaceSquare(B)``

Definition at line 493 of file zogy.py.

◆ prepareFullExposure()

def lsst.ip.diffim.zogy.ZogyTask.prepareFullExposure (   self,
  exposure1,
  exposure2,
  correctBackground = False 
)
Performs calculations that apply to the full exposures once only in the psf matching.

Parameters
----------

correctBackground : `bool`, optional
    If True, subtracts sigma-clipped mean of exposures. The algorithm
    assumes zero expectation value at background pixels.

Returns
-------
None

Notes
-----
Set a number of instance fields with pre-calculated values. ``psfShape``,
``imgShape`` fields follow the numpy ndarray shape convention i.e. height,
width.

Raises
------
ValueError : If photometric calibrations are not available while
    ``config.scaleByCalibration`` equals True.

Definition at line 346 of file zogy.py.

◆ prepareSubExposure()

def lsst.ip.diffim.zogy.ZogyTask.prepareSubExposure (   self,
  bbox1 = None,
  bbox2 = None,
  psf1 = None,
  psf2 = None,
  sig1 = None,
  sig2 = None 
)
Perform per-sub exposure preparations.

Parameters
----------
sig1, sig2 : `float`, optional
    For debug purposes only, copnsider that the image
    may already be rescaled by the photometric calibration.
bbox1, bbox2 : `lsst.geom.Box2I`, optional
    If specified, the region of the full exposure to use.

psf1, psf2 : `lsst.afw.detection.Psf`, optional
    If specified, use given psf as the sub exposure psf. For debug purposes.

sig1, sig2 : `float`, optional
    If specified, use value as the sub-exposures' background noise sigma value.

Returns
-------
None

Notes
-----
TODO DM-23855: Performing ZOGY on a grid is not yet implemented.
Set (replace) a number of instance fields with pre-calculated values
about the current sub exposure including the FFT of the psfs.

Raises
------
ValueError: If sub-exposure dimensions do not match.

Definition at line 424 of file zogy.py.

◆ run()

def lsst.ip.diffim.zogy.ZogyTask.run (   self,
  exposure1,
  exposure2,
  calculateScore = True 
)
Task entry point to perform the zogy subtraction
of ``exposure1-exposure2``.

Parameters
----------
exposure1, exposure2 : `lsst.afw.image.Exposure`
    Two exposures warped and matched into matching pixel dimensions.
calculateScore : `bool`, optional
    If True (default), calculate the score image and return in ``scoreExp``.


Returns
-------
resultName : `lsst.pipe.base.Struct`
    - ``diffExp`` : `lsst.afw.image.Exposure`
The Zogy difference exposure (``exposure1-exposure2``).
    - ``scoreExp`` : `lsst.afw.image.Exposure` or `None`
The Zogy significance or score (S) exposure if ``calculateScore==True``.
    - ``ftDiff`` : `lsst.pipe.base.Struct`
Lower level return struct by `calculateFourierDiffim` with added
fields from the task instance. For debug purposes.

Notes
-----

The score image (``S``) is defined in the ZOGY paper as the detection
statistic value at each pixel. In the ZOGY image model, the input images
have uniform variance noises and thus ``S`` has uniform per pixel
variance (though it is not scaled to 1). In Section 3.3 of the paper,
there are "corrections" defined to the score image to correct the
significance values for some deviations from the image model. The first
of these corrections is the calculation of the _variance plane_ of ``S``
allowing for different per pixel variance values by following the
overall convolution operation on the pixels of the input images. ``S``
scaled (divided) by its corrected per pixel noise is referred as
``Scorr`` in the paper.

In the current implementation, ``scoreExp`` contains ``S`` in its image
plane and the calculated (non-uniform) variance plane of ``S`` in its
variance plane. ``scoreExp`` can be used directly for source detection
as a likelihood image by respecting its variance plane or can be divided
by the square root of the variance plane to scale detection significance
values into units of sigma.

TODO DM-23855 : Implement further correction tags to the variance of
``scoreExp``. As of DM-25174 it is not determined how important these
further correction tags are.

TODO DM-23855 : spatially varying solution on a grid is not yet implemented

Definition at line 831 of file zogy.py.

◆ subtractImageMean()

def lsst.ip.diffim.zogy.ZogyTask.subtractImageMean (   image,
  mask,
  statsControl 
)
static
In-place subtraction of sigma-clipped mean of the image.

Parameters
----------
image : `lsst.afw.image.Image`
    Image to manipulate. Its sigma clipped mean is in-place subtracted.

mask : `lsst.afw.image.Mask`
    Mask to use for ignoring pixels.

statsControl : `lsst.afw.math.StatisticsControl`
    Config of sigma clipped mean statistics calculation.

Returns
-------
None

Raises
------
ValueError : If image mean is nan.

Definition at line 316 of file zogy.py.

Member Data Documentation

◆ ConfigClass

lsst.ip.diffim.zogy.ZogyTask.ConfigClass = ZogyConfig
static

Definition at line 115 of file zogy.py.

◆ F1

lsst.ip.diffim.zogy.ZogyTask.F1

Definition at line 388 of file zogy.py.

◆ F2

lsst.ip.diffim.zogy.ZogyTask.F2

Definition at line 389 of file zogy.py.

◆ fftFullIm1

lsst.ip.diffim.zogy.ZogyTask.fftFullIm1

Definition at line 419 of file zogy.py.

◆ fftFullIm2

lsst.ip.diffim.zogy.ZogyTask.fftFullIm2

Definition at line 421 of file zogy.py.

◆ fftVarPl1

lsst.ip.diffim.zogy.ZogyTask.fftVarPl1

Definition at line 420 of file zogy.py.

◆ fftVarPl2

lsst.ip.diffim.zogy.ZogyTask.fftVarPl2

Definition at line 422 of file zogy.py.

◆ freqSpaceShape

lsst.ip.diffim.zogy.ZogyTask.freqSpaceShape

Definition at line 226 of file zogy.py.

◆ fullExp1

lsst.ip.diffim.zogy.ZogyTask.fullExp1

Definition at line 416 of file zogy.py.

◆ fullExp2

lsst.ip.diffim.zogy.ZogyTask.fullExp2

Definition at line 417 of file zogy.py.

◆ imgShape

lsst.ip.diffim.zogy.ZogyTask.imgShape

Definition at line 406 of file zogy.py.

◆ psfFft1

lsst.ip.diffim.zogy.ZogyTask.psfFft1

Definition at line 485 of file zogy.py.

◆ psfFft2

lsst.ip.diffim.zogy.ZogyTask.psfFft2

Definition at line 487 of file zogy.py.

◆ psfShape1

lsst.ip.diffim.zogy.ZogyTask.psfShape1

Definition at line 404 of file zogy.py.

◆ psfShape2

lsst.ip.diffim.zogy.ZogyTask.psfShape2

Definition at line 405 of file zogy.py.

◆ statsControl

lsst.ip.diffim.zogy.ZogyTask.statsControl

Definition at line 372 of file zogy.py.

◆ subExposure1

lsst.ip.diffim.zogy.ZogyTask.subExposure1

Definition at line 489 of file zogy.py.

◆ subExposure2

lsst.ip.diffim.zogy.ZogyTask.subExposure2

Definition at line 490 of file zogy.py.

◆ subExpPsf1

lsst.ip.diffim.zogy.ZogyTask.subExpPsf1

Definition at line 468 of file zogy.py.

◆ subExpPsf2

lsst.ip.diffim.zogy.ZogyTask.subExpPsf2

Definition at line 472 of file zogy.py.

◆ subExpVar1

lsst.ip.diffim.zogy.ZogyTask.subExpVar1

Definition at line 479 of file zogy.py.

◆ subExpVar2

lsst.ip.diffim.zogy.ZogyTask.subExpVar2

Definition at line 482 of file zogy.py.


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