updates to text and a little code cleanup

Author: kadrlica

05_Intro_to_Source_Detection.ipynb

@@ -80,6 +80,7 @@
     "import lsst.afw.table as afwTable\n",
     "import lsst.geom as geom\n",
     "\n",
+    "# Import Pipeline tasks \n",
     "from lsst.pipe.tasks.characterizeImage import CharacterizeImageTask\n",
     "from lsst.pipe.tasks.calibrate import CalibrateTask\n",
     "from lsst.meas.algorithms.detection import SourceDetectionTask\n",
@@ -94,7 +95,8 @@
    "outputs": [],
    "source": [
     "# Use lsst.afw.display with the matplotlib backend\n",
-    "afwDisplay.setDefaultBackend('matplotlib')"
+    "afwDisplay.setDefaultBackend('matplotlib')\n",
+    "plt.rcParams['figure.figsize'] = (8.0, 8.0)"
    ]
   },
   {
@@ -114,7 +116,7 @@
    "source": [
     "## 1.0 Data access\n",
     "\n",
-    "Here we use the `butler` to access a `calexp` from the DP0.1 dataset. More information on the `butler` and `calexp`, and how to determine the `dataId` (e.g., tract and patch, or as in the example below, visit id, raftName, and detector) are available in other tutorials. Here we start assuming that information is known, and assuming a basic understanding of `butler` use.\n",
+    "Here we use the `butler` to access a `calexp` from the DP0.1 dataset. More information on the `butler` and `calexp`, and how to determine the `dataId` (e.g., the visit and detector numbers) are available in other tutorials. Here we start assuming that information is known, and assuming a basic understanding of `butler` use.\n",
     "\n",
     "If a warning in pink is output below, it is related to the recent gen2 to gen3 butler upgrade, and can be ignored."
    ]
@@ -197,7 +199,6 @@
    "outputs": [],
    "source": [
     "# Plot the calexp we just retrieved\n",
-    "plt.rcParams['figure.figsize'] = (5.0, 5.0)\n",
     "plt.figure()\n",
     "afw_display = afwDisplay.Display()\n",
     "afw_display.scale('asinh', 'zscale')\n",
@@ -235,7 +236,10 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "plt.imshow(bkgd.getImage().array, origin='lower', cmap='gray')\n",
+    "plt.figure()\n",
+    "afw_display = afwDisplay.Display()\n",
+    "afw_display.scale('linear', 'zscale')\n",
+    "afw_display.mtv(bkgd.getImage())\n",
     "plt.title(\"Local Polynomial Background\")"
    ]
   },
@@ -252,8 +256,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "mi = calexp.maskedImage\n",
-    "mi += bkgd.getImage()"
+    "# Note: executing this cell multiple times will add the background multiple times\n",
+    "calexp.maskedImage += bkgd.getImage()"
    ]
   },
   {
@@ -262,7 +266,6 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "plt.rcParams['figure.figsize'] = (5.0, 5.0)\n",
     "plt.figure()\n",
     "afw_display = afwDisplay.Display()\n",
     "afw_display.scale('asinh', 'zscale')\n",
@@ -319,7 +322,6 @@
    "outputs": [],
    "source": [
     "# Follow the same procedure as before to plot the cutout\n",
-    "plt.rcParams['figure.figsize'] = (5.0, 5.0)\n",
     "plt.figure()\n",
     "afw_display = afwDisplay.Display()\n",
     "afw_display.scale('asinh', 'zscale')\n",
@@ -335,9 +337,9 @@
     "\n",
     "We now want to run the LSST Science Pipelines' source detection, deblending, and measurement tasks. While we run all three tasks, this notebook is mostly focused on the detection of sources.\n",
     "\n",
-    "Recall that these tasks were imported up at the top of this notebook, from `lsst.pipe` and `lsst.meas`. More information can be found at pipelines.lsst.io (on that page, the search bar at upper left is a very handy way to find documentation for a specific task).\n",
+    "Recall that these tasks were imported up at the top of this notebook, from `lsst.pipe` and `lsst.meas`. More information can be found at [pipelines.lsst.io](https://pipelines.lsst.io/) (the search bar at the top left of that page is a very handy way to find documentation for a specific task).\n",
     "\n",
-    "We start by creating the most minimial schema possible. This schema will be passed to all of the tasks, as we call each in turn, and each task will add columns to this schema as it measures sources in the image."
+    "We start by creating a minimal schema for the source table. The schema describes the output properties that will be measured for each source. This schema will be passed to all of the tasks, as we call each in turn, and each task will add columns to this schema as it measures sources in the image."
    ]
   },
   {
@@ -361,9 +363,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### 2.1 Configuration Classes\n",
+    "### 2.1 Configuring Tasks\n",
     "\n",
-    "Each task possesses an associated configuration class. The properties of these classes can be determined from the classes themselves."
+    "Each task possesses an associated configuration class. The properties of these configuration classes can be determined from the classes themselves."
    ]
   },
   {
@@ -384,7 +386,12 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "As a starting point, like the `schema` and `algMetadata` above, here we set some basic config parameters to get you started."
+    "As a starting point, like the `schema` and `algMetadata` above, here we set some basic config parameters and instantiate the tasks to get you started. In this case, we configure several different tasks:\n",
+    "\n",
+    "* CharacterizeImageTask: Characterizes the image properties (e.g., PSF, etc.)\n",
+    "* SourceDetectionTask: Detects sources\n",
+    "* SourceDeblendTask: Deblend sources into constituent children\n",
+    "* SingleFrameMeasurementTask: Measures source properties"
    ]
   },
   {
@@ -393,21 +400,23 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "# Characterize the image properties\n",
     "config = CharacterizeImageTask.ConfigClass()\n",
     "config.psfIterations = 1\n",
     "charImageTask = CharacterizeImageTask(config=config)\n",
     "\n",
+    "# Detect sources\n",
     "config = SourceDetectionTask.ConfigClass()\n",
-    "\n",
     "# detection threshold in units of thresholdType\n",
     "config.thresholdValue = 10\n",
-    "\n",
     "# units for thresholdValue\n",
     "config.thresholdType = \"stdev\"\n",
-    "\n",
     "sourceDetectionTask = SourceDetectionTask(schema=schema, config=config)\n",
+    "\n",
+    "# Deblend sources\n",
     "sourceDeblendTask = SourceDeblendTask(schema=schema)\n",
     "\n",
+    "# Measure source properties\n",
     "config = SingleFrameMeasurementTask.ConfigClass()\n",
     "sourceMeasurementTask = SingleFrameMeasurementTask(schema=schema,\n",
     "                                                   config=config,\n",
@@ -685,20 +694,18 @@
    "source": [
     "## 3.0 Footprints\n",
     "\n",
-    "To quote [Bosch et al. (2017)](https://arxiv.org/pdf/1705.06766.pdf), \n",
+    "Object footprints are an integral component of the high-level CCD processing tasks (e.g., detection, measurement, and deblending). To quote [Bosch et al. (2017)](https://arxiv.org/pdf/1705.06766.pdf), \n",
     "\n",
     "> Footprints record the exact above-threshold detection region on a CCD. These are similar to  SExtractor’s “segmentation map\", in that they identify which pixels belong to which detected objects\n",
     "\n",
-    "As you might expect, this means footprints are integral to high-level CCD processing tasks—like detection, measurement, and deblending—which directly impact science results. Because footprints are so closely related to these very important processes, we will take a look at them in this notebook.\n",
-    "\n",
-    "In the quote above, an analogy was drawn between footprints and segmentation maps, as they both identify above threshold pixels. As we first introduce footprints, we will concentrate on this similarity as it gives us a place to start understanding the location and geometeric properties of footprints. "
+    "This quote draws an analogy between footprints and segmentation maps, since they both identify pixels with values above some threshold. This is a useful similarity, since it gives us a place to start understanding the properties of footprints."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "We will use the `detectFootprints` method in `SourceDetectionTask` to find and store the detected footprints in the image"
+    "The result of the `SourceDetectionTask` stores the footprints associated to detected objects"
    ]
   },
   {
@@ -736,7 +743,7 @@
    "source": [
     "### 3.1 Heavy Footprints\n",
     "\n",
-    "To extract the actual pixel values that correspond to the ones in the span, we need an additional step. At the moment, our footprints can tell you if a pixel belongs to it or not, but are not accessing pixel values on the image. To remedy this, we will turn our footprint into a `HeavyFootprint`. HeavyFootprints have all of the qualities of Footprints, but additionally 'know' about pixel level data from the image, variance, and mask planes."
+    "At the moment, our footprints indicate which pixels they consist of, but not the values of those pixels from the image. To extract the actual values of the pixels that correspond to the ones in the footprint span, we need to convert our footprint into a `HeavyFootprint`. HeavyFootprints have all of the qualities of Footprints, but additionally 'know' about pixel level data from the image, variance, and mask planes."
    ]
   },
   {
@@ -781,7 +788,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Now we can use the spanset to reassemble the image array into the footprint. Above we saw that the image array is a 1D numpy array-but the footprint itself is 2 dimensional. Fortunately, the span set has an `unflatten` method that we will use, which can rearrange the image array into the proper 2 dimensional shape. If you want to change the colormap, see [matplotlib colormap options](https://matplotlib.org/stable/tutorials/colors/colormaps.html)."
+    "Now we can use the span set to reassemble the image array into the footprint. Above we saw that the image array is a 1D numpy array, but the footprint itself is 2 dimensional. Fortunately, the span set has an `unflatten` method that rearranges the image array into the proper 2 dimensional shape. If you want to change the colormap, see [matplotlib colormap options](https://matplotlib.org/stable/tutorials/colors/colormaps.html)."
    ]
   },
   {
@@ -790,7 +797,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "plt.rcParams['figure.figsize'] = (6.0, 6.0)\n",
+    "plt.figure()\n",
     "plt.imshow(fps[0].getSpans().unflatten(hfps[0].getImageArray()),\n",
     "           cmap='bone', origin='lower')"
    ]
@@ -831,7 +838,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The values are the exponent of the bitmask. So pixels only marked detected will be 2^5 = 32. Pixels that are both on the edge and detected will be 2^5 + 2^4 = 48. Now we will visualize this in a similar manner to the imshow exercise we did before, only now we are *only* using data for the footprint because we are using the span."
+    "The values are the exponent of the bitmask. So pixels only marked detected will be 2^5 = 32. Pixels that are both on the edge of the original image and detected will be 2^5 + 2^4 = 48. We will visualize the mask plane values in a similar manner as before, except that we will be displaying the values of the mask array."
    ]
   },
   {
@@ -840,17 +847,16 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "plt.figure(figsize=(6, 6))\n",
-    "ax = plt.gca()\n",
-    "\n",
+    "plt.figure()\n",
     "im = plt.imshow(fps[0].getSpans().unflatten(hfps[0].getMaskArray()),\n",
     "                origin='lower')\n",
     "\n",
     "# Create a new axis, \"cax\" on the right side of the image display.\n",
     "# The width of cax will be 5% of the axis \"ax\".\n",
-    "# The padding between cax and ax will be fixed at 0.05 inch.\n",
+    "# The padding between cax and ax will be 1% of the axis.\n",
+    "ax = plt.gca()\n",
     "divider = make_axes_locatable(ax)\n",
-    "cax = divider.append_axes(\"right\", size=\"5%\", pad=0.05)\n",
+    "cax = divider.append_axes(\"right\", size=\"5%\", pad=\"1%\")\n",
     "plt.colorbar(im, cax=cax, ticks=[0, 32, 32+16])"
    ]
   },