DM-44889: Investigate feasibility of resurrecting matchBackgrounds.py background fitting algorithms #956

aemerywatkins · 2024-07-09T12:49:31Z

The matchBackgrounds.py script was an initial attempt at matching multiple warped visit-level images to a given reference image. Taking the difference images between the reference and each subsequent image allows for each of these images to be modified to match the background of the reference image. These images may then be stacked (coadded), and a single background estimation made on the combined (and, importantly, deeper) coadd image.

The existing matchBackgroundsTask has not been utilized in some time. This ticket aims to explore the feasibility of resurrecting this code base, with a mind towards testing on HSC in the near-term.

TallJimbo

Seems like a decent cleanup of the existing code. Only serious problem is the use of a single BackgroundList to represent the backgrounds for all visits, but that should be easy to fix (and I think using more visit-ID-keyed dicts instead of lists will help in other parts of the code, too).

TallJimbo · 2025-11-12T16:03:21Z

python/lsst/pipe/tasks/matchBackgrounds.py

+    refWarpVisit = Field[int](
+        doc="Visit ID of the reference warp. If None, the best warp is chosen from the list of warps.",
+        optional=True,
+    )


This field would always have to be None in production. I assume it's here just for testing?

TallJimbo · 2025-11-12T16:05:19Z

python/lsst/pipe/tasks/matchBackgrounds.py

+        default=0.2,
+        min=0.0,
+        max=1.0,
+    )


I think it might make sense to put reference image selection into a subtask, so if you wanted to use a different algorithm with totally different config parameters, you could retarget.

TallJimbo · 2025-11-12T16:07:22Z

python/lsst/pipe/tasks/matchBackgrounds.py

-        default=256
+    binSize = Field[int](
+        doc="Bin size for gridding the difference image and fitting a spatial model.",
+        default=1024,


This new default seems enormous for background matching. I think a lot of the point of the algorithm is to be able to fit the background on small scales, because you know what you're fitting is not astrophysical.

TallJimbo · 2025-11-12T16:30:46Z

python/lsst/pipe/tasks/matchBackgrounds.py

+        self.statsFlag = stringToStatisticsProperty(self.config.gridStatistic)
+        self.statsCtrl = StatisticsControl()
+        # TODO: Check that setting the mask planes here work - these planes
+        # can vary from exposure to exposure, I think?


This is safe. The mask planes do not vary from exposure to exposure (that's how getPlaneBitMask can be a static method). Enforcing that adds complexity in other places, but it's code like this that benefits.

TallJimbo · 2025-11-12T16:32:31Z

python/lsst/pipe/tasks/matchBackgrounds.py

-                All fields except isReference will be None if isReference True or the fit failed.
+        result : `~lsst.afw.math.BackgroundList`
+            Differential background model
+            Add this to the science exposure to match the reference exposure.


What "science exposure"? This method takes N warps, so it seems like it needs to return N-1 BackgroundList objects.

TallJimbo · 2025-11-12T16:42:02Z

python/lsst/pipe/tasks/matchBackgrounds.py

-        return pipeBase.Struct(
-            backgroundInfoList=backgroundInfoList)
+        # TODO: more elegant solution than inserting blank model at ref ind?
+        backgroundInfoList.insert(refInd, blank)


I think this explains my confusion about the return type in the docs. A BackgroundList represents the background for a single image (in this case, it'd all be single-element lists, or zero for the reference).

I think you want this to be a dict mapping visit ID to BackgroundList - and that solves the problem of what to do for the reference image, too: it just doesn't get an entry in that dict.

TallJimbo · 2025-11-12T16:49:50Z

python/lsst/pipe/tasks/matchBackgrounds.py

+        warpNPointsGlobal = []  # Global coverage
+        warpNPointsEdge = []  # Edge coverage
+        for warpDDH in warps:
+            warp = warpDDH.get()


In the long term, it'd be better to compute these quantities earlier, when we make the warps, and save a compact representation so we don't have read each full warp twice in this task.

TallJimbo · 2025-11-12T16:51:39Z

python/lsst/pipe/tasks/matchBackgrounds.py

-        costFunctionArr += self.config.bestRefWeightCoverage * coverageArr
-        return numpy.nanargmin(costFunctionArr)
+        nx = warp.getWidth() // self.config.binSize
+        ny = warp.getHeight() // self.config.binSize


Is it a problem that you're rounding down here but rounding up around line 291?

TallJimbo · 2025-11-12T16:54:01Z

python/lsst/pipe/tasks/matchBackgrounds.py

+        """
+        maskedImage = exposure.getMaskedImage()
+        fluxZp = exposure.getPhotoCalib().instFluxToNanojansky(1)
+        exposure.image.array *= fluxZp


I'm pretty sure the PhotoCalib method has a method that calibrates an image directly. That should also take care of scaling the variance appropriately, which is not happening (but should) here.

TallJimbo · 2025-11-12T16:55:30Z

python/lsst/pipe/tasks/matchBackgrounds.py

+        Process creates a difference image of the reference exposure minus the
+        science exposure, and then generates an afw.math.Background object. It
+        assumes (but does not require/check) that the mask plane already has
+        detections set. If detections have not been set/masked, sources will


The whole point of background matching is that the astrophysical sources should subtract away, and I think that means we don't need to mask detections. Even if the subtractions are't super clean, they should average out if we've done the right photometric scaling.

Initial version of this task is written using old architecture, and so needs updating. In MatchBackgroundsTask, and its method selectRefExposure, required parameters were equally outdated: DataId, DatasetType, and ImageScaler. All of these now seem consolidated under lsst.afw.image.Exposure, so separate calls to DataId and DatasetType are now single calls for Exposure objects. ImageScaler calls were replaced in-line with Exposure.getPhotoCalib() calls, to scale all image flux to the same zeropoint (nJy). Also, we want to process visit-level images using this, so a MatchBackgroundsConnections class was created, MatchBackgroundsConfig was updated to inherit from PipelineTaskConfig (and those connections), and a rudimentary runQuantum method was added to MatchBackgroundsTask.

Code now runs without complaint through self.matchBackgrounds. Also added a self._fluxScale method to replace repeat code blocks. Will decide later if scaling to nJy is the best way to do this.

Code is now functional, in that it accepts images and returns difference image background models as "psfMatchedWarpBackground_diff" (name likely to be altered later). Uses a fit to a blank image for that corresponding to the reference image.

Difference background models are now formatted properly, to allow for image creation from the spline parameters. Also did some adjustments to documentation for Flake8 formatting.

_defineWarps() now rejects any image with all NaNs along any image edge, and creates the cost function using a sky-subtracted image. This sky-subtraction fits a 1st order Chebyshev polynomial to the masked image background. Also fixed a bug from LSK refactor by inserting a blank sky model into the background model list at the chosen reference image index.

Otherwise, changes are clean-up from previous refactoring to restore functionality, plus a bug fix. Bug fix was the restoration of two lines of code in MatchBackgroundsTask.matchBackgrounds() which produced a difference image to work from.

All images and background models now returned in counts, not nJy.

`matchBackgrounds` in its original form matches by warps, i.e. single detectors. A more sensible thing to do is to match backgrounds across the whole focal plane. This functionality needed to be added to do this using warped exposures, in tract coordinates, so this is now added to `backgrounds.py`. This commit also includes a partial revision to `matchBackgrounds.py` using this new functionality, choosing a reference visit ID based on these background models instead of on individual warps. Full functionality has yet to be restored in light of these changes.

All methods, including run, updated to function properly with tract backgrounds rather than warps. Task completes without error when run on three full visits, and output appears roughly correct.

TallJimbo · 2025-11-13T19:52:00Z

python/lsst/pipe/tasks/background.py

    "SkyMeasurementTask",
    "SkyStatsConfig",
+    "TractBackground",
+    "TractBackgroundConfig",


Please move these tasks to a new module, and then revert any changes to the rest of this module that were just formatting.

Reformatting an existing file (in a package where we don't have GitHub Actions set up to keep it that way) is only merited in cases where you're doing significant modifications to that code anyway (so I think matchBackgrounds.py qualifies but background.py does not), and in that case the reformatting really should be on a separate commit.

TallJimbo · 2025-11-13T19:54:35Z

python/lsst/pipe/tasks/background.py

+class TractBackground:
+    """
+    As FocalPlaneBackground, but works in warped tract coordinates
+    """


Docstring should start on the first line, and I think it needs to be a bit more than just this sentence.

TallJimbo · 2025-11-13T19:55:11Z

python/lsst/pipe/tasks/background.py

+        background : `TractBackground`
+            Something guaranteed to be a `TractBackground`.
+        """
+        return cls(other.config, other.tract, other.dims, other.transform, other._values, other._numbers)


This method doesn't seem to be used anywhere.

TallJimbo · 2025-11-13T19:55:38Z

python/lsst/pipe/tasks/background.py

+        """Constructor
+
+        Developers should note that changes to the signature of this method
+        require coordinated changes to the `__reduce__` and `clone` methods.


Put this in a code comment.

TallJimbo · 2025-11-13T20:05:48Z

python/lsst/pipe/tasks/background.py

+        values : `lsst.afw.image.ImageF`
+            Measured background values.
+        numbers : `lsst.afw.image.ImageF`
+            Number of pixels in each background measurement.


__init__ parameter docs should go in the class docstring. I don't think a docstring on an __init__ actually goes anywhere useful. Or at least it doesn't end up in all of the useful places.

TallJimbo · 2025-11-13T20:50:19Z

python/lsst/pipe/tasks/matchBackgrounds.py

+            # TODO: as stated above, fitting a pre-binned image results in a
+            # null variance image.  But we want to add variance into the cost
+            # function.  How best to do that?  Below is a bad temporary
+            # solution, just assuming variance = mean


I'd recommend computing an estimate of the variance earlier and attaching it to the tract backgrounds (i.e. as a scalar). variance = mean is definitely not going to hold in nJy.

TallJimbo · 2025-11-13T20:56:02Z

python/lsst/pipe/tasks/matchBackgrounds.py

-            Data for ref 1.
+        fluxZp = exposure.getPhotoCalib().instFluxToNanojansky(1)
+        exposure.image *= fluxZp
+        return fluxZp


Since warps are now nJy, I don't think you need this method anymore, and deleting it is the easiest way to find the places that call it.

TallJimbo · 2025-11-13T20:57:25Z

python/lsst/pipe/tasks/matchBackgrounds.py

+        binned FFP reference image, then generates TractBackground
+        objects.  It assumes (but does not require/check) that the mask planes
+        already have detections set.  If detections have not been set/masked,
+        sources will bias the difference image background estimation.


Shouldn't the sources subtract out, and hence not bias the difference image background estimation?

If it looks like they are biasing the backgrounds, then that sort of throws the whole premise into doubt (unless it's something simple, like needing to use PSF-matched warps instead of direct warps).

TallJimbo · 2025-11-13T21:01:13Z

python/lsst/pipe/tasks/matchBackgrounds.py

+            maskIm.image += bkgdIm
+            # Then convert everything back to counts
+            maskIm.image /= instFluxToNanojansky
+            bkgdIm /= instFluxToNanojansky


More now-unnecessary pixel calibrations.

TallJimbo · 2025-11-13T21:01:55Z

python/lsst/pipe/tasks/matchBackgrounds.py

+        backgrounds are then used to generate 'offset' images for each warp
+        comprising the full science exposure visit, which are then added to
+        each warp to match the background to that of the reference visit at the
+        warp's location within the tract.


What happens when one of the patches doesn't fully overlap the reference visit?

aemerywatkins force-pushed the tickets/DM-44889 branch from d99bc60 to 8dfbe5e Compare July 15, 2024 12:56

leeskelvin force-pushed the tickets/DM-44889 branch 2 times, most recently from a95c234 to b0463a5 Compare July 19, 2024 19:32

leeskelvin force-pushed the tickets/DM-44889 branch from 7c1554f to fea12d4 Compare July 30, 2024 02:26

aemerywatkins force-pushed the tickets/DM-44889 branch from fea12d4 to 30ebfa0 Compare September 24, 2024 09:26

aemerywatkins force-pushed the tickets/DM-44889 branch from 52df871 to 3210ec9 Compare November 13, 2024 09:30

aemerywatkins force-pushed the tickets/DM-44889 branch from a969a20 to f379682 Compare December 16, 2024 19:04

aemerywatkins force-pushed the tickets/DM-44889 branch from ac42437 to c652ce0 Compare April 17, 2025 14:54

aemerywatkins force-pushed the tickets/DM-44889 branch from 6a6037f to 10cf7cc Compare June 5, 2025 13:57

aemerywatkins marked this pull request as ready for review June 5, 2025 13:58

aemerywatkins requested a review from TallJimbo June 5, 2025 14:14

leeskelvin force-pushed the tickets/DM-44889 branch from 10cf7cc to 072ece2 Compare November 12, 2025 15:54

TallJimbo approved these changes Nov 12, 2025

View reviewed changes

aemerywatkins force-pushed the tickets/DM-44889 branch from 072ece2 to d957a3c Compare November 13, 2025 16:55

aemerywatkins and others added 15 commits November 13, 2025 08:59

Change input data type to deepCoadd_psfMatchedWarp

8f41439

Code now runs without complaint through self.matchBackgrounds. Also added a self._fluxScale method to replace repeat code blocks. Will decide later if scaling to nJy is the best way to do this.

Change output from Struct to BackgroundList

2425945

Code is now functional, in that it accepts images and returns difference image background models as "psfMatchedWarpBackground_diff" (name likely to be altered later). Uses a fit to a blank image for that corresponding to the reference image.

Apply spline parameters to BackgroundList

2be09c5

Difference background models are now formatted properly, to allow for image creation from the spline parameters. Also did some adjustments to documentation for Flake8 formatting.

Refactor by LSK

a716628

Refactor by LSK, round 2

1204bf5

Add background-matched image data type

e31f60f

Otherwise, changes are clean-up from previous refactoring to restore functionality, plus a bug fix. Bug fix was the restoration of two lines of code in MatchBackgroundsTask.matchBackgrounds() which produced a difference image to work from.

Refactor and bug-fix, AEW

8cc4222

All images and background models now returned in counts, not nJy.

Add config for reference image selection bin size

b097ced

Refactor AEW

a681eda

Full tract background refactor AEW

48b51dc

All methods, including run, updated to function properly with tract backgrounds rather than warps. Task completes without error when run on three full visits, and output appears roughly correct.

Refactor and update TODO comments, AEW

6f25868

Rename connections; fix accidental forced rebasing

b7318ec

aemerywatkins force-pushed the tickets/DM-44889 branch from d957a3c to b7318ec Compare November 13, 2025 16:59

TallJimbo approved these changes Nov 13, 2025

View reviewed changes

DM-44889: Investigate feasibility of resurrecting matchBackgrounds.py background fitting algorithms #956

Are you sure you want to change the base?

DM-44889: Investigate feasibility of resurrecting matchBackgrounds.py background fitting algorithms #956

Uh oh!

Conversation

aemerywatkins commented Jul 9, 2024

Uh oh!

TallJimbo left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants