Add focal variety user guide notebook (#1040)

Author: brendancol

examples/user_guide/35_Focal_Variety.ipynb

@@ -0,0 +1,204 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# 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",
+    "\n",
+    "This notebook shows how to compute focal variety with\n",
+    "`xrspatial.focal.focal_stats` across different kernel shapes."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "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.focal import focal_stats"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Create a 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."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "rng = np.random.default_rng(42)\n",
+    "rows, cols = 60, 60\n",
+    "\n",
+    "# Four quadrants: classes 1-4\n",
+    "lc = np.ones((rows, cols), dtype=np.float64)\n",
+    "lc[:rows//2, cols//2:] = 2\n",
+    "lc[rows//2:, :cols//2] = 3\n",
+    "lc[rows//2:, cols//2:] = 4\n",
+    "\n",
+    "# Scatter some class-5 patches\n",
+    "for _ in range(30):\n",
+    "    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",
+    "fig, ax = plt.subplots(figsize=(5, 5))\n",
+    "land_cover.plot(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()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Compute 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."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "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",
+    "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",
+    "axes[1].set_title('Focal variety (3x3 box)')\n",
+    "axes[1].set_aspect('equal')\n",
+    "plt.tight_layout()\n",
+    "plt.show()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "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."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "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."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "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",
+    "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",
+    "axes[1].set_title('Variety (5x5 circle)')\n",
+    "axes[1].set_aspect('equal')\n",
+    "plt.tight_layout()\n",
+    "plt.show()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "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."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "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",
+    "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",
+    "axes[1].set_title('Focal variety')\n",
+    "axes[1].set_aspect('equal')\n",
+    "plt.tight_layout()\n",
+    "plt.show()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "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."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.10.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}