xES - Update Notebook

AbdelrahmanAmr3 · Mar 27, 2024 · 9ec21f0 · 9ec21f0
1 parent 1d84ded
commit 9ec21f0
Show file tree

Hide file tree

Showing 2 changed files with 138 additions and 9 deletions.
diff --git a/docs/examples/xES.ipynb b/docs/examples/xES.ipynb
@@ -6,7 +6,16 @@
       "source": [
         "# Welcom to xEarthStat For AgERA5\n",
         "\n",
-        "download aggregate AgERA5 for your ROI"
+        "xEarthStat for AgERA5 allows users to download and aggregate AgERA5 climate data for a specified Region of Interest (ROI). This document outlines the installation process, setup, and usage instructions to get you started."
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Installation\n",
+        "\n",
+        "To use xEarthStat for AgERA5, you first need to install the `earthstat` Python package. Run the following command in your Python environment:"
       ]
     },
     {
@@ -18,6 +27,13 @@
         "!pip install earthstat"
       ]
     },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Step 1: Import xEarthStat"
+      ]
+    },
     {
       "cell_type": "code",
       "execution_count": null,
@@ -29,6 +45,18 @@
         "from earthstat import xEarthStat as xES"
       ]
     },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Step 2: Define Your Region of Interest (ROI)\n",
+        "Specify your ROI's name, bounding box, and the time range for the data you're interested in:\n",
+        "\n",
+        "- **ROI Name** (`str`): Unique identifier for your ROI.\n",
+        "- **Bounding Box** (`list` of `float`): Define the north, west, south, and east coordinates of your ROI.\n",
+        "- **Time Range** (`int`): Specify the start and end years."
+      ]
+    },
     {
       "cell_type": "code",
       "execution_count": null,
@@ -41,14 +69,74 @@
         "start_year = 2000\n",
         "end_year = 2001\n",
         "\n",
-        "ROI_bounding_box = [71, -31, 34.5, 40]  # [north, west, south, east]\n",
+        "ROI_bounding_box = [71, -31, 34.5, 40]  # [north, west, south, east]"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Step 3: Set AgERA5 Parameters\n",
         "\n",
+        "List the climate parameters you want to download for your ROI:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
         "AgERA5_parameters = [\n",
         "    'Maximum_Temperature', 'Minimum_Temperature', 'Mean_Temperature',\n",
         "    'Solar_Radiation_Flux', 'Precipitation_Flux', 'Wind_Speed','Vapour_Pressure'\n",
-        "    ]\n",
+        "    ]"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "> <span style=\"color:red;\">**Note & Caution:**</span> xEarthStat can just download 7 variables included in the table below.\n",
+        "\n",
+        "| Variable                 | AgERA5 Parameter            | Statistical Download Type |\n",
+        "|--------------------------|-----------------------------|---------------------------|\n",
+        "| Maximum Temperature      | 2m_temperature              | 24_hour_maximum           |\n",
+        "| Minimum Temperature      | 2m_temperature              | 24_hour_minimum           |\n",
+        "| Mean Temperature         | 2m_temperature              | 24_hour_mean              |\n",
+        "| Solar Radiation Flux     | solar_radiation_flux        | -                         |\n",
+        "| Precipitation Flux       | precipitation_flux          | -                         |\n",
+        "| Wind Speed               | 10m_wind_speed              | 24_hour_mean              |\n",
+        "| Vapour Pressure          | vapour_pressure             | 24_hour_mean              |\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Step 4: Define the Shapefile Path\n",
         "\n",
-        "shapefile_file_path = 'maize_wheat_EU/maize_wheat_EU.shp'"
+        "Provide the file path to your shapefile:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "shapefile_file_path = 'EU/admin3.shp'"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Step 5: Initialize xEarthStat\n",
+        "\n",
+        "Create an instance of xEarthStat with the specified parameters:\n",
+        "- `workflow`: The type of final generated dataset, `dekadal` for aggregated dekadal (1,11,21 of month) dataset, `daily` for daily dataset.   \n",
+        "- `multi_processing`: Enables parallel processing."
       ]
     },
     {
@@ -69,6 +157,17 @@
         "                multi_processing=True)"
       ]
     },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Step 6: Download Data\n",
+        "\n",
+        "Download the AgERA5 data for your ROI:\n",
+        "- `num_requests`: the number of downloading requests sends to CDS's API server until download all data.\n",
+        "- `extract`: Extract the downloaded AgERA5 zip files, set `False` if you don't want to extract them."
+      ]
+    },
     {
       "cell_type": "code",
       "execution_count": null,
@@ -81,6 +180,26 @@
         "                          extract=True)"
       ]
     },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "> <span style=\"color:red;\">**Note & Caution:**</span> Don't send more than 6 requests to the server. That may lead to pressure on the server and may result in blocking your API key from downloading."
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Step 7: Aggregate Data\n",
+        "\n",
+        "xEarthStat's Aggregation process utilize the availability of GPU for parallel computation, and using the avilalble CPU cores for multiprocessing. it automatically detect if there is a GPU or not, if not it shift computational processing on CPU.\n",
+        "\n",
+        "- `max_workers`: Default to total number of CPU's cores. You can change the number of cores that used in multiprocessing.\n",
+        "- `all_touched`: Default to `False` to just consider pixels within the geometry object. `True` to consider all touched pixels by geo-object. \n",
+        "- `stat`:  `\"mean\"`(Default), `\"median\"`, `\"min\"`, `\"max\"`, `\"sum\"`."
+      ]
+    },
     {
       "cell_type": "code",
       "execution_count": null,
@@ -108,14 +227,24 @@
         "                           stat='mean')"
       ]
     },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Step 8: Export Aggregated Data\n",
+        "\n",
+        "Optionally, merge all generated datasets' csv files into one merged csv for all aggregated variables:\n",
+        "- `kelvin_to_celsius`: To convert the temperature unit from kelvin to celsius.\n",
+        "- `output_name`: option to add the name of merged csv, it's default to `AgERA5_{ROI_name}_merged_parameters_{workflow}_{timestamp}.csv`"
+      ]
+    },
     {
       "cell_type": "code",
       "execution_count": null,
       "metadata": {},
       "outputs": [],
       "source": [
-        "EU_AgERA5.AgERA5_merged_csv(kelvin_to_celsius=False, \n",
-        "                               output_name=None)"
+        "EU_AgERA5.AgERA5_merged_csv(kelvin_to_celsius=False, output_name=None)"
       ]
     }
   ],

diff --git a/docs/usage/xES_usage.md b/docs/usage/xES_usage.md
@@ -61,7 +61,7 @@ AgERA5_parameters = [
 
 ### Step 4: Define the Shapefile Path
 
-Provide the file path to your shapefile if you're using one:
+Provide the file path to your shapefile:
 
 ```python
 shapefile_file_path = 'EU/admin_3.shp'
@@ -98,12 +98,12 @@ EU_AgERA5.download_AgERA5(num_requests=6,
 
 
 ### Step 7: Aggregate Data
-f
+
 xEarthStat's Aggregation process utilize the availability of GPU for parallel computation, and using the avilalble CPU cores for multiprocessing. it automatically detect if there is a GPU or not, if not it shift computational processing on CPU.
 
 - `max_workers`: Default to total number of CPU's cores. You can change the number of cores that used in multiprocessing.
 - `all_touched`: Default to `False` to just consider pixels within the geometry object. `True` to consider all touched pixels by geo-object. 
-- `stat`: Default to `mean` to calculate the mean. There are other options, `"median"`, `"min"`, `"max"`, and `"sum"`.
+- `stat`: Default to `"mean"` to calculate the mean. There are other options, `"median"`, `"min"`, `"max"`, and `"sum"`.
 
 ```python
 import os