Classes
class	CovFastFourierTransform

Functions
def	computeCovDirect (diffImage, weightImage, maxRange)

def	covDirectValue (diffImage, weightImage, dx, dy)

def	parseData (dataset)

def	fitDataFullCovariance (dataset)

def	getFitDataFromCovariances (i, j, mu, fullCov, fullCovModel, fullCovSqrtWeights, gain=1.0, divideByMu=False, returnMasked=False)

Function Documentation

◆ computeCovDirect()

def lsst.cp.pipe.ptc.astierCovPtcUtils.computeCovDirect	(	diffImage,
		weightImage,
		maxRange
	)

Compute covariances of diffImage in real space.

For lags larger than ~25, it is slower than the FFT way.
Taken from https://github.com/PierreAstier/bfptc/

Parameters
----------
diffImage : `numpy.array`
    Image to compute the covariance of.

weightImage : `numpy.array`
    Weight image of diffImage (1's and 0's for good and bad pixels, respectively).

maxRange : `int`
    Last index of the covariance to be computed.

Returns
-------
outList : `list`
    List with tuples of the form (dx, dy, var, cov, npix), where:
    dx : `int`
        Lag in x
    dy : `int`
        Lag in y
    var : `float`
        Variance at (dx, dy).
    cov : `float`
        Covariance at (dx, dy).
    nPix : `int`
        Number of pixel pairs used to evaluate var and cov.

Definition at line 122 of file astierCovPtcUtils.py.

 def computeCovDirect(diffImage, weightImage, maxRange):
     """Compute covariances of diffImage in real space.
  
     For lags larger than ~25, it is slower than the FFT way.
     Taken from https://github.com/PierreAstier/bfptc/
  
     Parameters
     ----------
     diffImage : `numpy.array`
         Image to compute the covariance of.
  
     weightImage : `numpy.array`
         Weight image of diffImage (1's and 0's for good and bad pixels, respectively).
  
     maxRange : `int`
         Last index of the covariance to be computed.
  
     Returns
     -------
     outList : `list`
         List with tuples of the form (dx, dy, var, cov, npix), where:
         dx : `int`
             Lag in x
         dy : `int`
             Lag in y
         var : `float`
             Variance at (dx, dy).
         cov : `float`
             Covariance at (dx, dy).
         nPix : `int`
             Number of pixel pairs used to evaluate var and cov.
     """
     outList = []
     var = 0
     # (dy,dx) = (0,0) has to be first
     for dy in range(maxRange + 1):
         for dx in range(0, maxRange + 1):
             if (dx*dy > 0):
                 cov1, nPix1 = covDirectValue(diffImage, weightImage, dx, dy)
                 cov2, nPix2 = covDirectValue(diffImage, weightImage, dx, -dy)
                 cov = 0.5*(cov1 + cov2)
                 nPix = nPix1 + nPix2
             else:
                 cov, nPix = covDirectValue(diffImage, weightImage, dx, dy)
             if (dx == 0 and dy == 0):
                 var = cov
             outList.append((dx, dy, var, cov, nPix))
  
     return outList
  
  

◆ covDirectValue()

def lsst.cp.pipe.ptc.astierCovPtcUtils.covDirectValue	(	diffImage,
		weightImage,
		dx,
		dy
	)

Compute covariances of diffImage in real space at lag (dx, dy).

Taken from https://github.com/PierreAstier/bfptc/ (c.f., appendix of Astier+19).

Parameters
----------
diffImage : `numpy.array`
    Image to compute the covariance of.

weightImage : `numpy.array`
    Weight image of diffImage (1's and 0's for good and bad pixels, respectively).

dx : `int`
    Lag in x.

dy : `int`
    Lag in y.

Returns
-------
cov : `float`
    Covariance at (dx, dy)

nPix : `int`
    Number of pixel pairs used to evaluate var and cov.

Definition at line 173 of file astierCovPtcUtils.py.

 def covDirectValue(diffImage, weightImage, dx, dy):
     """Compute covariances of diffImage in real space at lag (dx, dy).
  
     Taken from https://github.com/PierreAstier/bfptc/ (c.f., appendix of Astier+19).
  
     Parameters
     ----------
     diffImage : `numpy.array`
         Image to compute the covariance of.
  
     weightImage : `numpy.array`
         Weight image of diffImage (1's and 0's for good and bad pixels, respectively).
  
     dx : `int`
         Lag in x.
  
     dy : `int`
         Lag in y.
  
     Returns
     -------
     cov : `float`
         Covariance at (dx, dy)
  
     nPix : `int`
         Number of pixel pairs used to evaluate var and cov.
     """
     (nCols, nRows) = diffImage.shape
     # switching both signs does not change anything:
     # it just swaps im1 and im2 below
     if (dx < 0):
         (dx, dy) = (-dx, -dy)
     # now, we have dx >0. We have to distinguish two cases
     # depending on the sign of dy
     if dy >= 0:
         im1 = diffImage[dy:, dx:]
         w1 = weightImage[dy:, dx:]
         im2 = diffImage[:nCols - dy, :nRows - dx]
         w2 = weightImage[:nCols - dy, :nRows - dx]
     else:
         im1 = diffImage[:nCols + dy, dx:]
         w1 = weightImage[:nCols + dy, dx:]
         im2 = diffImage[-dy:, :nRows - dx]
         w2 = weightImage[-dy:, :nRows - dx]
     # use the same mask for all 3 calculations
     wAll = w1*w2
     # do not use mean() because weightImage=0 pixels would then count
     nPix = wAll.sum()
     im1TimesW = im1*wAll
     s1 = im1TimesW.sum()/nPix
     s2 = (im2*wAll).sum()/nPix
     p = (im1TimesW*im2).sum()/nPix
     cov = p - s1*s2
  
     return cov, nPix
  
  

◆ fitDataFullCovariance()

def lsst.cp.pipe.ptc.astierCovPtcUtils.fitDataFullCovariance ( dataset )

Fit data to model in Astier+19 (Eq. 20).

Parameters
----------
dataset : `lsst.ip.isr.ptcDataset.PhotonTransferCurveDataset`
    The dataset containing the means, (co)variances, and exposure times.

Returns
-------
covFitDict: `dict`
    Dictionary of CovFit objects, with amp names as keys.

covFitNoBDict: `dict`
   Dictionary of CovFit objects, with amp names as keys (b=0 in Eq. 20 of Astier+19).

Notes
-----
The parameters of the full model for C_ij(mu) ("C_ij" and "mu" in ADU^2 and ADU, respectively)
in Astier+19 (Eq. 20) are:

    "a" coefficients (r by r matrix), units: 1/e
    "b" coefficients (r by r matrix), units: 1/e
    noise matrix (r by r matrix), units: e^2
    gain, units: e/ADU

"b" appears in Eq. 20 only through the "ab" combination, which is defined in this code as "c=ab".

Definition at line 263 of file astierCovPtcUtils.py.

 def fitDataFullCovariance(dataset):
     """Fit data to model in Astier+19 (Eq. 20).
  
     Parameters
     ----------
     dataset : `lsst.ip.isr.ptcDataset.PhotonTransferCurveDataset`
         The dataset containing the means, (co)variances, and exposure times.
  
     Returns
     -------
     covFitDict: `dict`
         Dictionary of CovFit objects, with amp names as keys.
  
     covFitNoBDict: `dict`
        Dictionary of CovFit objects, with amp names as keys (b=0 in Eq. 20 of Astier+19).
  
     Notes
     -----
     The parameters of the full model for C_ij(mu) ("C_ij" and "mu" in ADU^2 and ADU, respectively)
     in Astier+19 (Eq. 20) are:
  
         "a" coefficients (r by r matrix), units: 1/e
         "b" coefficients (r by r matrix), units: 1/e
         noise matrix (r by r matrix), units: e^2
         gain, units: e/ADU
  
     "b" appears in Eq. 20 only through the "ab" combination, which is defined in this code as "c=ab".
     """
  
     covFitDict = parseData(dataset)
     covFitNoBDict = {}
     for ext, c in covFitDict.items():
         c.fitFullModel()
         covFitNoBDict[ext] = c.copy()
         c.params['c'].release()
         c.fitFullModel()
     return covFitDict, covFitNoBDict
  
  

◆ getFitDataFromCovariances()

def lsst.cp.pipe.ptc.astierCovPtcUtils.getFitDataFromCovariances	(	i,
		j,
		mu,
		fullCov,
		fullCovModel,
		fullCovSqrtWeights,
		gain = `1.0`,
		divideByMu = `False`,
		returnMasked = `False`
	)

Get measured signal and covariance, cov model, weigths, and mask at covariance lag (i, j).

Parameters
----------
i :  `int`
    Lag for covariance matrix.

j: `int`
    Lag for covariance matrix.

mu : `list`
    Mean signal values.

fullCov: `list` of `numpy.array`
    Measured covariance matrices at each mean signal level in mu.

fullCovSqrtWeights: `list` of `numpy.array`
    List of square root of measured covariances at each mean signal level in mu.

fullCovModel : `list` of `numpy.array`
    List of modeled covariances at each mean signal level in mu.

gain : `float`, optional
    Gain, in e-/ADU. If other than 1.0 (default), the returned quantities will be in
    electrons or powers of electrons.

divideByMu: `bool`, optional
    Divide returned covariance, model, and weights by the mean signal mu?

returnMasked : `bool`, optional
    Use mask (based on weights) in returned arrays (mu, covariance, and model)?

Returns
-------
mu : `numpy.array`
    list of signal values at (i, j).

covariance : `numpy.array`
    Covariance at (i, j) at each mean signal mu value (fullCov[:, i, j]).

covarianceModel : `numpy.array`
    Covariance model at (i, j).

weights : `numpy.array`
    Weights at (i, j).

maskFromWeights : `numpy.array`, optional
    Boolean mask of the covariance at (i,j), where the weights differ from 0.

Notes
-----
This function is a method of the `CovFit` class.

Definition at line 302 of file astierCovPtcUtils.py.

                               divideByMu=False, returnMasked=False):
     """Get measured signal and covariance, cov model, weigths, and mask at covariance lag (i, j).
  
     Parameters
     ----------
     i :  `int`
         Lag for covariance matrix.
  
     j: `int`
         Lag for covariance matrix.
  
     mu : `list`
         Mean signal values.
  
     fullCov: `list` of `numpy.array`
         Measured covariance matrices at each mean signal level in mu.
  
     fullCovSqrtWeights: `list` of `numpy.array`
         List of square root of measured covariances at each mean signal level in mu.
  
     fullCovModel : `list` of `numpy.array`
         List of modeled covariances at each mean signal level in mu.
  
     gain : `float`, optional
         Gain, in e-/ADU. If other than 1.0 (default), the returned quantities will be in
         electrons or powers of electrons.
  
     divideByMu: `bool`, optional
         Divide returned covariance, model, and weights by the mean signal mu?
  
     returnMasked : `bool`, optional
         Use mask (based on weights) in returned arrays (mu, covariance, and model)?
  
     Returns
     -------
     mu : `numpy.array`
         list of signal values at (i, j).
  
     covariance : `numpy.array`
         Covariance at (i, j) at each mean signal mu value (fullCov[:, i, j]).
  
     covarianceModel : `numpy.array`
         Covariance model at (i, j).
  
     weights : `numpy.array`
         Weights at (i, j).
  
     maskFromWeights : `numpy.array`, optional
         Boolean mask of the covariance at (i,j), where the weights differ from 0.
  
     Notes
     -----
     This function is a method of the `CovFit` class.
     """
     mu = np.array(mu)
     fullCov = np.array(fullCov)
     fullCovModel = np.array(fullCovModel)
     fullCovSqrtWeights = np.array(fullCovSqrtWeights)
     covariance = fullCov[:, i, j]*(gain**2)
     covarianceModel = fullCovModel[:, i, j]*(gain**2)
     weights = fullCovSqrtWeights[:, i, j]/(gain**2)
  
     maskFromWeights = weights != 0
     if returnMasked:
         weights = weights[maskFromWeights]
         covarianceModel = covarianceModel[maskFromWeights]
         mu = mu[maskFromWeights]
         covariance = covariance[maskFromWeights]
  
     if divideByMu:
         covariance /= mu
         covarianceModel /= mu
         weights *= mu
     return mu, covariance, covarianceModel, weights, maskFromWeights

◆ parseData()

def lsst.cp.pipe.ptc.astierCovPtcUtils.parseData ( dataset )

 Returns a list of CovFit objects, indexed by amp number.

Params
------
dataset : `lsst.ip.isr.ptcDataset.PhotonTransferCurveDataset`
    The PTC dataset containing the means, variances, and
    exposure times.

Returns
-------
covFitDict: `dict`
    Dictionary with amps as keys, and CovFit objects as values.

Definition at line 230 of file astierCovPtcUtils.py.

 def parseData(dataset):
     """ Returns a list of CovFit objects, indexed by amp number.
  
     Params
     ------
     dataset : `lsst.ip.isr.ptcDataset.PhotonTransferCurveDataset`
         The PTC dataset containing the means, variances, and
         exposure times.
  
     Returns
     -------
     covFitDict: `dict`
         Dictionary with amps as keys, and CovFit objects as values.
     """
  
     covFitDict = {}
     for ampName in dataset.ampNames:
         # If there is a bad amp, don't fit it
         if ampName in dataset.badAmps:
             continue
         maskAtAmp = dataset.expIdMask[ampName]
         muAtAmp = dataset.rawMeans[ampName]
         covAtAmp = dataset.covariances[ampName]
         covSqrtWeightsAtAmp = dataset.covariancesSqrtWeights[ampName]
  
         c = CovFit(muAtAmp, covAtAmp, covSqrtWeightsAtAmp, dataset.covMatrixSide, maskAtAmp)
         cc = c.copy()
         cc.initFit()  # allows to get a crude gain.
         covFitDict[ampName] = cc
  
     return covFitDict
  
  