From 07c1ead0b37adaa2548e387a2d2d87f997b681db Mon Sep 17 00:00:00 2001 From: Fabien Maussion Date: Sun, 25 Aug 2024 12:19:13 +0100 Subject: [PATCH] More docs (#1739) --- README.rst | 2 -- docs/cloud.rst | 76 +++------------------------------------------- docs/faq.rst | 2 +- docs/index.rst | 21 ++++++------- docs/whats-new.rst | 27 ++++++++++------ 5 files changed, 34 insertions(+), 94 deletions(-) diff --git a/README.rst b/README.rst index 2963d2521..333ab2d21 100644 --- a/README.rst +++ b/README.rst @@ -29,14 +29,12 @@ Get in touch - View the source code `on GitHub`_. - Report bugs or share your ideas on the `issue tracker`_. - Improve the model by submitting a `pull request`_. -- Follow us on `Twitter`_. - Or you can always send us an `e-mail`_ the good old way. .. _e-mail: info@oggm.org .. _on GitHub: https://github.com/OGGM/oggm .. _issue tracker: https://github.com/OGGM/oggm/issues .. _pull request: https://github.com/OGGM/oggm/pulls -.. _Twitter: https://twitter.com/OGGM_org About diff --git a/docs/cloud.rst b/docs/cloud.rst index 0e03bb0a0..e73d9c929 100644 --- a/docs/cloud.rst +++ b/docs/cloud.rst @@ -5,44 +5,6 @@ You can try OGGM in your web browser **without having to install anything**! This is the best way to run the tutorials or even do exploratory research to test the model, before you move on to more serious computations. -We provide two solutions to try OGGM online, without local installation. - -The simplest and quickest solution is :ref:`oggm-binder` (no registration necessary). -:ref:`oggm-hub` is much better for more serious work and requires to send us -an email. If you are unsure, have a look at :ref:`hub-binder`! - -.. _oggm-binder: - -OGGM-Binder ------------ - -.. image:: https://mybinder.org/static/logo.svg - :width: 20% - :align: right - :target: https://mybinder.org/v2/gh/OGGM/tutorials/stable?labpath=notebooks%2Fwelcome.ipynb - -Thanks to the fantastic `MyBinder `_ service, our OGGM-Binder -test space is available to anyone, with no registration necessary. -Using it is very simple. Just click on the link below to get you started! - -.. figure:: https://img.shields.io/badge/Launch-OGGM%20tutorials-579ACA.svg?style=popout&logo=data:image/png;base64,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 - :target: https://mybinder.org/v2/gh/OGGM/tutorials/stable?labpath=notebooks%2Fwelcome.ipynb - -If you are new to the Jupyter Notebooks or to JupyterLab, you will probably -find this `introduction to interactive notebooks`_ quite useful. - -.. _introduction to interactive notebooks: http://edu.oggm.org/en/latest/notebooks_howto.html - -.. important:: - - Binder environments are only temporary! Perfect for trying and learning, - but not suitable for development work. Remember to download your notebooks - at the end of a session if you want to keep them for later. - - **If you want to use OGGM for more serious and permanent work**, we recommend to - use :ref:`oggm-hub` or :doc:`install OGGM on your computer `. - - .. _oggm-hub: OGGM-Hub @@ -54,10 +16,10 @@ OGGM-Hub :target: https://hub.oggm.org `hub.oggm.org`_ is our own `JupyterHub `_ deployment -of OGGM on our servers in Bremen. It works similarly to MyBinder +of OGGM on our servers in Bremen. It works similarly to MyBinder or Google Colab, but it is bound to a username (you'll need an account) and is therefore persistent (your files are saved between sessions). It also gives you access to more computing -resources than MyBinder. +resources than most free services. .. figure:: https://img.shields.io/badge/Launch-OGGM%20hub-F37524.svg?style=popout&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAlCAYAAAAjt+tHAAAACXBIWXMAABcSAAAXEgFnn9JSAAAAB3RJTUUH4wENDyoWA+0MpQAAAAZiS0dEAP8A/wD/oL2nkwAACE5JREFUWMO9WAtU1FUaH1BTQVJJKx+4BxDEgWEGFIzIVUMzPVBauYng8Jr3AxxAHObBvP6MinIUJdLwrTwqzXzkWVMSLW3N7bTrtmvpno7l6WEb7snMB6DffvfOzJ87A5a27t5zvjP/x/1/v9/9Xve7IxA84BFXYBMIi+zBIoUrOCLbxD9PVLgE/9MRtdhKfycW2gfGFzkMCFgXV2CPEStdAyQqLui/BhiXU3lP8xJkzkclSu77SapqSEYRyZ2bE+TO0b8JdGKRozeRRZWDcHXDEuWuEQkyx8gkJTcirtA2VCh3DvJYwJGT7AUngu9PDJ9nGH5/yM9oBU+X1fK3sXlVQyQKVyyu5lkELcUVviZRcHvECtc+BNiNz+vFSq5cWGifm6Sq/oghcE2s4GggRC+23Bv2hHwbfz1eankIFachkBsB/8mu7F4EyZyNzrNGUMsU2H4dfMxCI2v+cAQuRyWX+lSu5HrkbgSU3GcxeVWpgujZQd74uDs4+pS/jpZaxiD45kCFaHpIlDspaKp2JaQV10CavgYma5aDGJ/jN/RdAImvULc2Jt8WRnEIiQWGAPSZCr8oxiBrYRWRa6J8qqEW5tkbIXdlExSteQPkdbtR3oSC2lbIXr4DMq0bIb1kNU+SIXIdSdTE5FlHEoz4woDgFslc3mLhHIRA9X6rRuAUzQqY79gM2oa3wbTjCNib2/3E0eL5Xbb1MKjr98JLrq0wRbeCkmbioUskc64dm22iGRHPZ9gslSf4pLZ+yGwBTr7DghMzS1c1g2n7UbAhSFXTMbDueq+XmHYcpe9szcfAjNfEOjPK1lJr8AtSVneK5a5KksrelBUIAIASiFhUORx9fIE1+xPo37zVLRTgbsBEzDveg8bDH+Nvm3euZ77+1f0wa9l6PxJoiX9jZmX6V68iZ3/0kZI1/WS1GxZw234VvBIts+/05/CvH38G7vXjYGHeke+0DftgWukaak2fblI/hIW2CJ5AssqNvuc+7TE9BxkV66hPfwncsrMN1h04Dddu3gIyzpz/hhKyBpAoqH0dJuGCkhjrYkF7zlNac02C2AJbPGMiTLEVkLNyF9gxuHgwFDv6lyVEwM5c+BLu3LlDCXR2dcOu9rM0HlgCS7f8EeZaNvgFJV6vmVhkHyaIlzmCRDKHnvU9MVlp4ztg84L5zNr21y+g4dAZMOPKHc3vQ1atC56tk0P37dvgGx1Xr4OztR2t02MFkiEkkNnURIufwuyLInkfjOmxiSXwjLEeU+s4r8C47Qi0nvgb3Ojsgj99dgncb7wPFdvfgdHlT8MAlRDaPz/NE+jsvg0HPzoPRsYVJHs0mJ5PLanlSWAgdmDPIBZg5PdDafcRIL4ixcbZesIT4bjalbs/gPNf/0ABiLGb2/8B05eXwrDiFBisEYG+xcUT6OruggOfnAR9416o2uWxILHkktcO0rjyBWOSkkoaBmB1v2RmByNllRQSnwXI6vd+eI6u3je++O4KJNiyYIhOAqEoydw8/t2Nzptg318PT7qKqZt8cVC26RDMNr4SmA3TBNg49EM5xRJ40ckQ2P4unDx3EQKHvsUJ4UtSIEyfBAM1CXDpyrf0+c+3roN0SwWEl6SDdlMr2JuOUwKljYeoa1kCmG2/JyUxOKHI0cLWAFLTiQts+LFswxbYcOwt+P7qDxhs3TyBC5cvwnjzLBiCBEJ1YnAdbKDPf7zxEyS75kOoVgypDhkSOEFjoHjDfphRXkdT3BdrSGYK1n8uGCPSwgZhxtJ1NIrNO4/AVK4YQvUiyKjNg8N//4BPOTLmvaKBocWTqBUilk2Dn25eg8tXOyipEF0ijCqbDvkNG4FrPQnKdXvozskHocL1DTYyIkGU1Bo0ocCWxhJ4smQVqNe/DbKNm2FMeQYM1opAII+FREcWtJ37kCeg2lkFw0omUwIkFox7VsPWk3sgWBFHn4Xpk2GKU0FjgdQVP/8ruSPYK47z7APZxhB8cJHPBJUb5pjrYYa7DAZphVTZw6gsSDEBptbkwLZTb8HBs8dAZM/0AnlkiF4C0aaZNDjDvFaINM6F3LpGDMCGwEJkw2YlxLsNc/2xHuj9GhCNE6JKFlHz+wAICZL3jxhSYUTpFB6IJ4D3IdpEhpAYRi5Jh6QyA6RqatgN6Sa6fZZ/B1xgexzN/2kPCTfEq5fBY7rZqIgo7QEjQUeEBe8tnvmjtFkgUlqoPqazasbq+5jnQJHr6VYlai4Id8RMLA6drCsSkMQoXSZVSFb0y6A9riAyWvcciNRm1LOc7a6uYPBl+a1+TuV6z8a0sHIATihmXUFIiFVWiNLmQ7g+nbok0CKsycn7ofpUiNRKQay2+oN7fL9iXI5psKcDr/L1hMqe3kDuHIwTDaQksySSVE60hhGiNIXwuG4OgqQgWAJKPISgEPBHdNNhnHYhCNVL6fxJKlYHXf1ezDh6Stp0oC2gK1Y42XPeQDTTy+irgJacEHHhyqrQtCYkVAFCTSlKGd5XQqLaAhKVw8/fjOkPSZTVkT6Msdl9HPUmMt3qw/PLgnCrFmIPtw3j4lbvvt8dAOTuE9gbdK9G5pjC+zr89BqhmSUCac0Wpk13vIAKLt/vqchb6/+Mi5odmq3lT8dohfs4I05X98fVr2LjAQvWUVR8GEl1BAKSediAnsccr4/Nt6YTFRmla3l1v1tkur8zKnYsKQj0lx4/Vt9C8Kf4CZNzQ4c+b4gam22Mf2iuLkIQ8/wA9nvZqq140FX/9v8E0P+5GDy3EbybEMA60RSHBYu+TDL0/dFM1QP4uyPDd1QLIxtVKuZuE66+QyznXhb8v0bkYrPf/ag/VIwYLzWHsdXzQYz/ABScQI1BUjcgAAAAAElFTkSuQmCC :target: https://hub.oggm.org @@ -98,11 +60,9 @@ and if not it will download it for you and the other users. Welcome screen of https://hub.oggm.org -When logging in, you can choose between two environments: - -- ``oggm_latest``, with the latest OGGM installed from master (updated every few weeks) -- ``oggm_vXXX`` (starting from OGGM v1.4), which are environments made with a pinned OGGM version - +When logging in, you can choose between several environments. We suggest to +pick the latest OGGM version if you are not sure, and in general stick to +whatever worked for you last time. These environments are restarted each time you log-out and log-in again (don't worry, your ``HOME`` and all it contains won't be erased!). This means that while you *can* install things in the root tree (e.g. with ``pip install``), @@ -152,29 +112,3 @@ your hub: The full set of rules used by `nbgitpuller` while pulling is explained `here `_. - -.. _hub-binder: - -Hub or Binder? --------------- - -Which is best for you? Here is a quick comparison. - -.. list-table:: Binder vs. OGGM-Hub - :widths: 20 20 - :header-rows: 1 - - * - Binder - - OGGM-Hub - * - Files not saved between sessions - - Files saved between sessions - * - Limited computational resources - - Dedicated processing and space on OGGM servers - * - Use cases: quick tests and demos - - Use cases: deeper explorations and teaching - * - Can be slow to start / unreliable - - Reliable (with due caution!) - * - No registration required - - Contact us to register - * - Free! - - Free! diff --git a/docs/faq.rst b/docs/faq.rst index 3bb670605..0b3858797 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -82,7 +82,7 @@ Thanks for your interest in OGGM! Usually, we prefer to keep usage questions on `github 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 +more interactive forum. Keep in touch with us if you'd like to join, we are a very open community! diff --git a/docs/index.rst b/docs/index.rst index 6e2bfc69a..9023b3df0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -2,20 +2,21 @@ 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. +**OGGM is an open source modelling framework** designed to simulate +the past and future mass balance, volume, and geometry of all glaciers worldwide. -The model features several glacier evolution models, including an flowline ice -dynamics module accounting for glacier geometry and frontal ablation. -**WOGGM is a reliable and readily applicable tool for studying glaciers**. +The model framework features several glacier evolution models, including an flowline ice +dynamics module accounting for frontal ablation, and several mass-balance models, including +a pre-calibrated temperature-index model. -OGGM is also a modular platform that supports novel modelling workflows, -**encouraging researchers to create unique model chains and analyses for their research**. +OGGM is above all a modular platform that supports novel modelling workflows, +**encouraging researchers to create unique model chains 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. -**This webpage is for the software documentation: for general information about the -OGGM project and related news, visit** `oggm.org `_. +**This webpage is for the software documentation**: for general information about the +OGGM project and related news, visit `oggm.org `_. For +the educational platform, visit `edu.oggm.org `_ . .. admonition:: A note for new users @@ -148,7 +149,6 @@ Get in touch - Report bugs or share your ideas on the `issue tracker`_, and improve the model by submitting a `pull request`_. - Chat with us on `Slack`_! (just send us an `e-mail`_ so we can add you) -- Follow us on `Twitter`_. - Participate to our regular `meeting`_. (`reach out`_ if you want to join in) - Or you can always send us an `e-mail`_ the good old way. @@ -157,7 +157,6 @@ Get in touch .. _on GitHub: https://github.com/OGGM/oggm .. _issue tracker: https://github.com/OGGM/oggm/issues .. _pull request: https://github.com/OGGM/oggm/pulls -.. _Twitter: https://twitter.com/OGGM_org .. _meeting: https://oggm.org/meetings/ .. _reach out: info@oggm.org diff --git a/docs/whats-new.rst b/docs/whats-new.rst index bdd24639e..88eea37fc 100644 --- a/docs/whats-new.rst +++ b/docs/whats-new.rst @@ -6,6 +6,16 @@ Version history v1.6.2 (unreleased) ------------------- +A new minor release of the OGGM with several improvements and bug fixes. +The changes and additions are important, but not fundamental. +Most users should switch to this version if they don't care about +full reproducibility of existing results. The previous 1.6 preprocessed +directories are still compatible and can be used with this version. +Some bugs have been fixed however (see below), and if they matter to you, +you may have to reprocess the data yourself or be patient (we aim to +publish a "final" 1.6.X release before the end of the year, which will comprise +updated processed datasets, including a working version of RGI7 repositories). + Enhancements ~~~~~~~~~~~~ @@ -27,7 +37,7 @@ Enhancements `Patrick Schmitt `_ - Added a new calving module to the sandbox. The module is based on Malles et al., 2023, but is currently still in development and - cannot be used operational yet. In general, calving is not + cannot be used operationally yet. In general, calving is not operational in the v1.6 series, it can only be used on a glacier by glacier basis and is not yet fully integrated in the workflow (:pull:`1615`). @@ -49,22 +59,21 @@ Enhancements - Added GlaThiDa data to the shop (:pull:`1663`). By `Fabien Maussion `_ - Added an installation guide for Windows users (:pull:`1666` and :pull:`1683`). - By `Anouk Vlug `_, - `Rebekka Neugebauer `_ and - `Fabien Maussion `_ + By `Anouk Vlug `_ and + `Rebekka Neugebauer `_ - Made it easier to run parameter perturbation experiments by - allowing more than one mb_calib.json file in the + allowing more than one ``mb_calib.json`` file in the working directory (:pull:`1678`) and by adding a new - `perturbate_mb_params` task (:pull:`1669`). + ``perturbate_mb_params`` task (:pull:`1669`). By `Fabien Maussion `_ - Preprocessed directories can now have categorical resolution - classes like GloGEM does (did it for IGM), where users can choose + classes like GloGEM does, where users can choose bins where a given dx is used (:pull:`1664`). It looks nicer - to the eye but I still think the continue dx approach is better. + to the eye, but I still think the continuous ``dx`` approach is better. By `Fabien Maussion `_ - The mass-balance model can now be calibrated on regional averages instead of glacier-per-glacier values. This is useful to trick - RGI7 into being calibrated or other things (:pull:`1692`). + RGI7 into being calibrated (:pull:`1692`). By `Fabien Maussion `_ - Added the rgi7g_to_complex task which adds a mask of glacier entities in the glacier complex glacier dirs (:pull:`1736`).