DcrModel

class lsst.ip.diffim.DcrModel(modelImages, effectiveWavelength, bandwidth, filterInfo=None, psf=None, mask=None, variance=None, photoCalib=None)

Bases: object

A model of the true sky after correcting chromatic effects.

Notes

The DcrModel contains an estimate of the true sky, at a higher wavelength resolution than the input observations. It can be forward- modeled to produce Differential Chromatic Refraction (DCR) matched templates for a given Exposure, and provides utilities for conditioning the model in dcrAssembleCoadd to avoid oscillating solutions between iterations of forward modeling or between the subfilters of the model.

Attributes:
dcrNumSubfilters : int

Number of sub-filters used to model chromatic effects within a band.

modelImages : list of lsst.afw.image.Image

A list of masked images, each containing the model for one subfilter

Attributes Summary

bandwidth Return the bandwidth of the model.
bbox Return the common bounding box of each subfilter image.
effectiveWavelength Return the effective wavelength of the model.
filter Return the filter label for the model.
mask Return the common mask of each subfilter image.
psf Return the psf of the model.
variance Return the common variance of each subfilter image.

Methods Summary

applyImageThresholds(image[, highThreshold, …]) Restrict image values to be between upper and lower limits.
assign(dcrSubModel[, bbox]) Update a sub-region of the DcrModel with new values.
buildMatchedExposure([exposure, visitInfo, …]) Wrapper to create an exposure from a template image.
buildMatchedTemplate([exposure, order, …]) Create a DCR-matched template image for an exposure.
calculateNoiseCutoff(image, statsCtrl, …) Helper function to calculate the background noise level of an image.
conditionDcrModel(modelImages, bbox[, gain]) Average two iterations’ solutions to reduce oscillations.
fromDataRef(dataRef, effectiveWavelength, …) Load an existing DcrModel from a Gen 2 repository.
fromImage(maskedImage, dcrNumSubfilters, …) Initialize a DcrModel by dividing a coadd between the subfilters.
fromQuantum(availableCoaddRefs, …) Load an existing DcrModel from a Gen 3 repository.
getReferenceImage([bbox]) Calculate a reference image from the average of the subfilter images.
regularizeModelFreq(modelImages, bbox, …) Restrict large variations in the model between subfilters.
regularizeModelIter(subfilter, newModel, …) Restrict large variations in the model between iterations.

Attributes Documentation

bandwidth

Return the bandwidth of the model.

Returns:
bandwidth : float

The bandwidth of the current filter, in nanometers.
bbox

Return the common bounding box of each subfilter image.

Returns:
bbox : lsst.afw.geom.Box2I

Bounding box of the DCR model.
effectiveWavelength

Return the effective wavelength of the model.

Returns:
effectiveWavelength : float

The effective wavelength of the current filter, in nanometers.
filter

Return the filter label for the model.

Returns:
filterInfo : lsst.afw.image.Filter

The name of the filter used for the input observations. Note: this object will be changed in DM-21333.
mask

Return the common mask of each subfilter image.

Returns:
mask : lsst.afw.image.Mask

Mask plane of the DCR model.
psf

Return the psf of the model.

Returns:
psf : lsst.afw.detection.Psf

Point spread function (PSF) of the model.
variance

Return the common variance of each subfilter image.

Returns:
variance : lsst.afw.image.Image

Variance plane of the DCR model.

Methods Documentation

applyImageThresholds(image, highThreshold=None, lowThreshold=None, regularizationWidth=2)

Restrict image values to be between upper and lower limits.

This method flags all pixels in an image that are outside of the given threshold values. The threshold values are taken from a reference image, so noisy pixels are likely to get flagged. In order to exclude those noisy pixels, the array of flags is eroded and dilated, which removes isolated pixels outside of the thresholds from the list of pixels to be modified. Pixels that remain flagged after this operation have their values set to the appropriate upper or lower threshold value.

Parameters:
image : numpy.ndarray

The image to apply the thresholds to. The values will be modified in place.

highThreshold : numpy.ndarray, optional

Array of upper limit values for each pixel of image.

lowThreshold : numpy.ndarray, optional

Array of lower limit values for each pixel of image.

regularizationWidth : int, optional

Minimum radius of a region to include in regularization, in pixels.
assign(dcrSubModel, bbox=None)

Update a sub-region of the DcrModel with new values.

Parameters:
dcrSubModel : lsst.pipe.tasks.DcrModel

New model of the true scene after correcting chromatic effects.

bbox : lsst.afw.geom.Box2I, optional

Sub-region of the coadd. Defaults to the bounding box of dcrSubModel.
Raises:
ValueError

If the new model has a different number of subfilters.
buildMatchedExposure(exposure=None, visitInfo=None, bbox=None, wcs=None, mask=None)

Wrapper to create an exposure from a template image.

Parameters:
exposure : lsst.afw.image.Exposure, optional

The input exposure to build a matched template for. May be omitted if all of the metadata is supplied separately

visitInfo : lsst.afw.image.VisitInfo, optional

Metadata for the exposure. Ignored if exposure is set.

bbox : lsst.afw.geom.Box2I, optional

Sub-region of the coadd. Ignored if exposure is set.

wcs : lsst.afw.geom.SkyWcs, optional

Coordinate system definition (wcs) for the exposure. Ignored if exposure is set.

mask : lsst.afw.image.Mask, optional

reference mask to use for the template image.
Returns:
templateExposure : lsst.afw.image.exposureF

The DCR-matched template
Raises:
RuntimeError

If no photcCalib is set.
buildMatchedTemplate(exposure=None, order=3, visitInfo=None, bbox=None, wcs=None, mask=None, splitSubfilters=True, splitThreshold=0.0, amplifyModel=1.0)

Create a DCR-matched template image for an exposure.

Parameters:
exposure : lsst.afw.image.Exposure, optional

The input exposure to build a matched template for. May be omitted if all of the metadata is supplied separately

order : int, optional

Interpolation order of the DCR shift.

visitInfo : lsst.afw.image.VisitInfo, optional

Metadata for the exposure. Ignored if exposure is set.

bbox : lsst.afw.geom.Box2I, optional

Sub-region of the coadd. Ignored if exposure is set.

wcs : lsst.afw.geom.SkyWcs, optional

Coordinate system definition (wcs) for the exposure. Ignored if exposure is set.

mask : lsst.afw.image.Mask, optional

reference mask to use for the template image.

splitSubfilters : bool, optional

Calculate DCR for two evenly-spaced wavelengths in each subfilter, instead of at the midpoint. Default: True

splitThreshold : float, optional

Minimum DCR difference within a subfilter required to use splitSubfilters

amplifyModel : float, optional

Multiplication factor to amplify differences between model planes. Used to speed convergence of iterative forward modeling.
Returns:
templateImage : lsst.afw.image.ImageF

The DCR-matched template
Raises:
ValueError

If neither exposure or all of visitInfo, bbox, and wcs are set.
calculateNoiseCutoff(image, statsCtrl, bufferSize, convergenceMaskPlanes='DETECTED', mask=None, bbox=None)

Helper function to calculate the background noise level of an image.

Parameters:
image : lsst.afw.image.Image

The input image to evaluate the background noise properties.

statsCtrl : lsst.afw.math.StatisticsControl

Statistics control object for coaddition.

bufferSize : int

Number of additional pixels to exclude from the edges of the bounding box.

convergenceMaskPlanes : list of str, or str

Mask planes to use to calculate convergence.

mask : lsst.afw.image.Mask, Optional

Optional alternate mask

bbox : lsst.afw.geom.Box2I, optional

Sub-region of the masked image to calculate the noise level over.
Returns:
noiseCutoff : float

The threshold value to treat pixels as noise in an image..
conditionDcrModel(modelImages, bbox, gain=1.0)

Average two iterations’ solutions to reduce oscillations.

Parameters:
modelImages : list of lsst.afw.image.Image

The new DCR model images from the current iteration. The values will be modified in place.

bbox : lsst.afw.geom.Box2I

Sub-region of the coadd

gain : float, optional

Relative weight to give the new solution when updating the model. Defaults to 1.0, which gives equal weight to both solutions.
classmethod fromDataRef(dataRef, effectiveWavelength, bandwidth, datasetType='dcrCoadd', numSubfilters=None, **kwargs)

Load an existing DcrModel from a Gen 2 repository.

Parameters:
dataRef : lsst.daf.persistence.ButlerDataRef

Data reference defining the patch for coaddition and the reference Warp

effectiveWavelength : float

The effective wavelengths of the current filter, in nanometers.

bandwidth : float

The bandwidth of the current filter, in nanometers.

datasetType : str, optional

Name of the DcrModel in the registry {“dcrCoadd”, “dcrCoadd_sub”}

numSubfilters : int

Number of sub-filters used to model chromatic effects within a band.

**kwargs

Additional keyword arguments to pass to look up the model in the data registry. Common keywords and their types include: tract:str, patch:str, bbox:lsst.afw.geom.Box2I
Returns:
dcrModel : lsst.pipe.tasks.DcrModel

Best fit model of the true sky after correcting chromatic effects.
classmethod fromImage(maskedImage, dcrNumSubfilters, effectiveWavelength, bandwidth, filterInfo=None, psf=None, photoCalib=None)

Initialize a DcrModel by dividing a coadd between the subfilters.

Parameters:
maskedImage : lsst.afw.image.MaskedImage

Input coadded image to divide equally between the subfilters.

dcrNumSubfilters : int

Number of sub-filters used to model chromatic effects within a band.

effectiveWavelength : float

The effective wavelengths of the current filter, in nanometers.

bandwidth : float

The bandwidth of the current filter, in nanometers.

filterInfo : lsst.afw.image.Filter, optional

The filter definition, set in the current instruments’ obs package. Note: this object will be changed in DM-21333. Required for any calculation of DCR, including making matched templates.

psf : lsst.afw.detection.Psf, optional

Point spread function (PSF) of the model. Required if the DcrModel will be persisted.

photoCalib : lsst.afw.image.PhotoCalib, optional

Calibration to convert instrumental flux and flux error to nanoJansky.
Returns:
dcrModel : lsst.pipe.tasks.DcrModel

Best fit model of the true sky after correcting chromatic effects.
classmethod fromQuantum(availableCoaddRefs, effectiveWavelength, bandwidth)

Load an existing DcrModel from a Gen 3 repository.

Parameters:
availableCoaddRefs : dict of

Dictionary of spatially relevant retrieved coadd patches, indexed by their sequential patch number.

effectiveWavelength : float

The effective wavelengths of the current filter, in nanometers.

bandwidth : float

The bandwidth of the current filter, in nanometers.
Returns:
dcrModel : lsst.pipe.tasks.DcrModel

Best fit model of the true sky after correcting chromatic effects.
getReferenceImage(bbox=None)

Calculate a reference image from the average of the subfilter images.

Parameters:
bbox : lsst.afw.geom.Box2I, optional

Sub-region of the coadd. Returns the entire image if None.
Returns:
refImage : numpy.ndarray

The reference image with no chromatic effects applied.
regularizeModelFreq(modelImages, bbox, statsCtrl, regularizationFactor, regularizationWidth=2, mask=None, convergenceMaskPlanes='DETECTED')

Restrict large variations in the model between subfilters.

Parameters:
modelImages : list of lsst.afw.image.Image

The new DCR model images from the current iteration. The values will be modified in place.

bbox : lsst.afw.geom.Box2I

Sub-region to coadd

statsCtrl : lsst.afw.math.StatisticsControl

Statistics control object for coaddition.

regularizationFactor : float

Maximum relative change of the model allowed between subfilters.

regularizationWidth : int, optional

Minimum radius of a region to include in regularization, in pixels.

mask : lsst.afw.image.Mask, optional

Optional alternate mask

convergenceMaskPlanes : list of str, or str, optional

Mask planes to use to calculate convergence.

Notes

This implementation of frequency regularization restricts each subfilter image to be a smoothly-varying function times a reference image.

regularizeModelIter(subfilter, newModel, bbox, regularizationFactor, regularizationWidth=2)

Restrict large variations in the model between iterations.

Parameters:
subfilter : int

Index of the current subfilter within the full band.

newModel : lsst.afw.image.Image

The new DCR model for one subfilter from the current iteration. Values in newModel that are extreme compared with the last iteration are modified in place.

bbox : lsst.afw.geom.Box2I

Sub-region to coadd

regularizationFactor : float

Maximum relative change of the model allowed between iterations.

regularizationWidth : int, optional

Minimum radius of a region to include in regularization, in pixels.