Inheritance diagram for lsst.pipe.tasks.background.SkyMeasurementTask:

Public Member Functions
	backgroundToExposure (self, statsImage, bbox)

	measureBackground (self, image)

	averageBackgrounds (self, bgList)

	measureScale (self, image, skyBackground)

	solveScales (self, scales)

	subtractSkyFrame (self, image, skyBackground, scale, bgList=None)

Static Public Member Functions
	exposureToBackground (bgExp)

Static Public Attributes
	ConfigClass = SkyMeasurementConfig

Detailed Description

Task for creating, persisting and using sky frames

A sky frame is like a fringe frame (the sum of many exposures of the night sky,
combined with rejection to remove astrophysical objects) except the structure
is on larger scales, and hence we bin the images and represent them as a
background model (a `lsst.afw.math.BackgroundMI`).  The sky frame represents
the dominant response of the camera to the sky background.

Definition at line 116 of file background.py.

Member Function Documentation

◆ averageBackgrounds()

lsst.pipe.tasks.background.SkyMeasurementTask.averageBackgrounds	(		self,
			bgList )

Average multiple background models

The input background models should be a `BackgroundList` consisting
of a single `BackgroundMI`.

Parameters
----------
bgList : `list` of `lsst.afw.math.BackgroundList`
    Background models to average.

Returns
-------
bgExp : `lsst.afw.image.Exposure`
    Background model in Exposure format.

Definition at line 227 of file background.py.

    def averageBackgrounds(self, bgList):
        """Average multiple background models
 
        The input background models should be a `BackgroundList` consisting
        of a single `BackgroundMI`.
 
        Parameters
        ----------
        bgList : `list` of `lsst.afw.math.BackgroundList`
            Background models to average.
 
        Returns
        -------
        bgExp : `lsst.afw.image.Exposure`
            Background model in Exposure format.
        """
        assert all(len(bg) == 1 for bg in bgList), "Mixed bgList: %s" % ([len(bg) for bg in bgList],)
        images = [bg[0][0].getStatsImage() for bg in bgList]
        boxes = [bg[0][0].getImageBBox() for bg in bgList]
        assert len(set((box.getMinX(), box.getMinY(), box.getMaxX(), box.getMaxY()) for box in boxes)) == 1, \
            "Bounding boxes not all equal"
        bbox = boxes.pop(0)
 
        # Ensure bad pixels are masked
        maskVal = afwImage.Mask.getPlaneBitMask("BAD")
        for img in images:
            bad = numpy.isnan(img.getImage().getArray())
            img.getMask().getArray()[bad] = maskVal
 
        stats = afwMath.StatisticsControl()
        stats.setAndMask(maskVal)
        stats.setNanSafe(True)
        combined = afwMath.statisticsStack(images, afwMath.MEANCLIP, stats)
 
        # Set bad pixels to the median
        # Specifically NOT going to attempt to interpolate the bad values because we're only working on a
        # single CCD here and can't use the entire field-of-view to do the interpolation (which is what we
        # would need to avoid introducing problems at the edge of CCDs).
        array = combined.getImage().getArray()
        bad = numpy.isnan(array)
        median = numpy.median(array[~bad])
        array[bad] = median
 
        # Put it into an exposure, which is required for calibs
        return self.backgroundToExposure(combined, bbox)
 

◆ backgroundToExposure()

lsst.pipe.tasks.background.SkyMeasurementTask.backgroundToExposure	(	self,
		statsImage,
		bbox )

Convert a background model to an exposure

Calibs need to be persisted as an Exposure, so we need to convert
the background model to an Exposure.

Parameters
----------
statsImage : `lsst.afw.image.MaskedImageF`
    Background model's statistics image.
bbox : `lsst.geom.Box2I`
    Bounding box for image.

Returns
-------
exp : `lsst.afw.image.Exposure`
    Background model in Exposure format.

Definition at line 158 of file background.py.

    def backgroundToExposure(self, statsImage, bbox):
        """Convert a background model to an exposure
 
        Calibs need to be persisted as an Exposure, so we need to convert
        the background model to an Exposure.
 
        Parameters
        ----------
        statsImage : `lsst.afw.image.MaskedImageF`
            Background model's statistics image.
        bbox : `lsst.geom.Box2I`
            Bounding box for image.
 
        Returns
        -------
        exp : `lsst.afw.image.Exposure`
            Background model in Exposure format.
        """
        exp = afwImage.makeExposure(statsImage)
        header = exp.getMetadata()
        header.set("BOX.MINX", bbox.getMinX())
        header.set("BOX.MINY", bbox.getMinY())
        header.set("BOX.MAXX", bbox.getMaxX())
        header.set("BOX.MAXY", bbox.getMaxY())
        header.set("ALGORITHM", self.config.background.algorithm)
        return exp
 

◆ exposureToBackground()

lsst.pipe.tasks.background.SkyMeasurementTask.exposureToBackground ( bgExp )

static

Convert an exposure to background model

Calibs need to be persisted as an Exposure, so we need to convert
the persisted Exposure to a background model.

Parameters
----------
bgExp : `lsst.afw.image.Exposure`
    Background model in Exposure format.

Returns
-------
bg : `lsst.afw.math.BackgroundList`
    Background model

Definition at line 128 of file background.py.

    def exposureToBackground(bgExp):
        """Convert an exposure to background model
 
        Calibs need to be persisted as an Exposure, so we need to convert
        the persisted Exposure to a background model.
 
        Parameters
        ----------
        bgExp : `lsst.afw.image.Exposure`
            Background model in Exposure format.
 
        Returns
        -------
        bg : `lsst.afw.math.BackgroundList`
            Background model
        """
        header = bgExp.getMetadata()
        xMin = header.getScalar("BOX.MINX")
        yMin = header.getScalar("BOX.MINY")
        xMax = header.getScalar("BOX.MAXX")
        yMax = header.getScalar("BOX.MAXY")
        algorithm = header.getScalar("ALGORITHM")
        bbox = geom.Box2I(geom.Point2I(xMin, yMin), geom.Point2I(xMax, yMax))
        return afwMath.BackgroundList(
            (afwMath.BackgroundMI(bbox, bgExp.getMaskedImage()),
             afwMath.stringToInterpStyle(algorithm),
             afwMath.stringToUndersampleStyle("REDUCE_INTERP_ORDER"),
             afwMath.ApproximateControl.UNKNOWN,
             0, 0, False))
 

◆ measureBackground()

lsst.pipe.tasks.background.SkyMeasurementTask.measureBackground	(		self,
			image )

Measure a background model for image

This doesn't use a full-featured background model (e.g., no Chebyshev
approximation) because we just want the binning behaviour.  This will
allow us to average the bins later (`averageBackgrounds`).

The `BackgroundMI` is wrapped in a `BackgroundList` so it can be
pickled and persisted.

Parameters
----------
image : `lsst.afw.image.MaskedImage`
    Image for which to measure background.

Returns
-------
bgModel : `lsst.afw.math.BackgroundList`
    Background model.

Definition at line 185 of file background.py.

    def measureBackground(self, image):
        """Measure a background model for image
 
        This doesn't use a full-featured background model (e.g., no Chebyshev
        approximation) because we just want the binning behaviour.  This will
        allow us to average the bins later (`averageBackgrounds`).
 
        The `BackgroundMI` is wrapped in a `BackgroundList` so it can be
        pickled and persisted.
 
        Parameters
        ----------
        image : `lsst.afw.image.MaskedImage`
            Image for which to measure background.
 
        Returns
        -------
        bgModel : `lsst.afw.math.BackgroundList`
            Background model.
        """
        stats = afwMath.StatisticsControl()
        stats.setAndMask(image.getMask().getPlaneBitMask(self.config.background.mask))
        stats.setNanSafe(True)
        ctrl = afwMath.BackgroundControl(
            self.config.background.algorithm,
            max(int(image.getWidth()/self.config.background.xBinSize + 0.5), 1),
            max(int(image.getHeight()/self.config.background.yBinSize + 0.5), 1),
            "REDUCE_INTERP_ORDER",
            stats,
            self.config.background.statistic
        )
 
        bg = afwMath.makeBackground(image, ctrl)
 
        return afwMath.BackgroundList((
            bg,
            afwMath.stringToInterpStyle(self.config.background.algorithm),
            afwMath.stringToUndersampleStyle("REDUCE_INTERP_ORDER"),
            afwMath.ApproximateControl.UNKNOWN,
            0, 0, False
        ))
 

◆ measureScale()

lsst.pipe.tasks.background.SkyMeasurementTask.measureScale	(	self,
		image,
		skyBackground )

Measure scale of background model in image

We treat the sky frame much as we would a fringe frame
(except the length scale of the variations is different):
we measure samples on the input image and the sky frame,
which we will use to determine the scaling factor in the
'solveScales` method.

Parameters
----------
image : `lsst.afw.image.Exposure` or `lsst.afw.image.MaskedImage`
    Science image for which to measure scale.
skyBackground : `lsst.afw.math.BackgroundList`
    Sky background model.

Returns
-------
imageSamples : `numpy.ndarray`
    Sample measurements on image.
skySamples : `numpy.ndarray`
    Sample measurements on sky frame.

Definition at line 273 of file background.py.

    def measureScale(self, image, skyBackground):
        """Measure scale of background model in image
 
        We treat the sky frame much as we would a fringe frame
        (except the length scale of the variations is different):
        we measure samples on the input image and the sky frame,
        which we will use to determine the scaling factor in the
        'solveScales` method.
 
        Parameters
        ----------
        image : `lsst.afw.image.Exposure` or `lsst.afw.image.MaskedImage`
            Science image for which to measure scale.
        skyBackground : `lsst.afw.math.BackgroundList`
            Sky background model.
 
        Returns
        -------
        imageSamples : `numpy.ndarray`
            Sample measurements on image.
        skySamples : `numpy.ndarray`
            Sample measurements on sky frame.
        """
        if isinstance(image, afwImage.Exposure):
            image = image.getMaskedImage()
        # Ensure more samples than pixels
        xNumSamples = min(self.config.xNumSamples, image.getWidth())
        yNumSamples = min(self.config.yNumSamples, image.getHeight())
        xLimits = numpy.linspace(0, image.getWidth(), xNumSamples + 1, dtype=int)
        yLimits = numpy.linspace(0, image.getHeight(), yNumSamples + 1, dtype=int)
        sky = skyBackground.getImage()
        maskVal = image.getMask().getPlaneBitMask(self.config.stats.mask)
        ctrl = afwMath.StatisticsControl(self.config.stats.clip, self.config.stats.nIter, maskVal)
        statistic = afwMath.stringToStatisticsProperty(self.config.stats.statistic)
        imageSamples = []
        skySamples = []
        for xIndex, yIndex in itertools.product(range(xNumSamples), range(yNumSamples)):
            # -1 on the stop because Box2I is inclusive of the end point and we don't want to overlap boxes
            xStart, xStop = xLimits[xIndex], xLimits[xIndex + 1] - 1
            yStart, yStop = yLimits[yIndex], yLimits[yIndex + 1] - 1
            box = geom.Box2I(geom.Point2I(xStart, yStart), geom.Point2I(xStop, yStop))
            subImage = image.Factory(image, box)
            subSky = sky.Factory(sky, box)
            imageSamples.append(afwMath.makeStatistics(subImage, statistic, ctrl).getValue())
            skySamples.append(afwMath.makeStatistics(subSky, statistic, ctrl).getValue())
        return imageSamples, skySamples
 

◆ solveScales()

lsst.pipe.tasks.background.SkyMeasurementTask.solveScales	(		self,
			scales )

Solve multiple scales for a single scale factor

Having measured samples from the image and sky frame, we
fit for the scaling factor.

Parameters
----------
scales : `list` of a `tuple` of two `numpy.ndarray` arrays
    A `list` of the results from `measureScale` method.

Returns
-------
scale : `float`
    Scale factor.

Definition at line 320 of file background.py.

    def solveScales(self, scales):
        """Solve multiple scales for a single scale factor
 
        Having measured samples from the image and sky frame, we
        fit for the scaling factor.
 
        Parameters
        ----------
        scales : `list` of a `tuple` of two `numpy.ndarray` arrays
            A `list` of the results from `measureScale` method.
 
        Returns
        -------
        scale : `float`
            Scale factor.
        """
        imageSamples = []
        skySamples = []
        for ii, ss in scales:
            imageSamples.extend(ii)
            skySamples.extend(ss)
        assert len(imageSamples) == len(skySamples)
        imageSamples = numpy.array(imageSamples)
        skySamples = numpy.array(skySamples)
 
        def solve(mask):
            return afwMath.LeastSquares.fromDesignMatrix(skySamples[mask].reshape(mask.sum(), 1),
                                                         imageSamples[mask],
                                                         afwMath.LeastSquares.DIRECT_SVD).getSolution()
 
        mask = numpy.isfinite(imageSamples) & numpy.isfinite(skySamples)
        for ii in range(self.config.skyIter):
            solution = solve(mask)
            residuals = imageSamples - solution*skySamples
            lq, uq = numpy.percentile(residuals[mask], [25, 75])
            stdev = 0.741*(uq - lq)  # Robust stdev from IQR
            with numpy.errstate(invalid="ignore"):  # suppress NAN warnings
                bad = numpy.abs(residuals) > self.config.skyRej*stdev
            mask[bad] = False
 
        return solve(mask)
 

◆ subtractSkyFrame()

lsst.pipe.tasks.background.SkyMeasurementTask.subtractSkyFrame	(	self,
		image,
		skyBackground,
		scale,
		bgList = None )

Subtract sky frame from science image

Parameters
----------
image : `lsst.afw.image.Exposure` or `lsst.afw.image.MaskedImage`
    Science image.
skyBackground : `lsst.afw.math.BackgroundList`
    Sky background model.
scale : `float`
    Scale to apply to background model.
bgList : `lsst.afw.math.BackgroundList`
    List of backgrounds applied to image

Definition at line 362 of file background.py.

    def subtractSkyFrame(self, image, skyBackground, scale, bgList=None):
        """Subtract sky frame from science image
 
        Parameters
        ----------
        image : `lsst.afw.image.Exposure` or `lsst.afw.image.MaskedImage`
            Science image.
        skyBackground : `lsst.afw.math.BackgroundList`
            Sky background model.
        scale : `float`
            Scale to apply to background model.
        bgList : `lsst.afw.math.BackgroundList`
            List of backgrounds applied to image
        """
        if isinstance(image, afwImage.Exposure):
            image = image.getMaskedImage()
        if isinstance(image, afwImage.MaskedImage):
            image = image.getImage()
        image.scaledMinus(scale, skyBackground.getImage())
        if bgList is not None:
            # Append the sky frame to the list of applied background models
            bgData = list(skyBackground[0])
            bg = bgData[0]
            statsImage = bg.getStatsImage().clone()
            statsImage *= scale
            newBg = afwMath.BackgroundMI(bg.getImageBBox(), statsImage)
            newBgData = [newBg] + bgData[1:]
            bgList.append(newBgData)
 
 

Member Data Documentation

◆ ConfigClass

lsst.pipe.tasks.background.SkyMeasurementTask.ConfigClass = SkyMeasurementConfig