From 00552b6992515dba55dfb664c47913236814eb52 Mon Sep 17 00:00:00 2001 From: Fabien Maussion Date: Fri, 23 Aug 2024 17:09:22 +0100 Subject: [PATCH] Further doc updates (#1731) * Further doc updates * doc overload * Small think --- README.rst | 4 ++-- docs/api.rst | 30 ++++++++++++++++++------- docs/assets.rst | 5 +++++ docs/citing-oggm.rst | 2 +- docs/climate-data.rst | 29 +++++++++++++++---------- docs/download-projections.rst | 9 +++++--- docs/dynamic-spinup.rst | 4 ++-- docs/faq.rst | 10 ++++----- docs/flowlines.rst | 2 +- docs/frontal-ablation.rst | 2 +- docs/geometry-evolution.rst | 23 ++++++-------------- docs/getting-started.rst | 6 ++++- docs/igm.rst | 10 +++++++++ docs/index.rst | 36 +++++++++++++++--------------- docs/installing-oggm.rst | 4 ++++ docs/introduction.rst | 11 ++++++---- docs/mass-balance-16guide.rst | 6 ++--- docs/mass-balance-monthly.rst | 2 +- docs/mass-balance.rst | 41 ++++++++++++++++++++--------------- docs/practicalities.rst | 20 ++++++++--------- docs/rgitopo.rst | 2 +- docs/shop.rst | 40 +++++++++++++++++++++++++++++----- docs/whats-new.rst | 2 +- oggm/shop/cook23.py | 7 +++++- oggm/shop/gcm_climate.py | 2 +- oggm/utils/_downloads.py | 2 +- oggm/utils/_funcs.py | 10 ++++++--- oggm/workflow.py | 4 ++++ 28 files changed, 205 insertions(+), 120 deletions(-) create mode 100644 docs/igm.rst diff --git a/README.rst b/README.rst index db819bef6..2963d2521 100644 --- 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 index 880750013..d3b6ab49e 100644 --- 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,6 +73,8 @@ Input/Output global_tasks.compile_climate_statistics global_tasks.compile_ela +.. _apishop: + OGGM Shop ========= @@ -80,6 +82,10 @@ OGGM Shop :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 @@ -87,14 +93,22 @@ OGGM Shop 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 `_. +`tutorial on the topic `_. .. include:: _generated/basenames.txt diff --git a/docs/assets.rst b/docs/assets.rst index 301ec522e..df7f40bcb 100644 --- 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 `_ + The following files are available: - ``centerlines``: the geometrical centerlines diff --git a/docs/citing-oggm.rst b/docs/citing-oggm.rst index 43c43f12f..be53da8cb 100644 --- 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 index da42440a4..e105965a4 100644 --- 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 `_. + +Visit our online tutorials to see how this can be done +(`OGGM run with GCM tutorial `_). + +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 `_. - -Visit our online tutorials to see how this can be done -(`OGGM run with GCM tutorial `_). \ No newline at end of file diff --git a/docs/download-projections.rst b/docs/download-projections.rst index 1b7bfabbb..d6f8283c7 100644 --- 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) `_ together with the analysis jupyter notebooks can be found in the `OGGM/oggm-standard-projections-csv-files repository `_. +Data for the CMIP6 GCMs until 2100 is also described in +`Zekollari et al. (2024) `_. 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) `_. 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 index 430e5e945..fa31476fc 100644 --- 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 `_ +check out this `10 minute tutorial `_ 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 `_. +`advanced tutorial `_. diff --git a/docs/faq.rst b/docs/faq.rst index 0ac752d75..3bb670605 100644 --- 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 `_ 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 `_! +`tutorial `_! .. _pitfalls.numerics: diff --git a/docs/flowlines.rst b/docs/flowlines.rst index e6076eeb6..9ce138a34 100644 --- 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 `_. +`centerlines versus elevation-band flowlines comparison tutorial `_. .. figure:: _static/eb_vs_cl.png diff --git a/docs/frontal-ablation.rst b/docs/frontal-ablation.rst index 59561f02d..8909096e0 100644 --- 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 `_ +Visit our `tutorials `_ 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 index 2786b92b3..a2c6ff8f4 100644 --- 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) -`OGGM-VAS `_ is a complete python re-write of -`Ben Marzeion's 2012 model `_. -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 `_ -for more information. -The :doc:`mass-redistribution` is an implementation of the "delta-h" model -by `Huss & Hock (2015) `_ -and `Rounce et al., (2020) `_. -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 `_ -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) `_. It works quite well for short simulations of the glacier retreat phase. +* `OGGM-VAS (volume-area scaling) `_: a python re-write of `Ben Marzeion's 2012 model `_. See Moritz Oberrauch's `thesis `_ for more information. diff --git a/docs/getting-started.rst b/docs/getting-started.rst index e60bf0773..b8a15edd3 100644 --- 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 new file mode 100644 index 000000000..11b5da688 --- /dev/null +++ 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) `_ +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 `_ for a sneak peak! diff --git a/docs/index.rst b/docs/index.rst index a51fe1f04..6e2bfc69a 100644 --- 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 `_. +.. 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 `_ +* `Tutorials `_ * :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 + Tutorials 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 index 3f508443c..ecfb42303 100644 --- 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` diff --git a/docs/introduction.rst b/docs/introduction.rst index 28f1c102d..5e49181e1 100644 --- a/docs/introduction.rst +++ b/docs/introduction.rst @@ -7,9 +7,8 @@ regularly since 2016. Today, OGGM is continuously discussed and updated by a team of international researchers. Our main aim is to **assist the modelling of the evolution of mountains -glaciers at the river basin, regional and global scales**. - -The OGGM framework offers various solutions to the challenges encountered +glaciers at large scales**. The OGGM framework offers various solutions +to the challenges encountered when modelling a large number of glaciers. Here is a non-exhaustive list of its features: @@ -44,6 +43,10 @@ its features: maintained and freely available container environments for reproducibility across platforms and HPCs. + Standard projections + Pre-computed glacier change projections for a wide range of scenarios and use cases. + See :doc:`download-projections` for more information. + Community Welcoming community of users and developers: :ref:`get in touch ` and join us! @@ -90,7 +93,7 @@ Ice thickness inversion Using the mass balance data computed above and relying on mass-conservation considerations, an estimate of the ice flux along each glacier grid point cross-section is computed by making assumptions about the shape of the cross-section - (parabolic, rectangular or trapezoid). Using the physics of ice flow and the shallow ice approximation, + (parabolic, rectangular or trapezoid). Using the physics of ice flow and the shallow ice approximation, the model then computes the thickness of the glacier along the flowlines and the total volume of the glacier (**Fig. e**). diff --git a/docs/mass-balance-16guide.rst b/docs/mass-balance-16guide.rst index 13c16d81a..61fa21f72 100644 --- a/docs/mass-balance-16guide.rst +++ b/docs/mass-balance-16guide.rst @@ -1,7 +1,7 @@ .. currentmodule:: oggm -Transitioning from OGGM 1.5 to 1.6 -================================== +Transitioning from v1.5 to 1.6 +============================== OGGM version 1.6 and above have considerably improved how the calibration is done in OGGM. At the same time, we changed a few other aspects of the mass-balance @@ -18,5 +18,5 @@ Furthermore, the results will probably change quite a lot (depending on your use **We recommend all users to transition to OGGM 1.6 when they are ready to.** It's totally fine to continue using OGGM 1.5.3 as long as you need to. For transitioning, we recommend to have a look at our brand new -`tutorials `_. +`tutorials `_. diff --git a/docs/mass-balance-monthly.rst b/docs/mass-balance-monthly.rst index b9db5c7f1..c572a172d 100644 --- a/docs/mass-balance-monthly.rst +++ b/docs/mass-balance-monthly.rst @@ -42,7 +42,7 @@ Calibration spend some time in getting familiar with the calibration procedure in order to adapt it for their own purposes. -Visit the new `mass balance calibration tutorial `_ +Visit the new `mass balance calibration tutorial `_ for an overview. Notes diff --git a/docs/mass-balance.rst b/docs/mass-balance.rst index fcdb8bd2f..61bd2b8ef 100644 --- a/docs/mass-balance.rst +++ b/docs/mass-balance.rst @@ -5,26 +5,16 @@ Mass balance models OGGM allows to mix and compare many different implementations of climatic mass balance (MB) models. These models all follow a predefined -"interface" (programming jargon for *naming conventions*) so that they can -communicate with the :doc:`geometry-evolution`. +"interface" so that they can communicate with the :doc:`geometry-evolution`. -**In fact, what OGGM calls a "mass balance model" is any function that provides -surface mass balance information to the geometry evolution model for the -run**. Therefore, while some mass balance models can be quite complex and take +**In fact, what OGGM calls a "mass balance model" is any python function that +is able to provide annual surface mass balance information to the geometry evolution +model for the duration of the run**. + +Therefore, while some mass balance models can be quite complex and take many physical processes into account, other model classes can implement idealized concepts, random samples or simplifications of the more realistic ones. -Here are some of the options available to our users to compute the mass balance: - -.. toctree:: - :maxdepth: 1 - - mass-balance-monthly.rst - mass-balance-16guide.rst - mass-balance-toys.rst - PyGEM - massbalance-sandbox - .. admonition:: **Check out these recent developments!** PyGEM is a standalone model that has been applied to High Mountain Asia @@ -33,7 +23,7 @@ Here are some of the options available to our users to compute the mass balance: `2020b `_). David and the OGGM team have worked extensively to make PyGEM's MB model compatible with the OGGM workflow, resulting in this - `global PyGEM-OGGM study published in Science `_ + `global PyGEM-OGGM study published in Science `_. The capacity to run OGGM with PyGEM as mass balance model is now available on the PyGEM repository. @@ -41,3 +31,20 @@ Here are some of the options available to our users to compute the mass balance: is the future generation of OGGM's climatic MB models. They are currently in the development and testing phase, but they can readily be used with a recent OGGM version. + +Check out the following resources for more information: + +* :doc:`mass-balance-monthly` +* :doc:`mass-balance-16guide` +* :doc:`mass-balance-toys` +* The `massbalance-sandbox `_ repository + + +.. toctree:: + :maxdepth: 1 + :hidden: + + mass-balance-monthly.rst + mass-balance-16guide.rst + mass-balance-toys.rst + massbalance-sandbox \ No newline at end of file diff --git a/docs/practicalities.rst b/docs/practicalities.rst index 6c3b93086..c7668b369 100644 --- a/docs/practicalities.rst +++ b/docs/practicalities.rst @@ -114,7 +114,7 @@ The installation procedure explained in :doc:`installing-oggm` should also work in cluster environments. If you don't have admin rights, installing with conda in your ``$HOME`` probably is the easiest option. Once OGGM is installed, you can use your scripts (like the ones provided in the -`tutorials `_). But you probably want to check if the tests pass and our +`tutorials `_). But you probably want to check if the tests pass and our `Data storage`_ section below first! @@ -164,7 +164,7 @@ for your own purposes. Use ``base`` if you want to install your own OGGM version (don't forget to test it afterwards!), and use ``oggm`` if you know which OGGM version you want. -As an example, here is how we run a given fixed version of OGGM on our +As an example, here is how we run a given fixed version of OGGM on our own cluster. First we pull the image we want to run from GitHub somewhere on your system:: @@ -208,7 +208,7 @@ Some explanations: simply is taken from our Docker container base (singularity `can run docker containers `_). Singularity is preferred over Docker in cluster - environments, mostly for security and performance reasons. + environments, mostly for security and performance reasons. On our cluster, we use the SLURM manager to run a number of glaciers (an RGI region for example), and the script above is then run on a node. You can also use and run singularity with ``srun -n 1 -c X singularity exec ...``: @@ -218,18 +218,18 @@ Some explanations: guaranteed to always use the same software versions across runs. - it follows a number of commands to make sure we don't mess around with the system settings. Here we use an ``$OGGM_WORKDIR`` variable which is - probably not available in your case: it points to a directory you can - write to, and where OGGM will work (for example, it might also be the + probably not available in your case: it points to a directory you can + write to, and where OGGM will work (for example, it might also be the directory you are working on with OGGM (``cfg.PATHS['working_dir']``). We suggest to replace this variable with what works for you. - the ``oggm`` docker images ship with an OGGM version guaranteed to work on this container. - Sometimes, you may want to use another OGGM version, for example with newer developments - on it. You might also add your own flavor or parameterization to OGGM into the environment. - For this you can use pip and install the version you want. Here we show an example + Sometimes, you may want to use another OGGM version, for example with newer developments + on it. You might also add your own flavor or parameterization to OGGM into the environment. + For this you can use pip and install the version you want. Here we show an example where we install a specific OGGM version, here specified by its git hash (you can use a `git tag `_ - as well). If you do that, you might want to run the tests once first to make sure + as well). If you do that, you might want to run the tests once first to make sure that it works as expected. You can do that by replacing ``YOUR_RUN_SCRIPT_HERE`` with ``pytest.oggm --run-slow``! - finally, the `YOUR_RUN_SCRIPT_HERE` is the actual command you want to run @@ -286,7 +286,7 @@ you have to deal with: to create compressed, aggregated files of your directories. You can later initialize new directories from these tar files with the `from_tar` keyword argument in :py:func:`workflow.init_glacier_directories`. See our - dedicated `tutorials on the topic `_. + dedicated `tutorials on the topic `_. Run per RGI region, not globally diff --git a/docs/rgitopo.rst b/docs/rgitopo.rst index dd3ea2321..00029d198 100644 --- a/docs/rgitopo.rst +++ b/docs/rgitopo.rst @@ -3,7 +3,7 @@ RGI-TOPO (New! also for RGI 7.0) The RGI-TOPO dataset provides a local topography map for each single glacier in the RGI. It was generated with OGGM, and can be downloaded very easily with OGGM from the :doc:`shop` (visit -our `tutorials `_ if you want to learn how to do this!). +our `tutorials `_ if you want to learn how to do this!). **Non-OGGM users can access the data by themselves at the following links**: diff --git a/docs/shop.rst b/docs/shop.rst index 3aadf6a4b..39c0f6dcc 100644 --- a/docs/shop.rst +++ b/docs/shop.rst @@ -50,7 +50,7 @@ set to the values of your choice. This will fetch the desired directories: there are more options to these, which we explain in detail below. If you like to start using the pre-processed directories right away, with out reading about all the different options and details first, you can go to the -[10 minutes to… a preprocessed directory](https://oggm.org/tutorials/stable/notebooks/10minutes/preprocessed_directories.html) +`10 minutes to… a preprocessed directory `_ tutorial. Processing levels @@ -77,7 +77,7 @@ There are six available levels of pre-processing: the processing chain can be re-run from them. - **Level 4**: includes a historical simulation from the RGI date to the last possible date of the baseline climate file - (currently January 1st 2020 at 00H for most datasets), stored with the file suffix + (currently January 1st 2020 at 00H for most datasets), stored with the file suffix ``_historical``. Moreover, some configurations (called ``spinup``) may include a simulation running a spinup from 1979 to the last possible date of the baseline climate file, stored with the file suffix ``_spinup_historical``. This spinup attempts to conduct a @@ -228,7 +228,7 @@ The basic set-up is following: - "informed three-step" mass balance model calibration (see :ref:`mb-calib`) - :ref:`dynamic-spinup` with dynamic melt factor calibration -There are however multiple options to choose from. Our `tutorials `_ +There are however multiple options to choose from. Our `tutorials `_ showcase example of applications for some of them. One can explore `cluster.klima.uni-bremen.de/~oggm/gdirs/oggm_v1.6 `_ for more options. Here follows a brief guide through the folder structure: @@ -391,7 +391,8 @@ Additional available data ------------------------- Here follows a description of the additional data that can be added to the -pre-processed glacier directories, by choosing the 'w_data' option. +pre-processed glacier directories, by choosing the 'w_data' option or in code. +See also: :ref:`apientitytasks`. ITS_LIVE ~~~~~~~~ @@ -414,8 +415,8 @@ Currently the only data downloaded is the 120m composite for both If you want more velocity products, feel free to open a new topic on the OGGM issue tracker! -Ice thickness -~~~~~~~~~~~~~ +Gridded ice thickness +~~~~~~~~~~~~~~~~~~~~~ The `Farinotti et al., 2019 `_ ice thickness products can be downloaded and reprojected to the glacier directory @@ -428,6 +429,21 @@ ice thickness products can be downloaded and reprojected to the glacier director Example of the reprojected ice thickness products at Malaspina glacier +Ice thickness observations +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can now add observations from the Glacier Thickness Database +(`GlaThiDa `_) to your +glacier directory with: + +.. code-block:: python + + from oggm.shop import glathida + glathida.glathida_to_gdir(gdir) + +Checkout :py:func:`shop.glathida.glathida_to_gdir`. + + Millan et al. (2022) ice velocity and thickness products ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -435,6 +451,18 @@ Similarly, we provide data from the recent `Millan et al. (2022) `_ global study (visit our `tutorials`_ if you are interested!). +Cook et al. (2023) thickness products for the Alps +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + +`Cook et al. (2023) `_ +provided a new ice thickness dataset for the Alps. This is now also in the shop, +with :py:func:`shop.cook23.cook23_to_gdir`. + +.. code-block:: python + + from oggm.shop import cook23 + cook23.cook23_to_gdir(gdir) Raw data sources ---------------- diff --git a/docs/whats-new.rst b/docs/whats-new.rst index 7102f42c7..c6f1e8844 100644 --- a/docs/whats-new.rst +++ b/docs/whats-new.rst @@ -420,7 +420,7 @@ v1.5.0 This a new update of the OGGM model. It should be largely compatible with OGGM v1.4.0. **The main addition in this release is the computation of hydrological diagnostics.** Check-out the new tutorial at -https://oggm.org/tutorials ! +https://tutorials.oggm.org ! Breaking changes ~~~~~~~~~~~~~~~~ diff --git a/oggm/shop/cook23.py b/oggm/shop/cook23.py index 84a4a70e2..3da0695ea 100644 --- a/oggm/shop/cook23.py +++ b/oggm/shop/cook23.py @@ -51,12 +51,17 @@ def cook23_to_gdir(gdir, vars=['thk', 'divflux']): """ + # Very easy case: no cook file for this glacier + if gdir.rgi_region != '11' and gdir.rgi_subregion != '01': + raise InvalidWorkflowError(f'Cook23 data is only for the Alps: ' + f'{gdir.rgi_id}') + # Find out which file(s) we need gdf = _get_lookup_thickness() cp = shpg.Point(gdir.cenlon, gdir.cenlat) sel = gdf.loc[gdf.contains(cp)] if len(sel) == 0: - raise InvalidWorkflowError(f'There seems to be no Cook file for this ' + raise InvalidWorkflowError(f'There seems to be no Cook23 file for this ' f'glacier: {gdir.rgi_id}') if len(sel) > 1: diff --git a/oggm/shop/gcm_climate.py b/oggm/shop/gcm_climate.py index bc633b909..62fa33043 100644 --- a/oggm/shop/gcm_climate.py +++ b/oggm/shop/gcm_climate.py @@ -205,7 +205,7 @@ def process_monthly_isimip_data(gdir, output_filesuffix='', ssp scenario to process (only 'ssp126', 'ssp370' or 'ssp585' are available) year_range : tuple of str the year range for which the anomalies are computed - (passed to process_gcm_gdata). Default for ISIMIP3b `('1979', '2014') + (passed to process_gcm_gdata). Default for ISIMIP3b `('1979', '2014')` apply_bias_correction : bool whether the bias correction is applied (default is False) or not. As we use already internally bias-corrected GCMs, it is default set diff --git a/oggm/utils/_downloads.py b/oggm/utils/_downloads.py index 128d0ba38..e3037c2c4 100644 --- a/oggm/utils/_downloads.py +++ b/oggm/utils/_downloads.py @@ -67,7 +67,7 @@ # The given commit will be downloaded from github and used as source for # all sample data SAMPLE_DATA_GH_REPO = 'OGGM/oggm-sample-data' -SAMPLE_DATA_COMMIT = '281ccfae3c0e82a2cae34ccb47f4ef32eb5bf6f5' +SAMPLE_DATA_COMMIT = 'e6da53aea8438a06d7702769e73fe5df8ab0d669' CHECKSUM_URL = 'https://cluster.klima.uni-bremen.de/data/downloads.sha256.hdf' CHECKSUM_VALIDATION_URL = CHECKSUM_URL + '.sha256' diff --git a/oggm/utils/_funcs.py b/oggm/utils/_funcs.py index 51e4baa5a..8f9447320 100644 --- a/oggm/utils/_funcs.py +++ b/oggm/utils/_funcs.py @@ -13,6 +13,10 @@ # External libs import pandas as pd import numpy as np +try: + from numpy._core import umath +except ImportError: + from numpy.core import umath import xarray as xr from scipy.ndimage import convolve1d try: @@ -388,14 +392,14 @@ def weighted_average_1d(data, weights): else: # TODO: reassess this when https://github.com/numpy/numpy/issues/14281 # is solved - clip_array = np.core.umath.clip + clip_array = umath.clip # A faster numpy.clip when only one value is clipped (here: min). -clip_min = np.core.umath.maximum +clip_min = umath.maximum # A faster numpy.clip when only one value is clipped (here: max). -clip_max = np.core.umath.minimum +clip_max = umath.minimum def nicenumber(number, binsize, lower=False): diff --git a/oggm/workflow.py b/oggm/workflow.py index 73e3e3db0..8ee7a3aa7 100644 --- a/oggm/workflow.py +++ b/oggm/workflow.py @@ -451,6 +451,8 @@ def init_glacier_directories(rgidf=None, *, reset=False, force=False, else: rgi_version = rgi_ids[0].split('-')[0][-2:] + if rgi_version == '60': + rgi_version = '62' fp = utils.get_rgi_intersects_entities(rgi_ids, version=rgi_version) cfg.set_intersects_db(fp) @@ -460,6 +462,8 @@ def init_glacier_directories(rgidf=None, *, reset=False, force=False, rgi_ids = np.unique(np.sort([entity.RGIId for entity in entities])) rgi_version = rgi_ids[0].split('-')[0][-2:] + if rgi_version == '60': + rgi_version = '62' fp = utils.get_rgi_intersects_entities(rgi_ids, version=rgi_version) cfg.set_intersects_db(fp)