02_jupyter_notebooks_key_concepts.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img src='./img/jupyter_logo.png' align='right' width='30%'></img>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a href=\"./01_example_how_to_not_do_it.ipynb\"><< 01 - Example - How to NOT do it</a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-block alert-success\">\n",
    "<b>MAKE USE OF THE KEY CONCEPTS BELOW</b> \n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Jupyter notebooks - Key concepts"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This notebook gives an overview of the key concepts to make `Jupyter notebooks` more `educational` and `effective`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<hr>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Table of contents"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### [GET ORGANIZED](#get_organized)\n",
    "* [Index notebook](#index)\n",
    "* [Naming convention](#naming_convention)\n",
    "* [Navigation pane](#navigation)\n",
    "\n",
    "\n",
    "#### [LAYOUT AND OUTLINE ARE KEY](#layout)\n",
    "* [Header and Footer](#header_footer)\n",
    "* [Table of contents / Notebook Outline](#toc)\n",
    "* [Alert boxes](#alert_boxes)\n",
    "* [Other styling options](#other)\n",
    "\n",
    "\n",
    "#### [OUTSOURCE AND MODULARIZE](#outsource_modularize)\n",
    "* [Example: functions](#functions)\n",
    "\n",
    "\n",
    "#### [RESOURCES](#resources)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<hr>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## <a id='get_organized'></a>GET ORGANIZED"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### <a id='index'></a>Index notebook"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "An `index notebook` provides the following:\n",
    "* gives an `overview` of what the notebooks / course / tutorial is about\n",
    "* provides an outline and links to other notebooks with `Markdown`\n",
    "* Links to additional (external) content"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-block alert-success\">\n",
    "<b>See an example index notebook <a href='./00_index.ipynb'>here</a></b>\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### <a id='naming_convention'></a> Naming Convention"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Indicate the order of the notebooks with a naming convention. For example by starting the notebooks with numbers, your notebooks are autmatically displayed in the expected order.\n",
    "\n",
    "This helps your audience to get a better overview of what sequence to follow."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img src='./img/naming_convention.png' width='100%'></img>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### <a id='navigation'></a>Navigation pane"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The order of notebooks can also be reflected in a navigation pane. This helps your audience to click through the notebooks without the need to go back to the `Home`.\n",
    "\n",
    "You can make use of `html functionalities` to create a navigation pane on the top of each notebook:\n",
    "* link notebooks with `<a href=\"\"> Notebook Name </a>`\n",
    "* with `<span style=\"float:right;\">...</span>` you can place a link to a notebook floated on the right"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Code example"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`<a href=\"./00_index.ipynb\"><< 00 - Index</a><span style=\"float:right;\"><a href=\"./02_jupyter_notebooks_key_concepts.ipynb\">02 - Jupyter Notebooks - Key concepts >></a></span>`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Result"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-block alert-success\">\n",
    "<a href=\"./00_index.ipynb\"><< 00 - Index</a><span style=\"float:right;\"><a href=\"./02_jupyter_notebooks_key_concepts.ipynb\">02 - Jupyter Notebooks - Key concepts >></a></span>\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<hr>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## <a id='layout'></a>LAYOUT AND OUTLINE ARE KEY"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### <a id='header_footer'></a>Header and Footer"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Header and Footer cells allow you to customized your notebooks. A `header` cell can e.g. show a logo of a project. A `footer` cell can provide additional links or license information."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Images can be added with `html`:\n",
    "\n",
    "`<img src='./img/jupytercon_logo.png' align='right' width='30%'></img>`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-block alert-warning\">\n",
    "<b>TIP: Organize images in a dedicated folder called e.g. <i>img</i>.</b>\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img src='./img/header_footer.png' width='80%'></img>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### <a id='toc'></a>Table of contents / Notebook Outline"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A `table of contents` helps your audience to navigate through the notebook by providing an overview of it's content and the main headings. Your audience can navigate directly to a specific section of interest."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "First: You generate your `Table of contents` providing an overview of all main headings.\n",
    "Each heading a `hashtag` is assigned and you add a hyperlink with `markdown`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### [GET ORGANIZED](#get_organized)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In a second step, you define the `heading` and to each heading, you assign the defined `hashtag`:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## <a id='get_organized'></a> GET ORGANIZED"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> ## <a id='get_organized'></a> GET ORGANIZED"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### <a id='alert_boxes'></a>Alert boxes"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`Alert boxes` colorize notebook cells based on `alert levels`. Alert boxes are helpful to highlight specific content.\n",
    "\n",
    "Alert boxes are `html div` statements from `class:alert alert-block`:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-block alert-warning\">\n",
    "\n",
    "<b>NOTE:</b> Alert level 'warning' colorizes a cell <i>yellow</i>.\n",
    "\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There are four different `alert levels`: "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Alert level - warning"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> <div class=\"alert alert-block alert-warning\">\n",
    "> <b>NOTE:</b> Alert level 'warning' colorizes a cell <i>yellow</i>.\n",
    "> </div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Alert level - success"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> <div class=\"alert alert-block alert-success\">\n",
    "> <b>NOTE:</b> Alert level 'success' colorizes a cell <i>green</i>.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Alert level - danger"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> <div class=\"alert alert-block alert-danger\">\n",
    "> <b>NOTE:</b> Alert level 'danger' colorizes a cell <i>danger</i>.\n",
    "> </div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Alert level - info"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> <div class=\"alert alert-block alert-info\">\n",
    "> <b>NOTE:</b> Alert level 'info' colorizes a cell <i>info</i>.\n",
    "> </div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### <a id='other'></a>Other styling options"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### <a id='other'></a>Other styling options"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`<hr>`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<hr>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Space cell"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`<br>`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Code formatter"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`This should be formatted as 'code'`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`This should be formatted as 'code'`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<hr>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## <a id='outsource_modularize'></a>OUTSOURCE AND MODULARIZE"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### <a id='functions'></a>Example: functions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You might need to re-use some lines of code. The best way is to modularize code and define functions for common operations. You can outsource functions in a `functions` notebook and load required functions when needed. This helps to keep you notebooks organized and reduce redundant code."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`ipynb` library allows to load content from another notebook. In the example below, from the notebook called `functions.ipynb`, we import the function `generate_geographical_subset`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from ipynb.fs.full.functions import generate_geographical_subset"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the [functions](./functions.ipynb) notebook, you can define the function and add a `docstring` as function description:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def generate_geographical_subset(xarray, latmin, latmax, lonmin, lonmax):\n",
    "    \"\"\" \n",
    "    Generates a geographical subset of a xarray DataArray.\n",
    "    \n",
    "    Parameters:\n",
    "        xarray (xarray DataArray): a xarray DataArray with latitude and longitude coordinates\n",
    "        latmin, latmax, lonmin, lonmax (int): boundaries of the geographical subset\n",
    "        \n",
    "    Returns:\n",
    "        Geographical subset of a xarray DataArray.\n",
    "    \"\"\"   \n",
    "    return xarray.where((xarray.latitude < latmax) & (xarray.latitude > latmin) & (xarray.longitude < lonmax) & (xarray.longitude > lonmin),drop=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When you load the function from the functions notebook, you can use `?function name` and a window opens with the docstring of the function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "?generate_geographical_subset"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<hr>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## <a id='resources'></a>RESOURCES"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Some example tutorials related to `meteorological`, `climate` and `atmospheric composition` data processing:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* [Learning tool for Python (LTPy) on Atmospheric Composition](https://gitlab.eumetsat.int/eo-lab-usc-open/atmospheric-composition)\n",
    "* [Analysis of Big Earth Data with Jupyter notebooks](https://github.com/jwagemann/2020_analysis_of_big_earth_data_with_jupyter)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "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.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}