Further doc updates (#1731)

* Further doc updates * doc overload * Small think
OGGM · Aug 23, 2024 · 00552b6 · 00552b6
1 parent 280141b
commit 00552b6
Show file tree

Hide file tree

Showing 28 changed files with 205 additions and 120 deletions.
diff --git a/README.rst b/README.rst
@@ -56,8 +56,8 @@ About
         :target: https://www.geosci-model-dev.net/12/909/2019/
         :alt: GMD Paper
 
-    .. image:: https://zenodo.org/badge/43965645.svg
-        :target: https://zenodo.org/badge/latestdoi/43965645
+    .. image:: https://img.shields.io/badge/DOI-10.5281%2Fzenodo.597193-blue.svg
+        :target: https://zenodo.org/doi/10.5281/zenodo.597193
         :alt: Zenodo
 
 :Tests:

diff --git a/docs/api.rst b/docs/api.rst
@@ -1,6 +1,6 @@
-################################
-List of OGGM functions and tasks
-################################
+######################
+List of OGGM functions
+######################
 
 .. currentmodule:: oggm
 
@@ -73,28 +73,42 @@ Input/Output
     global_tasks.compile_climate_statistics
     global_tasks.compile_ela
 
+.. _apishop:
+
 OGGM Shop
 =========
 
 .. autosummary::
     :toctree: generated/
     :nosignatures:
 
+    shop.bedtopo.add_consensus_thickness
+    shop.bedtopo.compile_consensus_statistics
+    shop.cook23.cook23_to_gdir
+    shop.cook23.compile_cook23_statistics
     shop.cru.get_cru_file
     shop.cru.process_cru_data
     shop.cru.process_dummy_cru_file
     shop.ecmwf.get_ecmwf_file
     shop.ecmwf.process_ecmwf_data
     shop.histalp.get_histalp_file
     shop.histalp.process_histalp_data
-    shop.gcm_climate.process_gcm_data
-    shop.gcm_climate.process_cesm_data
-    shop.gcm_climate.process_cmip_data
-    shop.bedtopo.add_consensus_thickness
+    shop.hugonnet_maps.hugonnet_to_gdir
+    shop.hugonnet_maps.compile_hugonnet_statistics
     shop.its_live.velocity_to_gdir
+    shop.its_live.compile_itslive_statistics
+    shop.millan22.thickness_to_gdir
+    shop.millan22.velocity_to_gdir
+    shop.millan22.compile_millan_statistics
     shop.rgitopo.init_glacier_directories_from_rgitopo
     shop.rgitopo.select_dem_from_dir
     shop.rgitopo.dem_quality_check
+    shop.gcm_climate.process_gcm_data
+    shop.gcm_climate.process_monthly_isimip_data
+    shop.gcm_climate.process_cesm_data
+    shop.gcm_climate.process_cmip_data
+    shop.gcm_climate.process_lmr_data
+    shop.gcm_climate.process_modera_data
 
 .. _apientitytasks:
 
@@ -305,7 +319,7 @@ folder won't erase its content:
     os.listdir(gdir.dir)  # the directory still contains the data
 
 For more information about how to use GlacierDirectories, visit our
-`tutorial on the topic <https://oggm.org/tutorials/master/notebooks/store_and_compress_glacierdirs.html>`_.
+`tutorial on the topic <https://tutorials.oggm.org/master/notebooks/tutorials/store_and_compress_glacierdirs.html>`_.
 
 
 .. include:: _generated/basenames.txt

diff --git a/docs/assets.rst b/docs/assets.rst
@@ -10,6 +10,11 @@ Shapefiles of glacier centerlines, flowlines and widths
 These variables are a standard output of OGGM, and can be useful to many.
 You will find the files here: https://cluster.klima.uni-bremen.de/~oggm/gdirs/oggm_v1.6/L1-L2_files/centerlines/RGI62/b_010/L2/summary
 
+.. note::
+
+  Note that centerlines computed by OGGM are now a standard product for
+  RGI version 7! Check out the `RGI User Guide <https://www.glims.org/rgi_user_guide>`_
+
 The following files are available:
 
 - ``centerlines``: the geometrical centerlines

diff --git a/docs/citing-oggm.rst b/docs/citing-oggm.rst
@@ -52,7 +52,7 @@ the `Zenodo citation`_ for this purpose. An example BibTeX entry::
     url          = {https://doi.org/10.5281/zenodo.5327634}
     }
 
-.. _Zenodo citation: https://zenodo.org/badge/latestdoi/43965645
+.. _Zenodo citation: https://zenodo.org/doi/10.5281/zenodo.597193
 
 Logo
 ----

diff --git a/docs/climate-data.rst b/docs/climate-data.rst
@@ -69,6 +69,23 @@ and Implications for Our Perception of the Land Surface. Bulletin of the America
    https://doi:10.5194/gmd-12-3055-2019
 
 
+GCM data
+~~~~~~~~
+
+On of the main applications is to use climate model output to drive the mass balance model. In
+this case we still rely on gridded observations (e.g. W5E5) for the reference
+climatology and apply the GCM anomalies computed from a preselected reference
+period. This method is often called the
+`delta method <http://www.ciesin.org/documents/Downscaling_CLEARED_000.pdf>`_.
+
+Visit our online tutorials to see how this can be done
+(`OGGM run with GCM tutorial <https://tutorials.oggm.org/master/notebooks/10minutes/run_with_gcm.html>`_).
+
+Paleo data
+~~~~~~~~~~
+
+Check out :ref:`apishop` for the latest fancy datasets.
+
 CRU
 ~~~
 
@@ -174,15 +191,3 @@ Any other climate dataset
 It is fairly easy to force OGGM with other datasets too. Recent publications have used
 plenty of options, from ERA5-Land to regional reanalyses or more.
 
-
-GCM data
-~~~~~~~~
-
-OGGM can also use climate model output to drive the mass balance model. In
-this case we still rely on gridded observations (e.g. W5E5) for the reference
-climatology and apply the GCM anomalies computed from a preselected reference
-period. This method is often called the
-`delta method <http://www.ciesin.org/documents/Downscaling_CLEARED_000.pdf>`_.
-
-Visit our online tutorials to see how this can be done
-(`OGGM run with GCM tutorial <https://oggm.org/tutorials/master/notebooks/run_with_gcm.html>`_).
diff --git a/docs/download-projections.rst b/docs/download-projections.rst
@@ -1,8 +1,8 @@
 OGGM global glacier projections
 ===============================
 
-.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.8286065.svg
-   :target: https://doi.org/10.5281/zenodo.8286065
+.. image:: https://img.shields.io/badge/DOI-10.5281%2Fzenodo.8286064-blue.svg
+   :target: https://doi.org/10.5281/zenodo.8286064
 
 |
 
@@ -15,6 +15,8 @@ A detailed description of the experimental-setup, information on the data
 structure, analysis of the data and a brief comparison to `Rounce et al. (2023) <https://www.science.org/doi/10.1126/science.abo1324>`_
 together with the analysis jupyter notebooks can be found in the
 `OGGM/oggm-standard-projections-csv-files repository <https://github.com/OGGM/oggm-standard-projections-csv-files>`_.
+Data for the CMIP6 GCMs until 2100 is also described in
+`Zekollari et al. (2024) <https://doi.org/10.5194/egusphere-2024-1013>`_.
 
 These projections use :ref:`eb-flowlines`, make use of the :ref:`dynamic-spinup`,
 the new "informed 3-step" :ref:`mb-calib` method for each glacier with geodetic data,
@@ -56,6 +58,7 @@ If you use these data (either aggregated csv or the per-glacier netcdf files), p
 *Lilian Schuster, Patrick Schmitt, Anouk Vlug, & Fabien Maussion. (2023). OGGM/oggm-standard-projections-csv-files: v1.0 (v1.0). Zenodo. https://doi.org/10.5281/zenodo.8286065*
 
 In addition, please cite OGGM (Maussion et al., 2019) and the specific OGGM version as
-specified in the OGGM documentation: :ref:`citing-oggm`.
+specified in the OGGM documentation: :ref:`citing-oggm`. The data for the CMIP6 GCMs
+until 2100 is also described in `Zekollari et al. (2024) <https://doi.org/10.5194/egusphere-2024-1013>`_.
 
 We also recommend to refer to the CMIP option that you are using (references are listed in the data repository).
diff --git a/docs/dynamic-spinup.rst b/docs/dynamic-spinup.rst
@@ -29,10 +29,10 @@ following schematic for a description of the standard steps in the spinup.
    Default dynamic calibration workflow (adapted from Aguayo et al. 2023, in prep.)
 
 We offer pre-processed directories including a dynamic spinup run. You can
-check out this `10 minute tutorial <https://oggm.org/tutorials/stable/notebooks/10minutes/dynamical_spinup.html>`_
+check out this `10 minute tutorial <https://tutorials.oggm.org/stable/notebooks/10minutes/dynamical_spinup.html>`_
 for a short introduction to the spinup functions and how to use the
 pre-processed directories.
 
 If you are looking for an in-depth explanation of the dynamic functions you
 should check out this
-`advanced tutorial <https://oggm.org/tutorials/stable/notebooks/advanced/dynamical_spinup.html>`_.
+`advanced tutorial <https://tutorials.oggm.org/master/notebooks/tutorials/dynamical_spinup.html>`_.
diff --git a/docs/faq.rst b/docs/faq.rst
@@ -78,11 +78,11 @@ progress.
 I have a question about OGGM, can we talk about it per email/phone?
 -------------------------------------------------------------------
 
-Thanks for your interest in OGGM! Usually, we prefer to keep 
+Thanks for your interest in OGGM! Usually, we prefer to keep
 usage questions on `github issues <https://github.com/OGGM/oggm/issues>`_
 so that everybody can learn from all questions and their answers.
-You can also join our Slack discussion channel if you want a 
-more interactive forum. Keep in touch with us per email if you'd 
+You can also join our Slack discussion channel if you want a
+more interactive forum. Keep in touch with us per email if you'd
 like to join, we are a very open community!
 
 
@@ -227,7 +227,7 @@ We recommend to increase the glacier map in this case, by setting
 `cfg.PARAMS['border']` to a larger value, e.g. 100 or 200. The larger this
 value, the larger the glacier can grow (the drawback is that simulations
 become slower and hungrier in memory because the number of grid points
-increases as well). We do not recommend to go larger than 250. However, 
+increases as well). We do not recommend to go larger than 250. However,
 for these cases it is likely that something else is wrong in your workflow
 or OGGM itself.
 
@@ -256,7 +256,7 @@ encourage you to contact the `GLIMS core team <https://www.glims.org/maps/contac
 to let them know how your inventory improves the glacier digitalization compared to the
 current RGI version. If you want to see an example on how to give OGGM a different shapefile than RGI,
 have a look to this
-`tutorial <https://oggm.org/tutorials/stable/notebooks/use_your_own_inventory.html>`_!
+`tutorial <https://tutorials.oggm.org/master/notebooks/tutorials/use_your_own_inventory.html>`_!
 
 .. _pitfalls.numerics:
 

diff --git a/docs/flowlines.rst b/docs/flowlines.rst
@@ -212,7 +212,7 @@ elevation-band and geometrical flowlines.
 
 Both flowline types are available for download and for use in the OGGM
 framework. The plot below has been obtained from the
-`centerlines versus elevation-band flowlines comparison tutorial <https://oggm.org/tutorials/stable/notebooks/10minutes/elevation_bands_vs_centerlines.html>`_.
+`centerlines versus elevation-band flowlines comparison tutorial <https://tutorials.oggm.org/master/notebooks/tutorials/elevation_bands_vs_centerlines.html>`_.
 
 
 .. figure:: _static/eb_vs_cl.png

diff --git a/docs/frontal-ablation.rst b/docs/frontal-ablation.rst
@@ -5,7 +5,7 @@ OGGM has a simple parameterisation for frontal ablation that can be used
 during the ice volume estimation and for dynamical runs. These features
 are still in the testing phase and are switched off per default.
 
-Visit our `tutorials <https://oggm.org/tutorials>`_
+Visit our `tutorials <https://tutorials.oggm.org>`_
 if you are interested and would like to give them a go.
 
 .. figure:: https://oggm.org/img/blog/calving_param/calving_ex.png

diff --git a/docs/geometry-evolution.rst b/docs/geometry-evolution.rst
@@ -7,28 +7,19 @@ forcing computed with the :doc:`mass-balance`. They are also in charge of report
 diagnostic variables such as length, area, volume. Depending on the model's complexity,
 they can also report about ice velocity, ice thickness, etc.
 
-Currently, OGGM has three operational geometry evolution models:
+Currently, OGGM has four geometry evolution models:
 
 .. toctree::
     :maxdepth: 1
+    :hidden:
 
     ice-dynamics.rst
+    igm.rst
     mass-redistribution.rst
     OGGM-VAS (volume-area scaling) <https://github.com/OGGM/oggm-vas>
 
-`OGGM-VAS <https://github.com/OGGM/oggm-vas>`_ is a complete python re-write of
-`Ben Marzeion's 2012 model <https://tc.copernicus.org/articles/6/1295/2012/>`_.
-It should be equivalent to the original matlab model,
-but follows the OGGM syntax very closely (and uses OGGM for data pre- and
-post-processing). See Moritz Oberrauch's
-`thesis <https://diglib.uibk.ac.at/ulbtirolhs/content/titleinfo/5878449>`_
-for more information.
 
-The :doc:`mass-redistribution` is an implementation of the "delta-h" model
-by `Huss & Hock (2015) <https://www.frontiersin.org/articles/10.3389/feart.2015.00054/full>`_
-and `Rounce et al., (2020) <https://doi.org/10.3389/feart.2019.00331>`_.
-It works quite well for short simulations of the glacier retreat phase.
-
-The default geometry evolution model in OGGM is the :doc:`ice-dynamics`.
-We also have a `distributed SIA model <https://github.com/OGGM/oggm/blob/master/oggm/core/sia2d.py>`_
-to play around, but nothing operational yet.
+* :doc:`ice-dynamics`: the default!
+* :doc:`igm`: the future!
+* :doc:`mass-redistribution`: an implementation of the "delta-h" model by `Huss & Hock (2015) <https://www.frontiersin.org/articles/10.3389/feart.2015.00054/full>`_. It works quite well for short simulations of the glacier retreat phase.
+* `OGGM-VAS (volume-area scaling) <https://github.com/OGGM/oggm-vas>`_: a python re-write of `Ben Marzeion's 2012 model <https://tc.copernicus.org/articles/6/1295/2012/>`_. See Moritz Oberrauch's `thesis <https://diglib.uibk.ac.at/ulbtirolhs/content/titleinfo/5878449>`_ for more information.
diff --git a/docs/getting-started.rst b/docs/getting-started.rst
@@ -19,6 +19,10 @@ through several examples to get you started.
    Did you know that you can try OGGM in your browser before installing it
    on your computer? Visit :doc:`cloud` for more information.
 
+   Did you know that we provide standard projections for all glaciers in the
+   world, and that you may not have to run OGGM for your use case?
+   Visit :doc:`download-projections` for more information.
+
 .. _system-settings:
 
 First step: system settings for input data
@@ -144,4 +148,4 @@ OGGM tutorials
 
 Refer to our `tutorials`_ for real-world applications!
 
-.. _tutorials: https://oggm.org/tutorials
+.. _tutorials: https://tutorials.oggm.org
diff --git a/docs/igm.rst b/docs/igm.rst
@@ -0,0 +1,10 @@
+Instructed Glacier Model (IGM)
+==============================
+
+Since v1.6.2, OGGM comes with a new interface able to call the
+`Instructed Glacier Model (IGM) <https://github.com/jouvetg/igm>`_
+while keeping your familiar OGGM workflow. This is still very
+much experimental and under development, but we are excited to
+see where this will lead us!
+
+See `this tutorial <https://tutorials.oggm.org/master/notebooks/tutorials/ioggm.html>`_ for a sneak peak!
diff --git a/docs/index.rst b/docs/index.rst
@@ -5,30 +5,28 @@ A modular and open source glacier model
 **OGGM is a cutting-edge open source modelling framework** designed to simulate
 the past and future mass balance, volume, and geometry of glaciers worldwide.
 
-The model features several glacier evolution models, including an explicit ice
+The model features several glacier evolution models, including an flowline ice
 dynamics module accounting for glacier geometry and frontal ablation.
-**With an unwavering commitment to using publicly available data for calibration
-and validation, OGGM is a reliable and readily applicable tool for studying glaciers**.
+**WOGGM is a reliable and readily applicable tool for studying glaciers**.
 
 OGGM is also a modular platform that supports novel modelling workflows,
-**encouraging researchers to create unique models and analyses for their research**.
+**encouraging researchers to create unique model chains and analyses for their research**.
 Our framework is designed to be flexible and adaptable, making it an
 ideal tool for a wide range of applications in glaciology and related fields.
 
-.. warning::
-
-   OGGM v1.6 is a substantial change to v1.5.3. Among other developments,
-   the mass balance calibration has substantially improved. In order to
-   allow easier and faster developments from the community in the future,
-   several variable names have changed and older workflows are not available
-   anymore. **We recommend our users to switch to 1.6 as soon as
-   possible, but only if they are at the development stage of a study.**
-   Older versions of OGGM will always be available via github and Zenodo,
-   and older documentation pages can be accessed via the interface below.
-
 **This webpage is for the software documentation: for general information about the
 OGGM project and related news, visit** `oggm.org <http://oggm.org>`_.
 
+.. admonition:: A note for new users
+
+    OGGM is well established and well documented, but it is a complex model requiring
+    background knowledge in glacier modelling and programming.
+    In our experience, many research projects can actually be completed *without*
+    running OGGM yourself: we provide a range of pre-computed glacier change projections
+    covering a wide range of scenarios and use cases. Checkout :doc:`download-projections`
+    and see if this fits your needs before diving into the model itself.
+
+
 Video presentation
 ^^^^^^^^^^^^^^^^^^
 
@@ -81,7 +79,7 @@ How to use the model, with concrete code examples and links to the tutorials.
 * :doc:`cloud`
 * :doc:`installing-oggm`
 * :doc:`getting-started`
-* `Tutorials <https://oggm.org/tutorials/stable>`_
+* `Tutorials <https://tutorials.oggm.org/stable>`_
 * :doc:`api`
 * :doc:`practicalities`
 * :doc:`faq`
@@ -94,7 +92,7 @@ How to use the model, with concrete code examples and links to the tutorials.
     cloud.rst
     installing-oggm.rst
     getting-started.rst
-    Tutorials <https://oggm.org/tutorials/stable>
+    Tutorials <https://tutorials.oggm.org/stable>
     api.rst
     practicalities.rst
     faq.rst
@@ -209,8 +207,8 @@ About
         :target: https://www.geosci-model-dev.net/12/909/2019/
         :alt: GMD Paper
 
-    .. image:: https://zenodo.org/badge/43965645.svg
-        :target: https://zenodo.org/badge/latestdoi/43965645
+    .. image:: https://img.shields.io/badge/DOI-10.5281%2Fzenodo.597193-blue.svg
+        :target: https://zenodo.org/doi/10.5281/zenodo.597193
         :alt: Zenodo
 
 :Tests:

diff --git a/docs/installing-oggm.rst b/docs/installing-oggm.rst
@@ -6,6 +6,10 @@ Installing OGGM
    Did you know that you can try OGGM in your browser before installing it
    on your computer? Visit :doc:`cloud` for more information.
 
+   Did you know that we provide standard projections for all glaciers in the
+   world, and that you may not have to run OGGM for your use case?
+   Visit :doc:`download-projections` for more information.
+
 OGGM itself is a pure python package, but it has several dependencies which
 are not trivial to install. The instructions below provide all the required
 details and should work on Linux and Mac OS. See :ref:`install-troubleshooting`
-Original file line number
+Diff line change
@@ Expand Up @@
         url          = {https://doi.org/10.5281/zenodo.5327634}
         }
-    .. _Zenodo citation: https://zenodo.org/badge/latestdoi/43965645
+    .. _Zenodo citation: https://zenodo.org/doi/10.5281/zenodo.597193
     Logo
     ----
@@ Expand Down @@