ECDI notebooks

Use_cases/Enhanced_Combined_Drought_Index/00_EnhancedDroughtIndex.ipynb

@@ -0,0 +1,254 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "a1ee47cf-3544-4245-9884-92989e9f8877",
+   "metadata": {},
+   "source": [
+    "<img align=\"centre\" src=\"../../Supplementary_data/Github_banner.jpg\" width=\"100%\">\n",
+    "\n",
+    "# Enhanced Combined Drought Index"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4d6ce758-4950-4cea-96e6-ee58a302108a",
+   "metadata": {},
+   "source": [
+    "## Background "
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1d1c29f8-816c-414b-8d63-efd95a7a647c",
+   "metadata": {},
+   "source": [
+    "Drought is an extended period, during which fresh water availability and accessibility for the ecosystem at a given place is below normal due to unfavourable spatial and temporal distribution of rainfall, temperature, soil moisture and wind characteristics [(Balint et al., 2013)](https://doi.org/10.1016/B978-0-444-59559-1.00023-2). Severe droughts can affect large populations, threatening people's livelihoods and resulting in economic loss [(Enenkel et al., 2016)](https://doi.org/10.3390/rs8040340)."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "d93fb910-bc48-4a5b-a885-131251436d75",
+   "metadata": {},
+   "source": [
+    "The Enhanced Combined Drought Index (ECDI) provides timely and reliable detection of drought events with regard to their spatio-temporal extent and severity. The Enhanced Drought Index is a combination of the following:\n",
+    "\n",
+    "- **Vegetation** component which considers NDVI anomalies and their persistence. The index based on the vegetation component is named as **Vegetation Drought Index (VDI)**.\n",
+    "- **Precipitation** component, which considers rainfall deficits and dryness persistence. The index calculated using the precipitation component is referred as the  **Precipitation Drought Index (PDI)**.\n",
+    "- **Temperature** component, which considers temperature excesses and persistence of high temperatures. The index based on temperature is named as **Temperature Drought Index (TDI)**.\n",
+    "- **Soil moisture** component, which considers soil moisture deficits and deficit persistence. The index based on soil moisture is named as the **Soil Moisture Drought Index (SMDI)**.\n",
+    "\n",
+    "The index uses **satellite-derived** rainfall, soil moisture, land surface temperature, and vegetation status as input datasets [(Enenkel et al., 2016)](https://doi.org/10.3390/rs8040340)."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6fa3a6ca-552c-44ee-a3cc-c77d1c2470f0",
+   "metadata": {},
+   "source": [
+    "### Enhanced Drought Index Formulae"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ecca9fa6-651b-415b-9552-b13e0e96ffbd",
+   "metadata": {},
+   "source": [
+    "Each drought index can be expressed as:\n",
+    "\n",
+    "$\\text{Drought Index} = \\frac{\\text{Actual Average for Interest Period}}{\\text{Long Term Average for Interest Period}} * \\sqrt{\\frac{\\text{Actual Length of Continuous Deficit or Excess in the Interest Period}}{\\text{Long Term Average of Continuous Deficit or Excess in the Interest Period}}}$"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "7fcf3b69-9a11-4ce8-ab76-34f1dfc54ccf",
+   "metadata": {},
+   "source": [
+    "Each drought index is calculated similarly. The equation below illustrates the calculation of the ECDI precipitation component:\n",
+    "\n",
+    "\\begin{equation}\n",
+    "\\text{PDI}_{y,d} = \\frac{\n",
+    "\\frac{1}{\\text{IP}} \\sum_{j=0}^{\\text{IP} - 1} P^*_{y,(d-j)}}{\\frac{1}{n}\\sum_{k=1}^n[\\frac{1}{\\text{IP}} \\sum_{j=0}^{\\text{IP} - 1} P^*_{(d-j), k}]} * \\sqrt{\\frac{(\\text{RL}^*)P^*_{d, y}}{\\frac{1}{n}\\sum_{k=1}^{n}(\\text{RL}^*)P^*_{d, k}}}\n",
+    "\\end{equation}\n",
+    "\n",
+    "- $\\text{PDI}_{y,d}$ is the Precipitation Drought Index for year $\\text{y}$ and time unit (dekad/month) $\\text{d}$\n",
+    "\n",
+    "- $P^*$ is the modified dekadal/monthly precipitation average \n",
+    "\n",
+    "- $\\text{RL}*$ is the modified run length parameter \n",
+    "\n",
+    "- $\\text{RL*}(P*)$ (run length) is the maximum number of successive dekads/months below the long-term average rainfall in the interest period\n",
+    "> **Note**: For temperature, run length is the maximum number of successive dekads/months above the long-term average temperature in the interest period\n",
+    "\n",
+    "- $\\text{IP}$ is the interest period (e.g. 3, 4, 5, . . . dekads/months) (longer IPs detect more severe drought events). IP is flexible defines to what extent past observations are considered.\n",
+    "\n",
+    "- $n$ is the number of years where relevant data are available,\n",
+    "\n",
+    "- $j$ is the summation running parameter covering the Interest Period\n",
+    "\n",
+    "- $k$ is the summation parameter covering the years where relevant data are available\n",
+    "\n",
+    "- $d$ time unit (dekad or month) \n",
+    "\n",
+    "- $y$ year"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ef502771-249d-4f52-bc39-7f49491e3fe2",
+   "metadata": {},
+   "source": [
+    "The raw time series of temperature and precipitation as well as the run length are modified to adjust the range of all variables and to avoid a division by zero.\n",
+    "\n",
+    "\\begin{equation}\n",
+    "T^* = (T_{max} + 1) - T\n",
+    "\\end{equation}\n",
+    "\n",
+    "\\begin{equation}\n",
+    "P^* = P + 1\n",
+    "\\end{equation}\n",
+    "\n",
+    "\\begin{equation}\n",
+    "\\text{RL}^* = (\\text{RL}_{max} + 1) - \\text{RL}\n",
+    "\\end{equation}\n",
+    "\n",
+    "\\begin{equation}\n",
+    "\\text{NDVI}^* = \\text{NDVI} - (\\text{NDVI}_{min} -0.01)\n",
+    "\\end{equation}\n",
+    "\n",
+    "\n",
+    "- $T^*$ is the modified dekadal/monthly temperature average \n",
+    "- $P^*$ is the modified dekadal/monthly precipitation average \n",
+    "- $\\text{RL}^*$ is the modified run length"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "67e6e6b9-a159-4fcc-b976-3ab9db86922e",
+   "metadata": {},
+   "source": [
+    "All the individual drought indices differ in range. To improve their interpretability and visual comparability a simple scaling factor is introduced.\n",
+    "\n",
+    "\\begin{equation}\n",
+    "PDI_{scaled} = \\frac{(PDI - PDI_{min})}{(PDI_{max} - PDI_{min})}\n",
+    "\\end{equation}"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e6caab44-32ee-4d7d-87b8-2486108f5cf7",
+   "metadata": {},
+   "source": [
+    "\n",
+    "The **weight** of each individual drought index is automatically calculated for every grid point (pixel) with respect to its capability to reflect the future vegetation status (NDVI) and multiplied by the respective individual index to calculate the ECDI. In the case of data gaps in one input dataset, the weights are automatically redistributed to other available variables.\n",
+    "\n",
+    "\\begin{equation}\n",
+    "ECDI = \\sum_{i-1}^{n}w_{i} * \\text{DI}_{i}\n",
+    "\\end{equation}\n",
+    "\n",
+    "- $ECDI$ Enhanced Combined Drought Index \n",
+    "\n",
+    "- $w$ Weight for each individual drought index (e.g., rainfall)\n",
+    "\n",
+    "- $\\text{DI}$ Individual drought index \n",
+    "\n",
+    "- $n$ number of drought indices used to calculate the ECDI \n",
+    "\n",
+    "- $i$ running parameter covering the number of drought indices\n",
+    "\n",
+    "\\begin{equation}\n",
+    "w_{i} = \\frac{\\frac{lag^*_{i}}{\\sum_{j=1}^{n} lag^*_{j}} + \\frac{corr^*_{i}}{\\sum_{j=1}^{n} corr^*_{j}}}{2}\n",
+    "\\end{equation}\n",
+    "\n",
+    "- $w$ weight for the respective drought index \n",
+    "\n",
+    "- $lag^*$ modified time lag for the respective parameter \n",
+    "\n",
+    "- $corr^*$ modified correlation coefficient for the respective parameter \n",
+    "\n",
+    "- $i$ index for the respective parameter/drought index \n",
+    "\n",
+    "- $j$ running parameter covering all parameters used for the ECDI calculation\n",
+    "\n",
+    "- $n$ number of individual drought indices used for the ECDI calculation"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "9568d111-65c6-4dc8-a713-21a41c739e3c",
+   "metadata": {},
+   "source": [
+    "There are five primary notebooks in this notebook series, each represent a critical step in a ECDI workflow. \n",
+    "\n",
+    "1. The `Vegetation Drought Index notebook` calculates the Vegetation Drought Index using Landsat Surface Reflectance Collections 5, 7, 8, and 9.\n",
+    "   \n",
+    "2. The `Precipitation Drought Index notebook` calculates the Precipitation Drought Index using CHIRPS.\n",
+    "\n",
+    "3. The `Temperature Drought Index notebook` calculates the Temperature Drought Index using Landsat Surface Temperature Collections 5, 7, 8, and 9\n",
+    "\n",
+    "4. The `Soil Moisture Drought Index`notebook calculates the Soil Moisture Drought Index using WAPOR.\n",
+    "\n",
+    "5. The `Enhanced Combined Drought Index` notebook combines the indices calculated from Step 1 to 4 to compute the ECDI results"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c78f1f54-fea9-41b0-ba00-cb4f8724a5a1",
+   "metadata": {
+    "jp-MarkdownHeadingCollapsed": true
+   },
+   "source": [
+    "## Getting Started\n",
+    "\n",
+    "To begin, work through the notebooks in this workflow, starting with Notebook 1 below:\n",
+    "\n",
+    "1. [VegetationDroughtIndex](01_VegetationDroughtIndex.ipynb)\n",
+    "2. [PrecipitationDroughtIndex](02_PrecipitationDroughtIndex.ipynb)\n",
+    "3. [TemperatureDroughtIndex](03_TemperatureDroughtIndex.ipynb)\n",
+    "4. [SoilMoistureDroughtIndex](04_SoilMoistureDroughtIndex.ipynb)\n",
+    "5. [EnhancedCombinedDroughtIndex](05_EnhancedCombinedDroughtIndex.ipynb)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "2792a22b-6593-42ea-a5c4-a2c3c7704063",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "\n",
+    "## Additional information\n",
+    "\n",
+    "<b> License </b> The code in this notebook is licensed under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0).\n",
+    "\n",
+    "Digital Earth Africa data is licensed under the [Creative Commons by Attribution 4.0](https://creativecommons.org/licenses/by/4.0/) license.\n",
+    "\n",
+    "<b> Contact </b> If you need assistance, please post a question on the [DE Africa Slack channel](https://digitalearthafrica.slack.com/) or on the [GIS Stack Exchange](https://gis.stackexchange.com/questions/ask?tags=open-data-cube) using the `open-data-cube` tag (you can view previously asked questions [here](https://gis.stackexchange.com/questions/tagged/open-data-cube)).\n",
+    "\n",
+    "If you would like to report an issue with this notebook, you can file one on [Github](https://github.com/digitalearthafrica/deafrica-sandbox-notebooks).\n",
+    "\n",
+    "<b> Compatible datacube version </b>"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}