lsst.cp.pipe  20.0.0-11-g716e02e+073108dc36
Public Member Functions | Static Public Attributes | List of all members
lsst.cp.pipe.ptc.MeasurePhotonTransferCurveTask Class Reference
Inheritance diagram for lsst.cp.pipe.ptc.MeasurePhotonTransferCurveTask:

Public Member Functions

def __init__ (self, *args, **kwargs)
 
def runDataRef (self, dataRef, visitPairs)
 
def fitCovariancesAstier (self, dataset, covariancesWithTagsArray)
 
def getOutputPtcDataCovAstier (self, dataset, covFits)
 
def measureMeanVarCov (self, exposure1, exposure2, region=None, covAstierRealSpace=False)
 
def computeCovDirect (self, diffImage, weightImage, maxRange)
 
def covDirectValue (self, diffImage, weightImage, dx, dy)
 
def fitNonLinearityAndBuildLinearizers (self, datasetPtc, detector, tableArray=None, log=None)
 
def fitNonLinearity (self, datasetPtc, tableArray=None)
 
def calculateLinearityResidualAndLinearizers (self, exposureTimeVector, meanSignalVector)
 
def buildLinearizerObject (self, datasetNonLinearity, detector, calibDate, linearizerType, instruName='', tableArray=None, log=None)
 
def fitPtc (self, dataset, ptcFitType)
 

Static Public Attributes

 RunnerClass = PairedVisitListTaskRunner
 
 ConfigClass = MeasurePhotonTransferCurveTaskConfig
 

Detailed Description

A class to calculate, fit, and plot a PTC from a set of flat pairs.

The Photon Transfer Curve (var(signal) vs mean(signal)) is a standard tool
used in astronomical detectors characterization (e.g., Janesick 2001,
Janesick 2007). If ptcFitType is "EXPAPPROXIMATION" or "POLYNOMIAL",  this task calculates the
PTC from a series of pairs of flat-field images; each pair taken at identical exposure
times. The difference image of each pair is formed to eliminate fixed pattern noise,
and then the variance of the difference image and the mean of the average image
are used to produce the PTC. An n-degree polynomial or the approximation in Equation
16 of Astier+19 ("The Shape of the Photon Transfer Curve of CCD sensors",
arXiv:1905.08677) can be fitted to the PTC curve. These models include
parameters such as the gain (e/DN) and readout noise.

Linearizers to correct for signal-chain non-linearity are also calculated.
The `Linearizer` class, in general, can support per-amp linearizers, but in this
task this is not supported.

If ptcFitType is "FULLCOVARIANCE", the covariances of the difference images are calculated via the
DFT methods described in Astier+19 and the variances for the PTC are given by the cov[0,0] elements
at each signal level. The full model in Equation 20 of Astier+19 is fit to the PTC to get the gain
and the noise.

Parameters
----------

*args: `list`
    Positional arguments passed to the Task constructor. None used at this
    time.
**kwargs: `dict`
    Keyword arguments passed on to the Task constructor. None used at this
    time.

Definition at line 309 of file ptc.py.

Constructor & Destructor Documentation

◆ __init__()

def lsst.cp.pipe.ptc.MeasurePhotonTransferCurveTask.__init__ (   self,
args,
**  kwargs 
)

Definition at line 348 of file ptc.py.

Member Function Documentation

◆ buildLinearizerObject()

def lsst.cp.pipe.ptc.MeasurePhotonTransferCurveTask.buildLinearizerObject (   self,
  datasetNonLinearity,
  detector,
  calibDate,
  linearizerType,
  instruName = '',
  tableArray = None,
  log = None 
)
Build linearizer object to persist.

Parameters
----------
datasetNonLinearity : `dict`
    Dictionary of `lsst.cp.pipe.ptc.LinearityResidualsAndLinearizersDataset` objects.

detector : `lsst.afw.cameraGeom.Detector`
    Detector object

calibDate : `datetime.datetime`
    Calibration date

linearizerType : `str`
    'LOOKUPTABLE', 'LINEARIZESQUARED', or 'LINEARIZEPOLYNOMIAL'

instruName : `str`, optional
    Instrument name

tableArray : `np.array`, optional
    Look-up table array with size rows=nAmps and columns=DN values

log : `lsst.log.Log`, optional
    Logger to handle messages

Returns
-------
linearizer : `lsst.ip.isr.Linearizer`
    Linearizer object

Definition at line 995 of file ptc.py.

◆ calculateLinearityResidualAndLinearizers()

def lsst.cp.pipe.ptc.MeasurePhotonTransferCurveTask.calculateLinearityResidualAndLinearizers (   self,
  exposureTimeVector,
  meanSignalVector 
)
Calculate linearity residual and fit an n-order polynomial to the mean vs time curve
to produce corrections (deviation from linear part of polynomial) for a particular amplifier
to populate LinearizeLookupTable.
Use the coefficients of this fit to calculate the correction coefficients for  LinearizePolynomial
and LinearizeSquared."

Parameters
---------

exposureTimeVector: `list` of `float`
    List of exposure times for each flat pair

meanSignalVector: `list` of `float`
    List of mean signal from diference image of flat pairs

Returns
-------
dataset : `lsst.cp.pipe.ptc.LinearityResidualsAndLinearizersDataset`
    The dataset containing the fit parameters, the NL correction coefficients, and the
    LUT row for the amplifier at hand.

Notes
-----
datase members:

dataset.polynomialLinearizerCoefficients : `list` of `float`
    Coefficients for LinearizePolynomial, where corrImage = uncorrImage + sum_i c_i uncorrImage^(2 +
    i).
    c_(j-2) = -k_j/(k_1^j) with units DN^(1-j) (c.f., Eq. 37 of 2003.05978). The units of k_j are
    DN/t^j, and they are fit from meanSignalVector = k0 + k1*exposureTimeVector +
    k2*exposureTimeVector^2 + ... + kn*exposureTimeVector^n, with
    n = "polynomialFitDegreeNonLinearity". k_0 and k_1 and degenerate with bias level and gain,
    and are not used by the non-linearity correction. Therefore, j = 2...n in the above expression
    (see `LinearizePolynomial` class in `linearize.py`.)

dataset.quadraticPolynomialLinearizerCoefficient : `float`
    Coefficient for LinearizeSquared, where corrImage = uncorrImage + c0*uncorrImage^2.
    c0 = -k2/(k1^2), where k1 and k2 are fit from
    meanSignalVector = k0 + k1*exposureTimeVector + k2*exposureTimeVector^2 +...
               + kn*exposureTimeVector^n, with n = "polynomialFitDegreeNonLinearity".

dataset.linearizerTableRow : `list` of `float`
   One dimensional array with deviation from linear part of n-order polynomial fit
   to mean vs time curve. This array will be one row (for the particular amplifier at hand)
   of the table array for LinearizeLookupTable.

dataset.meanSignalVsTimePolyFitPars  : `list` of `float`
    Parameters from n-order polynomial fit to meanSignalVector vs exposureTimeVector.

dataset.meanSignalVsTimePolyFitParsErr : `list` of `float`
    Parameters from n-order polynomial fit to meanSignalVector vs exposureTimeVector.

dataset.meanSignalVsTimePolyFitReducedChiSq  : `float`
    Reduced unweighted chi squared from polynomial fit to meanSignalVector vs exposureTimeVector.

Definition at line 889 of file ptc.py.

◆ computeCovDirect()

def lsst.cp.pipe.ptc.MeasurePhotonTransferCurveTask.computeCovDirect (   self,
  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 695 of file ptc.py.

◆ covDirectValue()

def lsst.cp.pipe.ptc.MeasurePhotonTransferCurveTask.covDirectValue (   self,
  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 745 of file ptc.py.

◆ fitCovariancesAstier()

def lsst.cp.pipe.ptc.MeasurePhotonTransferCurveTask.fitCovariancesAstier (   self,
  dataset,
  covariancesWithTagsArray 
)
Fit measured flat covariances to full model in Astier+19.

Parameters
----------
dataset : `lsst.cp.pipe.ptc.PhotonTransferCurveDataset`
    The dataset containing information such as the means, variances and exposure times.

covariancesWithTagsArray : `numpy.recarray`
    Tuple with at least (mu, cov, var, i, j, npix), where:
    mu : 0.5*(m1 + m2), where:
mu1: mean value of flat1
mu2: mean value of flat2
    cov: covariance value at lag(i, j)
    var: variance(covariance value at lag(0, 0))
    i: lag dimension
    j: lag dimension
    npix: number of pixels used for covariance calculation.

Returns
-------
dataset: `lsst.cp.pipe.ptc.PhotonTransferCurveDataset`
    This is the same dataset as the input paramter, however, it has been modified
    to include information such as the fit vectors and the fit parameters. See
    the class `PhotonTransferCurveDatase`.

Definition at line 502 of file ptc.py.

◆ fitNonLinearity()

def lsst.cp.pipe.ptc.MeasurePhotonTransferCurveTask.fitNonLinearity (   self,
  datasetPtc,
  tableArray = None 
)
Fit a polynomial to signal vs effective time curve to calculate linearity and residuals.

Parameters
----------
datasetPtc : `lsst.cp.pipe.ptc.PhotonTransferCurveDataset`
    The dataset containing the means, variances and exposure times.

tableArray : `np.array`
    Optional. Look-up table array with size rows=nAmps and columns=DN values.
    It will be modified in-place if supplied.

Returns
-------
datasetNonLinearity : `dict`
    Dictionary of `lsst.cp.pipe.ptc.LinearityResidualsAndLinearizersDataset`
    dataclasses. Each one holds the output of `calculateLinearityResidualAndLinearizers` per
    amplifier.

Definition at line 846 of file ptc.py.

◆ fitNonLinearityAndBuildLinearizers()

def lsst.cp.pipe.ptc.MeasurePhotonTransferCurveTask.fitNonLinearityAndBuildLinearizers (   self,
  datasetPtc,
  detector,
  tableArray = None,
  log = None 
)
Fit non-linearity function and build linearizer objects.

Parameters
----------
datasePtct : `lsst.cp.pipe.ptc.PhotonTransferCurveDataset`
    The dataset containing information such as the means, variances and exposure times.
    nLinearity

detector : `lsst.afw.cameraGeom.Detector`
    Detector object.

tableArray : `np.array`, optional
    Optional. Look-up table array with size rows=nAmps and columns=DN values.
    It will be modified in-place if supplied.

log : `lsst.log.Log`, optional
    Logger to handle messages.

Returns
-------
linearizer : `lsst.ip.isr.Linearizer`
    Linearizer object

Definition at line 801 of file ptc.py.

◆ fitPtc()

def lsst.cp.pipe.ptc.MeasurePhotonTransferCurveTask.fitPtc (   self,
  dataset,
  ptcFitType 
)
Fit the photon transfer curve to a polynimial or to Astier+19 approximation.

Fit the photon transfer curve with either a polynomial of the order
specified in the task config, or using the Astier approximation.

Sigma clipping is performed iteratively for the fit, as well as an
initial clipping of data points that are more than
config.initialNonLinearityExclusionThreshold away from lying on a
straight line. This other step is necessary because the photon transfer
curve turns over catastrophically at very high flux (because saturation
drops the variance to ~0) and these far outliers cause the initial fit
to fail, meaning the sigma cannot be calculated to perform the
sigma-clipping.

Parameters
----------
dataset : `lsst.cp.pipe.ptc.PhotonTransferCurveDataset`
    The dataset containing the means, variances and exposure times

ptcFitType : `str`
    Fit a 'POLYNOMIAL' (degree: 'polynomialFitDegree') or
    'EXPAPPROXIMATION' (Eq. 16 of Astier+19) to the PTC

Returns
-------
dataset: `lsst.cp.pipe.ptc.PhotonTransferCurveDataset`
    This is the same dataset as the input paramter, however, it has been modified
    to include information such as the fit vectors and the fit parameters. See
    the class `PhotonTransferCurveDatase`.

Definition at line 1143 of file ptc.py.

◆ getOutputPtcDataCovAstier()

def lsst.cp.pipe.ptc.MeasurePhotonTransferCurveTask.getOutputPtcDataCovAstier (   self,
  dataset,
  covFits 
)
Get output data for PhotonTransferCurveCovAstierDataset from CovFit objects.

Parameters
----------
dataset : `lsst.cp.pipe.ptc.PhotonTransferCurveDataset`
    The dataset containing information such as the means, variances and exposure times.

covFits: `dict`
    Dictionary of CovFit objects, with amp names as keys.

Returns
-------
dataset : `lsst.cp.pipe.ptc.PhotonTransferCurveDataset`
    This is the same dataset as the input paramter, however, it has been modified
    to include extra information such as the mask 1D array, gains, reoudout noise, measured signal,
    measured variance, modeled variance, a, and b coefficient matrices (see Astier+19) per amplifier.
    See the class `PhotonTransferCurveDatase`.

Definition at line 541 of file ptc.py.

◆ measureMeanVarCov()

def lsst.cp.pipe.ptc.MeasurePhotonTransferCurveTask.measureMeanVarCov (   self,
  exposure1,
  exposure2,
  region = None,
  covAstierRealSpace = False 
)
Calculate the mean of each of two exposures and the variance and covariance of their difference.

The variance is calculated via afwMath, and the covariance via the methods in Astier+19 (appendix A).
In theory, var = covariance[0,0]. This should be validated, and in the future, we may decide to just
keep one (covariance).

Parameters
----------
exposure1 : `lsst.afw.image.exposure.exposure.ExposureF`
    First exposure of flat field pair.

exposure2 : `lsst.afw.image.exposure.exposure.ExposureF`
    Second exposure of flat field pair.

region : `lsst.geom.Box2I`, optional
    Region of each exposure where to perform the calculations (e.g, an amplifier).

covAstierRealSpace : `bool`, optional
    Should the covariannces in Astier+19 be calculated in real space or via FFT?
    See Appendix A of Astier+19.

Returns
-------
mu : `float` or `NaN`
    0.5*(mu1 + mu2), where mu1, and mu2 are the clipped means of the regions in
    both exposures. If either mu1 or m2 are NaN's, the returned value is NaN.

varDiff : `float` or `NaN`
    Half of the clipped variance of the difference of the regions inthe two input
    exposures. If either mu1 or m2 are NaN's, the returned value is NaN.

covDiffAstier : `list` or `NaN`
    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.
    If either mu1 or m2 are NaN's, the returned value is NaN.

Definition at line 579 of file ptc.py.

◆ runDataRef()

def lsst.cp.pipe.ptc.MeasurePhotonTransferCurveTask.runDataRef (   self,
  dataRef,
  visitPairs 
)
Run the Photon Transfer Curve (PTC) measurement task.

For a dataRef (which is each detector here),
and given a list of visit pairs (postISR) at different exposure times,
measure the PTC.

Parameters
----------
dataRef : list of lsst.daf.persistence.ButlerDataRef
    dataRef for the detector for the visits to be fit.

visitPairs : `iterable` of `tuple` of `int`
    Pairs of visit numbers to be processed together

Definition at line 366 of file ptc.py.

Member Data Documentation

◆ ConfigClass

lsst.cp.pipe.ptc.MeasurePhotonTransferCurveTask.ConfigClass = MeasurePhotonTransferCurveTaskConfig
static

Definition at line 345 of file ptc.py.

◆ RunnerClass

lsst.cp.pipe.ptc.MeasurePhotonTransferCurveTask.RunnerClass = PairedVisitListTaskRunner
static

Definition at line 344 of file ptc.py.


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