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,153 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "fabulous-watson",
+   "metadata": {},
+   "source": [
+    "# plotting quantified data"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "silver-coordinator",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import xarray as xr\n",
+    "import pint_xarray"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "dutch-wrestling",
+   "metadata": {},
+   "source": [
+    "## load the data"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "reserved-genetics",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "ds = xr.tutorial.open_dataset(\"air_temperature\")\n",
+    "data = ds.air\n",
+    "data"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "moderate-comfort",
+   "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.\n",
+    "    As such, the units attributes follow the CF conventions, which by default <code>pint</code> does not \n",
+    "    understand. To work around that, we are modifying the <code>units</code> attributes here, but in general it\n",
+    "    is better to use a library that modifies the <code>UnitRegistry</code>.\n",
+    "</div>"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "passing-macintosh",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "data.lat.attrs[\"units\"] = \"degree\"\n",
+    "data.lon.attrs[\"units\"] = \"degree\""
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "legal-arctic",
+   "metadata": {},
+   "source": [
+    "## quantify the data"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "advanced-seating",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "quantified = data.pint.quantify()\n",
+    "quantified"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "smoking-playback",
+   "metadata": {},
+   "source": [
+    "## work with the data"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "satellite-performer",
+   "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": "temporal-joint",
+   "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": "sensitive-television",
+   "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