First few changes to tutorials (#94)

_toc.yml

@@ -38,10 +38,14 @@ parts:
     - file: notebooks/advanced/merge_gcm_runs_and_visualize
     - file: notebooks/advanced/dynamical_spinup
 
+  - caption: RGI-TOPO
+    chapters:
+    - file: notebooks/others/rgitopo_rgi6
+    - file: notebooks/others/rgitopo_rgi7
+
   - caption: Related to OGGM
     chapters:
     - file: notebooks/others/holoviz_intro
-    - file: notebooks/others/dem_comparison
 
   - caption: In (re-)construction
     chapters:

notebooks/10minutes/dynamical_spinup.ipynb

@@ -11,7 +11,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "In this example, we highlight a recent addition to OGGM: a dynamical spinup during the historical period."
+    "In this example, we highlight a recent addition to OGGM: a dynamical spinup during the historical period. We explain why this was added and how it works."
    ]
   },
   {
@@ -28,7 +28,7 @@
     "\n",
     "# Locals\n",
     "import oggm.cfg as cfg\n",
-    "from oggm import utils, workflow, tasks\n",
+    "from oggm import utils, workflow, tasks, DEFAULT_BASE_URL\n",
     "from oggm.shop import gcm_climate"
    ]
   },
@@ -63,14 +63,14 @@
     "cfg.PATHS['working_dir'] = utils.gettempdir('OGGM_gcm_run', reset=True)\n",
     "\n",
     "# RGI glacier \n",
-    "rgi_ids = utils.get_rgi_glacier_entities(['RGI60-11.00897'])"
+    "rgi_ids = 'RGI60-11.00897'"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "To fetch the preprocessed directories including spinup, we have to tell OGGM where to find them:"
+    "To fetch the preprocessed directories including spinup, we have to tell OGGM where to find them. The default URL contains the runs with spinup:"
    ]
   },
   {
@@ -81,10 +81,7 @@
    },
    "outputs": [],
    "source": [
-    "# Currently only available with border 160\n",
-    "cfg.PARAMS['border'] = 160 \n",
-    "base_url = 'https://cluster.klima.uni-bremen.de/~oggm/gdirs/oggm_v1.6/L3-L5_files/2023.1/elev_bands/W5E5_spinup'\n",
-    "gdirs = workflow.init_glacier_directories(rgi_ids, from_prepro_level=5, prepro_base_url=base_url)"
+    "gdirs = workflow.init_glacier_directories(rgi_ids, from_prepro_level=5, prepro_base_url=DEFAULT_BASE_URL)"
    ]
   },
   {
@@ -100,7 +97,7 @@
     "tags": []
    },
    "source": [
-    "These directories are very similar to the default ones (same input data, same baseline climate...). In addition, they include a new historical simulation run with a dynamic spinup. Let's open it and compare it to the old historical run without a spinup."
+    "These directories are very similar to the \"old\" ones (same input data, same baseline climate...). But in addition, they include a new historical simulation run with a dynamic spinup. Let's open it and compare it to the old historical run without a spinup:"
    ]
   },
   {
@@ -133,6 +130,13 @@
     "plt.legend();"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Let's have a look at what happens here."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -164,16 +168,14 @@
    "source": [
     "We achieve this by searching for a glacier state in 1979 which evolves to match the area at the RGI date. Therefore, you can see that the areas around the RGI date (2003) are very close.\n",
     "\n",
-    "However, the volumes show some difference around the RGI date, as it was not tried to match the values. The reason is that the current workflow can match area OR volume. By default, we decided to match area as it is a direct observation (from the RGI outlines), in contrast to a model guess for the volume (e.g. [Farinotti et al. 2019](https://www.nature.com/articles/s41561-019-0300-3)).\n",
-    "\n",
-    "Another advantage of the dynamic spinup is that we do not expect any problems due to an 'initial shock' at the start of our model run."
+    "However, the volumes show some difference around the RGI date, as we did not attempt to match the volume. The current workflow can match area OR volume and, by default, we decided to match area as it is a direct observation (from the RGI outlines), in contrast to a model guess for the volume (e.g. [Farinotti et al. 2019](https://www.nature.com/articles/s41561-019-0300-3))."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Dynamically recalibrated *melt_f*"
+    "### Dynamical spinup also uses a dynamically recalibrated melt factor *melt_f*"
    ]
   },
   {
@@ -182,15 +184,17 @@
    "source": [
     "The second big difference is not directly visible, but during the dynamic spinup, we check that the dynamically modelled geodetic mass balance fits the given observations from [Hugonnet et al. 2021](https://www.nature.com/articles/s41586-021-03436-z). To achieve this, we use the *melt_f* of the mass balance as a tuning variable.\n",
     "\n",
-    "We need this step because the initial mass balance model calibration (see this [tutorial](../advanced/massbalance_calibration.ipynb)) assumes constant glacier surface geometry, defined by the RGI outline. However, the observed geodetic mass balance also contains surface geometry changes, which we only can consider during a dynamic model run.\n",
+    "We need this step because the initial mass balance model calibration (see this [tutorial](../advanced/massbalance_calibration.ipynb)) assumes constant glacier surface geometry, as defined by the RGI outline. However, the observed geodetic mass balance also contains surface geometry changes, which we only can consider during a dynamic model run.\n",
     "\n",
-    "Let's check that the dynamic geodetic mass balance fits inside the given observations:"
+    "Let's check that the dynamically calibrated geodetic mass balance fits the given observations:"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "metadata": {
+    "tags": []
+   },
    "outputs": [],
    "source": [
     "gdir = gdirs[0]\n",
@@ -221,6 +225,38 @@
     "print(f\"Dynamically calibrated melt_f:                 {gdir.read_json('mb_calib')['melt_f']:.1f}                 kg m-2 day-1 °C-1\")"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "This fits quite well! The default in OGGM is to try to match the observations within 20% of the reported error by Hugonnet et al. This is a model option, and can be changed at wish."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Dynamical spinup addresses \"initial shock\" problems"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "This is not really visible in the plots above, but the \"old\" method of initialisation in OGGM had another issue. It assumed dynamical steady state at the begining of the simulation (the RGI date), which was required by the bed inversion process. This could lead to artifacts (mainly in the glacier length and area, as well as velocities) during the first few years of the simulation. The dynamical spinup addresses this issue by starting the simulation in 1979."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "# TODO: showcase the velocities in the fl diagnostics"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -232,7 +268,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "We recommend that you use the provided preprocessed directories for your analysis. However, if you want to learn more about how the dynamic spinup works in detail or if you plan to use it in your workflow, maybe with different data, you should check out the more comprehensive tutorial ['Dynamic spinup and dynamic melt_f calibration for past simulations'](../advanced/dynamical_spinup.ipynb). And do not hesitate to [reach out to us](https://oggm.org/community/)!"
+    "We recommend that you use the provided preprocessed directories for your analysis. However, if you want to learn more about how the dynamic spinup works in detail or if you plan to use it in your workflow, maybe with different data, you should check out the more comprehensive tutorial: [Dynamic spinup and dynamic melt_f calibration for past simulations](../advanced/dynamical_spinup.ipynb). And do not hesitate to [reach out](https://oggm.org/community) if you have any questions!"
    ]
   },
   {
@@ -241,7 +277,7 @@
    "source": [
     "## What's next?\n",
     "\n",
-    "- Look at the more comprehensive tutorial ['Dynamic spinup and dynamic melt_f calibration for past simulations'](../advanced/dynamical_spinup.ipynb)\n",
+    "- Look at the more comprehensive tutorial [Dynamic spinup and dynamic melt_f calibration for past simulations](../advanced/dynamical_spinup.ipynb)\n",
     "- return to the [OGGM documentation](https://docs.oggm.org)\n",
     "- back to the [table of contents](../welcome.ipynb)"
    ]
@@ -264,7 +300,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.6"
+   "version": "3.10.9"
   },
   "latex_envs": {
    "LaTeX_envs_menu_present": true,

notebooks/10minutes/elevation_bands_vs_centerlines.ipynb

@@ -79,7 +79,7 @@
     "cfg.PATHS['working_dir'] = utils.gettempdir(dirname='OGGM-centerlines', reset=True)\n",
     "\n",
     "# We start from prepro level 3 with all data ready - note the url here\n",
-    "base_url = 'https://cluster.klima.uni-bremen.de/~oggm/gdirs/oggm_v1.6/L3-L5_files/2023.1/centerlines/W5E5/'\n",
+    "base_url = 'https://cluster.klima.uni-bremen.de/~oggm/gdirs/oggm_v1.6/L3-L5_files/2023.3/centerlines/W5E5/'\n",
     "gdirs = workflow.init_glacier_directories(rgi_ids, from_prepro_level=3, prepro_border=80, prepro_base_url=base_url)\n",
     "gdir_cl = gdirs[0]\n",
     "gdir_cl"
@@ -88,15 +88,17 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "metadata": {
+    "tags": []
+   },
    "outputs": [],
    "source": [
     "# Elevation band flowline\n",
     "# New working directory\n",
     "cfg.PATHS['working_dir'] = utils.gettempdir(dirname='OGGM-elevbands', reset=True)\n",
     "\n",
     "# Note the new url\n",
-    "base_url = 'https://cluster.klima.uni-bremen.de/~oggm/gdirs/oggm_v1.6/L3-L5_files/2023.1/elev_bands/W5E5/'\n",
+    "base_url = 'https://cluster.klima.uni-bremen.de/~oggm/gdirs/oggm_v1.6/L3-L5_files/2023.3/elev_bands/W5E5/'\n",
     "gdirs = workflow.init_glacier_directories(rgi_ids, from_prepro_level=3, prepro_border=80, prepro_base_url=base_url)\n",
     "gdir_eb = gdirs[0]\n",
     "gdir_eb"
@@ -113,7 +115,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "we wrote a bit of information about the differences between these to. First, go to the [glacier flowlines](https://docs.oggm.org/en/stable/flowlines.html#glacier-flowlines) documentation where you can find detailed information about the two flowline types and also a [guideline when to use which flowline method](https://docs.oggm.org/en/stable/flowlines.html#pros-and-cons-of-both-methods).\n",
+    "We wrote a bit of information about the differences between these to. First, go to the [glacier flowlines](https://docs.oggm.org/en/stable/flowlines.html#glacier-flowlines) documentation where you can find detailed information about the two flowline types and also a [guideline when to use which flowline method](https://docs.oggm.org/en/stable/flowlines.html#pros-and-cons-of-both-methods).\n",
     "\n",
     "The examples below illustrate these differences, without much text for now because of lack of time:"
    ]
@@ -128,7 +130,9 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "metadata": {
+    "tags": []
+   },
    "outputs": [],
    "source": [
     "fls_cl = gdir_cl.read_pickle('model_flowlines')\n",
@@ -138,7 +142,9 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "metadata": {
+    "tags": []
+   },
    "outputs": [],
    "source": [
     "f, (ax1, ax2) = plt.subplots(2, 1, figsize=(10, 14), sharex=True, sharey=True)\n",
@@ -210,7 +216,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "For the ice dynamics simulations, the commands are exactly the same as well. The only difference is that centerlines require the more flexible \"FluxBased\" numerical model, while the elevation bands can also use the more robust \"SemiImplicit\" one. The runs are considerabily faster with the elevation bands flowlines."
+    "For the ice dynamics simulations, the commands are exactly the same as well. The only difference is that centerlines require the more flexible \"FluxBased\" numerical model, while the elevation bands can also use the more robust \"SemiImplicit\" one. **The runs are considerabily faster with the elevation bands flowlines.**"
    ]
   },
   {
@@ -392,7 +398,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "We are however working on a [better representation of retreating glaciers](https://github.com/OGGM/oggm/pull/1490) for outreach. Stay tuned!"
+    "We are however working on a better representation of retreating glaciers for outreach. Have a look at [this tutorial](../beginner/distribute_flowline.ipynb)!"
    ]
   },
   {
@@ -439,7 +445,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.6"
+   "version": "3.10.9"
   },
   "latex_envs": {
    "LaTeX_envs_menu_present": true,

notebooks/10minutes/machine_learning.ipynb

@@ -64,7 +64,7 @@
     "# Local working directory (where OGGM will write its output)\n",
     "cfg.PATHS['working_dir'] = utils.gettempdir('OGGM_Toy_Thickness_Model')\n",
     "# We use the directories with the shop data in it: \"W5E5_w_data\"\n",
-    "base_url = 'https://cluster.klima.uni-bremen.de/~oggm/gdirs/oggm_v1.6/L3-L5_files/2023.1/elev_bands/W5E5_w_data/'\n",
+    "base_url = 'https://cluster.klima.uni-bremen.de/~oggm/gdirs/oggm_v1.6/L3-L5_files/2023.3/elev_bands/W5E5_w_data/'\n",
     "gdirs = workflow.init_glacier_directories(['RGI60-01.16195'], from_prepro_level=3, prepro_base_url=base_url, prepro_border=10)"
    ]
   },
@@ -993,6 +993,13 @@
     "df_agg.plot.scatter(x='thick', y='consensus_thick', ax=ax4);\n",
     "ax4.set_xlim([-25, 220]); ax4.set_ylim([-25, 220]); ax4.set_title('Farinotti 2019');"
    ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
   }
  ],
  "metadata": {
@@ -1012,7 +1019,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.6"
+   "version": "3.10.9"
   },
   "toc": {
    "base_numbering": 1,