lsst.ip.isr  13.0-13-gd4b2922+23
 All Classes Namespaces Files Functions Variables Typedefs Macros Groups
Public Member Functions | Static Public Attributes | List of all members
lsst.ip.isr.isrTask.IsrTask Class Reference

Apply common instrument signature correction algorithms to a raw frame. More...

Inheritance diagram for lsst.ip.isr.isrTask.IsrTask:

Public Member Functions

def __init__
 Constructor for IsrTask. More...
 
def readIsrData
 Retrieve necessary frames for instrument signature removal. More...
 
def run
 Perform instrument signature removal on an exposure. More...
 
def runDataRef
 Perform instrument signature removal on a ButlerDataRef of a Sensor. More...
 
def convertIntToFloat
 
def biasCorrection
 Apply bias correction in place. More...
 
def darkCorrection
 Apply dark correction in place. More...
 
def doLinearize
 Is linearization wanted for this detector? More...
 
def updateVariance
 Set the variance plane based on the image plane, plus amplifier gain and read noise. More...
 
def flatCorrection
 Apply flat correction in place. More...
 
def getIsrExposure
 Retrieve a calibration dataset for removing instrument signature. More...
 
def saturationDetection
 Detect saturated pixels and mask them using mask plane config.saturatedMaskName, in place. More...
 
def saturationInterpolation
 Interpolate over saturated pixels, in place. More...
 
def suspectDetection
 Detect suspect pixels and mask them using mask plane config.suspectMaskName, in place. More...
 
def maskAndInterpDefect
 Mask defects using mask plane "BAD" and interpolate over them, in place. More...
 
def maskAndInterpNan
 Mask NaNs using mask plane "UNMASKEDNAN" and interpolate over them, in place. More...
 
def overscanCorrection
 Apply overscan correction, in place. More...
 
def setValidPolygonIntersect
 Set the valid polygon as the intersection of fpPolygon and the ccd corners. More...
 
def brighterFatterCorrection
 
def gainContext
 

Static Public Attributes

 ConfigClass = IsrTaskConfig
 

Detailed Description

Apply common instrument signature correction algorithms to a raw frame.

Contents

Description

The process for correcting imaging data is very similar from camera to camera. This task provides a vanilla implementation of doing these corrections, including the ability to turn certain corrections off if they are not needed. The inputs to the primary method, run, are a raw exposure to be corrected and the calibration data products. The raw input is a single chip sized mosaic of all amps including overscans and other non-science pixels. The method runDataRef() is intended for use by a lsst.pipe.base.cmdLineTask.CmdLineTask and takes as input only a daf.persistence.butlerSubset.ButlerDataRef. This task may not meet all needs and it is expected that it will be subclassed for specific applications.

Task initialization

Constructor for IsrTask.

Parameters
[in]*args– a list of positional arguments passed on to the Task constructor
[in]**kwargs– a dictionary of keyword arguments passed on to the Task constructor Call the lsst.pipe.base.task.Task.__init__ method Then setup the assembly and fringe correction subtasks

Inputs/Outputs to the run method

Perform instrument signature removal on an exposure. Steps include:

Parameters
[in]ccdExposure– lsst.afw.image.exposure of detector data
[in]bias– exposure of bias frame
[in]linearizer– linearizing functor; a subclass of lsst.ip.isrFunctions.LinearizeBase
[in]dark– exposure of dark frame
[in]flat– exposure of flatfield
[in]defects– list of detects
[in]fringes– a pipeBase.Struct with field fringes containing exposure of fringe frame or list of fringe exposure
[in]bfKernel– kernel for brighter-fatter correction
Returns
a pipeBase.Struct with field:
  • exposure

Configuration parameters

See IsrTaskConfig

Debug variables

The command line task interface supports a flag –debug, -d to import debug.py from your PYTHONPATH; see Using lsstDebug to control debugging output for more about debug.py files.

The available variables in IsrTask are:

display
A dictionary containing debug point names as keys with frame number as value. Valid keys are:
postISRCCD
display exposure after ISR has been applied

For example, put something like

1 import lsstDebug
2 def DebugInfo(name):
3  di = lsstDebug.getInfo(name) # N.b. lsstDebug.Info(name) would call us recursively
4  if name == "lsst.ip.isrFunctions.isrTask":
5  di.display = {'postISRCCD':2}
6  return di
7 lsstDebug.Info = DebugInfo

into your debug.py file and run the commandline task with the –debug flag.


Definition at line 245 of file isrTask.py.

Constructor & Destructor Documentation

def lsst.ip.isr.isrTask.IsrTask.__init__ (   self,
  args,
  kwargs 
)

Constructor for IsrTask.

Parameters
[in]*args– a list of positional arguments passed on to the Task constructor
[in]**kwargs– a dictionary of keyword arguments passed on to the Task constructor Call the lsst.pipe.base.task.Task.__init__ method Then setup the assembly and fringe correction subtasks

Definition at line 319 of file isrTask.py.

Member Function Documentation

def lsst.ip.isr.isrTask.IsrTask.biasCorrection (   self,
  exposure,
  biasExposure 
)

Apply bias correction in place.

Parameters
[in,out]exposureexposure to process
[in]biasExposurebias exposure of same size as exposure

Definition at line 528 of file isrTask.py.

def lsst.ip.isr.isrTask.IsrTask.brighterFatterCorrection (   self,
  exposure,
  kernel,
  maxIter,
  threshold,
  applyGain 
)
Apply brighter fatter correction in place for the image

This correction takes a kernel that has been derived from flat field images to
redistribute the charge.  The gradient of the kernel is the deflection
field due to the accumulated charge.

Given the original image I(x) and the kernel K(x) we can compute the corrected image  Ic(x)
using the following equation:

Ic(x) = I(x) + 0.5*d/dx(I(x)*d/dx(int( dy*K(x-y)*I(y))))

To evaluate the derivative term we expand it as follows:

0.5 * ( d/dx(I(x))*d/dx(int(dy*K(x-y)*I(y))) + I(x)*d^2/dx^2(int(dy* K(x-y)*I(y))) )

Because we use the measured counts instead of the incident counts we apply the correction
iteratively to reconstruct the original counts and the correction.  We stop iterating when the
summed difference between the current corrected image and the one from the previous iteration
is below the threshold.  We do not require convergence because the number of iterations is
too large a computational cost.  How we define the threshold still needs to be evaluated, the
current default was shown to work reasonably well on a small set of images.  For more information
on the method see DocuShare Document-19407.

The edges as defined by the kernel are not corrected because they have spurious values
due to the convolution.

Definition at line 773 of file isrTask.py.

def lsst.ip.isr.isrTask.IsrTask.convertIntToFloat (   self,
  exposure 
)
Convert an exposure from uint16 to float, set variance plane to 1 and mask plane to 0

Definition at line 511 of file isrTask.py.

def lsst.ip.isr.isrTask.IsrTask.darkCorrection (   self,
  exposure,
  darkExposure 
)

Apply dark correction in place.

Parameters
[in,out]exposureexposure to process
[in]darkExposuredark exposure of same size as exposure

Definition at line 536 of file isrTask.py.

def lsst.ip.isr.isrTask.IsrTask.doLinearize (   self,
  detector 
)

Is linearization wanted for this detector?

Checks config.doLinearize and the linearity type of the first amplifier.

Parameters
[in]detectordetector information (an lsst.afw.cameraGeom.Detector)

Definition at line 555 of file isrTask.py.

def lsst.ip.isr.isrTask.IsrTask.flatCorrection (   self,
  exposure,
  flatExposure 
)

Apply flat correction in place.

Parameters
[in,out]exposureexposure to process
[in]flatExposureflatfield exposure same size as exposure

Definition at line 578 of file isrTask.py.

def lsst.ip.isr.isrTask.IsrTask.gainContext (   self,
  exp,
  image,
  apply 
)
Context manager that applies and removes gain

Definition at line 868 of file isrTask.py.

def lsst.ip.isr.isrTask.IsrTask.getIsrExposure (   self,
  dataRef,
  datasetType,
  immediate = True 
)

Retrieve a calibration dataset for removing instrument signature.

Parameters
[in]dataRefdata reference for exposure
[in]datasetTypetype of dataset to retrieve (e.g. 'bias', 'flat')
[in]immediateif True, disable butler proxies to enable error handling within this routine
Returns
exposure

Definition at line 591 of file isrTask.py.

def lsst.ip.isr.isrTask.IsrTask.maskAndInterpDefect (   self,
  ccdExposure,
  defectBaseList 
)

Mask defects using mask plane "BAD" and interpolate over them, in place.

Parameters
[in,out]ccdExposureexposure to process
[in]defectBaseLista list of defects to mask and interpolate
Warning
: call this after CCD assembly, since defects may cross amplifier boundaries

Definition at line 673 of file isrTask.py.

def lsst.ip.isr.isrTask.IsrTask.maskAndInterpNan (   self,
  exposure 
)

Mask NaNs using mask plane "UNMASKEDNAN" and interpolate over them, in place.

We mask and interpolate over all NaNs, including those that are masked with other bits (because those may or may not be interpolated over later, and we want to remove all NaNs). Despite this behaviour, the "UNMASKEDNAN" mask plane is used to preserve the historical name.

Parameters
[in,out]exposureexposure to process

Definition at line 694 of file isrTask.py.

def lsst.ip.isr.isrTask.IsrTask.overscanCorrection (   self,
  exposure,
  amp 
)

Apply overscan correction, in place.

Parameters
[in,out]exposureexposure to process; must include both DataSec and BiasSec pixels
[in]ampamplifier device data

Definition at line 727 of file isrTask.py.

def lsst.ip.isr.isrTask.IsrTask.readIsrData (   self,
  dataRef,
  rawExposure 
)

Retrieve necessary frames for instrument signature removal.

Parameters
[in]dataRef– a daf.persistence.butlerSubset.ButlerDataRef of the detector data to be processed
[in]rawExposure– a reference raw exposure that will later be corrected with the retrieved calibration data; should not be modified in this method.
Returns
a pipeBase.Struct with fields containing kwargs expected by run()
  • bias: exposure of bias frame
  • dark: exposure of dark frame
  • flat: exposure of flat field
  • defects: list of detects
  • fringeStruct: a pipeBase.Struct with field fringes containing exposure of fringe frame or list of fringe exposure

Definition at line 330 of file isrTask.py.

def lsst.ip.isr.isrTask.IsrTask.run (   self,
  ccdExposure,
  bias = None,
  linearizer = None,
  dark = None,
  flat = None,
  defects = None,
  fringes = None,
  bfKernel = None 
)

Perform instrument signature removal on an exposure.

Steps include:

  • Detect saturation, apply overscan correction, bias, dark and flat
  • Perform CCD assembly
  • Interpolate over defects, saturated pixels and all NaNs
Parameters
[in]ccdExposure– lsst.afw.image.exposure of detector data
[in]bias– exposure of bias frame
[in]linearizer– linearizing functor; a subclass of lsst.ip.isrFunctions.LinearizeBase
[in]dark– exposure of dark frame
[in]flat– exposure of flatfield
[in]defects– list of detects
[in]fringes– a pipeBase.Struct with field fringes containing exposure of fringe frame or list of fringe exposure
[in]bfKernel– kernel for brighter-fatter correction
Returns
a pipeBase.Struct with field:
  • exposure

Definition at line 373 of file isrTask.py.

def lsst.ip.isr.isrTask.IsrTask.runDataRef (   self,
  sensorRef 
)

Perform instrument signature removal on a ButlerDataRef of a Sensor.

  • Read in necessary detrending/isr/calibration data
  • Process raw exposure in run()
  • Persist the ISR-corrected exposure as "postISRCCD" if config.doWrite is True
Parameters
[in]sensorRef– daf.persistence.butlerSubset.ButlerDataRef of the detector data to be processed
Returns
a pipeBase.Struct with fields:
  • exposure: the exposure after application of ISR

Definition at line 488 of file isrTask.py.

def lsst.ip.isr.isrTask.IsrTask.saturationDetection (   self,
  exposure,
  amp 
)

Detect saturated pixels and mask them using mask plane config.saturatedMaskName, in place.

Parameters
[in,out]exposureexposure to process; only the amp DataSec is processed
[in]ampamplifier device data

Definition at line 616 of file isrTask.py.

def lsst.ip.isr.isrTask.IsrTask.saturationInterpolation (   self,
  ccdExposure 
)

Interpolate over saturated pixels, in place.

Parameters
[in,out]ccdExposureexposure to process
Warning
:
  • Call saturationDetection first, so that saturated pixels have been identified in the "SAT" mask.
  • Call this after CCD assembly, since saturated regions may cross amplifier boundaries

Definition at line 632 of file isrTask.py.

def lsst.ip.isr.isrTask.IsrTask.setValidPolygonIntersect (   self,
  ccdExposure,
  fpPolygon 
)

Set the valid polygon as the intersection of fpPolygon and the ccd corners.

Parameters
[in,out]ccdExposureexposure to process
[in]fpPolygonPolygon in focal plane coordinates

Definition at line 754 of file isrTask.py.

def lsst.ip.isr.isrTask.IsrTask.suspectDetection (   self,
  exposure,
  amp 
)

Detect suspect pixels and mask them using mask plane config.suspectMaskName, in place.

Suspect pixels are pixels whose value is greater than amp.getSuspectLevel(). This is intended to indicate pixels that may be affected by unknown systematics; for example if non-linearity corrections above a certain level are unstable then that would be a useful value for suspectLevel. A value of nan indicates that no such level exists and no pixels are to be masked as suspicious.

Parameters
[in,out]exposureexposure to process; only the amp DataSec is processed
[in]ampamplifier device data

Definition at line 648 of file isrTask.py.

def lsst.ip.isr.isrTask.IsrTask.updateVariance (   self,
  ampExposure,
  amp 
)

Set the variance plane based on the image plane, plus amplifier gain and read noise.

Parameters
[in,out]ampExposureexposure to process
[in]ampamplifier detector information

Definition at line 565 of file isrTask.py.

Member Data Documentation

lsst.ip.isr.isrTask.IsrTask.ConfigClass = IsrTaskConfig
static

Definition at line 316 of file isrTask.py.


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