02_sample_design.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "d90d518a-4ebf-4e82-9f08-68b10676bba8",
   "metadata": {},
   "source": [
    "<font face=\"Calibri\" size=\"2\"> <i>SBAE - Notebook Series - Part II, version 0.2,  May 2023. Andreas Vollrath, UN-Food and Agricultural Organization, Rome</i>\n",
    "</font>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fff4369c-dec3-43b8-b9a9-a4bb36b4bf48",
   "metadata": {
    "tags": []
   },
   "source": [
    "![title](images/header.png)\n",
    "\n",
    "# II - Sample Design \n",
    "### Creation of point samples for subsequent time-series extraction and analysis\n",
    "-------\n",
    "\n",
    "#### **Introduction**\n",
    "\n",
    "The base for the eSBAE approach is a dense grid that captures change at a sufficient level of confidence. A systematic sampling design shall be be employed. This notebook provides the functionality to create such a grid over the given AOI (defined in Notebook 1). \n",
    "\n",
    "Two grid shapes are available, i.e. squared or hexagonal grid. In addition, it is necessary to determine the size of each grid cell as well as the projection.\n",
    "\n",
    "#### **Squared grid**\n",
    "\n",
    "Squared grids are a simple way of creating a grid. They are in use for various geospatial applications. The grid size of the squared grid is selected in metres, defining the single border length of each grid cell.\n",
    "\n",
    "#### **Hexagonal grid**\n",
    "\n",
    "Lately, hexagonal grids are adapted in National Forest Monitoring Sytems as they possess some particular characteristics. Foremost, they reduce the error on area, but they also do assure that each point within the grid cell is mre or less at the same distance to the centre. Indeed, the ideal shape under that criteria would be a circle. It is however not possible to create a consistent grid of circles. The hexagon is the shape of polygon that comes closest to this criteria, while being able to provide a consistent grid.\n",
    "\n",
    "The notebook provides a simplified interface to the dggrid software library from [Southern Oregon University](https://www.discreteglobalgrids.org/software/). \n",
    "DGGRID holds code to generetate standardized hexagonal grids based on a *Discrete Global Grid System (DGGS)*  with a set of predefined resolutions for specific projections optimized for equal area.\n",
    "\n",
    "It is important to understand that DGGRID has a **fixed set of resolutions** that should be selected from column *res* in the below table (You need to check the manual for other resolutions if you select a different projection than the ISEA3H)\n",
    "\n",
    "For advanced usage it is recommended to consult the [manual](https://webpages.sou.edu/~sahrk/docs/dggridManualV70.pdf).\n",
    "\n",
    "![title](images/dggrid_isea3h_ap3_res_table.png)\n",
    "\n",
    "#### **Sampling strategies**\n",
    "\n",
    "The notebook allows to select from 2 sampling strategies within each grid cell, *centroid* and *random*. The centroid will take the centre point according to the projection selected, while the random option \n",
    "\n",
    "\n",
    "#### ***Projections***\n",
    "\n",
    "When creating samples, an important consideration is the projection used. Projections always exhibit distortions with regard to the actual sphere-like shape of the Earth. As our aim is to give each sample the same weight in terms of area representativeness, we shall select a projection that is optimised for **equal area**. \n",
    "\n",
    "##### **Squared grid projections**\n",
    "\n",
    "In the table below you can find some examples of global equal area projections to select from. The information is taken from an article from Yildrim & Kaya 2008 and can be found [here](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC3790990/#:~:text=The%20level%20of%20distortion%20can,compared%20to%20equal%2Darea%20maps). **Note** that the commonly used Lat/Lon projection (EPSG:4326) **does** contain distortions that shall be avoided.\n",
    "\n",
    "| **Projection**    | **Code**       |\n",
    "| -------------     |----------------|\n",
    "| Behrmann          | ESRI:54017     | \n",
    "| Bonne             | ESRI:54024     | \n",
    "| Sinusoidal        | ESRI:54008     |\n",
    "\n",
    "\n",
    "##### **Hexagonal grid projections and grid size**\n",
    "\n",
    "By default, the ISEA3H projection is used. Consult the [dggrid manual](https://webpages.sou.edu/~sahrk/docs/dggridManualV70.pdf) for further projections options. "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9f1f9d9a-8a0d-4d85-b134-f0bda3727152",
   "metadata": {},
   "source": [
    "### Import libs\n",
    "\n",
    "*Execute only* [CTRL+ENTER]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "a75e78de-8687-4632-8586-9ca964b31045",
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "/usr/local/share/jupyter/kernels/venv-eSBAE_notebooks/venv/lib/python3.10/site-packages/bfast/__init__.py:10: UserWarning: cupy is not available in this environment, GPU fonctionnalities won't be available\n",
      "  warn(\"cupy is not available in this environment, GPU fonctionnalities won't be available\")\n"
     ]
    }
   ],
   "source": [
    "import ee\n",
    "# initialize EE    \n",
    "try:\n",
    "    ee.Initialize()\n",
    "except:\n",
    "    ee.Authenticate()\n",
    "    ee.Initialize()\n",
    "    \n",
    "from sampling_handler import SampleDesign"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5823fb25-9996-4041-81ce-f2af8ad6fc55",
   "metadata": {},
   "source": [
    "#### 2 - Initialize SampleDesign Class\n",
    "\n",
    "In the below cell we initialize the SampleDesign Class\n",
    "\n",
    "1. Grid shape: This defines which shape the underlying systematic grid shall have. Choices are squared or hexagonal. \n",
    "2. Sampling strategy: Here it is set if the samplng point is set in the centre or at a random point within each grid cell.\n",
    "3. Grid projection (as epsg/esri code): As described above, projection is an important part when creating the grid. However, equal area projections are not the most commonly used projections. The routine is able to use a different grid system internally for creating the grid and/or placing the centroid. Note that when having selected a hexagonal grid, this projection is only being used for the placement of the centroid.\n",
    "4. Output projection: this will define the projection of the final output file, independent of the projection the grid was defined. For this, it can also be a projection that is not ideal for the creation of sampling grids such as Lat/Long.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "79717889-63f4-4ceb-bc40-8d763e1aa808",
   "metadata": {},
   "source": [
    "#### 1.2 - Create grid cells and sample points for a squared grid"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e4493a15-8bf2-4db9-a953-e94265c40a67",
   "metadata": {},
   "outputs": [],
   "source": [
    "esbae = SampleDesign(\n",
    "    \n",
    "    # set your project's name (NEEDS to be the same as in notebook 1)\n",
    "    # no space allowed, use _ instead\n",
    "    project_name='my_first_esbae_project',\n",
    "    \n",
    "    # defines the underlying grid, \n",
    "    # choices: 'squared', 'hexagonal'\n",
    "    shape='hexagonal',              \n",
    "    \n",
    "    # defines where the sample is placed within the grid, \n",
    "    # choices: 'random', 'centroid'\n",
    "    strategy='centroid',          \n",
    "    \n",
    "    # defines the projection in which the grid is generated,\n",
    "    # for hexagonal it applies to the centroid calculation only, as dggrid uses its own projection\n",
    "    grid_crs=\"ESRI:54017\",\n",
    "    \n",
    "     # defines the projection in which the grid is saved\n",
    "    out_crs='EPSG:4326',\n",
    "    \n",
    "    # This is in case you haven't run notebook 1 and want to directly start from here\n",
    "    # aoi = ee.FeatureCollection('my_ee_feature_collection')\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "28042408-29be-49d7-8609-3a4ace29cdd4",
   "metadata": {
    "tags": []
   },
   "source": [
    "### 2 - Create Grid\n",
    "\n",
    "Another important aspect is the grid size. **NOTE** that the grid size is selected differently for squared and hexagonal grids. \n",
    "A squared grid is simply defined by the distance between each point (which is the same as a single border length of the underlying grid).\n",
    "\n",
    "The hexagonal grid, instead, relies on a hierarchical system and has fixed resolutions (see Internode spacing in the above table). In addition, it uses a very specific projection optimized for equal area projections using hexagons. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a7fdbfe3-383b-46d4-a166-e98af2c9f396",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Those parameters apply to squared grid only (otherwise ignored)\n",
    "esbae.squared_grid_size = 5000\n",
    "\n",
    "# Those parameters apply to hexagonal grid only\n",
    "esbae.dggrid_resolution = 11     # this relates to the res column from the table above\n",
    "esbae.dggrid_projection = 'ISEA3H'\n",
    "\n",
    "# generation of grid\n",
    "c, p = esbae.generate_samples(upload_to_ee=True, save_as_ceo=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cbf47b80-a507-4eca-9a4d-ee20b2364aab",
   "metadata": {},
   "source": [
    "#### 3 - Plot hexagonal grid and save figure"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b44ae3e7-1bdc-45c6-9f6d-b872f0524035",
   "metadata": {},
   "outputs": [],
   "source": [
    "esbae.plot_samples()"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": " (venv) Sample Based Area Estimation",
   "language": "python",
   "name": "venv-esbae_notebooks"
  },
  "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.10.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}