Merge pull request #49 from digitalearthafrica/geomedian-overhaul

Added information to the geomedian explanation.

docs/Geomedian_widget.ipynb

@@ -0,0 +1,103 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Geomedian widget"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Geomedian composites are introduced in [Session 3](./session_3/01_intro_composites.ipynb). Geomedians are a method of combining multiple timesteps of data into one image. \n",
+    "\n",
+    "Geomedians were defined as follows:\n",
+    "\n",
+    "> A geomedian composite finds the median values of the bands for each pixel when considered **together**. This means they represent the data **better** than median composites. \n",
+    "\n",
+    "This gives rise to a few common questions. \n",
+    "\n",
+    "* What does it mean to **consider the bands together**? \n",
+    "* What might that look like? \n",
+    "* How does it affect the colour of each pixel in my final composite image?\n",
+    "\n",
+    "To explore the answers to these questions, we can use an interactive module known as a **widget**. Instead of looking at one whole image, the widget focuses on a single pixel.\n",
+    "\n",
+    "The geomedian widget gives three timesteps of data. You can click on the sliders to change the data for each timestep, which affects the pixel colour. In turn, this will impact the computation of the median and geomedian. As you will see, they are not always the same!"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "<img align=\"middle\" src=\"./_static/other_information/widget2.PNG\" alt=\"Example of the widget.\" width=650>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "*An example of what the geomedian widget looks like. To interact with the widget, download and run the geomedian widget notebook.*"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Follow the instructions below to download the widget notebook. It can help with understanding the following concepts:\n",
+    "\n",
+    "* In which cases are the median and geomedian very similar or the same?\n",
+    "* In which cases are the median and geomedian very different?\n",
+    "* Why are geomedians more representative of the whole dataset, compared to medians?"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Download geomedian widget notebook"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "[Download the geomedian widget notebook](./_static/other_information/Geomedian_interactive_extend1.ipynb)\n",
+    "\n",
+    "To view this notebook on the Sandbox, you will need to first download it to your computer, then upload it to the Sandbox. Follow these instructions:\n",
+    "\n",
+    "1. Download the notebook by clicking the link above.\n",
+    "2. On the Sandbox, open the **Training** folder.\n",
+    "3. Click the **Upload Files** button as shown below.\n",
+    "\n",
+    "<img align=\"middle\" src=\"./_static/session_2/05_solution_uploadbutton.png\" alt=\"Upload button.\" width=400>\n",
+    "\n",
+    "4. Select the downloaded notebook using the file browser. Click **OK**.\n",
+    "5. The solution notebook will appear in the **Training** folder. Double-click to open it."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "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.6.9"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}

docs/index.rst

@@ -56,4 +56,5 @@ Latest Updates
    Frequently_asked_questions
    help_documentation
    Maps_help
+   Geomedian_widget
    License

docs/session_3/01_intro_composites.ipynb

@@ -168,6 +168,20 @@
     "However, medians do not account for the fact that every pixel holds information for multiple bands. It is therefore better to use a statistic that is configured for multi-dimensional data, such as a geomedian."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "<img align=\"middle\" src=\"../_static/session_3/median-composite_edit.png\" alt=\"Median composite explanation\" width=\"800\">"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "*A median considers data from each band independently. This can be seen in Step 2 of the median compositing algorithm shown above.*"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -179,6 +193,20 @@
     "This means they represent the data **better** than median composites. "
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "<img align=\"middle\" src=\"../_static/session_3/geomedian-composite_edit.png\" alt=\"Geomedian composite explanation\" width=\"800\">"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "*Unlike the median composite, the geometric median (geomedian) considers all bands of data together. Each band adds a dimension to the geomedian calculation. For a three-band dataset, such as the RGB dataset shown in the geomedian compositing algorithm above, each point can be represented on a three-dimensional scatter plot. The geomedian is the minimised 'sum of distances' between all the points.*"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -204,30 +232,29 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "However, on a pixel-by-pixel basis, it is possible to visualise the difference between median and geomedian.\n",
+    "However, on a pixel-by-pixel basis, it is possible to visualise the difference between median and geomedian. The best way to do this is to use the **geomedian widget** to explore the effects of different datasets on the median and geomedian.\n",
     "\n",
-    "<img align=\"middle\" src=\"../_static/session_3/01_intro_composites_geomedian_median_line.png\" alt=\"Dataset scatter plot.\" width=\"850\">\n",
+    "<img align=\"middle\" src=\"../_static/other_information/widget2.PNG\" alt=\"Example of the widget.\" width=850>\n",
     "\n",
-    "Inspect the above plot of reflectance for a single pixel. The values for median and geomedian are **not** the same &mdash; you can see the green and red lines do not quite overlap. Imagine this difference over millions of pixels. The composite results will certainly be affected. "
+    "The geomedian widget uses interactive sliders to change the value of the data. This affects the output median and geomedian values. You will soon see that each compositing method can produce significantly different results. On a larger scale (like a whole image, or over several years), this can affect the end composite image.\n",
+    "\n",
+    "[Download the widget notebook here](../_static/other_information/Geomedian_interactive_extend1.ipynb) or visit the [Geomedian widget](../Geomedian_widget.ipynb) page for for more information, including instructions on running the widget."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Geomedians take more processing time to calculate than median composites. However, unless you are only doing a quick visualisation, you should use the geomedian method when creating composites. This is because the geomedian value is more scientifically rigorous as it accounts for all the bands in the dataset.\n",
-    "\n",
-    "To learn more about geomedians, you can read the following paper: [High-Dimensional Pixel Composites From Earth Observation Time Series](https://ieeexplore.ieee.org/abstract/document/8004469)."
+    "## The bottom line: use geomedians"
    ]
   },
   {
-   "cell_type": "raw",
-   "metadata": {
-    "raw_mimetype": "text/restructuredtext"
-   },
+   "cell_type": "markdown",
+   "metadata": {},
    "source": [
-    ".. note::\n",
-    "    The ``median`` and ``geomedian`` are plotted here as lines to better show their differences -- scatter points are harder to see. The lines are not indicative of any 'trends' over the different bands."
+    "Geomedians take more processing time to calculate than median composites. However, unless you are only doing a quick visualisation, you should use the geomedian method when creating composites. This is because the geomedian value is more scientifically rigorous as it accounts for all the bands in the dataset.\n",
+    "\n",
+    "To learn more about geomedians, you can read the following paper: [High-Dimensional Pixel Composites From Earth Observation Time Series](https://ieeexplore.ieee.org/abstract/document/8004469)."
    ]
   },
   {