Public Member Functions
	__init__ (self)

	makeBackgroundModel (self, in_x, pars=None)

	fitFootprintBackground (self, source, posImage, order=1)

	makeStarModel (self, bbox, psf, xcen, ycen, flux)

	makeModel (self, x, flux, xcenPos, ycenPos, xcenNeg, ycenNeg, fluxNeg=None, b=None, x1=None, y1=None, xy=None, x2=None, y2=None, bNeg=None, x1Neg=None, y1Neg=None, xyNeg=None, x2Neg=None, y2Neg=None, **kwargs)

Public Attributes
	debug

	log

Protected Member Functions
	_generateXYGrid (self, bbox)

	_getHeavyFootprintSubimage (self, fp, badfill=np.nan, grow=0)

Detailed Description

Lightweight class containing methods for generating a dipole model for fitting
to sources in diffims, used by DipoleFitAlgorithm.

See also:
`DMTN-007: Dipole characterization for image differencing  <https://dmtn-007.lsst.io>`_.

Definition at line 192 of file dipoleFitTask.py.

Constructor & Destructor Documentation

◆ init()

lsst.ip.diffim.dipoleFitTask.DipoleModel.__init__ ( self )

Definition at line 200 of file dipoleFitTask.py.

    def __init__(self):
        import lsstDebug
        self.debug = lsstDebug.Info(__name__).debug
        self.log = logging.getLogger(__name__)
 

Member Function Documentation

◆ _generateXYGrid()

lsst.ip.diffim.dipoleFitTask.DipoleModel._generateXYGrid	(		self,
			bbox )

protected

Generate a meshgrid covering the x,y coordinates bounded by bbox

Parameters
----------
bbox : `lsst.geom.Box2I`
    input Bounding Box defining the coordinate limits

Returns
-------
in_x : `numpy.array`
    (2, w, h)-dimensional numpy array containing the grid indexing over x- and
    y- coordinates

Definition at line 248 of file dipoleFitTask.py.

    def _generateXYGrid(self, bbox):
        """Generate a meshgrid covering the x,y coordinates bounded by bbox
 
        Parameters
        ----------
        bbox : `lsst.geom.Box2I`
            input Bounding Box defining the coordinate limits
 
        Returns
        -------
        in_x : `numpy.array`
            (2, w, h)-dimensional numpy array containing the grid indexing over x- and
            y- coordinates
        """
 
        x, y = np.mgrid[bbox.getBeginY():bbox.getEndY(), bbox.getBeginX():bbox.getEndX()]
        in_x = np.array([y, x]).astype(np.float64)
        in_x[0, :] -= np.mean(in_x[0, :])
        in_x[1, :] -= np.mean(in_x[1, :])
        return in_x
 

◆ _getHeavyFootprintSubimage()

lsst.ip.diffim.dipoleFitTask.DipoleModel._getHeavyFootprintSubimage	(	self,
		fp,
		badfill = np.nan,
		grow = 0 )

protected

Extract the image from a ``~lsst.afw.detection.HeavyFootprint``
as an `lsst.afw.image.ImageF`.

Parameters
----------
fp : `lsst.afw.detection.HeavyFootprint`
    HeavyFootprint to use to generate the subimage
badfill : `float`, optional
    Value to fill in pixels in extracted image that are outside the footprint
grow : `int`
    Optionally grow the footprint by this amount before extraction

Returns
-------
subim2 : `lsst.afw.image.ImageF`
    An `~lsst.afw.image.ImageF` containing the subimage.

Definition at line 269 of file dipoleFitTask.py.

    def _getHeavyFootprintSubimage(self, fp, badfill=np.nan, grow=0):
        """Extract the image from a ``~lsst.afw.detection.HeavyFootprint``
        as an `lsst.afw.image.ImageF`.
 
        Parameters
        ----------
        fp : `lsst.afw.detection.HeavyFootprint`
            HeavyFootprint to use to generate the subimage
        badfill : `float`, optional
            Value to fill in pixels in extracted image that are outside the footprint
        grow : `int`
            Optionally grow the footprint by this amount before extraction
 
        Returns
        -------
        subim2 : `lsst.afw.image.ImageF`
            An `~lsst.afw.image.ImageF` containing the subimage.
        """
        bbox = fp.getBBox()
        if grow > 0:
            bbox.grow(grow)
 
        subim2 = afwImage.ImageF(bbox, badfill)
        fp.getSpans().unflatten(subim2.array, fp.getImageArray(), bbox.getCorners()[0])
        return subim2
 

◆ fitFootprintBackground()

lsst.ip.diffim.dipoleFitTask.DipoleModel.fitFootprintBackground	(	self,
		source,
		posImage,
		order = 1 )

Fit a linear (polynomial) model of given order (max 2) to the background of a footprint.

Only fit the pixels OUTSIDE of the footprint, but within its bounding box.

Parameters
----------
source : `lsst.afw.table.SourceRecord`
    SourceRecord, the footprint of which is to be fit
posImage : `lsst.afw.image.Exposure`
    The exposure from which to extract the footprint subimage
order : `int`
    Polynomial order of background gradient to fit.

Returns
-------
pars : `tuple` of `float`
    `tuple` of length (1 if order==0; 3 if order==1; 6 if order == 2),
    containing the resulting fit parameters

Definition at line 295 of file dipoleFitTask.py.

    def fitFootprintBackground(self, source, posImage, order=1):
        """Fit a linear (polynomial) model of given order (max 2) to the background of a footprint.
 
        Only fit the pixels OUTSIDE of the footprint, but within its bounding box.
 
        Parameters
        ----------
        source : `lsst.afw.table.SourceRecord`
            SourceRecord, the footprint of which is to be fit
        posImage : `lsst.afw.image.Exposure`
            The exposure from which to extract the footprint subimage
        order : `int`
            Polynomial order of background gradient to fit.
 
        Returns
        -------
        pars : `tuple` of `float`
            `tuple` of length (1 if order==0; 3 if order==1; 6 if order == 2),
            containing the resulting fit parameters
        """
 
        # TODO look into whether to use afwMath background methods -- see
        # http://lsst-web.ncsa.illinois.edu/doxygen/x_masterDoxyDoc/_background_example.html
        fp = source.getFootprint()
        bbox = fp.getBBox()
        bbox.grow(3)
        posImg = afwImage.ImageF(posImage.image, bbox, afwImage.PARENT)
 
        # This code constructs the footprint image so that we can identify the pixels that are
        # outside the footprint (but within the bounding box). These are the pixels used for
        # fitting the background.
        posHfp = afwDet.HeavyFootprintF(fp, posImage.getMaskedImage())
        posFpImg = self._getHeavyFootprintSubimage(posHfp, grow=3)
 
        isBg = np.isnan(posFpImg.array).ravel()
 
        data = posImg.array.ravel()
        data = data[isBg]
        B = data
 
        x, y = np.mgrid[bbox.getBeginY():bbox.getEndY(), bbox.getBeginX():bbox.getEndX()]
        x = x.astype(np.float64).ravel()
        x -= np.mean(x)
        x = x[isBg]
        y = y.astype(np.float64).ravel()
        y -= np.mean(y)
        y = y[isBg]
        b = np.ones_like(x, dtype=np.float64)
 
        M = np.vstack([b]).T  # order = 0
        if order == 1:
            M = np.vstack([b, x, y]).T
        elif order == 2:
            M = np.vstack([b, x, y, x**2., y**2., x*y]).T
 
        pars = np.linalg.lstsq(M, B, rcond=-1)[0]
        return pars
 

◆ makeBackgroundModel()

lsst.ip.diffim.dipoleFitTask.DipoleModel.makeBackgroundModel	(	self,
		in_x,
		pars = None )

Generate gradient model (2-d array) with up to 2nd-order polynomial

Parameters
----------
in_x : `numpy.array`
    (2, w, h)-dimensional `numpy.array`, containing the
    input x,y meshgrid providing the coordinates upon which to
    compute the gradient. This will typically be generated via
    `_generateXYGrid()`. `w` and `h` correspond to the width and
    height of the desired grid.
pars : `list` of `float`, optional
    Up to 6 floats for up
    to 6 2nd-order 2-d polynomial gradient parameters, in the
    following order: (intercept, x, y, xy, x**2, y**2). If `pars`
    is emtpy or `None`, do nothing and return `None` (for speed).

Returns
-------
result : `None` or `numpy.array`
    return None, or 2-d numpy.array of width/height matching
    input bbox, containing computed gradient values.

Definition at line 205 of file dipoleFitTask.py.

    def makeBackgroundModel(self, in_x, pars=None):
        """Generate gradient model (2-d array) with up to 2nd-order polynomial
 
        Parameters
        ----------
        in_x : `numpy.array`
            (2, w, h)-dimensional `numpy.array`, containing the
            input x,y meshgrid providing the coordinates upon which to
            compute the gradient. This will typically be generated via
            `_generateXYGrid()`. `w` and `h` correspond to the width and
            height of the desired grid.
        pars : `list` of `float`, optional
            Up to 6 floats for up
            to 6 2nd-order 2-d polynomial gradient parameters, in the
            following order: (intercept, x, y, xy, x**2, y**2). If `pars`
            is emtpy or `None`, do nothing and return `None` (for speed).
 
        Returns
        -------
        result : `None` or `numpy.array`
            return None, or 2-d numpy.array of width/height matching
            input bbox, containing computed gradient values.
        """
 
        # Don't fit for other gradient parameters if the intercept is not included.
        if (pars is None) or (len(pars) <= 0) or (pars[0] is None):
            return
 
        y, x = in_x[0, :], in_x[1, :]
        gradient = np.full_like(x, pars[0], dtype='float64')
        if len(pars) > 1 and pars[1] is not None:
            gradient += pars[1] * x
        if len(pars) > 2 and pars[2] is not None:
            gradient += pars[2] * y
        if len(pars) > 3 and pars[3] is not None:
            gradient += pars[3] * (x * y)
        if len(pars) > 4 and pars[4] is not None:
            gradient += pars[4] * (x * x)
        if len(pars) > 5 and pars[5] is not None:
            gradient += pars[5] * (y * y)
 
        return gradient
 

◆ makeModel()

lsst.ip.diffim.dipoleFitTask.DipoleModel.makeModel	(		self,
			x,
			flux,
			xcenPos,
			ycenPos,
			xcenNeg,
			ycenNeg,
			fluxNeg = None,
			b = None,
			x1 = None,
			y1 = None,
			xy = None,
			x2 = None,
			y2 = None,
			bNeg = None,
			x1Neg = None,
			y1Neg = None,
			xyNeg = None,
			x2Neg = None,
			y2Neg = None,
		**	kwargs )

Generate dipole model with given parameters.

This is the function whose sum-of-squared difference from data
is minimized by `lmfit`.

x : TODO: DM-17458
    Input independent variable. Used here as the grid on
    which to compute the background gradient model.
flux : `float`
    Desired flux of the positive lobe of the dipole
xcenPos, ycenPos : `float`
    Desired x,y-centroid of the positive lobe of the dipole
xcenNeg, ycenNeg : `float`
    Desired x,y-centroid of the negative lobe of the dipole
fluxNeg : `float`, optional
    Desired flux of the negative lobe of the dipole, set to 'flux' if None
b, x1, y1, xy, x2, y2 : `float`
    Gradient parameters for positive lobe.
bNeg, x1Neg, y1Neg, xyNeg, x2Neg, y2Neg : `float`, optional
    Gradient parameters for negative lobe.
    They are set to the corresponding positive values if None.

**kwargs : `dict` [`str`]
    Keyword arguments passed through ``lmfit`` and
    used by this function. These must include:

    - ``psf`` Psf model used to generate the 'star'
    - ``rel_weight`` Used to signify least-squares weighting of posImage/negImage
        relative to diffim. If ``rel_weight == 0`` then posImage/negImage are ignored.
    - ``bbox`` Bounding box containing region to be modelled

Returns
-------
zout : `numpy.array`
    Has width and height matching the input bbox, and
    contains the dipole model with given centroids and flux(es). If
    ``rel_weight`` = 0, this is a 2-d array with dimensions matching
    those of bbox; otherwise a stack of three such arrays,
    representing the dipole (diffim), positive, and negative images
    respectively.

Definition at line 396 of file dipoleFitTask.py.

                  **kwargs):
        """Generate dipole model with given parameters.
 
        This is the function whose sum-of-squared difference from data
        is minimized by `lmfit`.
 
        x : TODO: DM-17458
            Input independent variable. Used here as the grid on
            which to compute the background gradient model.
        flux : `float`
            Desired flux of the positive lobe of the dipole
        xcenPos, ycenPos : `float`
            Desired x,y-centroid of the positive lobe of the dipole
        xcenNeg, ycenNeg : `float`
            Desired x,y-centroid of the negative lobe of the dipole
        fluxNeg : `float`, optional
            Desired flux of the negative lobe of the dipole, set to 'flux' if None
        b, x1, y1, xy, x2, y2 : `float`
            Gradient parameters for positive lobe.
        bNeg, x1Neg, y1Neg, xyNeg, x2Neg, y2Neg : `float`, optional
            Gradient parameters for negative lobe.
            They are set to the corresponding positive values if None.
 
        **kwargs : `dict` [`str`]
            Keyword arguments passed through ``lmfit`` and
            used by this function. These must include:
 
            - ``psf`` Psf model used to generate the 'star'
            - ``rel_weight`` Used to signify least-squares weighting of posImage/negImage
                relative to diffim. If ``rel_weight == 0`` then posImage/negImage are ignored.
            - ``bbox`` Bounding box containing region to be modelled
 
        Returns
        -------
        zout : `numpy.array`
            Has width and height matching the input bbox, and
            contains the dipole model with given centroids and flux(es). If
            ``rel_weight`` = 0, this is a 2-d array with dimensions matching
            those of bbox; otherwise a stack of three such arrays,
            representing the dipole (diffim), positive, and negative images
            respectively.
        """
 
        psf = kwargs.get('psf')
        rel_weight = kwargs.get('rel_weight')  # if > 0, we're including pre-sub. images
        fp = kwargs.get('footprint')
        bbox = fp.getBBox()
 
        if fluxNeg is None:
            fluxNeg = flux
 
        self.log.debug('flux: %.2f fluxNeg: %.2f x+: %.2f x-: %.2f y+: %.2f y-: %.2f ',
                       flux, fluxNeg, xcenPos, xcenNeg, ycenPos, ycenNeg)
        if x1 is not None:
            self.log.debug('     b: %.2f x1: %.2f y1: %.2f', b, x1, y1)
        if xy is not None:
            self.log.debug('     xy: %.2f x2: %.2f y2: %.2f', xy, x2, y2)
 
        posIm = self.makeStarModel(bbox, psf, xcenPos, ycenPos, flux)
        negIm = self.makeStarModel(bbox, psf, xcenNeg, ycenNeg, fluxNeg)
 
        in_x = x
        if in_x is None:  # use the footprint to generate the input grid
            y, x = np.mgrid[bbox.getBeginY():bbox.getEndY(), bbox.getBeginX():bbox.getEndX()]
            in_x = np.array([x, y]) * 1.
            in_x[0, :] -= in_x[0, :].mean()  # center it!
            in_x[1, :] -= in_x[1, :].mean()
 
        if b is not None:
            gradient = self.makeBackgroundModel(in_x, (b, x1, y1, xy, x2, y2))
 
            # If bNeg is None, then don't fit the negative background separately
            if bNeg is not None:
                gradientNeg = self.makeBackgroundModel(in_x, (bNeg, x1Neg, y1Neg, xyNeg, x2Neg, y2Neg))
            else:
                gradientNeg = gradient
 
            posIm.array[:, :] += gradient
            negIm.array[:, :] += gradientNeg
 
        # Generate the diffIm model
        diffIm = afwImage.ImageF(bbox)
        diffIm += posIm
        diffIm -= negIm
 
        zout = diffIm.array
        if rel_weight > 0.:
            zout = np.append([zout], [posIm.array, negIm.array], axis=0)
 
        return zout
 
 

◆ makeStarModel()

lsst.ip.diffim.dipoleFitTask.DipoleModel.makeStarModel	(	self,
		bbox,
		psf,
		xcen,
		ycen,
		flux )

Generate a 2D image model of a single PDF centered at the given coordinates.

Parameters
----------
bbox : `lsst.geom.Box`
    Bounding box marking pixel coordinates for generated model
psf : TODO: DM-17458
    Psf model used to generate the 'star'
xcen : `float`
    Desired x-centroid of the 'star'
ycen : `float`
    Desired y-centroid of the 'star'
flux : `float`
    Desired flux of the 'star'

Returns
-------
p_Im : `lsst.afw.image.Image`
    2-d stellar image of width/height matching input ``bbox``,
    containing PSF with given centroid and flux

Definition at line 353 of file dipoleFitTask.py.

    def makeStarModel(self, bbox, psf, xcen, ycen, flux):
        """Generate a 2D image model of a single PDF centered at the given coordinates.
 
        Parameters
        ----------
        bbox : `lsst.geom.Box`
            Bounding box marking pixel coordinates for generated model
        psf : TODO: DM-17458
            Psf model used to generate the 'star'
        xcen : `float`
            Desired x-centroid of the 'star'
        ycen : `float`
            Desired y-centroid of the 'star'
        flux : `float`
            Desired flux of the 'star'
 
        Returns
        -------
        p_Im : `lsst.afw.image.Image`
            2-d stellar image of width/height matching input ``bbox``,
            containing PSF with given centroid and flux
        """
 
        # Generate the psf image, normalize to flux
        psf_img = psf.computeImage(geom.Point2D(xcen, ycen)).convertF()
        psf_img_sum = np.nansum(psf_img.array)
        psf_img *= (flux/psf_img_sum)
 
        # Clip the PSF image bounding box to fall within the footprint bounding box
        psf_box = psf_img.getBBox()
        psf_box.clip(bbox)
        psf_img = afwImage.ImageF(psf_img, psf_box, afwImage.PARENT)
 
        # Then actually crop the psf image.
        # Usually not necessary, but if the dipole is near the edge of the image...
        # Would be nice if we could compare original pos_box with clipped pos_box and
        #     see if it actually was clipped.
        p_Im = afwImage.ImageF(bbox)
        tmpSubim = afwImage.ImageF(p_Im, psf_box, afwImage.PARENT)
        tmpSubim += psf_img
 
        return p_Im
 

Member Data Documentation

◆ debug

lsst.ip.diffim.dipoleFitTask.DipoleModel.debug

Definition at line 202 of file dipoleFitTask.py.

◆ log

lsst.ip.diffim.dipoleFitTask.DipoleModel.log

Definition at line 203 of file dipoleFitTask.py.

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

/j/snowflake/release/lsstsw/stack/lsst-scipipe-8.0.0/Linux64/ip_diffim/g180d380827+a53a32eff8/python/lsst/ip/diffim/dipoleFitTask.py

Public Member Functions

Public Attributes

Protected Member Functions