new degurba example

.gitignore

@@ -137,3 +137,6 @@ docs/notebooks/
 # ignore the generated sphinx conf.py file
 # we generate it during the doc build using jupyter-book from _conf.py
 docs/conf.py
+
+# ignore any notebooks/implementations/output
+notebooks/Implementations/output

notebooks/Tutorials/Degurba_Example.ipynb

@@ -0,0 +1,170 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Example Degurba Calculation\n",
+    "\n",
+    "This sample notebook is being created in response to a question raised in [Issue #6](https://github.com/worldbank/GOSTurban/issues/6) about the Degurba Calculation functionality.\n",
+    "\n",
+    "To run this notebook you will need to install the dependency [`pooch`](https://www.fatiando.org/pooch/latest/) which allows us to reference some sample data without explicitly including it in the repository.\n",
+    "Conveniently, `pooch` also keeps you from downloading the same data multiple times, so the first time you run the notebook the data will be downloaded and stored in a cache folder, but subsequent runs will use the cached data.\n",
+    "\n",
+    "To install `pooch` you can run the following command:\n",
+    "\n",
+    "```bash\n",
+    "pip install pooch\n",
+    "```\n",
+    "\n",
+    "Once you have installed `pooch` you can restart the kernel and run the notebook."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Importing the necessary libraries"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# import libraries\n",
+    "import os\n",
+    "import zipfile\n",
+    "import rasterio\n",
+    "import rasterio.warp\n",
+    "\n",
+    "import geopandas as gpd\n",
+    "\n",
+    "\n",
+    "# Import GOSTurban functions\n",
+    "import GOSTurban.UrbanRaster as urban\n",
+    "\n",
+    "# Import raster helpers from GOSTrocks\n",
+    "import GOSTrocks.rasterMisc as rMisc\n",
+    "\n",
+    "# import pooch to fetch data\n",
+    "import pooch"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Path and Data Setup\n",
+    "\n",
+    "Setting up the paths and downloading the data."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# define location to put outputs\n",
+    "output_folder = \"./output\"\n",
+    "# make sure the folder exists\n",
+    "if not os.path.exists(output_folder):\n",
+    "    os.makedirs(output_folder)\n",
+    "\n",
+    "# define files to write out\n",
+    "deg_file = os.path.join(output_folder, \"FINAL_STANDARD\", \"GHS_DEG.tif\")\n",
+    "adm1_file = os.path.join(output_folder, \"ADM1.shp\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# set path to global administrative boundaries file\n",
+    "# GEOJSON format downloaded from: https://public.opendatasoft.com/explore/dataset/world-administrative-boundaries/export/\n",
+    "global_bounds_adm1 = pooch.retrieve(\n",
+    "    url=\"https://public.opendatasoft.com/api/explore/v2.1/catalog/datasets/world-administrative-boundaries/exports/geojson?lang=en&timezone=America%2FNew_York\",\n",
+    "    known_hash=\"a84673ed03db7196464b2771c6fd47c1afe184eb06a38c0e92cb4aedff5ee0da\",\n",
+    ")\n",
+    "\n",
+    "# define specific country of interest based on iso3 code\n",
+    "iso3 = \"GHA\"\n",
+    "\n",
+    "# read the global admin boundaries\n",
+    "inG1 = gpd.read_file(global_bounds_adm1)\n",
+    "# filter the global admin boundaries to the specific country of interest\n",
+    "inD1 = inG1.loc[inG1[\"iso3\"] == iso3]\n",
+    "# reproject the admin boundaries to WGS84\n",
+    "inD1 = inD1.to_crs({\"init\": \"epsg:4326\"})\n",
+    "# save the admin boundary for the specific country of interest to the output folder\n",
+    "if not os.path.exists(adm1_file):\n",
+    "    inD1.to_file(adm1_file)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# define path to the global human settlement (GHS) population (GHS-POP) data\n",
+    "# can be downloaded from: https://ghsl.jrc.ec.europa.eu/download.php\n",
+    "pop_layer_zip = pooch.retrieve(\n",
+    "    url=\"https://jeodpp.jrc.ec.europa.eu/ftp/jrc-opendata/GHSL/GHS_POP_GLOBE_R2023A/GHS_POP_E2030_GLOBE_R2023A_54009_100/V1-0/tiles/GHS_POP_E2030_GLOBE_R2023A_54009_100_V1_0_R9_C18.zip\",\n",
+    "    known_hash=\"dba662e12455541546efdb118433fd8b08dcd36e5c978cf88e0e14bb1db599e8\",\n",
+    ")\n",
+    "# unzip the GHS-POP data\n",
+    "zip_ref = zipfile.ZipFile(pop_layer_zip, \"r\")\n",
+    "zip_ref.extractall(output_folder)\n",
+    "zip_ref.close()\n",
+    "# path to the tif file\n",
+    "pop_layer = os.path.join(\n",
+    "    output_folder, \"GHS_POP_E2030_GLOBE_R2023A_54009_100_V1_0_R9_C18.tif\"\n",
+    ")\n",
+    "\n",
+    "# file to clip data to\n",
+    "temp_pop_file = os.path.join(output_folder, \"GHS_TEMP.tif\")\n",
+    "# open and clip the GHS-POP data to the specific country of interest\n",
+    "inR = rasterio.open(pop_layer)\n",
+    "selD = inD1.loc[inD1[\"region\"] == \"Western Africa\"]\n",
+    "rMisc.clipRaster(inR, selD, temp_pop_file)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Degurba Calculation\n",
+    "\n",
+    "Performing the Degurba Calculation."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "xx = urban.urbanGriddedPop(pop_layer)\n",
+    "res = xx.calculateDegurba(\n",
+    "    urbDens=21,\n",
+    "    hdDens=(15 * 7),\n",
+    "    minPopThresh=0.5 * 7,\n",
+    "    out_raster=deg_file,\n",
+    "    verbose=True,\n",
+    ")"
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}