02_combine_jupyter_widgets_with_events.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "Collapsed": "false"
   },
   "source": [
    "<img src='./img/opengeohub_logo.png' alt='OpenGeoHub Logo' align='right' width='15%'></img>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a href=\"./01_Introduction_Jupyter_widgets.ipynb\"><< 01 - Introduction to Jupyter widgets </a><span style=\"float:right;\"><a href=\"./03_voila_dashboards.ipynb\"> 03 - Introduction to Voilà dashboards >></a></span>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "Collapsed": "false"
   },
   "source": [
    "# 2 - Combine Jupyter widgets with events\n",
    "### Let's get interactive with Jupyter widgets "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* [Output widgets](#output)\n",
    "* [Example - Interactive climate graph application](#climate_graph)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "Collapsed": "false"
   },
   "source": [
    "## <a id='climate_graph'></a>Example - Interactive climate graph application"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "Collapsed": "false"
   },
   "source": [
    "Required libraries:\n",
    "* [Plotly](https://plot.ly/) for interactive visualization\n",
    "* [Widgets](https://ipywidgets.readthedocs.io/en/stable/examples/Widget%20Basics.html)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Load required libraries"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "Collapsed": "false"
   },
   "outputs": [],
   "source": [
    "from IPython.display import display, clear_output\n",
    "import ipywidgets as widgets\n",
    "import numpy as np\n",
    "import ee\n",
    "\n",
    "import plotly.graph_objs as go\n",
    "from matplotlib import pyplot as plt\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Load ERA5 precipitation and 2m air temperature data from the Google Earth Engine data catalogue"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Initialise EarthEngine"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The following command initialises the EarthEngine Python API."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "Collapsed": "false"
   },
   "outputs": [],
   "source": [
    "ee.Initialize()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "Collapsed": "false"
   },
   "source": [
    "#### Load ERA5 monthly ImageCollection "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "With the `ee.ImageCollection` constructor, you can construct a data object with data from the Earth Engine data catalogue. Let us load the ImageCollection of the monthly aggregated ERA5 reanalysis data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "Collapsed": "false"
   },
   "outputs": [],
   "source": [
    "era5_monthly = ee.ImageCollection('ECMWF/ERA5/MONTHLY')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "Collapsed": "false"
   },
   "source": [
    "#### Process mean precipitation for each month based on entire time series and build an `ImageCollection` of the resulting image list"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "From the entire data period (1979 to 2020), let us create the average for each month. For this we have to apply the `ImageCollection.reduce()` function.\n",
    "\n",
    "If a reducer function is applied to an image collection, the output looses its projections information, as a collection can store images with different projections. For this reason, you have to set the projection again, after the `reduce` function was applied.\n",
    "\n",
    "You can select and the projection information from the first image of the `ImageCollection` with the `select(i).projection()` function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "Collapsed": "false"
   },
   "outputs": [],
   "source": [
    "era5_monthly_img = era5_monthly.limit(1).first()\n",
    "collection_img_proj = era5_monthly_img.select(0).projection()\n",
    "#era5_monthly_img.getInfo()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, you can loop over a list of 12 integer values (for each month one) and filter the specific months of each year. On the resulting list, a `reducer` function is applied and the outcome is appended to an empty list."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "Collapsed": "false"
   },
   "outputs": [],
   "source": [
    "months = range(1,13)\n",
    "\n",
    "# Store images in a list\n",
    "img_list = []\n",
    "for i in months:\n",
    "    collection_filtered = era5_monthly.filter(ee.Filter.calendarRange(i,i, 'month'))\n",
    "    collection_red = collection_filtered.reduce(ee.Reducer.mean())\n",
    "    \n",
    "    collection_red_proj = collection_red.setDefaultProjection(collection_img_proj)\n",
    "    img_list.append(collection_red_proj)\n",
    "    \n",
    "#img_list[0].getInfo()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "Collapsed": "false"
   },
   "source": [
    "As a final step, you can build an ImageCollection out of the image list with the function `ee.ImageCollection.fromImages()`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "Collapsed": "false"
   },
   "outputs": [],
   "source": [
    "meanMonths_collection = ee.ImageCollection.fromImages(img_list)\n",
    "#meanMonths_collection.getInfo()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Visualize an interactive climate graph with `Plotly`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Select the temperature and precipitation time-series based on a point feature "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "With `ee.Geometry.Point()`, you can define a point feature with EarthEngine. Based on this point location, you can select the two ERA5 variables `total_precipitation_mean` and `mean_2m_air_temperature_mean`.\n",
    "\n",
    "The result is a list of lists containing the the information `id`, `longitude`, `latitude`, `time` and `temperature`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As an example we can specify the latitude and longitude values for Rome:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "longitude =12.5\n",
    "latitude = 41.9"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "point = ee.Geometry.Point(longitude,latitude)\n",
    "tp_point = meanMonths_collection.select('total_precipitation_mean').getRegion(point,500).getInfo()\n",
    "t2m_point = meanMonths_collection.select('mean_2m_air_temperature_mean').getRegion(point,500).getInfo()\n",
    "t2m_point"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Select the data series and convert the variable units"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let us select only the temperature and precipitation data series. During selection, you can directly convert the variable units:\n",
    "- the precipitation values from `m` to `mm` by multiplying with 1000\n",
    "- the 2m air temperature values from `K` to `degC` by substracting 273.15"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ydata_tp = [row[4]*1000 for row in tp_point[1:]]\n",
    "    \n",
    "ydata_t2m = [row[4]-273.15 for row in t2m_point[1:]]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Define the plot and plot the climate graph "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For `precipitation`, we define a `barplot` and for `temperature` we define a `lineplot`. With the `data` and `layout` kwargs, we can bring everything together. \n",
    "\n",
    "The result is a climate graph for the specified location."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "tp = go.Bar(\n",
    "        x=['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun','Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],\n",
    "        y=ydata_tp,\n",
    "        name='Total precipitation in mm',\n",
    "        marker=dict(\n",
    "            color='rgb(204,204,204)',\n",
    "        ))\n",
    "    \n",
    "t2m = go.Scatter(\n",
    "        x=['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun','Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],\n",
    "        y=ydata_t2m,\n",
    "        name=\"2m air temperature in deg C\",\n",
    "        yaxis='y2')\n",
    "\n",
    "data = [tp,t2m]\n",
    "layout = go.Layout(\n",
    "        title='Climate graph at location '+ str(round(latitude,2)) + ' / '+ str(round(longitude,2)) + ' (lat/lon)',\n",
    "        yaxis=dict(\n",
    "            title=\"Total precipitation in mm\",\n",
    "            dtick=20\n",
    "        ),\n",
    "        yaxis2=dict(\n",
    "            title=\"2 m air temperature in degC\",\n",
    "            overlaying='y',\n",
    "            side='right',\n",
    "            range=[min(ydata_t2m)-2,max(ydata_t2m)+2],\n",
    "            dtick=5\n",
    "        ),\n",
    "        plot_bgcolor='white',\n",
    "        legend=dict(\n",
    "            orientation='h')\n",
    "    )\n",
    "\n",
    "fig = go.Figure(data=data, layout=layout)\n",
    "fig"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let us define a function called `visualize_climate_graph` for the visualization, as we might want to re-use it later. But instead of `lat` and `lon`, we specify `lon.value` and `lat.value`. You will understand later why."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def visualize_climate_graph():    \n",
    "    point = ee.Geometry.Point(lon.value, lat.value)\n",
    "    tp_point = meanMonths_collection.select('total_precipitation_mean').getRegion(point,500).getInfo()\n",
    "    t2m_point = meanMonths_collection.select('mean_2m_air_temperature_mean').getRegion(point,500).getInfo()\n",
    "\n",
    "    ydata_tp = [row[4]*1000 for row in tp_point[1:]]\n",
    "    ydata_t2m = [row[4]-273.2 for row in t2m_point[1:]]\n",
    "\n",
    "    tp = go.Bar(\n",
    "        x=['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun','Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],\n",
    "        y=ydata_tp,\n",
    "        name='Total precipitation in mm',\n",
    "        marker=dict(\n",
    "            color='rgb(204,204,204)',\n",
    "        ))\n",
    "    \n",
    "    t2m = go.Scatter(\n",
    "        x=['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun','Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],\n",
    "        y=ydata_t2m,\n",
    "        name=\"2m air temperature in deg C\",\n",
    "        yaxis='y2')\n",
    "\n",
    "    data = [tp,t2m]\n",
    "    layout = go.Layout(\n",
    "        title='Climate graph at location '+ str(round(lat.value,2)) + ' / '+ str(round(lon.value,2)) + ' (lat/lon)',\n",
    "        yaxis=dict(\n",
    "            title=\"Total precipitation in mm\",\n",
    "            dtick=20\n",
    "        ),\n",
    "        yaxis2=dict(\n",
    "            title=\"2 m air temperature in degC\",\n",
    "            overlaying='y',\n",
    "            side='right',\n",
    "            range=[min(ydata_t2m)-2,max(ydata_t2m)+2],\n",
    "            dtick=5\n",
    "        ),\n",
    "        plot_bgcolor='white',\n",
    "        legend=dict(\n",
    "            orientation='h')\n",
    "    )\n",
    "\n",
    "    fig = go.Figure(data=data, layout=layout)\n",
    "    return fig"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Combine the climate graph with `ipywidgets` to make it dynamic"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let us develop a small application where we have two different `FloatSliders` with the range of latitude and longitude ranges. As soon as the sliders are modified, we can click a button in order to updated the climate graph.\n",
    "\n",
    "The first step is to define two `FloatSliders`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "lat = widgets.FloatSlider(\n",
    "    value=41.9,\n",
    "    min=-90.0,\n",
    "    max=90.0,\n",
    "    step=0.25,\n",
    "    description='Latitude:',\n",
    "    disabled=False,\n",
    "    continuous_update=False,\n",
    "    orientation='horizontal', #horizontal\n",
    "    readout=True\n",
    ")\n",
    "lat"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "lon = widgets.FloatSlider(\n",
    "    value=12.5,\n",
    "    min=-180.0,\n",
    "    max=180.0,\n",
    "    step=0.25,\n",
    "    description='Longitude:',\n",
    "    disabled=False,\n",
    "    continuous_update=False,\n",
    "    orientation='horizontal',\n",
    "    readout=True\n",
    ")\n",
    "lon"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `keys` command helps you to inspect the information the widget object holds. Let us inspect the `keys` from the slider `lon`. You see that it contains an entry value, which stores the current value displayed from the slider. In order to dynamically update a plot based on the slider entries, we have to use `lon.value` and `lat.value`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "lon.keys"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "lon.value"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we define a function called `click()` that calls the visualization function `visualize_climate_graph()`, which returns the plotted figure."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def click(b):\n",
    "    fig = visualize_climate_graph()\n",
    "    with out:\n",
    "        clear_output(wait=True)\n",
    "        fig.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let us define a `Button` widget with the description `Plot climate graph`. You can add an event handler `on_click()`. The event handler calls the function `click()` which returns the plotted climate graph. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "button=widgets.Button(description='Plot climate graph')\n",
    "button.on_click(click)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The final step is to define an `Output` widget and to `display` all the widgets that shall be part of the application. Let us also make use of the `HBox` widget to arrange the two sliders horizontally."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "Collapsed": "false"
   },
   "outputs": [],
   "source": [
    "out=widgets.Output()\n",
    "display(widgets.HBox([lat,lon]))\n",
    "display(button)\n",
    "display(out)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Resources\n",
    "\n",
    "- [Jupyter Output widgets](https://ipywidgets.readthedocs.io/en/stable/examples/Output%20Widget.html#)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a href=\"./01_Introduction_Jupyter_widgets.ipynb\"><< 01 - Introduction to Jupyter widgets </a><span style=\"float:right;\"><a href=\"./03_voila_dashboards.ipynb\"> 03 - Introduction to Voilà dashboards >></a></span>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "Collapsed": "false"
   },
   "source": [
    "<hr>\n",
    "&copy; 2020 | Julia Wagemann\n",
    "<a rel=\"license\" href=\"http://creativecommons.org/licenses/by/4.0/\"><img style=\"float: right\" alt=\"Creative Commons Lizenzvertrag\" style=\"border-width:0\" src=\"https://i.creativecommons.org/l/by/4.0/88x31.png\" /></a>"
   ]
  }
 ],
 "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.7.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}