VIS_000_Intro_to_Matplotlib.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a href=\"https://www.hydroffice.org/epom/\"><img src=\"images/000_000_epom_logo.png\" alt=\"ePOM\" title=\"Open ePOM home page\" align=\"center\" width=\"12%\" alt=\"Python logo\\\"></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a href=\"https://piazza.com/class/jtn9igrguw476h\"><img src=\"images/help.png\" alt=\"ePOM\" title=\"Ask questions on Piazza.com\" align=\"right\" width=\"10%\" alt=\"Piazza.com\\\"></a>\n",
    "# Introduction to Matplotlib"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[Matplotlib](https://matplotlib.org/) is the most popular Python plotting package for creating figures such as histograms, bar charts, scatter plots, etc."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/key.png\">\n",
    "\n",
    "You can use Matplotlib to create high-quality figures in a variety of formats, with just a few lines of code."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To see examples of what you can do with Matplotlib, you can explore the official [sample plots](https://matplotlib.org/tutorials/introductory/sample_plots.html) and the [thumbnail gallery](https://matplotlib.org/gallery/index.html)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The following code cell performs two preliminary **required** operations:\n",
    "\n",
    "1. Import the `pyplot` module from the `matplotlib` package, and give it the commonly-used short name of `plt` using the keyword `as`. \n",
    "2. Set the `%matplotlib` [magic function](https://ipython.readthedocs.io/en/stable/interactive/tutorial.html#magic-functions) to `inline` and store the figures in the notebook. (Follow [this link](https://ipython.readthedocs.io/en/stable/interactive/plotting.html#id1) for more details.)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "\n",
    "%matplotlib inline"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/info.png\">\n",
    "\n",
    "With the keyword `as`, you can use *almost* any short name (see the [Python Variable Naming](../python_basics/001_Variables_and_Types.ipynb#Python-Variable-Naming) section for the naming convention). However, deviating from commonly-adopted short names (e.g., `plt` for `matplotlib.pyplot`) makes your code less readable by others."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/key.png\">\n",
    "\n",
    "Every time that you restart this notebook, remember to execute the above cell!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Package such Matplotlib are continuously improved with new capabilities as well as with the removal of existing coding  errors (i.e., [software bugs](https://en.wikipedia.org/wiki/Software_bug)). Thus, in case of troubles with a specific package, it is important to know which package version is currently in use. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/key.png\">\n",
    "\n",
    "You can access the package version through the associated `__version__` variable."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import matplotlib\n",
    "\n",
    "print(\"Matplotlib version: %s\" % (matplotlib.__version__, ))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Your First Plots"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Our first plot will display a list of temperature values:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "temp_list = [11.2, 11.0, 13.7, 16.0, 16.1, 16.2, 16.1]\n",
    "plt.plot(temp_list)\n",
    "plt.show()  # This is required outside of a notebook"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As the code above shows, basic plotting is very simple! \n",
    "\n",
    "The two minimum required steps are:\n",
    "\n",
    "* Call the `plot()` function with some data (the `temp_list` in this specific case).\n",
    "* Call the `show()` function."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The above plot has:\n",
    "\n",
    "* A range of values based on the content of `temp_list` on the vertical axis (i.e., the `y` values).\n",
    "* The indices of the temperature values in the `temp_list` on the horizontal axis (i.e., the `x` values)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If two lists of data are passed to the `plot()` function, then:\n",
    "\n",
    "* The values in the first list are used as the coordinates for the horizontal axis.\n",
    "* The values in the second list are used as the coordinates for the vertical axis."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We will use a [temperature-salinity diagram](https://en.wikipedia.org/wiki/Temperature%E2%80%93salinity_diagram) as an example of a plot that can be created by passing two lists: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sal_list = [34.4, 34.1, 33.6, 31.7, 31.3, 31.2, 31.0]  # new list\n",
    "temp_list = [11.2, 11.0, 13.7, 16.0, 16.1, 16.2, 16.1]\n",
    "plt.plot(sal_list, temp_list)  # modified code\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The axes match the extent of the data in the above plot. This is the default behavior!\n",
    "\n",
    "However, you may need to select a particular area of the plot (e.g., zoom in or zoom out). You can achieve such a task by manually defining the plot extent calling the `axis()` function with a list of four values: `[xmin, xmax, ymin, ymax]`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sal_list = [34.4, 34.1, 33.6, 31.7, 31.3, 31.2, 31.0]\n",
    "temp_list = [11.2, 11.0, 13.7, 16.0, 16.1, 16.2, 16.1]\n",
    "plt.plot(sal_list, temp_list)\n",
    "plt.axis([32.0, 34.0, 11.0, 16.0])  # new code\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Customizing your plots"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The above plots lack several important elements that would help a reader better understand its content. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the next code cell, we will add a few elements:\n",
    "\n",
    "* A title (using the `plt.title()` function).\n",
    "* A label for the `x` and the `y` axes (using the `plt.xlabel()` and `plt.ylabel()` functions).\n",
    "* A grid in the plot background (using the `plt.grid()` function)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sal_list = [34.4, 34.1, 33.6, 31.7, 31.3, 31.2, 31.0]\n",
    "temp_list = [11.2, 11.0, 13.7, 16.0, 16.1, 16.2, 16.1]\n",
    "plt.plot(sal_list, temp_list)\n",
    "plt.axis([32.0, 34.0, 11.0, 16.0])  \n",
    "plt.title(\"T-S Diagram\")  # new code\n",
    "plt.xlabel(\"Salinity[PSU]\")  # new code\n",
    "plt.ylabel(\"Temperature[\\u00B0C]\")  # new code\n",
    "plt.grid()  # new code\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/info.png\">\n",
    "\n",
    "What is `\"\\u00B0\"` for? Follow [this url](https://en.wikipedia.org/wiki/List_of_Unicode_characters#Latin-1_Supplement)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As you may have noticed in the above plots, `matplotlib` draws a solid blue line between the consecutive points. \n",
    "\n",
    "This default behavior can be modified by passing additional parameters to the `plot()` function. A small selection of these parameters are:\n",
    "\n",
    "* `color`: To set color of the drawn line.\n",
    "* `linewidth`: To define the number of points used to draw the line.\n",
    "* `linestyle`: To modify the style of the line such as solid, dashed, dotted, etc.\n",
    "\n",
    "It is possible to show a marker at each point in the input lists, and this marker can also be customized with the following parameters: \n",
    "* `marker`: To set/unset the drawing of markers as well as the shape of the markers.\n",
    "* `markersize`: To define the number of points used to draw the marker.\n",
    "* `markerfacecolor`/`markeredgecolor`: To modify the color of the marker face/edge."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/info.png\">\n",
    "\n",
    "[Here](https://raw.githubusercontent.com/rougier/matplotlib-cheatsheet/master/matplotlib-cheatsheet.png) you can find a helpful Matplotlib cheatsheet to customize your plots."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the code below, we provide an example of how to use these parameters:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sal_list = [34.4, 34.1, 33.6, 31.7, 31.3, 31.2, 31.0]\n",
    "temp_list = [11.2, 11.0, 13.7, 16.0, 16.1, 16.2, 16.1]\n",
    "plt.plot(sal_list, temp_list, \n",
    "         color='green', linewidth=1.5, linestyle='dotted', \n",
    "         marker='o', markersize=12, markerfacecolor='yellow', markeredgecolor='red') # new code\n",
    "plt.axis([32.0, 34.0, 11.0, 16.0])  \n",
    "plt.title(\"T-S Diagram\")  \n",
    "plt.xlabel(\"Salinity[PSU]\") \n",
    "plt.ylabel(\"Temperature[\\u00B0C]\")\n",
    "plt.grid()\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/key.png\">\n",
    "\n",
    "All the `plot()` parameters (and their accepted values) are extensively described in the [official Matplotlib documentation](https://matplotlib.org/api/_as_gen/matplotlib.pyplot.plot.html#matplotlib-pyplot-plot). Consult the Matplotlib documentation when you want to customize your figures!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/key.png\">\n",
    "\n",
    "Properly labeled and legible plots are a key requirement for communicating scientific results."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    " "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "solution2": "hidden",
    "solution2_first": true
   },
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/test.png\">\n",
    "\n",
    "Create a \"Vessel Positions\" plot showing the position of vessel provided as two lists of values (longitudes and latitudes, respectively). Set the plot extent between `13.2` and `16.0`, for longitudes, and between `35.6` and `37.0`, for latitudes. \n",
    "Make the vessel tracklines displayed as dashed lines and the vessel positions with square markers.\n",
    "<br><br>\n",
    "*Consult the [official Matplotlib documentation](https://matplotlib.org/api/_as_gen/matplotlib.pyplot.plot.html#matplotlib-pyplot-plot) to retrieve the values to pass as parameters for dashed lines and square markers.*"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "solution2": "hidden"
   },
   "outputs": [],
   "source": [
    "lon_list = [14.52, 14.66, 14.72, 14.74, 14.85, 14.98, 15.20]\n",
    "lat_list = [35.90, 36.02, 36.17, 36.34, 36.51, 36.60, 36.62]\n",
    "\n",
    "plt.plot(lon_list, lat_list, linestyle=\"dashed\", marker=\"s\")\n",
    "plt.axis([13.2, 16.0, 35.6, 37.0])\n",
    "plt.title(\"Vessel Position\")\n",
    "plt.xlabel(\"Longitude\")\n",
    "plt.ylabel(\"Latitude\")\n",
    "plt.grid()\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "lon_list = [14.52, 14.66, 14.72, 14.74, 14.85, 14.98, 15.20]\n",
    "lat_list = [35.90, 36.02, 36.17, 36.34, 36.51, 36.60, 36.62]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "***"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Georeferenced Plotting"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the above exercise, the geographic coordinates are described by [geodetic latitudes and longitudes](https://en.wikipedia.org/wiki/Geographic_coordinate_system#Latitude_and_longitude). This is common in ocean mapping!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Since latitudes and longitudes are curvilinear, the distance between lines of equal longitude ([**meridians**](https://en.wikipedia.org/wiki/Meridian_(geography))) is a function of the latitude. This has a number of consequences: for instance, the distance between meridians at the poles goes down to zero (see the yellow arrow in the figure below). "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![Longitudes and Latitudes at the North Pole](images/VIS_000_000_lats_and_lons_at_the_north_pole.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As you can imagine, simply plotting latitudes and longitudes in a Cartesian coordinate system - like we did in the previous exercise - will return a distorted representation of geographic data. During the Geodesy course, you will learn how this distortion may be reduced. For this notebook, it is enough to know that we can control the distortion by applying a [map projection](https://en.wikipedia.org/wiki/Map_projection) to the geographic coordinates."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The good news is that there is a Python package, named [Cartopy](https://scitools.org.uk/cartopy/docs/latest/), specifically designed to extend Matplotlib with geospatial plotting capabilities."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px;\" src=\"images/key.png\">\n",
    "\n",
    "The `cartopy` package handles the projection of geographic coordinates. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Cartopy supports [several popular map projections](https://scitools.org.uk/cartopy/docs/latest/crs/projections.html). To use them, you just need to pass a `projection` parameter to Matplotlib's `axes()` function.\n",
    "\n",
    "For instance, the following code shows an example that uses an [orthographic projection](https://en.wikipedia.org/wiki/Orthographic_projection_in_cartography). The code also adds the world coastlines and a grid with latitudes and longitudes. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import cartopy.crs as ccrs\n",
    "\n",
    "adopted_proj = ccrs.Orthographic()\n",
    "ax = plt.axes(projection=adopted_proj)\n",
    "ax.coastlines()  # to display the world coastlines\n",
    "ax.gridlines()  # to display a grid with latitudes and longitudes\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The above code can easily be modified to use other supported projections such as the [Plate-Carrée equirectangular projection](https://en.wikipedia.org/wiki/Equirectangular_projection) or the [Mercator projection](https://en.wikipedia.org/wiki/Mercator_projection)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import cartopy.crs as ccrs\n",
    "\n",
    "adopted_proj = ccrs.PlateCarree()  # modified code\n",
    "ax = plt.axes(projection=adopted_proj)\n",
    "ax.coastlines()\n",
    "ax.gridlines()\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import cartopy.crs as ccrs\n",
    "\n",
    "adopted_proj = ccrs.Mercator()  # modified code\n",
    "ax = plt.axes(projection=adopted_proj)\n",
    "ax.coastlines()\n",
    "ax.gridlines()\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Below, we rewrite the solution to the previous exercise using the `cartopy` package and the Mercator projection."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import cartopy.crs as ccrs\n",
    "from cartopy.mpl.gridliner import LONGITUDE_FORMATTER, LATITUDE_FORMATTER\n",
    "\n",
    "lon_list = [14.52, 14.66, 14.72, 14.74, 14.85, 14.98, 15.20]\n",
    "lat_list = [35.90, 36.02, 36.17, 36.34, 36.51, 36.60, 36.62]\n",
    "\n",
    "adopted_proj = ccrs.Mercator()  # create a Mercator projection object for the figure\n",
    "ax = plt.axes(projection=adopted_proj)  # set the output projection to Mercator\n",
    "\n",
    "data_proj = ccrs.Geodetic() # create a Geodetic projection object for the geographic positions\n",
    "ax.plot(lon_list, lat_list, linestyle=\"dashed\", marker=\"s\", transform=data_proj)  # plot the geographic positions\n",
    "ax.set_extent([13.2, 16.0, 35.6, 37.0], data_proj)  # set the figure extent using values in the data projection\n",
    "\n",
    "gl = ax.gridlines(draw_labels=True)  # superimpose a grid and related labels\n",
    "gl.xlabels_top = False  # remove the longitude labels at the top of the figure \n",
    "gl.ylabels_left = False  # remove the latitude labels at the left on the figure\n",
    "gl.xformatter = LONGITUDE_FORMATTER  # pretty-print the longitude labels\n",
    "gl.yformatter = LATITUDE_FORMATTER  # pretty-print the latitude labels\n",
    "\n",
    "ax.coastlines(resolution='10m')  # show the coastlines at 10m resolution \n",
    "\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Can you name the islands shown in the figure? Modify the plot extent to see where the vessel was in the world!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "***"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"6%\" style=\"padding-right:10px; padding-top:10px;\" src=\"images/refs.png\">\n",
    "\n",
    "## Useful References"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* [Introduction to Ocean Data Science - Data Visualization slides](https://bitbucket.org/hydroffice/hyo_epom/downloads/ePOM.Intro_to_Ocean_Data_Science.Data_Visualization.pdf)\n",
    "* The Matplotlib Package:\n",
    "  * [Website](https://matplotlib.org/)\n",
    "  * [Documentation](https://matplotlib.org/users/index.html)\n",
    "  * [plot()](https://matplotlib.org/api/_as_gen/matplotlib.pyplot.plot.html#matplotlib-pyplot-plot)\n",
    "* [Matplotlib 3.1 cheatsheet](https://raw.githubusercontent.com/rougier/matplotlib-cheatsheet/master/matplotlib-cheatsheet.png)\n",
    "* The Cartopy Package:\n",
    "  * [Documentation](https://scitools.org.uk/cartopy/docs/latest/)\n",
    "  * [Map Projections](https://scitools.org.uk/cartopy/docs/latest/crs/projections.html)\n",
    "* [Software Bug](https://en.wikipedia.org/wiki/Software_bug)  \n",
    "* [Temperature-Salinity Diagram](https://en.wikipedia.org/wiki/Temperature%E2%80%93salinity_diagram)\n",
    "* [Latitudes and Longitudes](https://en.wikipedia.org/wiki/Geographic_coordinate_system#Latitude_and_longitude)\n",
    "* [Meridian](https://en.wikipedia.org/wiki/Meridian_(geography))\n",
    "* [Map Projection](https://en.wikipedia.org/wiki/Map_projection)\n",
    "  * [Orthographic Projection](https://en.wikipedia.org/wiki/Orthographic_projection_in_cartography)\n",
    "  * [Plate-Carrée Equirectangular Projection](https://en.wikipedia.org/wiki/Equirectangular_projection)\n",
    "  * [Mercator Projection](https://en.wikipedia.org/wiki/Mercator_projection)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"left\" width=\"5%\" style=\"padding-right:10px;\" src=\"images/email.png\">\n",
    "\n",
    "*For issues or suggestions related to this notebook, write to: epom@ccom.unh.edu*"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<!--NAVIGATION-->\n",
    "| [Contents](index.ipynb) | [Adding a Plotting Method >](VIS_001_Adding_a_Plotting_Method.ipynb)"
   ]
  }
 ],
 "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.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}