add a plotting example

docs/conf.py

@@ -46,6 +46,7 @@
     "sphinx_autosummary_accessors",
     "IPython.sphinxext.ipython_directive",
     "IPython.sphinxext.ipython_console_highlighting",
+    "nbsphinx",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -100,6 +101,10 @@
     "unit-like": ":term:`unit-like`",
 }
 
+# nbsphinx
+nbsphinx_timeout = 600
+nbsphinx_execute = "always"
+
 # -- Options for intersphinx extension ---------------------------------------
 
 intersphinx_mapping = {

docs/examples.rst

@@ -1,3 +1,7 @@
 Examples
 ========
-There are no examples yet.
+
+.. toctree::
+    :maxdepth: 1
+
+    examples/plotting

docs/examples/plotting.ipynb

@@ -0,0 +1,150 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "round-optimization",
+   "metadata": {},
+   "source": [
+    "# plotting quantified data"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "greatest-smart",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import xarray as xr\n",
+    "import pint_xarray"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "fuzzy-maintenance",
+   "metadata": {},
+   "source": [
+    "## load the data"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "proved-racing",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "ds = xr.tutorial.open_dataset(\"air_temperature\")\n",
+    "data = ds.air\n",
+    "data"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "medium-backup",
+   "metadata": {},
+   "source": [
+    "## convert units into a format understood by pint\n",
+    "\n",
+    "<div class=\"alert alert-info\">\n",
+    "<strong>Note:</strong> this example uses the data provided by the <code>xarray.tutorial</code> functions. As such, the <code>units</code> attributes follow the CF conventions, which <code>pint</code> does not understand by default. To work around that, we are modifying the <code>units</code> attributes here, but in general it is better to use a library that adds support for the units used by the CF conventions to <code>pint</code>.\n",
+    "</div>"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "published-powell",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "data.lat.attrs[\"units\"] = \"degree\"\n",
+    "data.lon.attrs[\"units\"] = \"degree\""
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "banned-tolerance",
+   "metadata": {},
+   "source": [
+    "## quantify the data"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "divine-boost",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "quantified = data.pint.quantify()\n",
+    "quantified"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "whole-momentum",
+   "metadata": {},
+   "source": [
+    "## work with the data"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "dried-friday",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "monthly_means = (\n",
+    "    quantified\n",
+    "    .pint.to(\"degC\")\n",
+    "    .sel(time=\"2013\")\n",
+    "    .groupby(\"time.month\").mean()\n",
+    ")\n",
+    "monthly_means"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "still-ebony",
+   "metadata": {},
+   "source": [
+    "## plot\n",
+    "\n",
+    "`xarray`'s plotting functions will cast the data to `numpy.ndarray`, so we need to \"dequantify\" first."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "united-machine",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "monthly_means.pint.dequantify(format=\"~P\").plot.imshow(col=\"month\", col_wrap=4)"
+   ]
+  }
+ ],
+ "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.8.6"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

docs/requirements.txt

@@ -4,5 +4,8 @@ netCDF4
 sphinx>=3.2
 sphinx_rtd_theme
 ipython
+ipykernel
+jupyter_client
 nbsphinx
+matplotlib
 sphinx-autosummary-accessors

readthedocs.yml

@@ -8,3 +8,6 @@ python:
     - requirements: docs/requirements.txt
     - method: pip
       path: .
+
+sphinx:
+  fail_on_warning: true