Add resample user guide notebook (#1152)

Author: brendancol

examples/user_guide/48_Resample.ipynb

@@ -0,0 +1,210 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Raster Resampling\n",
+    "\n",
+    "The `resample` function changes a raster's resolution (cell size) without\n",
+    "changing its CRS. This is the operation you'd reach for when you need to\n",
+    "match two rasters to a common grid or reduce a raster's memory footprint\n",
+    "before analysis.\n",
+    "\n",
+    "**Methods**:\n",
+    "\n",
+    "| Method | Direction | Best for |\n",
+    "|--------|-----------|----------|\n",
+    "| `nearest` | up/down | Categorical data, fast preview |\n",
+    "| `bilinear` | up/down | Smooth continuous surfaces |\n",
+    "| `cubic` | up/down | High-quality continuous surfaces |\n",
+    "| `average` | down only | Aggregating high-res to low-res |\n",
+    "| `min`, `max` | down only | Extremes within each output cell |\n",
+    "| `median` | down only | Robust centre, ignores outliers |\n",
+    "| `mode` | down only | Majority class in categorical rasters |"
+   ]
+  },
+  {
+   "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 import resample\n",
+    "from xrspatial.terrain import generate_terrain"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Generate synthetic terrain"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "dem = generate_terrain(width=200, height=200)\n",
+    "# Assign a regular coordinate grid\n",
+    "dem = dem.assign_coords(\n",
+    "    y=np.linspace(100, 0, dem.sizes['y']),\n",
+    "    x=np.linspace(0, 100, dem.sizes['x']),\n",
+    ")\n",
+    "dem.attrs['res'] = (0.5, 0.5)\n",
+    "\n",
+    "fig, ax = plt.subplots(figsize=(6, 5))\n",
+    "dem.plot(ax=ax, cmap='terrain')\n",
+    "ax.set_title(f'Original DEM ({dem.shape[0]}x{dem.shape[1]}, res={dem.attrs[\"res\"][0]:.1f}m)')\n",
+    "plt.tight_layout()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Downsample with `scale_factor`"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "down = resample(dem, scale_factor=0.25, method='bilinear')\n",
+    "\n",
+    "fig, axes = plt.subplots(1, 2, figsize=(12, 5))\n",
+    "dem.plot(ax=axes[0], cmap='terrain')\n",
+    "axes[0].set_title(f'Original ({dem.shape[0]}x{dem.shape[1]})')\n",
+    "down.plot(ax=axes[1], cmap='terrain')\n",
+    "axes[1].set_title(f'Downsampled 4x ({down.shape[0]}x{down.shape[1]})')\n",
+    "plt.tight_layout()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Upsample with `target_resolution`"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "up = resample(down, target_resolution=0.5, method='cubic')\n",
+    "\n",
+    "fig, axes = plt.subplots(1, 2, figsize=(12, 5))\n",
+    "down.plot(ax=axes[0], cmap='terrain')\n",
+    "axes[0].set_title(f'Coarse ({down.shape[0]}x{down.shape[1]})')\n",
+    "up.plot(ax=axes[1], cmap='terrain')\n",
+    "axes[1].set_title(f'Upsampled to 0.5m ({up.shape[0]}x{up.shape[1]})')\n",
+    "plt.tight_layout()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Compare resampling methods"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "methods = ['nearest', 'bilinear', 'cubic', 'average']\n",
+    "fig, axes = plt.subplots(1, 4, figsize=(16, 4))\n",
+    "\n",
+    "for ax, method in zip(axes, methods):\n",
+    "    out = resample(dem, scale_factor=0.1, method=method)\n",
+    "    out.plot(ax=ax, cmap='terrain', add_colorbar=False)\n",
+    "    ax.set_title(method)\n",
+    "    ax.set_aspect('equal')\n",
+    "\n",
+    "plt.suptitle('Downsample 10x with different methods', y=1.02)\n",
+    "plt.tight_layout()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Categorical raster with `mode`"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from xrspatial import equal_interval\n",
+    "\n",
+    "# Classify elevation into 5 zones\n",
+    "classes = equal_interval(dem, k=5)\n",
+    "classes.attrs = dem.attrs.copy()\n",
+    "classes = classes.assign_coords(dem.coords)\n",
+    "\n",
+    "# Downsample: mode preserves class boundaries\n",
+    "classes_down = resample(classes.astype('float32'),\n",
+    "                        scale_factor=0.2, method='mode')\n",
+    "\n",
+    "fig, axes = plt.subplots(1, 2, figsize=(12, 5))\n",
+    "classes.plot(ax=axes[0], cmap='Set2')\n",
+    "axes[0].set_title(f'Classes ({classes.shape[0]}x{classes.shape[1]})')\n",
+    "classes_down.plot(ax=axes[1], cmap='Set2')\n",
+    "axes[1].set_title(f'Mode downsample ({classes_down.shape[0]}x{classes_down.shape[1]})')\n",
+    "plt.tight_layout()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Works with Dask"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import dask.array as da\n",
+    "\n",
+    "dask_dem = dem.copy()\n",
+    "dask_dem.data = da.from_array(dem.values, chunks=(100, 100))\n",
+    "\n",
+    "result = resample(dask_dem, scale_factor=0.5, method='bilinear')\n",
+    "print(f'Input:  {dask_dem.shape} (dask, chunks={dask_dem.data.chunksize})')\n",
+    "print(f'Output: {result.shape} (dask, chunks={result.data.chunksize})')\n",
+    "print(f'Computed shape: {result.compute().shape}')"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.14.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}