Add sample data notebook

docs/source/examples.rst

@@ -4,6 +4,7 @@ Examples
 .. toctree::
     :maxdepth: 2
 
+    examples/sample-data.ipynb
     examples/get-model-grid.ipynb
     examples/eos.ipynb
     examples/region-mask.ipynb

docs/source/examples/sample-data.ipynb

@@ -0,0 +1,115 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Sample Data\n",
+    "\n",
+    "`pop-tools` provides some sample data through the `pop_tools.datasets` module."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Where are my data files?\n",
+    "\n",
+    "The sample data files are downloaded automatically by [pooch](https://www.fatiando.org/pooch/latest/api/index.html#module-pooch) the first time you load them. \n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import pop_tools\n",
+    "import xarray as xr\n",
+    "xr.set_options(display_style=\"html\")  # fancy HTML repr"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "To find which data files are available via `pop_tools`, you can run the following:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "pop_tools.DATASETS.registry_files"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Once you know which file you are interested in, you can pass the name to the `pop_tools.DATASETS.fetch()` function. \n",
+    "This function will download the file if it does not exist already on your local system. After the file has been downloaded, the fetch function returns the path: "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "filepath = pop_tools.DATASETS.fetch('cesm_pop_monthly.T62_g17.nc')\n",
+    "print(filepath)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Now, we can pass the file path to the appropriate I/O package for loading the content of the file:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "ds = xr.open_dataset(filepath)\n",
+    "ds"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%load_ext watermark\n",
+    "%watermark -d -iv -m -g -h"
+   ]
+  }
+ ],
+ "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.6"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}