Add an example notebook for custom models.

.gitlab-ci.yml

@@ -123,10 +123,11 @@ test-debian:
 pages:
   stage: deploy
   script:
+    - cp examples/*.ipynb docs/
     - apt-get update -y -qq
-    - apt-get install -y -qq python3-dev python3-pip python3-cartopy
+    - apt-get install -y -qq python3-dev python3-pip python3-cartopy pandoc
     - pip install pymagglobal --extra-index-url https://public:5mz_iyigu-WE3HySBH1J@git.gfz-potsdam.de/api/v4/projects/${CI_PROJECT_ID}/packages/pypi/simple
-    - pip install sphinx sphinx-argparse
+    - pip install jupyter notebook sphinx nbsphinx sphinx-argparse
     - sphinx-build -b html docs public
   artifacts:
     paths:

docs/examples.rst

+.. _examples-label:
+
+Example Notebooks
+=================
+Here we collect relevant examples. The list may grow over time.
+
+.. toctree::
+   :maxdepth: 2
+
+   example_1

docs/index.rst

@@ -9,6 +9,7 @@ It can be applied to all cubic-spline based geomagnetic field models stored in t
 
    package_documentation
    command_line_interface
+   examples
 
 
 Installation

examples/example_1.ipynb

+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "681fb4de",
+   "metadata": {},
+   "source": [
+    "# Using pymagglobal with custom models"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "7c938d6b",
+   "metadata": {},
+   "source": [
+    "This notebook focusses on how to translate a custom model to `pymagglobal`. We focus on the SHA.DIF.14k-model by [Pavón-Carrasco et al.](#pavon), which is publicly available [here](http://pc213fis.fis.ucm.es/sha.dif.14k/).\n",
+    "\n",
+    "> <a name=\"pavon\"></a> Pavón-Carrasco, F.J., M. L. Osete, J. M. Torta and A. De Santis (2014)  \n",
+    "> A Geomagnetic Field Model for the Holocene based on archaeomagnetic  \n",
+    "> and lava flow data. Earth Planet. Sci. Lett., 388, 98 - 109.\n",
+    "\n",
+    "To access the model, we download it directly using `urllib` and `numpy`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "dbcb982b",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import numpy as np\n",
+    "from urllib.request import urlopen\n",
+    "\n",
+    "raw_data = urlopen('http://pc213fis.fis.ucm.es/sha.dif.14k/coeff_SHA.DIF.14k.dat')\n",
+    "data = np.genfromtxt(raw_data).T"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "837cd058",
+   "metadata": {},
+   "source": [
+    "With the additional knowledge that the model is valid in the interval `[-12000, 1800]`, we can set up an object that can be used by `pymagglobal`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "f4b5705d",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pymagglobal import Model\n",
+    "from pymagglobal.utils import i2lm_l, i2lm_m, lmax2N\n",
+    "\n",
+    "from scipy.interpolate import BSpline\n",
+    "\n",
+    "\n",
+    "# Inherit from pymagglobals Model-class\n",
+    "class SHADIF14k(Model):\n",
+    "    # Override the __init__ method to set up\n",
+    "    # the model with our data\n",
+    "    def __init__(self):\n",
+    "        # set up the name\n",
+    "        self.name = 'sha.dif.14k'\n",
+    "        # The first column consists of the knots,\n",
+    "        # but it contains many duplications\n",
+    "        self.knots = np.unique(data[0])\n",
+    "        # Set the interval in which the model is valid\n",
+    "        self.t_min = -12000\n",
+    "        self.t_max = 1800\n",
+    "        # The first column contains the degrees, so\n",
+    "        # we extract the maxum\n",
+    "        self.l_max = int(np.max(data[1]))\n",
+    "        # Now we go through the data and access the\n",
+    "        # coefficients line by line\n",
+    "        \n",
+    "        # First set up an empty array of the right size\n",
+    "        self.coeffs = np.empty((len(self.knots), lmax2N(self.l_max)))\n",
+    "        # Then iterate over all coefficients\n",
+    "        for it in range(lmax2N(self.l_max)):\n",
+    "            # Get degree and order from the index\n",
+    "            ell = i2lm_l(it)\n",
+    "            m = i2lm_m(it)\n",
+    "            # Get the corresponding indices in the data-array\n",
+    "            inds = (data[1] == ell) * (data[2] == abs(m))\n",
+    "            # Write the data to the coefficient-array\n",
+    "            if m < 0:\n",
+    "                # scale to nT\n",
+    "                self.coeffs[:, it] = data[4][inds]*1000\n",
+    "            else:\n",
+    "                # scale to nT\n",
+    "                self.coeffs[:, it] = data[3][inds]*1000\n",
+    "\n",
+    "        # Finally initialize the BSpline object\n",
+    "        self.splines = BSpline(self.knots,\n",
+    "                               self.coeffs,\n",
+    "                               3)\n",
+    "        # The model file does not report uncertainties\n",
+    "        self.cov_splines = None"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4a463586",
+   "metadata": {},
+   "source": [
+    "This model can now be initialized and used like any other model in `pymagglobal`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "d891c8d5",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from matplotlib import pyplot as plt\n",
+    "from pymagglobal import dipole_series\n",
+    "\n",
+    "plt.rcParams['font.size'] = '14'\n",
+    "\n",
+    "shadif14k = SHADIF14k()\n",
+    "\n",
+    "times = np.linspace(-1000, 1500, 501)\n",
+    "\n",
+    "fig, ax = plt.subplots(1, 1, figsize=(10, 6))\n",
+    "for color, model in zip(['C0', 'C1'], [shadif14k, Model('ARCH10k.1')]):\n",
+    "    dip = dipole_series(times, model)\n",
+    "    ax.plot(times, dip, color=color, zorder=2, label=model.name)\n",
+    "\n",
+    "ax.legend();\n",
+    "ax.set_ylabel(r'Dipole moment [$10^{22}$Am$^2$]');\n",
+    "ax.set_xlabel(r'time [yrs.]');"
+   ]
+  }
+ ],
+ "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.9.5"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}