More examples to user guide (#742)

* add zonal crosstab example

* focal hotspots

* more examples on multispectral tools

* zonal crosstab example

Author: thuydotm

examples/user_guide/3_Zonal.ipynb

@@ -157,6 +157,7 @@
    "outputs": [],
    "source": [
     "from xrspatial import zonal_stats\n",
+    "\n",
     "zones_agg.values = np.nan_to_num(zones_agg.values, copy=False).astype(int)\n",
     "zonal_stats(zones_agg, terrain)"
    ]
@@ -191,6 +192,54 @@
    "source": [
     "Here the zones are defined by line segments, but they can be any spatial pattern or, more specifically, any region computable as a Datashader aggregate."
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Zonal crosstab\n",
+    "\n",
+    "Zonal crosstab function can be used when we want to calculate cross-tabulated (categorical stats) areas between two datasets. As an example, assume we have gender data (male/female), and we want to see how all the gender groups distributed over all the zones defined above.\n",
+    "\n",
+    "First, let's create a mock dataset for gender: 1 for male, and 2 for female. "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# define a mask where 0s are water, and 1s are land areas\n",
+    "mask = terrain.data.astype(bool).astype(int)\n",
+    "\n",
+    "# gender data where 0s are nodata, 1s are male, and 2s are female\n",
+    "# assume that the population only takes 10% overall, and the probability of male and female are equal.\n",
+    "genders = np.random.choice([0, 1, 2], p=[0.9, 0.05, 0.05], size=zones_agg.shape) * mask\n",
+    "genders_agg = xr.DataArray(genders, coords=terrain.coords, dims=terrain.dims)\n",
+    "\n",
+    "# visualize the results\n",
+    "genders_shaded = shade(genders_agg, cmap=['white', 'blue', 'red'])\n",
+    "stack(genders_shaded, terrain_shaded)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Now, let's calculate the stats between the 2 datasets of genders and zones."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from xrspatial import zonal_crosstab\n",
+    "\n",
+    "zonal_crosstab(zones=zones_agg, values=genders_agg, zone_ids=[11, 12, 13, 14, 15, 16], cat_ids=[1, 2])"
+   ]
   }
  ],
  "metadata": {
@@ -209,7 +258,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.10"
+   "version": "3.9.14"
   }
  },
  "nbformat": 4,

examples/user_guide/4_Focal.ipynb

@@ -201,11 +201,72 @@
     ")\n",
     "stack(illuminated_shaded, sobel_terrain_shaded)"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Focal hotspots\n",
+    "\n",
+    "The focal hotspots tool helps identify significant hot and cold spots in a raster. A hot spot has a high value and be surrounded by neighbors with high values as well. Similarly, a cold spot has a low value and surrounded by other low value pixels. The neighborhood of a pixel is defined by an odd sized kernel.\n",
+    "\n",
+    "The result of the function is a data array with the following 7 values:\n",
+    "- 90 for 90% confidence high value cluster\n",
+    "- 95 for 95% confidence high value cluster\n",
+    "- 99 for 99% confidence high value cluster\n",
+    "- 90 for 90% confidence low value cluster\n",
+    "- 95 for 95% confidence low value cluster\n",
+    "- 99 for 99% confidence low value cluster\n",
+    "- 0 for no significance\n",
+    "\n",
+    "In this example, let's see if there are any hot or cold spots in our elevation terrain."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "kernel = convolution.circle_kernel(cellsize_x, cellsize_y, 5*cellsize_x)\n",
+    "kernel"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from xrspatial.focal import hotspots\n",
+    "\n",
+    "elevation_hotspots = hotspots(terrain, kernel)\n",
+    "np.unique(elevation_hotspots.data)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Visualize hotspots (if any) with Fuchsia color, and cold spots (if any) with Black color."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# visualize the result\n",
+    "hotspots_shaded = shade(elevation_hotspots, cmap=[\"gray\", \"black\", \"fuchsia\"], alpha=255, how=\"linear\")\n",
+    "\n",
+    "stack(hotspots_shaded, terrain_shaded)"
+   ]
   }
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -219,7 +280,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.5"
+   "version": "3.9.14"
   }
  },
  "nbformat": 4,