examples/user_guide/8_Local_Tools.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "e9045413",
   "metadata": {},
   "source": [
    "## Exploring Xarray-spatial local tools functions"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "32b5e1bf",
   "metadata": {},
   "source": [
    "Local tools operate at the cell level, where values with the same position from a set of input rasters are used to calculate the values of the cells at the output raster.\n",
    "Some examples of the application of local tools are:\n",
    "- Change over time: You can use local tools to identify places where a value like land use or temperature changed over time.\n",
    "- Aggregate over time: You can use local tools to aggregate values over time, for example calculating the average rainfall or hours of sunshine for each cell.\n",
    "- Threshold over time: You can use local tools to identify places where a value is above or below a specified threshold, for example where the temperature was below a 0 °C.\n",
    "- Data aggregation: You can use local tools to calculate the [cost surface](http://wiki.gis.com/wiki/index.php/Cost_surface) of an area, summing up different types of cost over the same cell in different layers."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ea55ffed",
   "metadata": {},
   "source": [
    "In this notebook, we'll demonstrate how to use the [Xarray-spatial](http://xarray-spatial.org/) local tools functions supported by [Numpy](https://numpy.org/). The spatial functions available are:\n",
    "- [Cell Statistics](#Cell-Statistics)\n",
    "- [Combine](#Combine)\n",
    "- [Lesser Frequency](#Lesser-Frequency)\n",
    "- [Equal Frequency](#Equal-Frequency)\n",
    "- [Greater Frequency](#Greater-Frequency)\n",
    "- [Lowest Position](#Lowest-Position)\n",
    "- [Highest Position](#Highest-Position)\n",
    "- [Popularity](#Popularity)\n",
    "- [Rank](#Rank)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b9c4ed8c",
   "metadata": {},
   "source": [
    "### Creating the sample data"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "af3c5207",
   "metadata": {},
   "source": [
    "In order to present the functions in a very simple and easy to understand way, we'll use 4x4 data arrays and create an `xarray.Dataset`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c7945275",
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import xarray as xr\n",
    "\n",
    "arr = xr.DataArray([[2, 2, 2, 2], [2, 2, 2, 2], [2, 2, 2, 2], [2, 2, 2, 2]], name=\"arr\")\n",
    "\n",
    "arr1 = xr.DataArray(\n",
    "    [[np.nan, 4, 2, 0], [2, 3, np.nan, 1], [5, 1, 2, 0], [1, 3, 2, np.nan]], name=\"arr1\"\n",
    ")\n",
    "\n",
    "arr2 = xr.DataArray(\n",
    "    [[3, 1, 1, 2], [4, 1, 2, 5], [0, 0, 0, 0], [np.nan, 1, 1, 1]], name=\"arr2\"\n",
    ")\n",
    "\n",
    "arr3 = xr.DataArray(\n",
    "    [[3, 3, 2, 0], [4, 1, 3, 1], [6, 1, 2, 2], [0, 0, 1, 1]], name=\"arr3\"\n",
    ")\n",
    "\n",
    "raster_ds = xr.merge([arr, arr1, arr2, arr3])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d12080a6",
   "metadata": {},
   "source": [
    "### Helping function"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "17d54999",
   "metadata": {},
   "source": [
    "This function will be used to plot the arrays for all the examples in this notebook."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9ce0bf94",
   "metadata": {},
   "outputs": [],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "\n",
    "\n",
    "def plot_arrays(arr_list, title_list):\n",
    "    fig, ax = plt.subplots(nrows=1, ncols=len(arr_list), figsize=(15, 10))\n",
    "\n",
    "    for idx, arr in zip(range(0, len(arr_list)), arr_list):\n",
    "        for i in range(arr.shape[0]):\n",
    "            for j in range(arr.shape[1]):\n",
    "                ax[idx].text(\n",
    "                    j,\n",
    "                    i,\n",
    "                    int(arr.data[i, j]) if str(arr.data[i, j]) != \"nan\" else np.nan,\n",
    "                    ha=\"center\",\n",
    "                    va=\"center\",\n",
    "                    color=\"black\",\n",
    "                )\n",
    "\n",
    "        ax[idx].imshow(arr.values, cmap=\"tab20c_r\")\n",
    "        ax[idx].set_xticks([])\n",
    "        ax[idx].set_yticks([])\n",
    "        ax[idx].set_title(title_list[idx])\n",
    "\n",
    "    plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "00300315",
   "metadata": {},
   "source": [
    "### Cell Statistics"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "01ab159c",
   "metadata": {},
   "source": [
    "[`xrspatial.local.cell_stats`](https://xarray-spatial.org/reference/_autosummary/xrspatial.local.cell_stats.html) calculates statistics from a raster dataset on a cell-by-cell basis."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "86353494",
   "metadata": {},
   "outputs": [],
   "source": [
    "from xrspatial.local import cell_stats\n",
    "\n",
    "func_list = [\"max\", \"mean\", \"median\", \"min\", \"std\", \"sum\"]\n",
    "statistics = [\n",
    "    cell_stats(raster=raster_ds[[\"arr1\", \"arr2\", \"arr3\"]], func=func)\n",
    "    for func in func_list\n",
    "]\n",
    "\n",
    "plot_arrays(\n",
    "    [\n",
    "        raster_ds[\"arr1\"],\n",
    "        raster_ds[\"arr2\"],\n",
    "        raster_ds[\"arr3\"],\n",
    "    ],\n",
    "    [\"arr1\", \"arr2\", \"arr3\"],\n",
    ")\n",
    "\n",
    "plot_arrays(statistics, func_list)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b8008262",
   "metadata": {},
   "source": [
    "### Combine"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "87c34a83",
   "metadata": {},
   "source": [
    "[`xrspatial.local.combine`](https://xarray-spatial.org/reference/_autosummary/xrspatial.local.combine.html) combines multiple arrays from a raster dataset, assigning a unique output value to each unique combination of raster values."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7f1b3bfa",
   "metadata": {},
   "outputs": [],
   "source": [
    "from xrspatial.local import combine\n",
    "\n",
    "result_arr = combine(raster=raster_ds[[\"arr1\", \"arr2\"]])\n",
    "\n",
    "plot_arrays(\n",
    "    [\n",
    "        raster_ds[\"arr1\"],\n",
    "        raster_ds[\"arr2\"],\n",
    "        result_arr,\n",
    "    ],\n",
    "    [\"arr1\", \"arr2\", \"result\"],\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a32b70bd",
   "metadata": {},
   "source": [
    "### Lesser-Frequency"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4f6da50e",
   "metadata": {},
   "source": [
    "[`xrspatial.local.lesser_frequency`](https://xarray-spatial.org/reference/_autosummary/xrspatial.local.lesser_frequency.html) calculates, given a raster dataset, the number of times the data variables values are lower than the values of a given reference data variable on a cell-by-cell basis."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b95f96c7",
   "metadata": {},
   "outputs": [],
   "source": [
    "from xrspatial.local import lesser_frequency\n",
    "\n",
    "result_arr = lesser_frequency(raster=raster_ds, ref_var=\"arr\")\n",
    "\n",
    "plot_arrays(\n",
    "    [\n",
    "        raster_ds[\"arr\"],\n",
    "        raster_ds[\"arr1\"],\n",
    "        raster_ds[\"arr2\"],\n",
    "        raster_ds[\"arr3\"],\n",
    "        result_arr,\n",
    "    ],\n",
    "    [\"arr_ref\", \"arr1\", \"arr2\", \"arr3\", \"result\"],\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "50d97b06",
   "metadata": {},
   "source": [
    "### Equal Frequency"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "intelligent-philadelphia",
   "metadata": {},
   "source": [
    "[`xrspatial.local.equal_frequency`](https://xarray-spatial.org/reference/_autosummary/xrspatial.local.equal_frequency.html) calculates, given a raster dataset, the number of times the data variables values are equal than the values of a given reference data variable on a cell-by-cell basis."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "78a7824e",
   "metadata": {},
   "outputs": [],
   "source": [
    "from xrspatial.local import equal_frequency\n",
    "\n",
    "result_arr = equal_frequency(raster=raster_ds, ref_var=\"arr\")\n",
    "\n",
    "plot_arrays(\n",
    "    [\n",
    "        raster_ds[\"arr\"],\n",
    "        raster_ds[\"arr1\"],\n",
    "        raster_ds[\"arr2\"],\n",
    "        raster_ds[\"arr3\"],\n",
    "        result_arr,\n",
    "    ],\n",
    "    [\"arr_ref\", \"arr1\", \"arr2\", \"arr3\", \"result\"],\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7c97b5fd",
   "metadata": {},
   "source": [
    "### Greater Frequency"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "vocational-inside",
   "metadata": {},
   "source": [
    "[`xrspatial.local.greater_frequency`](https://xarray-spatial.org/reference/_autosummary/xrspatial.local.greater_frequency.html) calculates, given a raster dataset, the number of times the data variables values are greater than the values of a given reference data variable on a cell-by-cell basis."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1c6ab615",
   "metadata": {},
   "outputs": [],
   "source": [
    "from xrspatial.local import greater_frequency\n",
    "\n",
    "result_arr = greater_frequency(raster=raster_ds, ref_var=\"arr\")\n",
    "\n",
    "plot_arrays(\n",
    "    [\n",
    "        raster_ds[\"arr\"],\n",
    "        raster_ds[\"arr1\"],\n",
    "        raster_ds[\"arr2\"],\n",
    "        raster_ds[\"arr3\"],\n",
    "        result_arr,\n",
    "    ],\n",
    "    [\"arr_ref\", \"arr1\", \"arr2\", \"arr3\", \"result\"],\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d197be65",
   "metadata": {},
   "source": [
    "### Lowest Position"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8d7235ec",
   "metadata": {},
   "source": [
    "[`xrspatial.local.lowest_position`](https://xarray-spatial.org/reference/_autosummary/xrspatial.local.lowest_position.html) calculates the data variable index of the lowest value on a cell-by-cell basis."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b5b7b743",
   "metadata": {},
   "outputs": [],
   "source": [
    "from xrspatial.local import lowest_position\n",
    "\n",
    "result_arr = lowest_position(raster=raster_ds)\n",
    "\n",
    "plot_arrays(\n",
    "    [\n",
    "        raster_ds[\"arr1\"],\n",
    "        raster_ds[\"arr2\"],\n",
    "        raster_ds[\"arr3\"],\n",
    "        result_arr,\n",
    "    ],\n",
    "    [\"arr1\", \"arr2\", \"arr3\", \"result\"],\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "839530ba",
   "metadata": {},
   "source": [
    "### Highest Position"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a17c6e93",
   "metadata": {},
   "source": [
    "[`xrspatial.local.highest_position`](https://xarray-spatial.org/reference/_autosummary/xrspatial.local.highest_position.html) calculates the data variable index of the highest value on a cell-by-cell basis."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "cf614920",
   "metadata": {},
   "outputs": [],
   "source": [
    "from xrspatial.local import highest_position\n",
    "\n",
    "result_arr = highest_position(raster=raster_ds)\n",
    "\n",
    "plot_arrays(\n",
    "    [\n",
    "        raster_ds[\"arr1\"],\n",
    "        raster_ds[\"arr2\"],\n",
    "        raster_ds[\"arr3\"],\n",
    "        result_arr,\n",
    "    ],\n",
    "    [\"arr1\", \"arr2\", \"arr3\", \"result\"],\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2168c7dd",
   "metadata": {},
   "source": [
    "### Popularity"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e5408cea",
   "metadata": {},
   "source": [
    "[`xrspatial.local.popularity`](https://xarray-spatial.org/reference/_autosummary/xrspatial.local.popularity.html) calculates the number of occurrences of each value of a raster dataset, on a cell-by-cell basis. The output value is assigned based on the reference data variable nth most popular."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "92d44cd2",
   "metadata": {},
   "outputs": [],
   "source": [
    "from xrspatial.local import popularity\n",
    "\n",
    "\n",
    "result_arr = popularity(raster=raster_ds, ref_var=\"arr\")\n",
    "\n",
    "plot_arrays(\n",
    "    [\n",
    "        raster_ds[\"arr\"],\n",
    "        raster_ds[\"arr1\"],\n",
    "        raster_ds[\"arr2\"],\n",
    "        raster_ds[\"arr3\"],\n",
    "        result_arr,\n",
    "    ],\n",
    "    [\"arr_ref\", \"arr1\", \"arr2\", \"arr3\", \"result\"],\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6a823a72",
   "metadata": {},
   "source": [
    "### Rank"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "385dac65",
   "metadata": {},
   "source": [
    "[`xrspatial.local.rank`](https://xarray-spatial.org/reference/_autosummary/xrspatial.local.rank.html) calculates the rank of each value of a raster dataset, on a cell-by-cell basis. The output value is assigned based on the rank of the reference data variable rank."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9d10ab75",
   "metadata": {},
   "outputs": [],
   "source": [
    "from xrspatial.local import rank\n",
    "\n",
    "result_arr = rank(raster=raster_ds, ref_var=\"arr\")\n",
    "\n",
    "plot_arrays(\n",
    "    [\n",
    "        raster_ds[\"arr\"],\n",
    "        raster_ds[\"arr1\"],\n",
    "        raster_ds[\"arr2\"],\n",
    "        raster_ds[\"arr3\"],\n",
    "        result_arr,\n",
    "    ],\n",
    "    [\"arr_ref\", \"arr1\", \"arr2\", \"arr3\", \"result\"],\n",
    ")"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}