diff --git a/docs/source/examples.rst b/docs/source/examples.rst index fc47f7f0..29bd808c 100644 --- a/docs/source/examples.rst +++ b/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 diff --git a/docs/source/examples/sample-data.ipynb b/docs/source/examples/sample-data.ipynb new file mode 100644 index 00000000..535083c6 --- /dev/null +++ b/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 +}