lsst.pipe.tasks.dcrAssembleCoadd Namespace Reference

Classes
class	DcrAssembleCoaddConnections

Functions
def	dcrAssembleSubregion (self, dcrModels, subExposures, bbox, dcrBBox, warpRefList, statsCtrl, convergenceMetric, gain, modelWeights, refImage, dcrWeights)
def	dcrResiduals (self, residual, visitInfo, wcs, effectiveWavelength, bandwidth)
def	newModelFromResidual (self, dcrModels, residualGeneratorList, dcrBBox, statsCtrl, gain, modelWeights, refImage, dcrWeights)
def	calculateConvergence (self, dcrModels, subExposures, bbox, warpRefList, weightList, statsCtrl)
def	calculateSingleConvergence (self, dcrModels, exposure, significanceImage, statsCtrl)
def	stackCoadd (self, dcrCoadds)
def	fillCoadd (self, dcrModels, skyInfo, warpRefList, weightList, calibration=None, coaddInputs=None, mask=None, variance=None)
def	calculateGain (self, convergenceList, gainList)
def	calculateModelWeights (self, dcrModels, dcrBBox)
def	applyModelWeights (self, modelImages, refImage, modelWeights)
def	loadSubExposures (self, bbox, statsCtrl, warpRefList, imageScalerList, spanSetMaskList)
def	selectCoaddPsf (self, templateCoadd, warpRefList)

Variables
	weightsThreshold
	goodPix

Function Documentation

applyModelWeights()

def lsst.pipe.tasks.dcrAssembleCoadd.applyModelWeights	(		self,
			modelImages,
			refImage,
			modelWeights
	)

Smoothly replace model pixel values with those from a
reference at locations away from detected sources.

Parameters
----------
modelImages : `list` of `lsst.afw.image.Image`
    The new DCR model images from the current iteration.
    The values will be modified in place.
refImage : `lsst.afw.image.MaskedImage`
    A reference image used to supply the default pixel values.
modelWeights : `numpy.ndarray` or `float`
    A 2D array of weight values that tapers smoothly to zero away from detected sources.
    Set to a placeholder value of 1.0 if ``self.config.useModelWeights`` is False.

Definition at line 1241 of file dcrAssembleCoadd.py.

    def applyModelWeights(self, modelImages, refImage, modelWeights):
        """Smoothly replace model pixel values with those from a
        reference at locations away from detected sources.
 
        Parameters
        ----------
        modelImages : `list` of `lsst.afw.image.Image`
            The new DCR model images from the current iteration.
            The values will be modified in place.
        refImage : `lsst.afw.image.MaskedImage`
            A reference image used to supply the default pixel values.
        modelWeights : `numpy.ndarray` or `float`
            A 2D array of weight values that tapers smoothly to zero away from detected sources.
            Set to a placeholder value of 1.0 if ``self.config.useModelWeights`` is False.
        """
        if self.config.useModelWeights:
            for model in modelImages:
                model.array *= modelWeights
                model.array += refImage.array*(1. - modelWeights)/self.config.dcrNumSubfilters
 

calculateConvergence()

def lsst.pipe.tasks.dcrAssembleCoadd.calculateConvergence	(		self,
			dcrModels,
			subExposures,
			bbox,
			warpRefList,
			weightList,
			statsCtrl
	)

Calculate a quality of fit metric for the matched templates.

Parameters
----------
dcrModels : `lsst.pipe.tasks.DcrModel`
    Best fit model of the true sky after correcting chromatic effects.
subExposures : `dict` of `lsst.afw.image.ExposureF`
    The pre-loaded exposures for the current subregion.
bbox : `lsst.geom.box.Box2I`
    Sub-region to coadd
warpRefList : `list` of `lsst.daf.butler.DeferredDatasetHandle` or
    `lsst.daf.persistence.ButlerDataRef`
    The data references to the input warped exposures.
weightList : `list` of `float`
    The weight to give each input exposure in the coadd
statsCtrl : `lsst.afw.math.StatisticsControl`
    Statistics control object for coadd

Returns
-------
convergenceMetric : `float`
    Quality of fit metric for all input exposures, within the sub-region

Definition at line 966 of file dcrAssembleCoadd.py.

    def calculateConvergence(self, dcrModels, subExposures, bbox, warpRefList, weightList, statsCtrl):
        """Calculate a quality of fit metric for the matched templates.
 
        Parameters
        ----------
        dcrModels : `lsst.pipe.tasks.DcrModel`
            Best fit model of the true sky after correcting chromatic effects.
        subExposures : `dict` of `lsst.afw.image.ExposureF`
            The pre-loaded exposures for the current subregion.
        bbox : `lsst.geom.box.Box2I`
            Sub-region to coadd
        warpRefList : `list` of `lsst.daf.butler.DeferredDatasetHandle` or
            `lsst.daf.persistence.ButlerDataRef`
            The data references to the input warped exposures.
        weightList : `list` of `float`
            The weight to give each input exposure in the coadd
        statsCtrl : `lsst.afw.math.StatisticsControl`
            Statistics control object for coadd
 
        Returns
        -------
        convergenceMetric : `float`
            Quality of fit metric for all input exposures, within the sub-region
        """
        significanceImage = np.abs(dcrModels.getReferenceImage(bbox))
        nSigma = 3.
        significanceImage += nSigma*dcrModels.calculateNoiseCutoff(dcrModels[1], statsCtrl,
                                                                   bufferSize=self.bufferSize)
        if np.max(significanceImage) == 0:
            significanceImage += 1.
        weight = 0
        metric = 0.
        metricList = {}
        for warpExpRef, expWeight in zip(warpRefList, weightList):
            visit = warpExpRef.dataId["visit"]
            exposure = subExposures[visit][bbox]
            singleMetric = self.calculateSingleConvergence(dcrModels, exposure, significanceImage, statsCtrl)
            metric += singleMetric
            metricList[visit] = singleMetric
            weight += 1.
        self.log.info("Individual metrics:\n%s", metricList)
        return 1.0 if weight == 0.0 else metric/weight
 

calculateGain()

def lsst.pipe.tasks.dcrAssembleCoadd.calculateGain	(		self,
			convergenceList,
			gainList
	)

Calculate the gain to use for the current iteration.

After calculating a new DcrModel, each value is averaged with the
value in the corresponding pixel from the previous iteration. This
reduces oscillating solutions that iterative techniques are plagued by,
and speeds convergence. By far the biggest changes to the model
happen in the first couple iterations, so we can also use a more
aggressive gain later when the model is changing slowly.

Parameters
----------
convergenceList : `list` of `float`
    The quality of fit metric from each previous iteration.
gainList : `list` of `float`
    The gains used in each previous iteration: appended with the new
    gain value.
    Gains are numbers between ``self.config.baseGain`` and 1.

Returns
-------
gain : `float`
    Relative weight to give the new solution when updating the model.
    A value of 1.0 gives equal weight to both solutions.

Raises
------
ValueError
    If ``len(convergenceList) != len(gainList)+1``.

Definition at line 1127 of file dcrAssembleCoadd.py.

    def calculateGain(self, convergenceList, gainList):
        """Calculate the gain to use for the current iteration.
 
        After calculating a new DcrModel, each value is averaged with the
        value in the corresponding pixel from the previous iteration. This
        reduces oscillating solutions that iterative techniques are plagued by,
        and speeds convergence. By far the biggest changes to the model
        happen in the first couple iterations, so we can also use a more
        aggressive gain later when the model is changing slowly.
 
        Parameters
        ----------
        convergenceList : `list` of `float`
            The quality of fit metric from each previous iteration.
        gainList : `list` of `float`
            The gains used in each previous iteration: appended with the new
            gain value.
            Gains are numbers between ``self.config.baseGain`` and 1.
 
        Returns
        -------
        gain : `float`
            Relative weight to give the new solution when updating the model.
            A value of 1.0 gives equal weight to both solutions.
 
        Raises
        ------
        ValueError
            If ``len(convergenceList) != len(gainList)+1``.
        """
        nIter = len(convergenceList)
        if nIter != len(gainList) + 1:
            raise ValueError("convergenceList (%d) must be one element longer than gainList (%d)."
                             % (len(convergenceList), len(gainList)))
 
        if self.config.baseGain is None:
            # If ``baseGain`` is not set, calculate it from the number of DCR subfilters
            # The more subfilters being modeled, the lower the gain should be.
            baseGain = 1./(self.config.dcrNumSubfilters - 1)
        else:
            baseGain = self.config.baseGain
 
        if self.config.useProgressiveGain and nIter > 2:
            # To calculate the best gain to use, compare the past gains that have been used
            # with the resulting convergences to estimate the best gain to use.
            # Algorithmically, this is a Kalman filter.
            # If forward modeling proceeds perfectly, the convergence metric should
            # asymptotically approach a final value.
            # We can estimate that value from the measured changes in convergence
            # weighted by the gains used in each previous iteration.
            estFinalConv = [((1 + gainList[i])*convergenceList[i + 1] - convergenceList[i])/gainList[i]
                            for i in range(nIter - 1)]
            # The convergence metric is strictly positive, so if the estimated final convergence is
            # less than zero, force it to zero.
            estFinalConv = np.array(estFinalConv)
            estFinalConv[estFinalConv < 0] = 0
            # Because the estimate may slowly change over time, only use the most recent measurements.
            estFinalConv = np.median(estFinalConv[max(nIter - 5, 0):])
            lastGain = gainList[-1]
            lastConv = convergenceList[-2]
            newConv = convergenceList[-1]
            # The predicted convergence is the value we would get if the new model calculated
            # in the previous iteration was perfect. Recall that the updated model that is
            # actually used is the gain-weighted average of the new and old model,
            # so the convergence would be similarly weighted.
            predictedConv = (estFinalConv*lastGain + lastConv)/(1. + lastGain)
            # If the measured and predicted convergence are very close, that indicates
            # that our forward model is accurate and we can use a more aggressive gain
            # If the measured convergence is significantly worse (or better!) than predicted,
            # that indicates that the model is not converging as expected and
            # we should use a more conservative gain.
            delta = (predictedConv - newConv)/((lastConv - estFinalConv)/(1 + lastGain))
            newGain = 1 - abs(delta)
            # Average the gains to prevent oscillating solutions.
            newGain = (newGain + lastGain)/2.
            gain = max(baseGain, newGain)
        else:
            gain = baseGain
        gainList.append(gain)
        return gain
 

calculateModelWeights()

def lsst.pipe.tasks.dcrAssembleCoadd.calculateModelWeights	(		self,
			dcrModels,
			dcrBBox
	)

Build an array that smoothly tapers to 0 away from detected sources.

Parameters
----------
dcrModels : `lsst.pipe.tasks.DcrModel`
    Best fit model of the true sky after correcting chromatic effects.
dcrBBox : `lsst.geom.box.Box2I`
    Sub-region of the coadd which includes a buffer to allow for DCR.

Returns
-------
weights : `numpy.ndarray` or `float`
    A 2D array of weight values that tapers smoothly to zero away from detected sources.
    Set to a placeholder value of 1.0 if ``self.config.useModelWeights`` is False.

Raises
------
ValueError
    If ``useModelWeights`` is set and ``modelWeightsWidth`` is negative.

Definition at line 1208 of file dcrAssembleCoadd.py.

    def calculateModelWeights(self, dcrModels, dcrBBox):
        """Build an array that smoothly tapers to 0 away from detected sources.
 
        Parameters
        ----------
        dcrModels : `lsst.pipe.tasks.DcrModel`
            Best fit model of the true sky after correcting chromatic effects.
        dcrBBox : `lsst.geom.box.Box2I`
            Sub-region of the coadd which includes a buffer to allow for DCR.
 
        Returns
        -------
        weights : `numpy.ndarray` or `float`
            A 2D array of weight values that tapers smoothly to zero away from detected sources.
            Set to a placeholder value of 1.0 if ``self.config.useModelWeights`` is False.
 
        Raises
        ------
        ValueError
            If ``useModelWeights`` is set and ``modelWeightsWidth`` is negative.
        """
        if not self.config.useModelWeights:
            return 1.0
        if self.config.modelWeightsWidth < 0:
            raise ValueError("modelWeightsWidth must not be negative if useModelWeights is set")
        convergeMask = dcrModels.mask.getPlaneBitMask(self.config.convergenceMaskPlanes)
        convergeMaskPixels = dcrModels.mask[dcrBBox].array & convergeMask > 0
        weights = np.zeros_like(dcrModels[0][dcrBBox].array)
        weights[convergeMaskPixels] = 1.
        weights = ndimage.filters.gaussian_filter(weights, self.config.modelWeightsWidth)
        weights /= np.max(weights)
        return weights
 

calculateSingleConvergence()

def lsst.pipe.tasks.dcrAssembleCoadd.calculateSingleConvergence	(		self,
			dcrModels,
			exposure,
			significanceImage,
			statsCtrl
	)

Calculate a quality of fit metric for a single matched template.

Parameters
----------
dcrModels : `lsst.pipe.tasks.DcrModel`
    Best fit model of the true sky after correcting chromatic effects.
exposure : `lsst.afw.image.ExposureF`
    The input warped exposure to evaluate.
significanceImage : `numpy.ndarray`
    Array of weights for each pixel corresponding to its significance
    for the convergence calculation.
statsCtrl : `lsst.afw.math.StatisticsControl`
    Statistics control object for coadd

Returns
-------
convergenceMetric : `float`
    Quality of fit metric for one exposure, within the sub-region.

Definition at line 1009 of file dcrAssembleCoadd.py.

    def calculateSingleConvergence(self, dcrModels, exposure, significanceImage, statsCtrl):
        """Calculate a quality of fit metric for a single matched template.
 
        Parameters
        ----------
        dcrModels : `lsst.pipe.tasks.DcrModel`
            Best fit model of the true sky after correcting chromatic effects.
        exposure : `lsst.afw.image.ExposureF`
            The input warped exposure to evaluate.
        significanceImage : `numpy.ndarray`
            Array of weights for each pixel corresponding to its significance
            for the convergence calculation.
        statsCtrl : `lsst.afw.math.StatisticsControl`
            Statistics control object for coadd
 
        Returns
        -------
        convergenceMetric : `float`
            Quality of fit metric for one exposure, within the sub-region.
        """
        convergeMask = exposure.mask.getPlaneBitMask(self.config.convergenceMaskPlanes)
        templateImage = dcrModels.buildMatchedTemplate(exposure=exposure,
                                                       order=self.config.imageInterpOrder,
                                                       splitSubfilters=self.config.splitSubfilters,
                                                       splitThreshold=self.config.splitThreshold,
                                                       amplifyModel=self.config.accelerateModel)
        diffVals = np.abs(exposure.image.array - templateImage.array)*significanceImage
        refVals = np.abs(exposure.image.array + templateImage.array)*significanceImage/2.
 
        finitePixels = np.isfinite(diffVals)
        goodMaskPixels = (exposure.mask.array & statsCtrl.getAndMask()) == 0
        convergeMaskPixels = exposure.mask.array & convergeMask > 0
        usePixels = finitePixels & goodMaskPixels & convergeMaskPixels
        if np.sum(usePixels) == 0:
            metric = 0.
        else:
            diffUse = diffVals[usePixels]
            refUse = refVals[usePixels]
            metric = np.sum(diffUse/np.median(diffUse))/np.sum(refUse/np.median(diffUse))
        return metric
 

dcrAssembleSubregion()

def lsst.pipe.tasks.dcrAssembleCoadd.dcrAssembleSubregion	(		self,
			dcrModels,
			subExposures,
			bbox,
			dcrBBox,
			warpRefList,
			statsCtrl,
			convergenceMetric,
			gain,
			modelWeights,
			refImage,
			dcrWeights
	)

Assemble the DCR coadd for a sub-region.

Build a DCR-matched template for each input exposure, then shift the
residuals according to the DCR in each subfilter.
Stack the shifted residuals and apply them as a correction to the
solution from the previous iteration.
Restrict the new model solutions from varying by more than a factor of
`modelClampFactor` from the last solution, and additionally restrict the
individual subfilter models from varying by more than a factor of
`frequencyClampFactor` from their average.
Finally, mitigate potentially oscillating solutions by averaging the new
solution with the solution from the previous iteration, weighted by
their convergence metric.

Parameters
----------
dcrModels : `lsst.pipe.tasks.DcrModel`
    Best fit model of the true sky after correcting chromatic effects.
subExposures : `dict` of `lsst.afw.image.ExposureF`
    The pre-loaded exposures for the current subregion.
bbox : `lsst.geom.box.Box2I`
    Bounding box of the subregion to coadd.
dcrBBox : `lsst.geom.box.Box2I`
    Sub-region of the coadd which includes a buffer to allow for DCR.
warpRefList : `list` of `lsst.daf.butler.DeferredDatasetHandle` or
    `lsst.daf.persistence.ButlerDataRef`
    The data references to the input warped exposures.
statsCtrl : `lsst.afw.math.StatisticsControl`
    Statistics control object for coadd
convergenceMetric : `float`
    Quality of fit metric for the matched templates of the input images.
gain : `float`, optional
    Relative weight to give the new solution when updating the model.
modelWeights : `numpy.ndarray` or `float`
    A 2D array of weight values that tapers smoothly to zero away from detected sources.
    Set to a placeholder value of 1.0 if ``self.config.useModelWeights`` is False.
refImage : `lsst.afw.image.Image`
    A reference image used to supply the default pixel values.
dcrWeights : `list` of `lsst.afw.image.Image`
    Per-pixel weights for each subfilter.
    Equal to 1/(number of unmasked images contributing to each pixel).

Definition at line 804 of file dcrAssembleCoadd.py.

    def dcrAssembleSubregion(self, dcrModels, subExposures, bbox, dcrBBox, warpRefList,
                             statsCtrl, convergenceMetric,
                             gain, modelWeights, refImage, dcrWeights):
        """Assemble the DCR coadd for a sub-region.
 
        Build a DCR-matched template for each input exposure, then shift the
        residuals according to the DCR in each subfilter.
        Stack the shifted residuals and apply them as a correction to the
        solution from the previous iteration.
        Restrict the new model solutions from varying by more than a factor of
        `modelClampFactor` from the last solution, and additionally restrict the
        individual subfilter models from varying by more than a factor of
        `frequencyClampFactor` from their average.
        Finally, mitigate potentially oscillating solutions by averaging the new
        solution with the solution from the previous iteration, weighted by
        their convergence metric.
 
        Parameters
        ----------
        dcrModels : `lsst.pipe.tasks.DcrModel`
            Best fit model of the true sky after correcting chromatic effects.
        subExposures : `dict` of `lsst.afw.image.ExposureF`
            The pre-loaded exposures for the current subregion.
        bbox : `lsst.geom.box.Box2I`
            Bounding box of the subregion to coadd.
        dcrBBox : `lsst.geom.box.Box2I`
            Sub-region of the coadd which includes a buffer to allow for DCR.
        warpRefList : `list` of `lsst.daf.butler.DeferredDatasetHandle` or
            `lsst.daf.persistence.ButlerDataRef`
            The data references to the input warped exposures.
        statsCtrl : `lsst.afw.math.StatisticsControl`
            Statistics control object for coadd
        convergenceMetric : `float`
            Quality of fit metric for the matched templates of the input images.
        gain : `float`, optional
            Relative weight to give the new solution when updating the model.
        modelWeights : `numpy.ndarray` or `float`
            A 2D array of weight values that tapers smoothly to zero away from detected sources.
            Set to a placeholder value of 1.0 if ``self.config.useModelWeights`` is False.
        refImage : `lsst.afw.image.Image`
            A reference image used to supply the default pixel values.
        dcrWeights : `list` of `lsst.afw.image.Image`
            Per-pixel weights for each subfilter.
            Equal to 1/(number of unmasked images contributing to each pixel).
        """
        residualGeneratorList = []
 
        for warpExpRef in warpRefList:
            visit = warpExpRef.dataId["visit"]
            exposure = subExposures[visit]
            visitInfo = exposure.getInfo().getVisitInfo()
            wcs = exposure.getInfo().getWcs()
            templateImage = dcrModels.buildMatchedTemplate(exposure=exposure,
                                                           order=self.config.imageInterpOrder,
                                                           splitSubfilters=self.config.splitSubfilters,
                                                           splitThreshold=self.config.splitThreshold,
                                                           amplifyModel=self.config.accelerateModel)
            residual = exposure.image.array - templateImage.array
            # Note that the variance plane here is used to store weights, not the actual variance
            residual *= exposure.variance.array
            # The residuals are stored as a list of generators.
            # This allows the residual for a given subfilter and exposure to be created
            # on the fly, instead of needing to store them all in memory.
            residualGeneratorList.append(self.dcrResiduals(residual, visitInfo, wcs,
                                                           dcrModels.effectiveWavelength,
                                                           dcrModels.bandwidth))
 
        dcrSubModelOut = self.newModelFromResidual(dcrModels, residualGeneratorList, dcrBBox, statsCtrl,
                                                   gain=gain,
                                                   modelWeights=modelWeights,
                                                   refImage=refImage,
                                                   dcrWeights=dcrWeights)
        dcrModels.assign(dcrSubModelOut, bbox)
 

dcrResiduals()

def lsst.pipe.tasks.dcrAssembleCoadd.dcrResiduals	(		self,
			residual,
			visitInfo,
			wcs,
			effectiveWavelength,
			bandwidth
	)

Prepare a residual image for stacking in each subfilter by applying the reverse DCR shifts.

Parameters
----------
residual : `numpy.ndarray`
    The residual masked image for one exposure,
    after subtracting the matched template
visitInfo : `lsst.afw.image.VisitInfo`
    Metadata for the exposure.
wcs : `lsst.afw.geom.SkyWcs`
    Coordinate system definition (wcs) for the exposure.
filterInfo : `lsst.afw.image.Filter`
    The filter definition, set in the current instruments' obs package.
    Note: this object will be changed in DM-21333.

Yields
------
residualImage : `numpy.ndarray`
    The residual image for the next subfilter, shifted for DCR.

Definition at line 878 of file dcrAssembleCoadd.py.

    def dcrResiduals(self, residual, visitInfo, wcs, effectiveWavelength, bandwidth):
        """Prepare a residual image for stacking in each subfilter by applying the reverse DCR shifts.
 
        Parameters
        ----------
        residual : `numpy.ndarray`
            The residual masked image for one exposure,
            after subtracting the matched template
        visitInfo : `lsst.afw.image.VisitInfo`
            Metadata for the exposure.
        wcs : `lsst.afw.geom.SkyWcs`
            Coordinate system definition (wcs) for the exposure.
        filterInfo : `lsst.afw.image.Filter`
            The filter definition, set in the current instruments' obs package.
            Note: this object will be changed in DM-21333.
 
        Yields
        ------
        residualImage : `numpy.ndarray`
            The residual image for the next subfilter, shifted for DCR.
        """
        # Pre-calculate the spline-filtered residual image, so that step can be
        # skipped in the shift calculation in `applyDcr`.
        filteredResidual = ndimage.spline_filter(residual, order=self.config.imageInterpOrder)
        # Note that `splitSubfilters` is always turned off in the reverse direction.
        # This option introduces additional blurring if applied to the residuals.
        dcrShift = calculateDcr(visitInfo, wcs, effectiveWavelength, bandwidth, self.config.dcrNumSubfilters,
                                splitSubfilters=False)
        for dcr in dcrShift:
            yield applyDcr(filteredResidual, dcr, useInverse=True, splitSubfilters=False,
                           doPrefilter=False, order=self.config.imageInterpOrder)
 

fillCoadd()

def lsst.pipe.tasks.dcrAssembleCoadd.fillCoadd	(		self,
			dcrModels,
			skyInfo,
			warpRefList,
			weightList,
			calibration = None,
			coaddInputs = None,
			mask = None,
			variance = None
	)

Create a list of coadd exposures from a list of masked images.

Parameters
----------
dcrModels : `lsst.pipe.tasks.DcrModel`
    Best fit model of the true sky after correcting chromatic effects.
skyInfo : `lsst.pipe.base.Struct`
    Patch geometry information, from getSkyInfo
warpRefList : `list` of `lsst.daf.butler.DeferredDatasetHandle` or
    `lsst.daf.persistence.ButlerDataRef`
    The data references to the input warped exposures.
weightList : `list` of `float`
    The weight to give each input exposure in the coadd
calibration : `lsst.afw.Image.PhotoCalib`, optional
    Scale factor to set the photometric calibration of an exposure.
coaddInputs : `lsst.afw.Image.CoaddInputs`, optional
    A record of the observations that are included in the coadd.
mask : `lsst.afw.image.Mask`, optional
    Optional mask to override the values in the final coadd.
variance : `lsst.afw.image.Image`, optional
    Optional variance plane to override the values in the final coadd.

Returns
-------
dcrCoadds : `list` of `lsst.afw.image.ExposureF`
    A list of coadd exposures, each exposure containing
    the model for one subfilter.

Definition at line 1069 of file dcrAssembleCoadd.py.

    def fillCoadd(self, dcrModels, skyInfo, warpRefList, weightList, calibration=None, coaddInputs=None,
                  mask=None, variance=None):
        """Create a list of coadd exposures from a list of masked images.
 
        Parameters
        ----------
        dcrModels : `lsst.pipe.tasks.DcrModel`
            Best fit model of the true sky after correcting chromatic effects.
        skyInfo : `lsst.pipe.base.Struct`
            Patch geometry information, from getSkyInfo
        warpRefList : `list` of `lsst.daf.butler.DeferredDatasetHandle` or
            `lsst.daf.persistence.ButlerDataRef`
            The data references to the input warped exposures.
        weightList : `list` of `float`
            The weight to give each input exposure in the coadd
        calibration : `lsst.afw.Image.PhotoCalib`, optional
            Scale factor to set the photometric calibration of an exposure.
        coaddInputs : `lsst.afw.Image.CoaddInputs`, optional
            A record of the observations that are included in the coadd.
        mask : `lsst.afw.image.Mask`, optional
            Optional mask to override the values in the final coadd.
        variance : `lsst.afw.image.Image`, optional
            Optional variance plane to override the values in the final coadd.
 
        Returns
        -------
        dcrCoadds : `list` of `lsst.afw.image.ExposureF`
            A list of coadd exposures, each exposure containing
            the model for one subfilter.
        """
        dcrCoadds = []
        refModel = dcrModels.getReferenceImage()
        for model in dcrModels:
            if self.config.accelerateModel > 1:
                model.array = (model.array - refModel)*self.config.accelerateModel + refModel
            coaddExposure = afwImage.ExposureF(skyInfo.bbox, skyInfo.wcs)
            if calibration is not None:
                coaddExposure.setPhotoCalib(calibration)
            if coaddInputs is not None:
                coaddExposure.getInfo().setCoaddInputs(coaddInputs)
            # Set the metadata for the coadd, including PSF and aperture corrections.
            self.assembleMetadata(coaddExposure, warpRefList, weightList)
            # Overwrite the PSF
            coaddExposure.setPsf(dcrModels.psf)
            coaddUtils.setCoaddEdgeBits(dcrModels.mask[skyInfo.bbox], dcrModels.variance[skyInfo.bbox])
            maskedImage = afwImage.MaskedImageF(dcrModels.bbox)
            maskedImage.image = model
            maskedImage.mask = dcrModels.mask
            maskedImage.variance = dcrModels.variance
            coaddExposure.setMaskedImage(maskedImage[skyInfo.bbox])
            coaddExposure.setPhotoCalib(self.scaleZeroPoint.getPhotoCalib())
            if mask is not None:
                coaddExposure.setMask(mask)
            if variance is not None:
                coaddExposure.setVariance(variance)
            dcrCoadds.append(coaddExposure)
        return dcrCoadds
 

loadSubExposures()

def lsst.pipe.tasks.dcrAssembleCoadd.loadSubExposures	(		self,
			bbox,
			statsCtrl,
			warpRefList,
			imageScalerList,
			spanSetMaskList
	)

Pre-load sub-regions of a list of exposures.

Parameters
----------
bbox : `lsst.geom.box.Box2I`
    Sub-region to coadd
statsCtrl : `lsst.afw.math.StatisticsControl`
    Statistics control object for coadd
warpRefList : `list` of `lsst.daf.butler.DeferredDatasetHandle` or
    `lsst.daf.persistence.ButlerDataRef`
    The data references to the input warped exposures.
imageScalerList : `list` of `lsst.pipe.task.ImageScaler`
    The image scalars correct for the zero point of the exposures.
spanSetMaskList : `list` of `dict` containing spanSet lists, or None
    Each element is dict with keys = mask plane name to add the spans to

Returns
-------
subExposures : `dict`
    The `dict` keys are the visit IDs,
    and the values are `lsst.afw.image.ExposureF`
    The pre-loaded exposures for the current subregion.
    The variance plane contains weights, and not the variance

Definition at line 1261 of file dcrAssembleCoadd.py.

    def loadSubExposures(self, bbox, statsCtrl, warpRefList, imageScalerList, spanSetMaskList):
        """Pre-load sub-regions of a list of exposures.
 
        Parameters
        ----------
        bbox : `lsst.geom.box.Box2I`
            Sub-region to coadd
        statsCtrl : `lsst.afw.math.StatisticsControl`
            Statistics control object for coadd
        warpRefList : `list` of `lsst.daf.butler.DeferredDatasetHandle` or
            `lsst.daf.persistence.ButlerDataRef`
            The data references to the input warped exposures.
        imageScalerList : `list` of `lsst.pipe.task.ImageScaler`
            The image scalars correct for the zero point of the exposures.
        spanSetMaskList : `list` of `dict` containing spanSet lists, or None
            Each element is dict with keys = mask plane name to add the spans to
 
        Returns
        -------
        subExposures : `dict`
            The `dict` keys are the visit IDs,
            and the values are `lsst.afw.image.ExposureF`
            The pre-loaded exposures for the current subregion.
            The variance plane contains weights, and not the variance
        """
        tempExpName = self.getTempExpDatasetName(self.warpType)
        zipIterables = zip(warpRefList, imageScalerList, spanSetMaskList)
        subExposures = {}
        for warpExpRef, imageScaler, altMaskSpans in zipIterables:
            if isinstance(warpExpRef, DeferredDatasetHandle):
                exposure = warpExpRef.get(parameters={'bbox': bbox})
            else:
                exposure = warpExpRef.get(tempExpName + "_sub", bbox=bbox)
            visit = warpExpRef.dataId["visit"]
            if altMaskSpans is not None:
                self.applyAltMaskPlanes(exposure.mask, altMaskSpans)
            imageScaler.scaleMaskedImage(exposure.maskedImage)
            # Note that the variance plane here is used to store weights, not the actual variance
            exposure.variance.array[:, :] = 0.
            # Set the weight of unmasked pixels to 1.
            exposure.variance.array[(exposure.mask.array & statsCtrl.getAndMask()) == 0] = 1.
            # Set the image value of masked pixels to zero.
            # This eliminates needing the mask plane when stacking images in ``newModelFromResidual``
            exposure.image.array[(exposure.mask.array & statsCtrl.getAndMask()) > 0] = 0.
            subExposures[visit] = exposure
        return subExposures
 

newModelFromResidual()

def lsst.pipe.tasks.dcrAssembleCoadd.newModelFromResidual	(		self,
			dcrModels,
			residualGeneratorList,
			dcrBBox,
			statsCtrl,
			gain,
			modelWeights,
			refImage,
			dcrWeights
	)

Calculate a new DcrModel from a set of image residuals.

Parameters
----------
dcrModels : `lsst.pipe.tasks.DcrModel`
    Current model of the true sky after correcting chromatic effects.
residualGeneratorList : `generator` of `numpy.ndarray`
    The residual image for the next subfilter, shifted for DCR.
dcrBBox : `lsst.geom.box.Box2I`
    Sub-region of the coadd which includes a buffer to allow for DCR.
statsCtrl : `lsst.afw.math.StatisticsControl`
    Statistics control object for coadd
gain : `float`
    Relative weight to give the new solution when updating the model.
modelWeights : `numpy.ndarray` or `float`
    A 2D array of weight values that tapers smoothly to zero away from detected sources.
    Set to a placeholder value of 1.0 if ``self.config.useModelWeights`` is False.
refImage : `lsst.afw.image.Image`
    A reference image used to supply the default pixel values.
dcrWeights : `list` of `lsst.afw.image.Image`
    Per-pixel weights for each subfilter.
    Equal to 1/(number of unmasked images contributing to each pixel).

Returns
-------
dcrModel : `lsst.pipe.tasks.DcrModel`
    New model of the true sky after correcting chromatic effects.

Definition at line 910 of file dcrAssembleCoadd.py.

    def newModelFromResidual(self, dcrModels, residualGeneratorList, dcrBBox, statsCtrl,
                             gain, modelWeights, refImage, dcrWeights):
        """Calculate a new DcrModel from a set of image residuals.
 
        Parameters
        ----------
        dcrModels : `lsst.pipe.tasks.DcrModel`
            Current model of the true sky after correcting chromatic effects.
        residualGeneratorList : `generator` of `numpy.ndarray`
            The residual image for the next subfilter, shifted for DCR.
        dcrBBox : `lsst.geom.box.Box2I`
            Sub-region of the coadd which includes a buffer to allow for DCR.
        statsCtrl : `lsst.afw.math.StatisticsControl`
            Statistics control object for coadd
        gain : `float`
            Relative weight to give the new solution when updating the model.
        modelWeights : `numpy.ndarray` or `float`
            A 2D array of weight values that tapers smoothly to zero away from detected sources.
            Set to a placeholder value of 1.0 if ``self.config.useModelWeights`` is False.
        refImage : `lsst.afw.image.Image`
            A reference image used to supply the default pixel values.
        dcrWeights : `list` of `lsst.afw.image.Image`
            Per-pixel weights for each subfilter.
            Equal to 1/(number of unmasked images contributing to each pixel).
 
        Returns
        -------
        dcrModel : `lsst.pipe.tasks.DcrModel`
            New model of the true sky after correcting chromatic effects.
        """
        newModelImages = []
        for subfilter, model in enumerate(dcrModels):
            residualsList = [next(residualGenerator) for residualGenerator in residualGeneratorList]
            residual = np.sum(residualsList, axis=0)
            residual *= dcrWeights[subfilter][dcrBBox].array
            # `MaskedImage`s only support in-place addition, so rename for readability
            newModel = model[dcrBBox].clone()
            newModel.array += residual
            # Catch any invalid values
            badPixels = ~np.isfinite(newModel.array)
            newModel.array[badPixels] = model[dcrBBox].array[badPixels]
            if self.config.regularizeModelIterations > 0:
                dcrModels.regularizeModelIter(subfilter, newModel, dcrBBox,
                                              self.config.regularizeModelIterations,
                                              self.config.regularizationWidth)
            newModelImages.append(newModel)
        if self.config.regularizeModelFrequency > 0:
            dcrModels.regularizeModelFreq(newModelImages, dcrBBox, statsCtrl,
                                          self.config.regularizeModelFrequency,
                                          self.config.regularizationWidth)
        dcrModels.conditionDcrModel(newModelImages, dcrBBox, gain=gain)
        self.applyModelWeights(newModelImages, refImage[dcrBBox], modelWeights)
        return DcrModel(newModelImages, dcrModels.filter, dcrModels.effectiveWavelength,
                        dcrModels.bandwidth, dcrModels.psf,
                        dcrModels.mask, dcrModels.variance)
 

selectCoaddPsf()

def lsst.pipe.tasks.dcrAssembleCoadd.selectCoaddPsf	(		self,
			templateCoadd,
			warpRefList
	)

Compute the PSF of the coadd from the exposures with the best seeing.

Parameters
----------
templateCoadd : `lsst.afw.image.ExposureF`
    The initial coadd exposure before accounting for DCR.
warpRefList : `list` of `lsst.daf.butler.DeferredDatasetHandle` or
    `lsst.daf.persistence.ButlerDataRef`
    The data references to the input warped exposures.

Returns
-------
psf : `lsst.meas.algorithms.CoaddPsf`
    The average PSF of the input exposures with the best seeing.

Definition at line 1308 of file dcrAssembleCoadd.py.

    def selectCoaddPsf(self, templateCoadd, warpRefList):
        """Compute the PSF of the coadd from the exposures with the best seeing.
 
        Parameters
        ----------
        templateCoadd : `lsst.afw.image.ExposureF`
            The initial coadd exposure before accounting for DCR.
        warpRefList : `list` of `lsst.daf.butler.DeferredDatasetHandle` or
            `lsst.daf.persistence.ButlerDataRef`
            The data references to the input warped exposures.
 
        Returns
        -------
        psf : `lsst.meas.algorithms.CoaddPsf`
            The average PSF of the input exposures with the best seeing.
        """
        sigma2fwhm = 2.*np.sqrt(2.*np.log(2.))
        tempExpName = self.getTempExpDatasetName(self.warpType)
        # Note: ``ccds`` is a `lsst.afw.table.ExposureCatalog` with one entry per ccd and per visit
        # If there are multiple ccds, it will have that many times more elements than ``warpExpRef``
        ccds = templateCoadd.getInfo().getCoaddInputs().ccds
        psfRefSize = templateCoadd.getPsf().computeShape().getDeterminantRadius()*sigma2fwhm
        psfSizes = np.zeros(len(ccds))
        ccdVisits = np.array(ccds["visit"])
        for warpExpRef in warpRefList:
            if isinstance(warpExpRef, DeferredDatasetHandle):
                # Gen 3 API
                psf = warpExpRef.get(component="psf")
            else:
                # Gen 2 API. Delete this when Gen 2 retired
                psf = warpExpRef.get(tempExpName).getPsf()
            visit = warpExpRef.dataId["visit"]
            psfSize = psf.computeShape().getDeterminantRadius()*sigma2fwhm
            psfSizes[ccdVisits == visit] = psfSize
        # Note that the input PSFs include DCR, which should be absent from the DcrCoadd
        # The selected PSFs are those that have a FWHM less than or equal to the smaller
        # of the mean or median FWHM of the input exposures.
        sizeThreshold = min(np.median(psfSizes), psfRefSize)
        goodPsfs = psfSizes <= sizeThreshold
        psf = measAlg.CoaddPsf(ccds[goodPsfs], templateCoadd.getWcs(),
                               self.config.coaddPsf.makeControl())
        return psf

stackCoadd()

def lsst.pipe.tasks.dcrAssembleCoadd.stackCoadd	(		self,
			dcrCoadds
	)

Add a list of sub-band coadds together.

Parameters
----------
dcrCoadds : `list` of `lsst.afw.image.ExposureF`
    A list of coadd exposures, each exposure containing
    the model for one subfilter.

Returns
-------
coaddExposure : `lsst.afw.image.ExposureF`
    A single coadd exposure that is the sum of the sub-bands.

Definition at line 1050 of file dcrAssembleCoadd.py.

    def stackCoadd(self, dcrCoadds):
        """Add a list of sub-band coadds together.
 
        Parameters
        ----------
        dcrCoadds : `list` of `lsst.afw.image.ExposureF`
            A list of coadd exposures, each exposure containing
            the model for one subfilter.
 
        Returns
        -------
        coaddExposure : `lsst.afw.image.ExposureF`
            A single coadd exposure that is the sum of the sub-bands.
        """
        coaddExposure = dcrCoadds[0].clone()
        for coadd in dcrCoadds[1:]:
            coaddExposure.maskedImage += coadd.maskedImage
        return coaddExposure
 

Variable Documentation

goodPix

lsst.pipe.tasks.dcrAssembleCoadd.goodPix

Definition at line 795 of file dcrAssembleCoadd.py.

weightsThreshold

lsst.pipe.tasks.dcrAssembleCoadd.weightsThreshold

Definition at line 794 of file dcrAssembleCoadd.py.