Add example on how to generate data.

docs/examples.rst

@@ -8,3 +8,4 @@ Here we collect relevant examples. The list may grow over time.
    :maxdepth: 2
 
    example_1
+   example_2

examples/example_1.ipynb.license

+This file complements pymagglobal.
+
+It is licensed under CC0 1.0 (https://creativecommons.org/publicdomain/zero/1.0/)

examples/example_2.ipynb

+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "681fb4de",
+   "metadata": {},
+   "source": [
+    "# Generate synthetic data"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "7c938d6b",
+   "metadata": {},
+   "source": [
+    "Here we briefly show how `pymagglobal` can be used to generate synthetic data. We first set up the model we want to use to generate the synthetic data:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "5380320c",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pymagglobal import Model\n",
+    "\n",
+    "myModel = Model('CALS10k.2')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "98302e49",
+   "metadata": {},
+   "source": [
+    "Next we have to generate a data distribution. We use `pymagglobal`s `get_z_at` routine, to generate `n_at` random locations, that are uniformly distributed on the sphere. Times are drawn uniformly as well."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "68d9a6d8",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pymagglobal.utils import get_z_at\n",
+    "\n",
+    "import numpy as np\n",
+    "from matplotlib import pyplot as plt\n",
+    "from cartopy import crs as ccrs\n",
+    "\n",
+    "# the number of artificial records\n",
+    "n_at = 400\n",
+    "z_at = get_z_at(n_at, random=True)\n",
+    "# set the times to something arbitrary\n",
+    "z_at[3] = np.random.uniform(-1000, 1900, size=n_at)\n",
+    "\n",
+    "# plot the records, convert co-lat to lat\n",
+    "fig, ax = plt.subplots(1, 1, subplot_kw={'projection': ccrs.Mollweide()})\n",
+    "ax.scatter(z_at[1], 90-z_at[0], transform=ccrs.PlateCarree())\n",
+    "ax.set_global()\n",
+    "ax.coastlines();"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "cbf80490",
+   "metadata": {},
+   "source": [
+    "Finally we can evaluate the model at the inputs, to get synthetic ''observations'' of the field"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "ea10fa42",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pymagglobal.core import field\n",
+    "obs = field(z_at, myModel)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "0c28838f",
+   "metadata": {},
+   "source": [
+    "Let's have a look at the records:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "119a535b",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "fig, axs = plt.subplots(1, 3, subplot_kw={'projection': ccrs.Mollweide()},\n",
+    "                        figsize=(15, 4))\n",
+    "titles = [r'$B_N$', r'$B_E$', r'$B_Z$']\n",
+    "for it in range(3):\n",
+    "    axs[it].set_title(titles[it])\n",
+    "    axs[it].scatter(z_at[1], 90-z_at[0], c=obs[it], transform=ccrs.PlateCarree())\n",
+    "    axs[it].set_global()\n",
+    "    axs[it].coastlines();"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "99e9b776",
+   "metadata": {},
+   "source": [
+    "Declination, inclination and intensity records are also easily generated, by using the `field` kwargs:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "8bda1baf",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "obs_dif = field(z_at, myModel, field_type='dif')\n",
+    "fig, axs = plt.subplots(1, 3, subplot_kw={'projection': ccrs.Mollweide()},\n",
+    "                        figsize=(15, 4))\n",
+    "titles = [r'$D$', r'$I$', r'$F$']\n",
+    "for it in range(3):\n",
+    "    axs[it].set_title(titles[it])\n",
+    "    axs[it].scatter(z_at[1], 90-z_at[0], c=obs_dif[it], transform=ccrs.PlateCarree())\n",
+    "    axs[it].set_global()\n",
+    "    axs[it].coastlines();"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "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.7"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
+%% Cell type:markdown id:681fb4de tags:
+
+# Generate synthetic data
+
+%% Cell type:markdown id:7c938d6b tags:
+
+Here we briefly show how `pymagglobal` can be used to generate synthetic data. We first set up the model we want to use to generate the synthetic data:
+
+%% Cell type:code id:5380320c tags:
+
+``` python
+from pymagglobal import Model
+
+myModel = Model('CALS10k.2')
+```
+
+%% Cell type:markdown id:98302e49 tags:
+
+Next we have to generate a data distribution. We use `pymagglobal`s `get_z_at` routine, to generate `n_at` random locations, that are uniformly distributed on the sphere. Times are drawn uniformly as well.
+
+%% Cell type:code id:68d9a6d8 tags:
+
+``` python
+from pymagglobal.utils import get_z_at
+
+import numpy as np
+from matplotlib import pyplot as plt
+from cartopy import crs as ccrs
+
+# the number of artificial records
+n_at = 400
+z_at = get_z_at(n_at, random=True)
+# set the times to something arbitrary
+z_at[3] = np.random.uniform(-1000, 1900, size=n_at)
+
+# plot the records, convert co-lat to lat
+fig, ax = plt.subplots(1, 1, subplot_kw={'projection': ccrs.Mollweide()})
+ax.scatter(z_at[1], 90-z_at[0], transform=ccrs.PlateCarree())
+ax.set_global()
+ax.coastlines();
+```
+
+%% Cell type:markdown id:cbf80490 tags:
+
+Finally we can evaluate the model at the inputs, to get synthetic ''observations'' of the field
+
+%% Cell type:code id:ea10fa42 tags:
+
+``` python
+from pymagglobal.core import field
+obs = field(z_at, myModel)
+```
+
+%% Cell type:markdown id:0c28838f tags:
+
+Let's have a look at the records:
+
+%% Cell type:code id:119a535b tags:
+
+``` python
+fig, axs = plt.subplots(1, 3, subplot_kw={'projection': ccrs.Mollweide()},
+                        figsize=(15, 4))
+titles = [r'$B_N$', r'$B_E$', r'$B_Z$']
+for it in range(3):
+    axs[it].set_title(titles[it])
+    axs[it].scatter(z_at[1], 90-z_at[0], c=obs[it], transform=ccrs.PlateCarree())
+    axs[it].set_global()
+    axs[it].coastlines();
+```
+
+%% Cell type:markdown id:99e9b776 tags:
+
+Declination, inclination and intensity records are also easily generated, by using the `field` kwargs:
+
+%% Cell type:code id:8bda1baf tags:
+
+``` python
+obs_dif = field(z_at, myModel, field_type='dif')
+fig, axs = plt.subplots(1, 3, subplot_kw={'projection': ccrs.Mollweide()},
+                        figsize=(15, 4))
+titles = [r'$D$', r'$I$', r'$F$']
+for it in range(3):
+    axs[it].set_title(titles[it])
+    axs[it].scatter(z_at[1], 90-z_at[0], c=obs_dif[it], transform=ccrs.PlateCarree())
+    axs[it].set_global()
+    axs[it].coastlines();
+```

examples/example_2.ipynb.license

+This file complements pymagglobal.
+
+It is licensed under CC0 1.0 (https://creativecommons.org/publicdomain/zero/1.0/)