lsst.ip.isr.electrostaticBrighterFatter Namespace Reference

Classes
class	CustomFFTConvolution
class	ElectrostaticBrighterFatterDistortionMatrix

Functions
	electrostaticBrighterFatterCorrection (exposure, electroBfDistortionMatrix, applyGain, gains=None)

Detailed Description

Brighter Fatter Kernel calibration definition.

Function Documentation

electrostaticBrighterFatterCorrection()

lsst.ip.isr.electrostaticBrighterFatter.electrostaticBrighterFatterCorrection	(		exposure,
			electroBfDistortionMatrix,
			applyGain,
			gains = None )

Evaluates the correction of CCD images affected by the
brighter-fatter effect, as described in
https://arxiv.org/abs/2301.03274. Requires as input the result of
an electrostatic fit to flat covariance data (or any other
determination of pixel boundary shifts under the influence of a
single electron).

The filename refers to an input tuple that contains the
boundary shifts for one electron. This file is produced by an
electrostatic fit to data extracted from flat-field statistics,
implemented in https://gitlab.in2p3.fr/astier/bfptc/tools/fit_cov.py.

Definition at line 559 of file electrostaticBrighterFatter.py.

def electrostaticBrighterFatterCorrection(exposure, electroBfDistortionMatrix, applyGain, gains=None):
    """
    Evaluates the correction of CCD images affected by the
    brighter-fatter effect, as described in
    https://arxiv.org/abs/2301.03274. Requires as input the result of
    an electrostatic fit to flat covariance data (or any other
    determination of pixel boundary shifts under the influence of a
    single electron).
 
    The filename refers to an input tuple that contains the
    boundary shifts for one electron. This file is produced by an
    electrostatic fit to data extracted from flat-field statistics,
    implemented in https://gitlab.in2p3.fr/astier/bfptc/tools/fit_cov.py.
    """
 
    # Use the symmetrize function to fill the four quadrants for each kernel
    r = electroBfDistortionMatrix.fitRange - 1
    aN = electroBfDistortionMatrix.aN
    aS = electroBfDistortionMatrix.aS
    aE = electroBfDistortionMatrix.aE
    aW = electroBfDistortionMatrix.aW
 
    # Initialize kN and kE arrays
    kN = np.zeros((2 * r + 1, 2 * r + 1))
    kE = np.zeros_like(kN)
 
    # Fill in the 4 quadrants for kN
    kN[r:, r:] = aN  # Quadrant 1 (bottom-right)
    kN[:r+1, r:] = np.flipud(aN)  # Quadrant 2 (top-right)
    kN[r:, :r+1] = np.fliplr(aS)  # Quadrant 3 (bottom-left)
    kN[:r+1, :r+1] = np.flipud(np.fliplr(aS))  # Quadrant 4 (top-left)
 
    # Fill in the 4 quadrants for kE
    kE[r:, r:] = aE  # Quadrant 1 (bottom-right)
    kE[:r+1, r:] = np.flipud(aW)  # Quadrant 2 (top-right)
    kE[r:, :r+1] = np.fliplr(aE)  # Quadrant 3 (bottom-left)
    kE[:r+1, :r+1] = np.flipud(np.fliplr(aW))  # Quadrant 4 (top-left)
 
    # Tweak the edges so that the sum rule applies.
    kN[:, 0] = -kN[:, -1]
    kE[0, :] = -kE[-1, :]
 
    # We use the normalization of Guyonnet et al. (2015),
    # which is compatible with the way the input file is produced.
    # The factor 1/2 is due to the fact that the charge distribution at the end
    # is twice the average, and the second 1/2 is due to
    # charge interpolation.
    kN *= 0.25
    kE *= 0.25
 
    # Indeed, i and j in the tuple refer to serial and parallel directions.
    # In most Python code, the image reads im[j, i], so we transpose:
    kN = kN.T
    kE = kE.T
 
    # Get the image to perform the correction
    image = exposure.getMaskedImage().getImage()
 
    # The image needs to be units of electrons/holes
    with gainContext(exposure, image, applyGain, gains):
        # Computes the correction and returns the "delta_image",
        # which should be subtracted from "im" in order to undo the BF effect.
        # The input image should be expressed in electrons
        im = image.getArray().copy()
        convolver = CustomFFTConvolution(im, kN)
        convolutions = convolver(im, [kN, kE])
 
        # The convolutions contain the boundary shifts (in pixel size units)
        # for [horizontal, vertical] boundaries.
        # We now compute the charge to move around.
        delta = np.zeros_like(im)
        boundaryCharge = np.zeros_like(im)
 
        # Horizontal boundaries (parallel direction).
        # We could use a more elaborate interpolator for estimating the
        # charge on the boundary.
        boundaryCharge[:-1, :] = im[1:, :] + im[:-1, :]
        # boundaryCharge[1:-2,:] = (9./8.)*(I[2:-1,:]+I[1:-2,:] -
        # (1./8.)*(I[0:-3,:]+I[3,:])
 
        # The charge to move around is the
        # product of the boundary shift (in pixel size units) times the
        # charge on the boundary (in charge per pixel unit).
        dq = boundaryCharge * convolutions[0]
        delta += dq
 
        # What is gained by a pixel is lost by its neighbor (the right one).
        delta[1:, :] -= dq[:-1, :]
 
        # Vertical boundaries.
        boundaryCharge = np.zeros_like(im)  # Reset to zero.
        boundaryCharge[:, :-1] = im[:, 1:] + im[:, :-1]
        dq = boundaryCharge * convolutions[1]
        delta += dq
 
        # What is gained by a pixel is lost by its neighbor.
        delta[:, 1:] -= dq[:, :-1]
 
        # TODO: One might check that delta.sum() ~ 0 (charge conservation).
 
        # Apply the correction to the original image
        exposure.image.array -= delta
 
    return exposure