Support generating regional heat maps from the volume metrics output

bin/sample_cmds_bash.ipynb

@@ -520,17 +520,107 @@
     "\n",
     "TODO\n",
     "\n",
-    "### Volume metrics for each atlas region\n",
+    "### Build and test ground truth sets\n",
     "\n",
-    "TODO\n",
+    "TODO"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Putting it together: quantify cells by region\n",
     "\n",
-    "### Blob colocalization\n",
+    "#### Regional quantification\n",
     "\n",
-    "TODO\n",
+    "After detection cells and registering an atlas, we can put these together to measure the cells per region.\n",
     "\n",
-    "### Build and test ground truth sets\n",
+    "First, generate a table of cells per atlas region:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "vscode": {
+     "languageId": "plaintext"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "./run.py --img \"$img\" --register vol_stats"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Next, combine regions into hierarchical structures. `level` sets the max (finest) hierarchical level, which allows only including high-level, larger structures (eg, `level=1`). In this case, we use a deep level to include all possible structures. `--atlas_profile combinesides` uses a profile that combines matching left and right regions and can be omitted to separate these regions."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "vscode": {
+     "languageId": "plaintext"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "./run.py --img \"$img\" \\\n",
+    "  --register vol_stats \\\n",
+    "  --labels level=13 \\\n",
+    "  --atlas_profile combinesides"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "#### Regional heat map\n",
     "\n",
-    "TODO"
+    "The cell counts, region densities, and other metrics can be visualized by replacing each region with its metric value.\n",
+    "\n",
+    "First, generate this regional heat map, here shown for the density values. Here, `\"${img}_volumes_level13.csv\"` is the path to the hierarchical volume metrics file produced above. `--plot_labels x_col=\"Density\"` says to use the density column in this file."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "vscode": {
+     "languageId": "plaintext"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "./run.py \"$img\" \"${img}_volumes_level13.csv\" \\\n",
+    "  --register labels_diff_stats \\\n",
+    "  --plot_labels x_col=\"Density\""
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Next, open the regional heat map. `--plot_labels nan_color=black` sets unlabeled regions to black. After opening the image, turn down the labels opacity to see the heat map. `--labels binary='#00000000,#000000ff'` can also be added to make the labels transparent automatically. The colormap can be changed in the \"Adjust Image > Color\" panel setting."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "vscode": {
+     "languageId": "plaintext"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "./run.py \"$img\" \\\n",
+    "  --reg_suffixes annotationDiff_Density.mhd annotation.mhd \\\n",
+    "  --roi_profile diverging \\\n",
+    "  --plot_labels nan_color=black"
    ]
   },
   {

magmap/atlas/reg_tasks.py

@@ -12,25 +12,35 @@
 
 
 def build_labels_diff_images(paths: Optional[Sequence[str]] = None):
-    """Build labels difference images for given metrics.
+    """Build labels difference images or regional heat maps for given metrics.
 
-    Replaces each label in an atlas labels image with the value of the effect
-    size of the given metric.
+    Replaces each label in an atlas labels image with the metric value.
 
     :class:`magmap.settings.config.PlotLabels.X_COL` in
     :attr:`magmap.settings.config.plot_labels` can be used to change the
-    metric column.
+    metric column, which otherwise defaults to "vals.effect".
 
     Args:
-        paths: Paths to volume stat files output from the R pipeline.
+        paths: Paths to volume stat files output from the R pipeline or
+            output from the ``--register vol_stats`` pipeline
+            (:meth:`magmap.atlas.register.volumes_by_id`).
 
     """
+    # set the measurement column
+    col_meas = config.plot_labels[config.PlotLabels.X_COL]
+    if not col_meas:
+        col_meas = "vals.effect"
+
     if paths:
         # set up metrics from filenames after first (image) filename;
         # extract metrics from R stats filename format
         path_dfs = paths
         metrics = [re.search(r"vols_stats_(.*).csv", p) for p in path_dfs]
         metrics = [m.group(1) if m else m for m in metrics]
+        if not metrics[0]:
+            # fall back to the measurement column, eg for metrics from the
+            # vol_stats pipeline
+            metrics[0] = col_meas
     else:
         # set up default metrics and assume corresponding CSVs are in
         # current working directory
@@ -44,11 +54,6 @@ def build_labels_diff_images(paths: Optional[Sequence[str]] = None):
         )
         path_dfs = [f"vols_stats_{m}.csv" for m in metrics]
 
-    # set the measurement column
-    col_meas = config.plot_labels[config.PlotLabels.X_COL]
-    if not col_meas:
-        col_meas = "vals.effect"
-
     for path_df, metric in zip(path_dfs, metrics):
         if not os.path.exists(path_df):
             # check for existing R stats file