update deblender nb Fred comments

Author: christinawilliams

DP1/200_Data_Products/206_Deblender_Products/206_2_Deblender_Footprints.ipynb

@@ -19,7 +19,7 @@
     "Data Release: DP1 <br>\n",
     "Container Size: Large <br>\n",
     "LSST Science Pipelines version: Weekly 29.2.0 <br>\n",
-    "Last verified to run: 2025-09-22 <br>\n",
+    "Last verified to run: 2025-10-05 <br>\n",
     "Repository: <a href=\"https://github.com/lsst/tutorial-notebooks\">github.com/lsst/tutorial-notebooks</a> <br>"
    ]
   },
@@ -52,17 +52,17 @@
     "\n",
     "## 1. Introduction\n",
     "\n",
-    "This notebook demonstrates hot to reconstruct per-pixel models of objects that are deblended by the LSST Science Pipeline when building the `Object` table.\n",
+    "This notebook demonstrates how to reconstruct per-pixel models of objects that are deblended by the LSST Science Pipeline when building the `Object` table.\n",
     "\n",
-    "To measure the photometry of objects in `deep_coadd` images the LSST Science Pipelines use the multi-band deblending scarlet algorithm [Melchior et al. 2018](https://ui.adsabs.harvard.edu/abs/2018A%26C....24..129M/abstract) implemented with optimizations for LSST data in [scarlet lite](https://github.com/lsst/scarlet_lite). The core algorithm models objects in a blend as a collection of components that have the same spectrum in each pixel of their morphology, assuming that flux monotonically decreases from the peak (maximum pixel value) of the component.\n",
+    "To measure the photometry of objects in `deep_coadd` images, the LSST Science Pipeline uses the multi-band deblending scarlet algorithm [Melchior et al. 2018](https://ui.adsabs.harvard.edu/abs/2018A%26C....24..129M/abstract) implemented with optimizations for LSST data in [Scarlet Lite](https://github.com/lsst/scarlet_lite). The core algorithm models objects in a blend as a collection of components that have the same spectrum in each pixel of their morphology, assuming that flux monotonically decreases from the peak (maximum pixel value) of the component.\n",
     "\n",
     "This tutorial will begin with the coordinates of an object of interest and show how to obtain its model and the model of the other sources that are extracted from the same blend.\n",
     "\n",
     "**Note**: There have been updates to the deblending implementation since DP1 so _expect the API to be slightly different (improved) in future data releases_, including having more information available to understand how blended an object is with its neighbors and useful cuts to remove potentially more difficult blends from analysis.\n",
     "\n",
     "**References:** \n",
     "- A general discussion of blending impacts to LSST can be found in this article titled \"<a href=\"https://lss.fnal.gov/archive/2021/pub/fermilab-pub-21-598-ppd.pdf\">The challenge of blending in large sky surveys</a>\" by Melchior et al. 2021. \n",
-    "- Some more in-depth presentations on the deblending implementation in the LSST Science Pipelines are available from recorded talks during the Rubin Project and Community Workshop 2022's session on \"<a href=\"https://project.lsst.org/meetings/rubin2022/agenda/deblending-plans-and-challenges\">Deblending Plans and Challenges</a>\". \n",
+    "- Some more in-depth presentations on the deblending implementation in the LSST Science Pipeline are available from recorded talks during the Rubin Project and Community Workshop 2022's session on \"<a href=\"https://project.lsst.org/meetings/rubin2022/agenda/deblending-plans-and-challenges\">Deblending Plans and Challenges</a>\". \n",
     "- Further information about the available deblending flags, and the processes that produce the deblender data products discussed in this tutorial\n",
     "can be found in this <a href=\"https://pipelines.lsst.io/modules/lsst.pipe.tasks/deblending-flags-overview.html\">overview of the deblending flags</a>.\n",
     "\n",
@@ -78,7 +78,7 @@
    "source": [
     "### 1.1. Import packages\n",
     "\n",
-    "The `lsst.afw.image` provide access to some of the extended products created by the deblender pipeline. The `lsst.afw.display` library provides access to image visualization routines and the `lsst.daf.butler` library is used to access data products via the butler. Finally, `lsst.scarlet.lite` and `lsst.meas.extensions.scarlet` are two packages containing the scarlet software infrastructure, to enable displaying and analyzing deblended models and object footprints. "
+    "`lsst.afw.image` provides access to some of the extended products created by the deblender pipeline. The `lsst.afw.display` library provides access to image visualization routines and the `lsst.daf.butler` library is used to access data products via the butler. Finally, `lsst.scarlet.lite` and `lsst.meas.extensions.scarlet` are two packages containing the scarlet software infrastructure, to enable displaying and analyzing deblended models and object footprints. "
    ]
   },
   {
@@ -184,7 +184,7 @@
    "source": [
     "### 2.1. Query for deblended objects\n",
     "\n",
-    "Re-use a blend from notebook 206-1 on deblender data products, whose `parentObjectId` 611256447031839519. The blend is near the center of the ECDFS field. Define the center coordinates to enable a faster search for all objects that were deblended from this parent."
+    "Re-use a known blend whose `parentObjectId` 611256447031839519. The blend is near the center of the ECDFS field. Define the center coordinates to enable a faster search for all objects that were deblended from this parent."
    ]
   },
   {
@@ -286,7 +286,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "def cutout_coadd(butler, ra, dec, band='r', datasetType='deepCoadd',\n",
+    "def cutout_coadd(butler, ra, dec, band='i', datasetType='deepCoadd',\n",
     "                 skymap=None, cutoutSideLength=51, **kwargs):\n",
     "    \"\"\"\n",
     "    Produce a cutout from a coadd at the given ra, dec position.\n",
@@ -331,7 +331,7 @@
     "    parameters = {'bbox': bbox}\n",
     "\n",
     "    query = \"\"\"band.name = '{}' AND patch = {} AND tract = {}\n",
-    "        \"\"\".format('i', patch, tract)\n",
+    "        \"\"\".format(band, patch, tract)\n",
     "    print(query)\n",
     "\n",
     "    dataset_refs = butler.query_datasets(\"deep_coadd\", where=query)\n",
@@ -399,7 +399,7 @@
    "id": "4dc608a8-cb6b-48c8-9aa9-e30338da2070",
    "metadata": {},
    "source": [
-    "> Figure 1: The cutout image displayed in greyscale, with red circles marking the deblended children. \n"
+    "> Figure 1: The cutout of the i-band `deep_coadd` image displayed in greyscale, with red circles marking the deblended children. \n"
    ]
   },
   {
@@ -491,7 +491,7 @@
    "id": "1eba1318-9e93-409f-a82b-9db6deff25bc",
    "metadata": {},
    "source": [
-    "The LSST science pipelines use persistable `dataclass` objects as intermediaries between the storage containers and python classes. In the case of scarlet lite blends this is the `ScarletBlendData` class. Some attributes of the blend model can be retrieved from `modelData`.\n",
+    "The LSST science pipelines use persistable `dataclass` objects as intermediaries between the storage containers and python classes. In the case of Scarlet Lite blends, this is the `ScarletBlendData` class. Some attributes of the blend model can be retrieved from `modelData`.\n",
     "\n",
     "In order to reconstruct the blend, the model PSF from the deconvolved model space is also required. The model PSF is the same for all blends, so extract that here.\n",
     "\n",
@@ -529,7 +529,9 @@
     "from numpy.typing import DTypeLike\n",
     "from lsst.scarlet.lite import Box, Blend, Observation\n",
     "\n",
+    "\n",
     "def minimal_data_to_blend(cls, model_psf: np.ndarray, dtype: DTypeLike) -> Blend:\n",
+    "\n",
     "    \"\"\"Convert the storage data model into a scarlet lite blend\n",
     "\n",
     "    Parameters\n",
@@ -554,6 +556,7 @@
     "    )\n",
     "    return cls.to_blend(observation)\n",
     "\n",
+    "\n",
     "import lsst.scarlet as scarlet\n",
     "scarlet.lite.io.ScarletBlendData.minimal_data_to_blend = minimal_data_to_blend"
    ]
@@ -602,9 +605,9 @@
    "id": "2f0198a2-7081-41c5-b9dc-f7a019f55f46",
    "metadata": {},
    "source": [
-    "Printing `blend_data.bands` shows that this patch and tract in ECDFS was observed with all 6 bands but they are not in the order of increasing wavelength. To ensure that expected order, specify `model[tuple(\"ugrizy\")]` when retrieving the blend model to display the image with the expected color assignment in the cell below. If fewer bands of coverage exist (as is the case for some DP1 fields), simply replace this by the combination of observed bands, e.g. `tuple(\"griz\")`. We do this here as the `u` and `y` bands add unnecessary noise that makes it difficult to see the underlying objects.\n",
+    "Printing `blend_data.bands` shows that this patch and tract in ECDFS was observed with all 6 bands but they are not in the order of increasing wavelength. To ensure that expected order, specify `model[tuple(\"ugrizy\")]` when retrieving the blend model to display the image with the expected color assignment in the cell below. If fewer bands of coverage exist (as is the case for some DP1 fields), simply replace this by the combination of observed bands, e.g. `tuple(\"griz\")`. For this example, select only 4 filters and exclude the `u` and `y` bands, which add unnecessary noise that makes it difficult to see the underlying objects.\n",
     "\n",
-    "Note: this will change the order of the bands displayed in the model but **not** in the `blend` instance. After DP1 a change is planned so that `blend = blend[display_bands]` can be used to reorganize all of the models so that they are displayed in a new order."
+    "Note: this will change the order of the bands displayed in the model but **not** in the `blend` instance. After DP1, a change is planned so that `blend = blend[display_bands]` can be used to reorganize all of the models so that they are displayed in a new order."
    ]
   },
   {
@@ -623,7 +626,7 @@
    "id": "d9f03503-8a25-4be4-b5a8-f9558eb1b769",
    "metadata": {},
    "source": [
-    "Finally, plot a color image of the blend model. Use the `AsinhMapping` to normalize: the asinh stretch preserves colors independent of brightness (for more information see <a href=\"https://ui.adsabs.harvard.edu/abs/2004PASP..116..133L\">Lupton et al. 2024</a>). By default, Scarlet Lite will map the input filters into an RGB scaling where shorter wavelength filters map to blue and longer wavelength map to red (and assumes the order in the model is set as such, defined in the previous cell). This relative weighting between filters to RGB can be altered with the `channel_map` keyword to `img_to_rgb` (see documentation <a href=\"https://pmelchior.github.io/scarlet/tutorials/display.html\">here</a>)."
+    "Finally, plot a color image of the blend model. Use the `AsinhMapping` to normalize: the asinh stretch preserves colors independent of brightness (for more information see <a href=\"https://ui.adsabs.harvard.edu/abs/2004PASP..116..133L\">Lupton et al. 2024</a>). By default, Scarlet Lite will map the input filters into an red green blue (RGB) scaling where shorter wavelength filters map to blue and longer wavelength map to red (and assumes the order in the model is set as such, defined in the previous cell). This relative weighting between filters to RGB can be altered with the `channel_map` keyword to `img_to_rgb` (see documentation <a href=\"https://pmelchior.github.io/scarlet/tutorials/display.html\">here</a>)."
    ]
   },
   {
@@ -674,11 +677,10 @@
    "id": "9c1c15ff-a8b6-4110-8bec-f0a5d5ba6a63",
    "metadata": {},
    "source": [
-    "Build the bounding box of the parent (this allows extraction of a smaller region from the full coadd).\n",
-    "- The bands that we wish to load. Note: this needs to be in the same order as the `blend` band order in DP1.\n",
     "\n",
     "The tract and patch were already identified as part of the deep_coadd dataId in Section 3. Here, all that is needed is extract the bounding box of the `blend` and convert it from a `lsst.scarlet.lite.Box` to an `lsst.afw.Box2I`\n",
-    "\n"
+    "\n",
+    "In the cell below, build the bounding box of the parent (this allows extraction of a smaller region from the full coadd).\n"
    ]
   },
   {
@@ -699,7 +701,7 @@
    "source": [
     "Load the subset of the image that overlaps with the blend, then use the `blend_data` and the `observation` to create a full `Blend`. All of the model information is the same as the information from the `Blend` that we created earlier. Here, attach real `Observation` data as opposed to an empty `Observation` (as was done in Section 3.2). Notice that the `observed_bands` are passed here, not the `display_bands`, as these bands must match the order of the bands in the `blend`.\n",
     "\n",
-    "Model residuals compared to the observations are of interest for exploring how well the blend model matches the data. To do this, first load a multiband exposure as the input observation. Use the patch and tract to reconstruct the multiband `deep_coadd` for this blend.\n"
+    "Model residuals compared to the observations are of interest for exploring how well the blend model matches the data. To do this, first load a multiband exposure as the input observation. Use the `patch` and `tract` to reconstruct the multiband `deep_coadd` for this blend.\n"
    ]
   },
   {
@@ -716,7 +718,7 @@
     "observation = mes.utils.buildObservation(modelPsf=model_psf,\n",
     "                                         psfCenter=bbox.getCenter(),\n",
     "                                         mExposure=mCoadd,\n",
-    "                                        )\n",
+    "                                         )\n",
     "\n",
     "blend = blend_data.to_blend(observation)"
    ]
@@ -761,7 +763,7 @@
     "\n",
     "Now display the scene. The function scarlet `show_scene` will include the model footprints, the model rendered (i.e. convolved with the PSF), the locations on the observed multiband image, and residuals between the real image and the model. Model residuals compared to the observations are of interest for exploring how well the blend model matches the data. \n",
     "\n",
-    "To normalize the image use the Lupton red green blue (RGB) AsinhMapping, which preserves the observed colors.\n",
+    "To normalize the image, use the Lupton RGB AsinhMapping, which preserves the observed colors.\n",
     "\n",
     "Note: You'll notice that the colors match the processed color order, not the correct band order. In the future passing `blend[display_bands]` should display everything in the correct order.\n"
    ]
@@ -854,7 +856,7 @@
    "source": [
     "### 5.2 Creating the flux re-distributed models\n",
     "\n",
-    "In the LSST science pipelines, measurements are not made on the scarlet models directly. Imperfections in the PSF measurement and deviations of bright galaxies from a simple two-component monotonic morphology solution (see Melchior paper cited above) result in improper measurements. THIS STATEMENT TBD: Instead, a deblending algorithm based on the SDSS deblender is employed, using the scarlet models as templates, and flux is re-distributed from the input image based on the ratio of values for overlapping templates in an image."
+    "In the LSST science pipeline, measurements are not made on the Scarlet models directly. Imperfections in the PSF measurement and deviations of bright galaxies from a simple two-component monotonic morphology solution (see Melchior paper cited above) result in improper measurements. THIS STATEMENT TBD: Instead, a deblending algorithm based on the SDSS deblender is employed, using the scarlet models as templates, and flux is re-distributed from the input image based on the ratio of values for overlapping templates in an image."
    ]
   },
   {