lsst.ip.isr  16.0-14-g6c7ed55+17
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__ (self, args, kwargs)
 Constructor for IsrTask. More...
 
def readIsrData (self, dataRef, rawExposure)
 Retrieve necessary frames for instrument signature removal. More...
 
def run (self, ccdExposure, bias=None, linearizer=None, dark=None, flat=None, defects=None, fringes=None, bfKernel=None, camera=None, opticsTransmission=None, filterTransmission=None, sensorTransmission=None, atmosphereTransmission=None, crosstalkSources=None)
 Perform instrument signature removal on an exposure. More...
 
def runDataRef (self, sensorRef)
 
def convertIntToFloat (self, exposure)
 
def biasCorrection (self, exposure, biasExposure)
 Apply bias correction in place. More...
 
def darkCorrection (self, exposure, darkExposure, invert=False)
 Apply dark correction in place. More...
 
def doLinearize (self, detector)
 Is linearization wanted for this detector? More...
 
def updateVariance (self, ampExposure, amp, overscanImage=None)
 
def flatCorrection (self, exposure, flatExposure, invert=False)
 Apply flat correction in place. More...
 
def getIsrExposure (self, dataRef, datasetType, immediate=True)
 Retrieve a calibration dataset for removing instrument signature. More...
 
def saturationDetection (self, exposure, amp)
 Detect saturated pixels and mask them using mask plane config.saturatedMaskName, in place. More...
 
def saturationInterpolation (self, ccdExposure)
 Interpolate over saturated pixels, in place. More...
 
def suspectDetection (self, exposure, amp)
 Detect suspect pixels and mask them using mask plane config.suspectMaskName, in place. More...
 
def maskAndInterpDefect (self, ccdExposure, defectBaseList)
 Mask defects using mask plane "BAD" and interpolate over them, in place. More...
 
def maskAndInterpNan (self, exposure)
 Mask NaNs using mask plane "UNMASKEDNAN" and interpolate over them, in place. More...
 
def overscanCorrection (self, exposure, amp)
 
def addDistortionModel (self, exposure, camera)
 Update the WCS in exposure with a distortion model based on camera geometry. More...
 
def setValidPolygonIntersect (self, ccdExposure, fpPolygon)
 Set the valid polygon as the intersection of fpPolygon and the ccd corners. More...
 
def brighterFatterCorrection (self, exposure, kernel, maxIter, threshold, applyGain)
 
def attachTransmissionCurve (self, exposure, opticsTransmission=None, filterTransmission=None, sensorTransmission=None, atmosphereTransmission=None)
 
def gainContext (self, exp, image, apply)
 
def flatContext (self, exp, flat, dark=None)
 

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]*argsa list of positional arguments passed on to the Task constructor
[in]**kwargsa 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]ccdExposurelsst.afw.image.exposure of detector data
[in]biasexposure of bias frame
[in]linearizerlinearizing functor; a subclass of lsst.ip.isrFunctions.LinearizeBase
[in]darkexposure of dark frame
[in]flatexposure of flatfield
[in]defectslist of detects
[in]fringesa pipeBase.Struct with field fringes containing exposure of fringe frame or list of fringe exposure
[in]bfKernelkernel for brighter-fatter correction, an lsst.cp.pipe.makeBrighterFatterKernel.BrighterFatterKernel object
[in]cameracamera geometry, an lsst.afw.cameraGeom.Camera; used by addDistortionModel
[in]opticsTransmissiona TransmissionCurve for the optics
[in]filterTransmissiona TransmissionCurve for the filter
[in]sensorTransmissiona TransmissionCurve for the sensor
[in]atmosphereTransmissiona TransmissionCurve for the atmosphere
[in]crosstalkSourcesa defaultdict used for DECam inter-CCD crosstalk
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

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

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


Definition at line 329 of file isrTask.py.

Constructor & Destructor Documentation

◆ __init__()

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

Constructor for IsrTask.

Parameters
[in]*argsa list of positional arguments passed on to the Task constructor
[in]**kwargsa 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 403 of file isrTask.py.

Member Function Documentation

◆ addDistortionModel()

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

Update the WCS in exposure with a distortion model based on camera geometry.

Add a model for optical distortion based on geometry found in camera and the exposure's detector. The raw input exposure is assumed have a TAN WCS that has no compensation for optical distortion. Two other possibilities are:

  • The raw input exposure already has a model for optical distortion, as is the case for raw DECam data. In that case you should set config.doAddDistortionModel False.
  • The raw input exposure has a model for distortion, but it has known deficiencies severe enough to be worth fixing (e.g. because they cause problems for fitting a better WCS). In that case you should override this method with a version suitable for your raw data.
Parameters
[in,out]exposureexposure to process; must include a Detector and a WCS; the WCS of the exposure is modified in place
[in]cameracamera geometry; an lsst.afw.cameraGeom.Camera

Definition at line 990 of file isrTask.py.

◆ attachTransmissionCurve()

def lsst.ip.isr.isrTask.IsrTask.attachTransmissionCurve (   self,
  exposure,
  opticsTransmission = None,
  filterTransmission = None,
  sensorTransmission = None,
  atmosphereTransmission = None 
)
Attach a TransmissionCurve to an Exposure, given separate curves for
different components.

Parameters
----------
exposure : `lsst.afw.image.Exposure`
    Exposure object to modify by attaching the product of all given
    ``TransmissionCurves`` in post-assembly trimmed detector
    coordinates.  Must have a valid ``Detector`` attached that matches
    the detector associated with sensorTransmission.
opticsTransmission : `lsst.afw.image.TransmissionCurve`
    A ``TransmissionCurve`` that represents the throughput of the
    optics, to be evaluated in focal-plane coordinates.
filterTransmission : `lsst.afw.image.TransmissionCurve`
    A ``TransmissionCurve`` that represents the throughput of the
    filter itself, to be evaluated in focal-plane coordinates.
sensorTransmission : `lsst.afw.image.TransmissionCurve`
    A ``TransmissionCurve`` that represents the throughput of the
    sensor itself, to be evaluated in post-assembly trimmed detector
    coordinates.
atmosphereTransmission : `lsst.afw.image.TransmissionCurve`
    A ``TransmissionCurve`` that represents the throughput of the
    atmosphere, assumed to be spatially constant.

All ``TransmissionCurve`` arguments are optional; if none are provided,
the attached ``TransmissionCurve`` will have unit transmission
everywhere.

Returns
-------
combined : ``lsst.afw.image.TransmissionCurve``
    The TransmissionCurve attached to the exposure.

Definition at line 1137 of file isrTask.py.

◆ biasCorrection()

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 699 of file isrTask.py.

◆ brighterFatterCorrection()

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 1042 of file isrTask.py.

◆ convertIntToFloat()

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 684 of file isrTask.py.

◆ darkCorrection()

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

Apply dark correction in place.

Parameters
[in,out]exposureexposure to process
[in]darkExposuredark exposure of same size as exposure
[in]invertif True, remove the dark from an already-corrected image

Definition at line 707 of file isrTask.py.

◆ doLinearize()

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 728 of file isrTask.py.

◆ flatContext()

def lsst.ip.isr.isrTask.IsrTask.flatContext (   self,
  exp,
  flat,
  dark = None 
)
Context manager that applies and removes flats and darks,
if the task is configured to apply them.

Definition at line 1196 of file isrTask.py.

◆ flatCorrection()

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

Apply flat correction in place.

Parameters
[in,out]exposureexposure to process
[in]flatExposureflatfield exposure same size as exposure
[in]invertif True, unflatten an already-flattened image instead.

Definition at line 777 of file isrTask.py.

◆ gainContext()

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

Definition at line 1177 of file isrTask.py.

◆ getIsrExposure()

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 792 of file isrTask.py.

◆ maskAndInterpDefect()

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 874 of file isrTask.py.

◆ maskAndInterpNan()

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 895 of file isrTask.py.

◆ overscanCorrection()

def lsst.ip.isr.isrTask.IsrTask.overscanCorrection (   self,
  exposure,
  amp 
)
Apply overscan correction, in-place

Parameters
----------
exposure : `lsst.afw.image.Exposure`
    Exposure to process; must include both data and bias regions.
amp : `lsst.afw.table.AmpInfoRecord`
    Amplifier device data.

Results
-------
result : `lsst.pipe.base.Struct` or `NoneType`
    `None` if there is no overscan; otherwise, this is a
    result struct with components:

    - ``imageFit``: Value(s) removed from image (scalar or
`lsst.afw.image.Image`).
    - ``overscanFit``: Value(s) removed from overscan (scalar or
`lsst.afw.image.Image`).
    - ``overscanImage``: Image of the overscan, post-subtraction
(`lsst.afw.image.Image`).

Definition at line 927 of file isrTask.py.

◆ readIsrData()

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

Retrieve necessary frames for instrument signature removal.

Parameters
[in]dataRefa daf.persistence.butlerSubset.ButlerDataRef of the detector data to be processed
[in]rawExposurea 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 415 of file isrTask.py.

◆ run()

def lsst.ip.isr.isrTask.IsrTask.run (   self,
  ccdExposure,
  bias = None,
  linearizer = None,
  dark = None,
  flat = None,
  defects = None,
  fringes = None,
  bfKernel = None,
  camera = None,
  opticsTransmission = None,
  filterTransmission = None,
  sensorTransmission = None,
  atmosphereTransmission = None,
  crosstalkSources = 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]ccdExposurelsst.afw.image.exposure of detector data
[in]biasexposure of bias frame
[in]linearizerlinearizing functor; a subclass of lsst.ip.isrFunctions.LinearizeBase
[in]darkexposure of dark frame
[in]flatexposure of flatfield
[in]defectslist of detects
[in]fringesa pipeBase.Struct with field fringes containing exposure of fringe frame or list of fringe exposure
[in]bfKernelkernel for brighter-fatter correction, an lsst.cp.pipe.makeBrighterFatterKernel.BrighterFatterKernel object
[in]cameracamera geometry, an lsst.afw.cameraGeom.Camera; used by addDistortionModel
[in]opticsTransmissiona TransmissionCurve for the optics
[in]filterTransmissiona TransmissionCurve for the filter
[in]sensorTransmissiona TransmissionCurve for the sensor
[in]atmosphereTransmissiona TransmissionCurve for the atmosphere
[in]crosstalkSourcesa defaultdict used for DECam inter-CCD crosstalk
Returns
a pipeBase.Struct with field:
  • exposure

Definition at line 489 of file isrTask.py.

◆ runDataRef()

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
----------
sensorRef : `daf.persistence.butlerSubset.ButlerDataRef`
    DataRef of the detector data to be processed

Returns
-------
result : `pipeBase.Struct`
    Struct contains field "exposure," which is the exposure after application of ISR

Definition at line 652 of file isrTask.py.

◆ saturationDetection()

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 817 of file isrTask.py.

◆ saturationInterpolation()

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 833 of file isrTask.py.

◆ setValidPolygonIntersect()

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 1023 of file isrTask.py.

◆ suspectDetection()

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 849 of file isrTask.py.

◆ updateVariance()

def lsst.ip.isr.isrTask.IsrTask.updateVariance (   self,
  ampExposure,
  amp,
  overscanImage = None 
)
Set the variance plane using the amplifier gain and read noise

The read noise is calculated from the ``overscanImage`` if the
``doEmpiricalReadNoise`` option is set in the configuration; otherwise
the value from the amplifier data is used.

Parameters
----------
ampExposure : `lsst.afw.image.Exposure`
    Exposure to process.
amp : `lsst.afw.table.AmpInfoRecord` or `FakeAmp`
    Amplifier detector data.
overscanImage : `lsst.afw.image.MaskedImage`, optional.
    Image of overscan, required only for empirical read noise.

Definition at line 738 of file isrTask.py.

Member Data Documentation

◆ ConfigClass

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

Definition at line 400 of file isrTask.py.


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