Fix duplicate notebook numbers and restructure to standard format (#1181)

* Renumber duplicate user guide notebooks (#1180)

Two notebooks shared prefix 48 and four shared prefix 50.
Renumber to a gap-free 48-54 sequence, ordered by commit date.

* Restructure 13 user guide notebooks to standard format (#1180)

Notebooks 38, 40-41, 44-49, 51-54 were missing the standard cell
sequence (title, "What you'll build", imports intro, data section,
References). Each notebook now follows the established structure:

- Cell 0: h1 title in "Xarray-Spatial {module}: {tools}" format
- Cell 1: "What you'll build" with anchor-linked section list
- Cells 2-7: imports one-liner, imports, data header, data gen, description, plot
- Final cell: References with real URLs

Also fixed:
- ax.imshow(data.values) replaced with data.plot.imshow() throughout
- Red/green colormap in 48_Sieve_Filter swapped for teal/blue/orange
- Em dashes removed from prose
- Patch legends added to categorical overlays

Author: brendancol

examples/user_guide/38_Focal_Variety.ipynb

@@ -2,48 +2,70 @@
  "cells": [
   {
    "cell_type": "markdown",
+   "id": "c7fbe19f",
    "metadata": {},
    "source": [
-    "# Focal Variety\n",
+    "# Xarray-Spatial Focal: Variety\n",
     "\n",
-    "Focal variety counts the number of distinct values in a sliding\n",
-    "neighbourhood window.  It is most useful for categorical rasters\n",
-    "(land-cover, soil type, geology codes) where you want to map\n",
-    "boundary complexity or patch fragmentation.\n",
+    "Focal variety counts distinct values in a sliding window over a categorical raster, making it a natural fit for mapping boundary complexity in land-cover, soil-type, or geology data. This notebook walks through computing focal variety with `xrspatial.focal.focal_stats`, comparing kernel shapes, and combining variety with other focal statistics."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "5be55dfa",
+   "metadata": {},
+   "source": [
+    "### What you'll build\n",
+    "\n",
+    "1. Create a synthetic categorical raster with multiple land-cover classes\n",
+    "2. Compute focal variety with a 3x3 box kernel\n",
+    "3. Compare kernel shapes: box vs. circle\n",
+    "4. Combine variety with other focal statistics in a single call\n",
     "\n",
-    "This notebook shows how to compute focal variety with\n",
-    "`xrspatial.focal.focal_stats` across different kernel shapes."
+    "![preview](images/38_focal_variety.png)\n",
+    "\n",
+    "**Jump to a section:**\n",
+    "[Box kernel](#Focal-variety-with-a-3x3-box-kernel) | [Circle kernel](#Larger-kernel:-5x5-circle) | [Combined stats](#Combining-variety-with-other-focal-stats)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "97b8f358",
+   "metadata": {},
+   "source": [
+    "Standard imports plus `focal_stats` and kernel helpers from xrspatial."
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "id": "02ef24af",
    "metadata": {},
-   "outputs": [],
    "source": [
+    "%matplotlib inline\n",
     "import numpy as np\n",
     "import xarray as xr\n",
     "import matplotlib.pyplot as plt\n",
     "\n",
-    "from xrspatial.convolution import circle_kernel, custom_kernel\n",
+    "from xrspatial.convolution import circle_kernel\n",
     "from xrspatial.focal import focal_stats"
-   ]
+   ],
+   "execution_count": null,
+   "outputs": []
   },
   {
    "cell_type": "markdown",
+   "id": "739ea631",
    "metadata": {},
    "source": [
-    "## Create a synthetic land-cover raster\n",
+    "## Synthetic land-cover raster\n",
     "\n",
-    "We build a 60x60 grid with four land-cover classes arranged in\n",
-    "quadrants, plus a few scattered patches to make things interesting."
+    "We build a 60x60 grid with four land-cover classes arranged in quadrants, plus scattered class-5 patches to introduce boundary complexity."
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "id": "e56a9eed",
    "metadata": {},
-   "outputs": [],
    "source": [
     "rng = np.random.default_rng(42)\n",
     "rows, cols = 60, 60\n",
@@ -59,132 +81,161 @@
     "    r, c = rng.integers(0, rows), rng.integers(0, cols)\n",
     "    lc[r:r+3, c:c+3] = 5\n",
     "\n",
-    "land_cover = xr.DataArray(lc, dims=['y', 'x'], name='land_cover')\n",
-    "\n",
+    "land_cover = xr.DataArray(lc, dims=['y', 'x'], name='land_cover')"
+   ],
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e0e82d41",
+   "metadata": {},
+   "source": [
+    "Five land-cover classes on a 60x60 grid. The quadrant layout gives clean boundaries for focal variety to detect, and the random class-5 patches add smaller-scale fragmentation."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "id": "71f0d71b",
+   "metadata": {},
+   "source": [
     "fig, ax = plt.subplots(figsize=(5, 5))\n",
-    "land_cover.plot(ax=ax, cmap='Set2', add_colorbar=True)\n",
+    "land_cover.plot.imshow(ax=ax, cmap='Set2', add_colorbar=True)\n",
     "ax.set_title('Synthetic land-cover raster')\n",
     "ax.set_aspect('equal')\n",
-    "plt.tight_layout()\n",
-    "plt.show()"
-   ]
+    "plt.tight_layout()"
+   ],
+   "execution_count": null,
+   "outputs": []
   },
   {
    "cell_type": "markdown",
+   "id": "d6612cec",
    "metadata": {},
    "source": [
-    "## Compute focal variety with a 3x3 box kernel\n",
+    "## Focal variety with a 3x3 box kernel\n",
     "\n",
-    "A 3x3 box kernel counts how many distinct classes appear in the\n",
-    "immediate 8-connected neighbourhood of each pixel."
+    "A 3x3 box kernel counts how many distinct classes appear in the immediate 8-connected neighborhood of each pixel."
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "id": "8d35b5ca",
    "metadata": {},
-   "outputs": [],
    "source": [
     "kernel_box = np.ones((3, 3))\n",
     "result_box = focal_stats(land_cover, kernel_box, stats_funcs=['variety'])\n",
     "variety_box = result_box.sel(stats='variety')\n",
     "\n",
     "fig, axes = plt.subplots(1, 2, figsize=(10, 4))\n",
-    "land_cover.plot(ax=axes[0], cmap='Set2', add_colorbar=True)\n",
+    "land_cover.plot.imshow(ax=axes[0], cmap='Set2', add_colorbar=True)\n",
     "axes[0].set_title('Land cover')\n",
     "axes[0].set_aspect('equal')\n",
     "\n",
-    "variety_box.plot(ax=axes[1], cmap='YlOrRd', add_colorbar=True)\n",
+    "variety_box.plot.imshow(ax=axes[1], cmap='YlOrBr', add_colorbar=True)\n",
     "axes[1].set_title('Focal variety (3x3 box)')\n",
     "axes[1].set_aspect('equal')\n",
-    "plt.tight_layout()\n",
-    "plt.show()"
-   ]
+    "plt.tight_layout()"
+   ],
+   "execution_count": null,
+   "outputs": []
   },
   {
    "cell_type": "markdown",
+   "id": "1c67b93d",
    "metadata": {},
    "source": [
-    "Pixels deep inside a uniform quadrant show variety = 1.  Pixels on\n",
-    "boundaries between classes show variety = 2, 3, or 4 depending on\n",
-    "how many classes meet at that point.  The scattered class-5 patches\n",
-    "create small pockets of higher variety."
+    "Pixels deep inside a uniform quadrant show variety = 1. Pixels on boundaries between classes show variety = 2, 3, or 4 depending on how many classes meet at that point. The scattered class-5 patches create small pockets of higher variety."
    ]
   },
   {
    "cell_type": "markdown",
+   "id": "68589081",
    "metadata": {},
    "source": [
     "## Larger kernel: 5x5 circle\n",
     "\n",
-    "Increasing the kernel radius captures more of the surrounding\n",
-    "landscape, so variety values near boundaries will be higher."
+    "Increasing the kernel radius captures more of the surrounding landscape, so variety values near boundaries will be higher."
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "id": "e5f082d4",
    "metadata": {},
-   "outputs": [],
    "source": [
     "kernel_circle = circle_kernel(2, 2, 2)\n",
     "result_circle = focal_stats(land_cover, kernel_circle, stats_funcs=['variety'])\n",
     "variety_circle = result_circle.sel(stats='variety')\n",
     "\n",
     "fig, axes = plt.subplots(1, 2, figsize=(10, 4))\n",
-    "variety_box.plot(ax=axes[0], cmap='YlOrRd', add_colorbar=True)\n",
+    "variety_box.plot.imshow(ax=axes[0], cmap='YlOrBr', add_colorbar=True)\n",
     "axes[0].set_title('Variety (3x3 box)')\n",
     "axes[0].set_aspect('equal')\n",
     "\n",
-    "variety_circle.plot(ax=axes[1], cmap='YlOrRd', add_colorbar=True)\n",
+    "variety_circle.plot.imshow(ax=axes[1], cmap='YlOrBr', add_colorbar=True)\n",
     "axes[1].set_title('Variety (5x5 circle)')\n",
     "axes[1].set_aspect('equal')\n",
     "plt.tight_layout()\n",
-    "plt.show()"
-   ]
+    "\n",
+    "# Save preview image\n",
+    "import pathlib\n",
+    "pathlib.Path('images').mkdir(exist_ok=True)\n",
+    "fig.savefig('images/38_focal_variety.png', bbox_inches='tight', dpi=120)"
+   ],
+   "execution_count": null,
+   "outputs": []
   },
   {
    "cell_type": "markdown",
+   "id": "917145b4",
    "metadata": {},
    "source": [
     "## Combining variety with other focal stats\n",
     "\n",
-    "You can request variety alongside other statistics in one call.\n",
-    "Here we grab both range and variety to compare continuous and\n",
-    "categorical measures of local heterogeneity."
+    "You can request variety alongside other statistics in one call. Here we compute both range and variety to compare continuous and categorical measures of local heterogeneity."
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "id": "e5a93cd5",
    "metadata": {},
-   "outputs": [],
    "source": [
     "result_combo = focal_stats(land_cover, kernel_box,\n",
     "                           stats_funcs=['range', 'variety'])\n",
     "\n",
     "fig, axes = plt.subplots(1, 2, figsize=(10, 4))\n",
-    "result_combo.sel(stats='range').plot(ax=axes[0], cmap='viridis',\n",
-    "                                     add_colorbar=True)\n",
+    "result_combo.sel(stats='range').plot.imshow(ax=axes[0], cmap='viridis',\n",
+    "                                            add_colorbar=True)\n",
     "axes[0].set_title('Focal range')\n",
     "axes[0].set_aspect('equal')\n",
     "\n",
-    "result_combo.sel(stats='variety').plot(ax=axes[1], cmap='YlOrRd',\n",
-    "                                       add_colorbar=True)\n",
+    "result_combo.sel(stats='variety').plot.imshow(ax=axes[1], cmap='YlOrBr',\n",
+    "                                              add_colorbar=True)\n",
     "axes[1].set_title('Focal variety')\n",
     "axes[1].set_aspect('equal')\n",
-    "plt.tight_layout()\n",
-    "plt.show()"
+    "plt.tight_layout()"
+   ],
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "id": "42a2fa87",
+   "metadata": {},
+   "source": [
+    "Range measures the numeric spread (max minus min) while variety counts distinct classes. For categorical data, variety is usually the more meaningful metric since the numeric distance between class codes is arbitrary."
    ]
   },
   {
    "cell_type": "markdown",
+   "id": "ad3e1f07",
    "metadata": {},
    "source": [
-    "Range measures the numeric spread (max minus min) while variety\n",
-    "counts distinct classes.  For categorical data, variety is usually\n",
-    "the more meaningful measure since the numeric distance between\n",
-    "class codes is arbitrary."
+    "### References\n",
+    "\n",
+    "- [Focal statistics overview (Esri)](https://pro.arcgis.com/en/pro-app/latest/tool-reference/spatial-analyst/focal-statistics.htm)\n",
+    "- [xrspatial.focal.focal_stats API docs](https://xarray-spatial.readthedocs.io/en/latest/reference/_autosummary/xrspatial.focal.focal_stats.html)\n",
+    "- McGarigal, K. & Marks, B. J. (1995). [FRAGSTATS: Spatial Pattern Analysis Program](https://www.fs.usda.gov/research/treesearch/3064). USDA Forest Service General Technical Report PNW-GTR-351."
    ]
   }
  ],
@@ -201,4 +252,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 4
-}
+}