cleaned notebooks for demo

notebooks/worldcereal_v1_demo_default_cropland.ipynb

@@ -0,0 +1,261 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "![](./resources/System_v1_cropland.png)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Introduction\n",
+    "\n",
+    "This notebook contains a short demo on how to use the WorldCereal system to generate a cropland extent map for your area and season of interest.<br>\n",
+    "The map is generated using a default model trained by the WorldCereal consortium to distinguish cropland from all other land use.\n",
+    "\n",
+    "Please note that for the purpose of this demo, the processing area is currently limited to 250 km² per model run.\n",
+    "\n",
+    "<div class=\"alert alert-block alert-info\">\n",
+    "<b>Cropland definition:</b> \n",
+    "Cropland is defined here as land used for temporary crops, i.e. crops with a less-than-1-year growing cycle which must be newly sown or planted for further production after the harvest. Sugar cane, asparagus, and cassava are also considered temporary crops, even though they remain in the field for more than 1 year. This cropland definition thus excludes perennial crops as well as (temporary) pastures.\n",
+    "</div>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Content\n",
+    "  \n",
+    "- [Before you start](###-Before-you-start)\n",
+    "- [1. Define your region of interest](#1.-Define-your-region-of-interest)\n",
+    "- [2. Define your year of interest](#2.-Define-your-year-of-interest)\n",
+    "- [3. Set some other options](#3.-Set-some-other-options)\n",
+    "- [4. Generate your map](#4.-Generate-your-map)\n",
+    "- [5. Final notes](#5.-Final-notes)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Before you start\n",
+    "\n",
+    "In order to run WorldCereal crop mapping jobs from this notebook, you need to create an account on the Copernicus Data Space Ecosystem,\n",
+    "by completing the form [here](https://dataspace.copernicus.eu/).\n",
+    "This is free of charge and will grant you a number of free openEO processing credits to continue this demo."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### 1. Define your region of interest\n",
+    "\n",
+    "When running the code snippet below, an interactive map will be visualized. Click the Rectangle button on the left hand side of the map to start drawing your region of interest.\n",
+    "\n",
+    "In case your region exceeds the 250 km² limit, you will be asked to draw again.\n",
+    "The widget will automatically store the coordinates of the last rectangle you drew on the map."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from worldcereal.utils.map import ui_map\n",
+    "\n",
+    "map = ui_map()\n",
+    "map.show_map()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### 2. Define your year of interest\n",
+    "\n",
+    "The default WorldCereal cropland model always uses a time series of exactly one year as input for the model.\n",
+    "\n",
+    "However, instead of just using a calendar year (January 1st - December 31st), we recommend to define the exact start and end date of your time series, or processing period, based on the timing of the local growing seasons.\n",
+    "\n",
+    "Take the following example for Western Europe, where we typically have a winter season (s1) and summer season (s2):\n",
+    "\n",
+    "<p align=\"center\">\n",
+    "<img src=\"./resources/Cropland_inference_choose_end_date.png\" width=\"500\"/>\n",
+    "</p>\n",
+    "\n",
+    "\n",
+    "The best timing to start and end the time series in this case would be October (green vertical line), as for both seasons this would result in nicely capturing the growing season within the time series. It would not make sense in this case to define the year from June to June (red vertical line), as you will miss the start of the summer season and the end of the winter season in your time series.\n",
+    "\n",
+    "So if you would like to map temporary crops in Western Europe for the year 2021, we would recommend to define your processing period as October 1st 2020 - September 30th 2021.\n",
+    "\n",
+    "In case you do not know the typical seasonality of crops in your area of interest, you can consult the WorldCereal crop calendars using the function below.\n",
+    "\n",
+    "Note that in case your area of interest is located in an extremely heterogeneous part of the world, the WorldCereal seasons cannot be retrieved at the moment. As a fall-back, please consult the [USDA crop calendars](https://ipad.fas.usda.gov/ogamaps/cropcalendar.aspx)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from utils import retrieve_worldcereal_seasons\n",
+    "\n",
+    "spatial_extent = map.get_processing_extent()\n",
+    "seasons = retrieve_worldcereal_seasons(spatial_extent)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Execute the next cell to select your processing period:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from utils import date_slider\n",
+    "\n",
+    "slider = date_slider()\n",
+    "slider.show_slider()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### 3. Set some other options"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from worldcereal.job import PostprocessParameters\n",
+    "import os\n",
+    "from pathlib import Path\n",
+    "\n",
+    "# Choose whether or not you want to spatially clean the classification results\n",
+    "postprocess_result = True\n",
+    "\n",
+    "postprocess_parameters = PostprocessParameters(enable=postprocess_result)\n",
+    "\n",
+    "# Specify the local directory where the resulting maps should be downloaded to.\n",
+    "output_dir = Path(os.getcwd()) / 'CROPLAND_test'\n",
+    "print(f\"Output directory: {output_dir}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### 4. Generate your map\n",
+    "\n",
+    "We now have all information we need to generate our map!<br>\n",
+    "The next cell will submit a map inference job on CDSE through OpenEO.<br>\n",
+    "The first time you run this, you will be asked to authenticate with your CDSE account by clicking the link provided below the cell.<br>\n",
+    "Then sit back and wait untill your map is ready..."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from worldcereal.job import generate_map\n",
+    "\n",
+    "processing_period = slider.get_processing_period()\n",
+    "processing_extent = map.get_processing_extent()\n",
+    "\n",
+    "# Launch the job on CDSE through OpenEO\n",
+    "results = generate_map(\n",
+    "    processing_extent,\n",
+    "    processing_period,\n",
+    "    output_dir=output_dir,\n",
+    "    postprocess_parameters=postprocess_parameters,\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The classification results will be automatically downloaded to your *output_dir* in .tif format.<br>\n",
+    "By default, OpenEO stores the class labels and confidence scores in one file.\n",
+    "\n",
+    "Using the function below, we split this information into separate .tif files, thereby adding metadata and a color map, to ease interpretation and visualization:\n",
+    "- \"cropland_classification_start-date_end-date.tif\" --> contains the classification labels. A class look-up table is included in the .tif metadata.\n",
+    "- \"cropland_confidence_start-date_end-date.tif\" -->  contains the probability associated to the prediction [0 - 100]"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from utils import prepare_visualization\n",
+    "\n",
+    "filepaths = prepare_visualization(results)\n",
+    "filepaths"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The resulting raster files can be visualized in QGIS."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### 5. Final notes\n",
+    "\n",
+    "Both the quantity and quality of training data are main drivers affecting the quality of the cropland extent map.<br>\n",
+    "Using the figure below, you get a relative indication how much training data was available for training our current default cropland model:\n",
+    "\n",
+    "<p align=\"center\">\n",
+    "<img src=\"./resources/Landcover_training_data_density_PhI.png\" width=\"700\"/>\n",
+    "</p>\n",
+    "\n",
+    "In case you own good quality reference data on land cover and/or crop types, consider contributing these data to the WorldCereal project through our [Reference Data Module](https://ewoc-rdm-ui.iiasa.ac.at/)."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "worldcereal",
+   "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.10.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}