lsst.ip.isr g02d81e74bb+3975d4ac1c
Loading...
Searching...
No Matches
Functions
lsst.ip.isr.isrFunctions Namespace Reference

Functions

 createPsf (fwhm)
 
 transposeMaskedImage (maskedImage)
 
 interpolateDefectList (maskedImage, defectList, fwhm, fallbackValue=None)
 
 makeThresholdMask (maskedImage, threshold, growFootprints=1, maskName='SAT')
 
 growMasks (mask, radius=0, maskNameList=['BAD'], maskValue="BAD")
 
 interpolateFromMask (maskedImage, fwhm, growSaturatedFootprints=1, maskNameList=['SAT'], fallbackValue=None)
 
 saturationCorrection (maskedImage, saturation, fwhm, growFootprints=1, interpolate=True, maskName='SAT', fallbackValue=None)
 
 trimToMatchCalibBBox (rawMaskedImage, calibMaskedImage)
 
 biasCorrection (maskedImage, biasMaskedImage, trimToFit=False)
 
 darkCorrection (maskedImage, darkMaskedImage, expScale, darkScale, invert=False, trimToFit=False)
 
 updateVariance (maskedImage, gain, readNoise)
 
 flatCorrection (maskedImage, flatMaskedImage, scalingType, userScale=1.0, invert=False, trimToFit=False)
 
 illuminationCorrection (maskedImage, illumMaskedImage, illumScale, trimToFit=True)
 
 brighterFatterCorrection (exposure, kernel, maxIter, threshold, applyGain, gains=None)
 
 transferFlux (cFunc, fStep, correctionMode=True)
 
 fluxConservingBrighterFatterCorrection (exposure, kernel, maxIter, threshold, applyGain, gains=None, correctionMode=True)
 
 gainContext (exp, image, apply, gains=None)
 
 attachTransmissionCurve (exposure, opticsTransmission=None, filterTransmission=None, sensorTransmission=None, atmosphereTransmission=None)
 
 applyGains (exposure, normalizeGains=False, ptcGains=None)
 
 widenSaturationTrails (mask)
 
 setBadRegions (exposure, badStatistic="MEDIAN")
 
 checkFilter (exposure, filterList, log)
 
 getPhysicalFilter (filterLabel, log)
 
 countMaskedPixels (maskedIm, maskPlane)
 

Function Documentation

◆ applyGains()

lsst.ip.isr.isrFunctions.applyGains ( exposure,
normalizeGains = False,
ptcGains = None )
Scale an exposure by the amplifier gains.

Parameters
----------
exposure : `lsst.afw.image.Exposure`
    Exposure to process.  The image is modified.
normalizeGains : `Bool`, optional
    If True, then amplifiers are scaled to force the median of
    each amplifier to equal the median of those medians.
ptcGains : `dict`[`str`], optional
    Dictionary keyed by amp name containing the PTC gains.

Definition at line 953 of file isrFunctions.py.

◆ attachTransmissionCurve()

lsst.ip.isr.isrFunctions.attachTransmissionCurve ( 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.

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

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

Definition at line 901 of file isrFunctions.py.

◆ biasCorrection()

lsst.ip.isr.isrFunctions.biasCorrection ( maskedImage,
biasMaskedImage,
trimToFit = False )
Apply bias correction in place.

Parameters
----------
maskedImage : `lsst.afw.image.MaskedImage`
   Image to process.  The image is modified by this method.
biasMaskedImage : `lsst.afw.image.MaskedImage`
    Bias image of the same size as ``maskedImage``
trimToFit : `Bool`, optional
    If True, raw data is symmetrically trimmed to match
    calibration size.

Raises
------
RuntimeError
    Raised if ``maskedImage`` and ``biasMaskedImage`` do not have
    the same size.

Definition at line 317 of file isrFunctions.py.

◆ brighterFatterCorrection()

lsst.ip.isr.isrFunctions.brighterFatterCorrection ( exposure,
kernel,
maxIter,
threshold,
applyGain,
gains = None )
Apply brighter fatter correction in place for the image.

Parameters
----------
exposure : `lsst.afw.image.Exposure`
    Exposure to have brighter-fatter correction applied.  Modified
    by this method.
kernel : `numpy.ndarray`
    Brighter-fatter kernel to apply.
maxIter : scalar
    Number of correction iterations to run.
threshold : scalar
    Convergence threshold in terms of the sum of absolute
    deviations between an iteration and the previous one.
applyGain : `Bool`
    If True, then the exposure values are scaled by the gain prior
    to correction.
gains : `dict` [`str`, `float`]
    A dictionary, keyed by amplifier name, of the gains to use.
    If gains is None, the nominal gains in the amplifier object are used.

Returns
-------
diff : `float`
    Final difference between iterations achieved in correction.
iteration : `int`
    Number of iterations used to calculate correction.

Notes
-----
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 490 of file isrFunctions.py.

◆ checkFilter()

lsst.ip.isr.isrFunctions.checkFilter ( exposure,
filterList,
log )
Check to see if an exposure is in a filter specified by a list.

The goal of this is to provide a unified filter checking interface
for all filter dependent stages.

Parameters
----------
exposure : `lsst.afw.image.Exposure`
    Exposure to examine.
filterList : `list` [`str`]
    List of physical_filter names to check.
log : `logging.Logger`
    Logger to handle messages.

Returns
-------
result : `bool`
    True if the exposure's filter is contained in the list.

Definition at line 1083 of file isrFunctions.py.

◆ countMaskedPixels()

lsst.ip.isr.isrFunctions.countMaskedPixels ( maskedIm,
maskPlane )
Count the number of pixels in a given mask plane.

Parameters
----------
maskedIm : `~lsst.afw.image.MaskedImage`
    Masked image to examine.
maskPlane : `str`
    Name of the mask plane to examine.

Returns
-------
nPix : `int`
    Number of pixels in the requested mask plane.

Definition at line 1155 of file isrFunctions.py.

◆ createPsf()

lsst.ip.isr.isrFunctions.createPsf ( fwhm)
Make a double Gaussian PSF.

Parameters
----------
fwhm : scalar
    FWHM of double Gaussian smoothing kernel.

Returns
-------
psf : `lsst.meas.algorithms.DoubleGaussianPsf`
    The created smoothing kernel.

Definition at line 67 of file isrFunctions.py.

◆ darkCorrection()

lsst.ip.isr.isrFunctions.darkCorrection ( maskedImage,
darkMaskedImage,
expScale,
darkScale,
invert = False,
trimToFit = False )
Apply dark correction in place.

Parameters
----------
maskedImage : `lsst.afw.image.MaskedImage`
   Image to process.  The image is modified by this method.
darkMaskedImage : `lsst.afw.image.MaskedImage`
    Dark image of the same size as ``maskedImage``.
expScale : scalar
    Dark exposure time for ``maskedImage``.
darkScale : scalar
    Dark exposure time for ``darkMaskedImage``.
invert : `Bool`, optional
    If True, re-add the dark to an already corrected image.
trimToFit : `Bool`, optional
    If True, raw data is symmetrically trimmed to match
    calibration size.

Raises
------
RuntimeError
    Raised if ``maskedImage`` and ``darkMaskedImage`` do not have
    the same size.

Notes
-----
The dark correction is applied by calculating:
    maskedImage -= dark * expScaling / darkScaling

Definition at line 346 of file isrFunctions.py.

◆ flatCorrection()

lsst.ip.isr.isrFunctions.flatCorrection ( maskedImage,
flatMaskedImage,
scalingType,
userScale = 1.0,
invert = False,
trimToFit = False )
Apply flat correction in place.

Parameters
----------
maskedImage : `lsst.afw.image.MaskedImage`
    Image to process.  The image is modified.
flatMaskedImage : `lsst.afw.image.MaskedImage`
    Flat image of the same size as ``maskedImage``
scalingType : str
    Flat scale computation method.  Allowed values are 'MEAN',
    'MEDIAN', or 'USER'.
userScale : scalar, optional
    Scale to use if ``scalingType='USER'``.
invert : `Bool`, optional
    If True, unflatten an already flattened image.
trimToFit : `Bool`, optional
    If True, raw data is symmetrically trimmed to match
    calibration size.

Raises
------
RuntimeError
    Raised if ``maskedImage`` and ``flatMaskedImage`` do not have
    the same size or if ``scalingType`` is not an allowed value.

Definition at line 408 of file isrFunctions.py.

◆ fluxConservingBrighterFatterCorrection()

lsst.ip.isr.isrFunctions.fluxConservingBrighterFatterCorrection ( exposure,
kernel,
maxIter,
threshold,
applyGain,
gains = None,
correctionMode = True )
Apply brighter fatter correction in place for the image.

This version presents a modified version of the algorithm
found in ``lsst.ip.isr.isrFunctions.brighterFatterCorrection``
which conserves the image flux, resulting in improved
correction of the cores of stars. The convolution has also been
modified to mitigate edge effects.

Parameters
----------
exposure : `lsst.afw.image.Exposure`
    Exposure to have brighter-fatter correction applied.  Modified
    by this method.
kernel : `numpy.ndarray`
    Brighter-fatter kernel to apply.
maxIter : scalar
    Number of correction iterations to run.
threshold : scalar
    Convergence threshold in terms of the sum of absolute
    deviations between an iteration and the previous one.
applyGain : `Bool`
    If True, then the exposure values are scaled by the gain prior
    to correction.
gains : `dict` [`str`, `float`]
    A dictionary, keyed by amplifier name, of the gains to use.
    If gains is None, the nominal gains in the amplifier object are used.
correctionMode : `Bool`
    If True (default) the function applies correction for BFE.  If False,
    the code can instead be used to generate a simulation of BFE (sign
    change in the direction of the effect)

Returns
-------
diff : `float`
    Final difference between iterations achieved in correction.
iteration : `int`
    Number of iterations used to calculate correction.

Notes
-----
Modified version of ``lsst.ip.isr.isrFunctions.brighterFatterCorrection``.

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))))

Improved algorithm at this step applies the divergence theorem to
obtain a pixelised correction.

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.

Edges are handled in the convolution by padding.  This is still not
a physical model for the edge, but avoids discontinuity in the correction.

Author of modified version: Lance.Miller@physics.ox.ac.uk
(see DM-38555).

Definition at line 699 of file isrFunctions.py.

◆ gainContext()

lsst.ip.isr.isrFunctions.gainContext ( exp,
image,
apply,
gains = None )
Context manager that applies and removes gain.

Parameters
----------
exp : `lsst.afw.image.Exposure`
    Exposure to apply/remove gain.
image : `lsst.afw.image.Image`
    Image to apply/remove gain.
apply : `Bool`
    If True, apply and remove the amplifier gain.
gains : `dict` [`str`, `float`]
    A dictionary, keyed by amplifier name, of the gains to use.
    If gains is None, the nominal gains in the amplifier object are used.

Yields
------
exp : `lsst.afw.image.Exposure`
    Exposure with the gain applied.

Definition at line 849 of file isrFunctions.py.

◆ getPhysicalFilter()

lsst.ip.isr.isrFunctions.getPhysicalFilter ( filterLabel,
log )
Get the physical filter label associated with the given filterLabel.

If ``filterLabel`` is `None` or there is no physicalLabel attribute
associated with the given ``filterLabel``, the returned label will be
"Unknown".

Parameters
----------
filterLabel : `lsst.afw.image.FilterLabel`
    The `lsst.afw.image.FilterLabel` object from which to derive the
    physical filter label.
log : `logging.Logger`
    Logger to handle messages.

Returns
-------
physicalFilter : `str`
    The value returned by the physicalLabel attribute of ``filterLabel`` if
    it exists, otherwise set to \"Unknown\".

Definition at line 1122 of file isrFunctions.py.

◆ growMasks()

lsst.ip.isr.isrFunctions.growMasks ( mask,
radius = 0,
maskNameList = ['BAD'],
maskValue = "BAD" )
Grow a mask by an amount and add to the requested plane.

Parameters
----------
mask : `lsst.afw.image.Mask`
    Mask image to process.
radius : scalar
    Amount to grow the mask.
maskNameList : `str` or `list` [`str`]
    Mask names that should be grown.
maskValue : `str`
    Mask plane to assign the newly masked pixels to.

Definition at line 169 of file isrFunctions.py.

◆ illuminationCorrection()

lsst.ip.isr.isrFunctions.illuminationCorrection ( maskedImage,
illumMaskedImage,
illumScale,
trimToFit = True )
Apply illumination correction in place.

Parameters
----------
maskedImage : `lsst.afw.image.MaskedImage`
    Image to process.  The image is modified.
illumMaskedImage : `lsst.afw.image.MaskedImage`
    Illumination correction image of the same size as ``maskedImage``.
illumScale : scalar
    Scale factor for the illumination correction.
trimToFit : `Bool`, optional
    If True, raw data is symmetrically trimmed to match
    calibration size.

Raises
------
RuntimeError
    Raised if ``maskedImage`` and ``illumMaskedImage`` do not have
    the same size.

Definition at line 459 of file isrFunctions.py.

◆ interpolateDefectList()

lsst.ip.isr.isrFunctions.interpolateDefectList ( maskedImage,
defectList,
fwhm,
fallbackValue = None )
Interpolate over defects specified in a defect list.

Parameters
----------
maskedImage : `lsst.afw.image.MaskedImage`
    Image to process.
defectList : `lsst.meas.algorithms.Defects`
    List of defects to interpolate over.
fwhm : `float`
    FWHM of double Gaussian smoothing kernel.
fallbackValue : scalar, optional
    Fallback value if an interpolated value cannot be determined.
    If None, then the clipped mean of the image is used.

Notes
-----
The ``fwhm`` parameter is used to create a PSF, but the underlying
interpolation code (`lsst.meas.algorithms.interpolateOverDefects`) does
not currently make use of this information.

Definition at line 104 of file isrFunctions.py.

◆ interpolateFromMask()

lsst.ip.isr.isrFunctions.interpolateFromMask ( maskedImage,
fwhm,
growSaturatedFootprints = 1,
maskNameList = ['SAT'],
fallbackValue = None )
Interpolate over defects identified by a particular set of mask planes.

Parameters
----------
maskedImage : `lsst.afw.image.MaskedImage`
    Image to process.
fwhm : `float`
    FWHM of double Gaussian smoothing kernel.
growSaturatedFootprints : scalar, optional
    Number of pixels to grow footprints for saturated pixels.
maskNameList : `List` of `str`, optional
    Mask plane name.
fallbackValue : scalar, optional
    Value of last resort for interpolation.

Notes
-----
The ``fwhm`` parameter is used to create a PSF, but the underlying
interpolation code (`lsst.meas.algorithms.interpolateOverDefects`) does
not currently make use of this information.

Definition at line 190 of file isrFunctions.py.

◆ makeThresholdMask()

lsst.ip.isr.isrFunctions.makeThresholdMask ( maskedImage,
threshold,
growFootprints = 1,
maskName = 'SAT' )
Mask pixels based on threshold detection.

Parameters
----------
maskedImage : `lsst.afw.image.MaskedImage`
    Image to process.  Only the mask plane is updated.
threshold : scalar
    Detection threshold.
growFootprints : scalar, optional
    Number of pixels to grow footprints of detected regions.
maskName : str, optional
    Mask plane name, or list of names to convert

Returns
-------
defectList : `lsst.meas.algorithms.Defects`
    Defect list constructed from pixels above the threshold.

Definition at line 134 of file isrFunctions.py.

◆ saturationCorrection()

lsst.ip.isr.isrFunctions.saturationCorrection ( maskedImage,
saturation,
fwhm,
growFootprints = 1,
interpolate = True,
maskName = 'SAT',
fallbackValue = None )
Mark saturated pixels and optionally interpolate over them

Parameters
----------
maskedImage : `lsst.afw.image.MaskedImage`
    Image to process.
saturation  : scalar
    Saturation level used as the detection threshold.
fwhm : `float`
    FWHM of double Gaussian smoothing kernel.
growFootprints : scalar, optional
    Number of pixels to grow footprints of detected regions.
interpolate : Bool, optional
    If True, saturated pixels are interpolated over.
maskName : str, optional
    Mask plane name.
fallbackValue : scalar, optional
    Value of last resort for interpolation.

Notes
-----
The ``fwhm`` parameter is used to create a PSF, but the underlying
interpolation code (`lsst.meas.algorithms.interpolateOverDefects`) does
not currently make use of this information.

Definition at line 230 of file isrFunctions.py.

◆ setBadRegions()

lsst.ip.isr.isrFunctions.setBadRegions ( exposure,
badStatistic = "MEDIAN" )
Set all BAD areas of the chip to the average of the rest of the exposure

Parameters
----------
exposure : `lsst.afw.image.Exposure`
    Exposure to mask.  The exposure mask is modified.
badStatistic : `str`, optional
    Statistic to use to generate the replacement value from the
    image data.  Allowed values are 'MEDIAN' or 'MEANCLIP'.

Returns
-------
badPixelCount : scalar
    Number of bad pixels masked.
badPixelValue : scalar
    Value substituted for bad pixels.

Raises
------
RuntimeError
    Raised if `badStatistic` is not an allowed value.

Definition at line 1036 of file isrFunctions.py.

◆ transferFlux()

lsst.ip.isr.isrFunctions.transferFlux ( cFunc,
fStep,
correctionMode = True )
Take the input convolved deflection potential and the flux array
to compute and apply the flux transfer into the correction array.

Parameters
----------
cFunc: `numpy.array`
    Deflection potential, being the convolution of the flux F with the
    kernel K.
fStep: `numpy.array`
    The array of flux values which act as the source of the flux transfer.
correctionMode: `bool`
    Defines if applying correction (True) or generating sims (False).

Returns
-------
corr:
    BFE correction array

Definition at line 615 of file isrFunctions.py.

◆ transposeMaskedImage()

lsst.ip.isr.isrFunctions.transposeMaskedImage ( maskedImage)
Make a transposed copy of a masked image.

Parameters
----------
maskedImage : `lsst.afw.image.MaskedImage`
    Image to process.

Returns
-------
transposed : `lsst.afw.image.MaskedImage`
    The transposed copy of the input image.

Definition at line 84 of file isrFunctions.py.

◆ trimToMatchCalibBBox()

lsst.ip.isr.isrFunctions.trimToMatchCalibBBox ( rawMaskedImage,
calibMaskedImage )
Compute number of edge trim pixels to match the calibration data.

Use the dimension difference between the raw exposure and the
calibration exposure to compute the edge trim pixels.  This trim
is applied symmetrically, with the same number of pixels masked on
each side.

Parameters
----------
rawMaskedImage : `lsst.afw.image.MaskedImage`
    Image to trim.
calibMaskedImage : `lsst.afw.image.MaskedImage`
    Calibration image to draw new bounding box from.

Returns
-------
replacementMaskedImage : `lsst.afw.image.MaskedImage`
    ``rawMaskedImage`` trimmed to the appropriate size.

Raises
------
RuntimeError
   Raised if ``rawMaskedImage`` cannot be symmetrically trimmed to
   match ``calibMaskedImage``.

Definition at line 269 of file isrFunctions.py.

◆ updateVariance()

lsst.ip.isr.isrFunctions.updateVariance ( maskedImage,
gain,
readNoise )
Set the variance plane based on the image plane.

Parameters
----------
maskedImage : `lsst.afw.image.MaskedImage`
    Image to process.  The variance plane is modified.
gain : scalar
    The amplifier gain in electrons/ADU.
readNoise : scalar
    The amplifier read nmoise in ADU/pixel.

Definition at line 390 of file isrFunctions.py.

◆ widenSaturationTrails()

lsst.ip.isr.isrFunctions.widenSaturationTrails ( mask)
Grow the saturation trails by an amount dependent on the width of the
trail.

Parameters
----------
mask : `lsst.afw.image.Mask`
    Mask which will have the saturated areas grown.

Definition at line 988 of file isrFunctions.py.