From f2bee1f7a55d90b5c59592811454048520317341 Mon Sep 17 00:00:00 2001 From: Kalle Westerling Date: Wed, 11 Oct 2023 16:09:44 +0100 Subject: [PATCH] Adding nbsphinx + setting up sample notebook --- docs/conf.py | 6 +- .../tutorials/quickstart.ipynb | 149 ++++++++++++++++++ docs/getting-started/tutorials/quickstart.rst | 84 ---------- requirements.docs.txt | 3 +- 4 files changed, 156 insertions(+), 86 deletions(-) create mode 100644 docs/getting-started/tutorials/quickstart.ipynb delete mode 100644 docs/getting-started/tutorials/quickstart.rst diff --git a/docs/conf.py b/docs/conf.py index 6e9e1835..b55015d0 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -25,7 +25,11 @@ # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration -extensions = ["sphinx.ext.autodoc", "sphinx.ext.intersphinx"] +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.intersphinx", + "nbsphinx", +] templates_path = ["_templates"] exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] diff --git a/docs/getting-started/tutorials/quickstart.ipynb b/docs/getting-started/tutorials/quickstart.ipynb new file mode 100644 index 00000000..1b325a04 --- /dev/null +++ b/docs/getting-started/tutorials/quickstart.ipynb @@ -0,0 +1,149 @@ +{ + "cells": [ + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "nbsphinx": "hidden" + }, + "outputs": [], + "source": [ + "import sys, os\n", + "sys.path.append(os.path.abspath(\"../../../\"))" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Tutorial: Quickstart" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Here we will demonstrate a simple example of training a convolutional conditional neural process (ConvCNP) to spatially interpolate ERA5 data.\n", + "\n", + "We can go from imports to predictions with a trained model in less than 30 lines of code!" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "import deepsensor.torch\n", + "from deepsensor.data.loader import TaskLoader\n", + "from deepsensor.data.processor import DataProcessor\n", + "from deepsensor.model.convnp import ConvNP\n", + "from deepsensor.train.train import train_epoch\n", + "\n", + "import xarray as xr\n", + "import pandas as pd\n", + "import numpy as np\n", + "\n", + "# Load raw data\n", + "ds_raw = xr.tutorial.open_dataset(\"air_temperature\")\n", + "\n", + "# Normalise data\n", + "data_processor = DataProcessor(x1_name=\"lat\", x1_map=(15, 75), x2_name=\"lon\", x2_map=(200, 330))\n", + "ds = data_processor(ds_raw)\n", + "\n", + "# Set up task loader\n", + "task_loader = TaskLoader(context=ds, target=ds)\n", + "\n", + "# Set up model\n", + "model = ConvNP(data_processor, task_loader)\n", + "\n", + "# Generate training tasks with up to 10% of grid cells passed as context and all grid cells\n", + "# passed as targets\n", + "train_tasks = []\n", + "for date in pd.date_range(\"2013-01-01\", \"2014-11-30\")[::7]:\n", + " task = task_loader(date, context_sampling=np.random.uniform(0.0, 0.1), target_sampling=\"all\")\n", + " train_tasks.append(task)\n", + "\n", + "# Train model\n", + "for epoch in range(10):\n", + " train_epoch(model, train_tasks, progress_bar=True)\n", + "\n", + "# Predict on new task with 10% of context data and a dense grid of target points\n", + "test_task = task_loader(\"2014-12-31\", 0.1)\n", + "mean_ds, std_ds = model.predict(test_task, X_t=ds_raw)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "After training, the model can predict directly to `xarray` in your data's original units and coordinate system:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "mean_ds" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "We can also predict directly to `pandas` containing a timeseries of predictions at off-grid locations\n", + "by passing a `numpy` array of target locations to the `X_t` argument of `.predict`:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Predict at two off-grid locations for three days in December 2014\n", + "test_tasks = task_loader(pd.date_range(\"2014-12-01\", \"2014-12-31\"), 0.1)\n", + "mean_df, std_df = model.predict(test_tasks, X_t=np.array([[50, 280], [40, 250]]).T)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "mean_df" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [] + } + ], + "metadata": { + "kernelspec": { + "display_name": "mr_py38", + "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.9.12" + } + }, + "nbformat": 4, + "nbformat_minor": 2 +} diff --git a/docs/getting-started/tutorials/quickstart.rst b/docs/getting-started/tutorials/quickstart.rst deleted file mode 100644 index 2da7f8d2..00000000 --- a/docs/getting-started/tutorials/quickstart.rst +++ /dev/null @@ -1,84 +0,0 @@ -==================== -Tutorial: Quickstart -==================== - -Here we will demonstrate a simple example of training a convolutional conditional neural process (ConvCNP) to spatially interpolate ERA5 data. - -We can go from imports to predictions with a trained model in less than 30 lines of code! - -.. code-block:: python - - import deepsensor.torch - from deepsensor.data.loader import TaskLoader - from deepsensor.data.processor import DataProcessor - from deepsensor.model.convnp import ConvNP - from deepsensor.train.train import train_epoch - - import xarray as xr - import pandas as pd - import numpy as np - - # Load raw data - ds_raw = xr.tutorial.open_dataset("air_temperature") - - # Normalise data - data_processor = DataProcessor(x1_name="lat", x1_map=(15, 75), x2_name="lon", x2_map=(200, 330)) - ds = data_processor(ds_raw) - - # Set up task loader - task_loader = TaskLoader(context=ds, target=ds) - - # Set up model - model = ConvNP(data_processor, task_loader) - - # Generate training tasks with up to 10% of grid cells passed as context and all grid cells - # passed as targets - train_tasks = [] - for date in pd.date_range("2013-01-01", "2014-11-30")[::7]: - task = task_loader(date, context_sampling=np.random.uniform(0.0, 0.1), target_sampling="all") - train_tasks.append(task) - - # Train model - for epoch in range(10): - train_epoch(model, train_tasks, progress_bar=True) - - # Predict on new task with 10% of context data and a dense grid of target points - test_task = task_loader("2014-12-31", 0.1) - mean_ds, std_ds = model.predict(test_task, X_t=ds_raw) - -After training, the model can predict directly to `xarray` in your data's original units and coordinate system: - -.. code-block:: python - - >>> mean_ds - - Dimensions: (time: 1, lat: 25, lon: 53) - Coordinates: - * time (time) datetime64[ns] 2014-12-31 - * lat (lat) float32 75.0 72.5 70.0 67.5 65.0 ... 25.0 22.5 20.0 17.5 15.0 - * lon (lon) float32 200.0 202.5 205.0 207.5 ... 322.5 325.0 327.5 330.0 - Data variables: - air (time, lat, lon) float32 246.7 244.4 245.5 ... 290.2 289.8 289.4 - -We can also predict directly to `pandas` containing a timeseries of predictions at off-grid locations -by passing a `numpy` array of target locations to the `X_t` argument of `.predict`: - -.. code-block:: python - - # Predict at two off-grid locations for three days in December 2014 - test_tasks = task_loader(pd.date_range("2014-12-01", "2014-12-31"), 0.1) - mean_df, std_df = model.predict(test_tasks, X_t=np.array([[50, 280], [40, 250]]).T) - -.. code-block:: python - - >>> mean_df - air - time lat lon - 2014-12-01 50.0 280.0 260.183056 - 40.0 250.0 277.947373 - 2014-12-02 50.0 280.0 261.08943 - 40.0 250.0 278.219599 - 2014-12-03 50.0 280.0 257.128185 - 40.0 250.0 278.444229 - -This quickstart example is also `available as a Jupyter notebook `_ with added visualisations. diff --git a/requirements.docs.txt b/requirements.docs.txt index bdbf0cc5..9f577ea5 100644 --- a/requirements.docs.txt +++ b/requirements.docs.txt @@ -1,2 +1,3 @@ Sphinx==7.2.6 -sphinx-rtd-theme==1.3.0 \ No newline at end of file +sphinx-rtd-theme==1.3.0 +nbsphinx==0.9.3 \ No newline at end of file