From 6983a1c84b5b59d83d44f807a5e406ccff8e736b Mon Sep 17 00:00:00 2001 From: Fabien Maussion Date: Tue, 15 Aug 2023 14:15:06 +0100 Subject: [PATCH] First docs - slaight reorganisation --- docs/assets.rst | 6 ++ docs/cloud.rst | 16 +-- docs/conf.py | 2 +- docs/contributing.rst | 7 +- docs/flowlines.rst | 1 + docs/index.rst | 12 +-- docs/installing-oggm.rst | 44 ++++---- docs/mass-balance-monthly.rst | 2 + docs/recommended_env.yml | 11 -- docs/shop.rst | 185 +++++++++++++++------------------- 10 files changed, 126 insertions(+), 160 deletions(-) diff --git a/docs/assets.rst b/docs/assets.rst index a6dfc8efe..890f6e8f1 100644 --- a/docs/assets.rst +++ b/docs/assets.rst @@ -4,6 +4,12 @@ Assets and downloads This page lists some datasets that are either generated or used by OGGM and that can be useful to others. +.. _standard-projs: + +OGGM standard projections (new in v1.6.1!) +------------------------------------------ + +TODO Shapefiles of glacier centerlines, flowlines and widths ------------------------------------------------------- diff --git a/docs/cloud.rst b/docs/cloud.rst index 75b524735..565e23f4c 100644 --- a/docs/cloud.rst +++ b/docs/cloud.rst @@ -1,26 +1,26 @@ Try OGGM online =============== +.. image:: https://mybinder.org/static/logo.svg + :width: 20% + :align: right + :target: https://mybinder.org/v2/gh/OGGM/tutorials/stable?labpath=notebooks%2Fwelcome.ipynb + 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. -.. image:: https://gke.mybinder.org/static/logo.svg - :width: 25% - :target: https://mybinder.org/v2/gh/OGGM/binder/stable?urlpath=git-pull?repo=https://github.com/OGGM/tutorials%26amp%3Bbranch=master%26amp%3Burlpath=lab/tree/tutorials/notebooks/welcome.ipynb%3Fautodecode - -Our `Binder `_ test space is available to anyone, with no +Our `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,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://mybinder.org/v2/gh/OGGM/binder/stable?urlpath=git-pull?repo=https://github.com/OGGM/tutorials%26amp%3Bbranch=master%26amp%3Burlpath=lab/tree/tutorials/notebooks/welcome.ipynb%3Fautodecode - :align: left + :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. -.. warning:: +.. important:: Binder environments are only temporary! Perfect for trying and learning, but not suitable for development work. Remember to download your notebooks diff --git a/docs/conf.py b/docs/conf.py index 46007271a..49d0ef803 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -228,7 +228,7 @@ # further. For a list of options available for each theme, see the # documentation. html_theme_options = { - "logo_only": True, + # "logo_only": True, "repository_url": "https://github.com/OGGM/oggm", "use_repository_button": True, "use_issues_button": True, diff --git a/docs/contributing.rst b/docs/contributing.rst index 6e0c24d62..8a8068c71 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -206,14 +206,13 @@ Installation ~~~~~~~~~~~~ There are some extra requirements to build the docs: you will need to -have ``sphinx``, ``sphinx-togglebutton``, ``sphinx-book-theme``, ``numpydoc`` -and ``ipython`` installed. +have ``sphinx``, ``sphinx-togglebutton``, ``sphinx-book-theme``, +``sphinx-reredirects``, ``numpydoc`` and ``ipython`` installed. If you have a conda environment named ``oggm_env``, you can install the extra requirements with:: - mamba install -c conda-forge sphinx ipython numpydoc sphinx-book-theme - pip install sphinx-togglebutton + mamba install -c conda-forge sphinx ipython numpydoc sphinx-book-theme sphinx-reredirects sphinx-togglebutton If you don't have an oggm installation yet, download (or clone) the latest version of the oggm repository. diff --git a/docs/flowlines.rst b/docs/flowlines.rst index a4a11c9de..3ffc1af74 100644 --- a/docs/flowlines.rst +++ b/docs/flowlines.rst @@ -158,6 +158,7 @@ Note that a *perfect* match is not possible since the sample size is not the same between the "1.5D" and the 2D representation of the glacier, but it's close enough. +.. _eb-flowlines: Elevation bands flowlines ------------------------- diff --git a/docs/index.rst b/docs/index.rst index 2390c76d7..761ec8eb8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,17 +7,17 @@ the past and future mass balance, volume, and geometry of glaciers worldwide. The model features several glacier evolution models, including an explicit 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. +**With an unwavering commitment to using publicly available data for calibration +and validation, OGGM 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 models 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.0 is a substantial change to v1.5.3. Among other developments, + 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 @@ -26,13 +26,9 @@ ideal tool for a wide range of applications in glaciology and related fields. 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 `_. - -.. include:: _generated/version_text.txt - Video presentation ^^^^^^^^^^^^^^^^^^ diff --git a/docs/installing-oggm.rst b/docs/installing-oggm.rst index e5efefef0..f6ed06634 100644 --- a/docs/installing-oggm.rst +++ b/docs/installing-oggm.rst @@ -275,6 +275,26 @@ are frequent and point to errors in upstream packages, rarely in OGGM itself. If you encounter issues, please get in touch with us `on github `_. +Install a minimal OGGM environment +---------------------------------- + +If you plan to use only the numerical core of OGGM (that is, for idealized +simulations or teaching), you can skip many dependencies and only +install this shorter list: + +.. include:: recommended_minimal_env.yml + :literal: + +Installing them with pip or conda should be much easier. +`Install OGGM itself`_ then as above. + +Running the tests in this minimal environment works the same. Simply run +from a terminal:: + + pytest.oggm + +The number of tests will be much smaller! + .. _virtualenv-install: Install with pyenv (Linux) @@ -303,7 +323,7 @@ For building python and stuff:: For NetCDF and HDF:: - $ sudo apt-get install netcdf-bin ncview hdf5-tools libhdf5-dev + $ sudo apt-get install netcdf-bin ncview hdf5-tools libhdf5-dev Pyenv and pyenv-virtualenv @@ -314,7 +334,7 @@ Pyenv and pyenv-virtualenv If you are not familiar with pyenv, you can visit `their documentation `_ (especially the installing pyenv section). - + Install `pyenv `_ and create a new virtual environment with a recent python version (3.7+) using `pyenv-virtualenv `_. @@ -348,23 +368,3 @@ Install OGGM and run the tests ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Refer to `Install OGGM itself`_ above. - -Install a minimal OGGM environment ----------------------------------- - -If you plan to use only the numerical core of OGGM (that is, for idealized -simulations or teaching), you can skip many dependencies and only -install this shorter list: - -.. include:: recommended_minimal_env.yml - :literal: - -Installing them with pip or conda should be much easier. -`Install OGGM itself`_ then as above. - -Running the tests in this minimal environment works the same. Simply run -from a terminal:: - - pytest.oggm - -The number of tests will be much smaller! diff --git a/docs/mass-balance-monthly.rst b/docs/mass-balance-monthly.rst index eb616624e..b9db5c7f1 100644 --- a/docs/mass-balance-monthly.rst +++ b/docs/mass-balance-monthly.rst @@ -30,6 +30,8 @@ temperature and precipitation at the altitude :math:`z` of the glacier grid points. The default is to use a fixed lapse rate of -6.5K km :math:`^{-1}` and no gradient for precipitation. +.. _mb-calib: + Calibration ----------- diff --git a/docs/recommended_env.yml b/docs/recommended_env.yml index 35164cdbe..1c9146dc2 100644 --- a/docs/recommended_env.yml +++ b/docs/recommended_env.yml @@ -2,8 +2,6 @@ name: oggm_env channels: - conda-forge dependencies: - - jupyter - - jupyterlab - numpy - scipy - pandas @@ -12,7 +10,6 @@ dependencies: - Pillow - netcdf4 - scikit-image - - scikit-learn - configobj - xarray - pytest @@ -27,17 +24,9 @@ dependencies: - pytables - salem - motionless - - sphinx - - sphinx-book-theme>=0.3.3 - - ipython - - numpydoc - - seaborn - - sphinx-intl - - sphinx-reredirects - pip - pip: - joblib - progressbar2 - - sphinx-togglebutton - git+https://github.com/OGGM/pytest-mpl - oggm \ No newline at end of file diff --git a/docs/shop.rst b/docs/shop.rst index e335a62e4..9a8fa8ff0 100644 --- a/docs/shop.rst +++ b/docs/shop.rst @@ -35,7 +35,7 @@ If you want to change some of these parameters, you may have to start a run from a lower processing level and re-run the processing tasks. Whether or not this is necessary depends on the stage of the workflow you'd like your computations to diverge from the -defaults (this will become more clear as we provide examples below). +defaults (this will become clearer as we provide examples workflow below). To start from a pre-processed state, simply use the :py:func:`workflow.init_glacier_directories` function with the @@ -48,9 +48,10 @@ Processing levels .. admonition:: **New in version 1.6!** - Since v1.6, Level 4 and Level 5 have changed! + In v1.6, Level 4 and Level 5 have changed! The explanations below are + valid for OGGM version 1.6.0 and above. -Currently, there are six available levels of pre-processing: +There are six available levels of pre-processing: - **Level 0**: the lowest level, with directories containing the glacier outlines only. @@ -89,18 +90,16 @@ experiments (but easily recovered if needed). In previous versions, level 4 files were the "reduced" directories with intermediate files removed. Level 5 was very similar, but without the dynamic spinup files. I practice, most users wont really see a change. - **All v1.4 directories are still working with OGGM v1.6: however, you may have to change - the run parameters back to their previous values**. Here are some example use cases for glacier directories, and recommendations on which level to pick: -1. *Running OGGM from GCM / RCM data with the default settings*: **start at level 5** -2. *Using OGGM's flowlines but running your own baseline climate, - mass balance or ice thickness inversion models*: **start at level 2** (and maybe +1. Running OGGM from GCM / RCM data with the default settings: **start at level 5** +2. Using OGGM's flowlines but running your own baseline climate, + mass balance or ice thickness inversion models: **start at level 2** (and maybe use OGGM's workflow again for glacier dynamic evolution?). This is the workflow used by associated model `PyGEM `_ for example. -3. *Run sensitivity experiments for the ice thickness inversion*: start at level +3. Run sensitivity experiments for the ice thickness inversion: start at level 3 (with climate data available) and re-run the inversion steps. @@ -136,6 +135,8 @@ become. Here is an example with Hintereisferner in the Alps: .. code-block:: python + base_url = 'https://cluster.klima.uni-bremen.de/~oggm/gdirs/oggm_v1.6' + base_url += '/L1-L2_files/elev_bands' f, axs = plt.subplots(2, 2, figsize=(8, 6)) for ax, border in zip(np.array(axs).flatten(), [10, 80, 160, 240]): gdir = workflow.init_glacier_directories('RGI60-11.00897', @@ -192,18 +193,38 @@ Available pre-processed configurations ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ OGGM has several configurations and directories to choose from, -and the list is getting larger. Don't hesitate to ask us if you are +and the list is getting larger regularly. Don't hesitate to ask us if you are unsure about which to use, or if you'd like to have more configurations to choose from! -To choose from a specific model configuration, use the ``prepro_base_url`` +To choose from a specific preprocessed configuration, use the ``prepro_base_url`` argument in your call to :py:func:`workflow.init_glacier_directories`, and set it to one of the urls listed below. -As of March 10, 2023, we offer several urls. Explore -`https://cluster.klima.uni-bremen.de/~oggm/gdirs/oggm_v1.6 `_ and our `tutorials `_ for examples of applications. +The recommended ``prepro_base_url`` for a standard OGGM run is: -.. admonition:: **Version 1.4 and 1.5 directories (before v1.6)** +.. ipython:: python + :okwarning: + + from oggm import DEFAULT_BASE_URL + DEFAULT_BASE_URL + +This is the setup that was used to generate the OGGM 1.6.1 standard projections +(:ref:`standard-projs`). +The basic set-up is following: + +- all default OGGM parameters +- :ref:`eb-flowlines` +- :ref:`climate-w5e5` reference climate +- "informed three-step" mass balance model calibration (see :ref:`mb-calib`) +- :ref:`dynamic-spinup` with dynamic melt factor calibration + + +Explore +`cluster.klima.uni-bremen.de/~oggm/gdirs/oggm_v1.6 `_ for more options. Our `tutorials `_ showcase +example of applications for some of them. + +.. admonition:: Deprecated: **version 1.4 and 1.5 directories (before v1.6)** :class: note, dropdown **All v1.4 directories are still working with OGGM v1.6: however, you may have to change @@ -342,8 +363,6 @@ As of March 10, 2023, we offer several urls. Explore you can check out this `jupyter notebook `_. - - .. _Marzeion et al., 2012: http://www.the-cryosphere.net/6/1295/2012/tc-6-1295-2012.html Climate data @@ -351,11 +370,15 @@ Climate data Here are the various climate datasets that OGGM handles automatically. +.. _climate-w5e5: + W5E5 ~~~~ -Since OGGM v1.5, users can also use the reanalysis data W5E5, which is a -bias-corrected ERA5... +As of v1.6, W5E5 is the standard dataset used by OGGM as reference. All +preprocessed directories use it. + +TODO: explain what W5E5 is and why it is the default. CRU ~~~ @@ -367,6 +390,16 @@ latest dataset from the CRU servers. .. _CRU TS: https://crudata.uea.ac.uk/cru/data/hrg/ +To download CRU data you can use the +following convenience functions: + +.. code-block:: python + + from oggm.shop import cru + cru.get_cl_file() + cru.get_cru_file(var='tmp') + cru.get_cru_file(var='pre') + .. warning:: While the downloaded zip files are ~370mb in size, they are ~5.6Gb large @@ -381,6 +414,12 @@ based on a presumably better climatology. The monthly anomalies are computed following [Harris_et_al_2010]_ : we use standard anomalies for temperature and scaled (fractional) anomalies for precipitation. +**When using these data, please refer to the original provider:** + +Harris, I., Jones, P. D., Osborn, T. J., & Lister, D. H. (2014). Updated +high-resolution grids of monthly climatic observations - the CRU TS3.10 Dataset. +International Journal of Climatology, 34(3), 623–642. https://doi.org/10.1002/joc.3711 + .. _CRU faq: https://crudata.uea.ac.uk/~timm/grid/faq.html .. [Harris_et_al_2010] Harris, I., Jones, P. D., Osborn, T. J., & Lister, @@ -388,7 +427,6 @@ scaled (fractional) anomalies for precipitation. - the CRU TS3.10 Dataset. International Journal of Climatology, 34(3), 623–642. https://doi.org/10.1002/joc.3711 - ERA5 and CERA-20C ~~~~~~~~~~~~~~~~~ @@ -401,12 +439,22 @@ datasets as baseline. One can also apply a combination of both, for example by applying the CERA-20C anomalies to the reference ERA5 for example (useful only in some circumstances). +**When using these data, please refer to the original provider:** + +For example for ERA5: + +Hersbach, H., Bell, B., Berrisford, P., Biavati, G., Horányi, A., +Muñoz Sabater, J., Nicolas, J., Peubey, C., Radu, R., Rozum, I., +Schepers, D., Simmons, A., Soci, C., Dee, D., Thépaut, J-N. (2019): +ERA5 monthly averaged data on single levels from 1979 to present. +Copernicus Climate Change Service (C3S) Climate Data Store (CDS). +(Accessed on < 01-12-2020 >), 10.24381/cds.f17050d7 + HISTALP ~~~~~~~ -If required by the user, OGGM can also automatically -download and use the data from the `HISTALP`_ dataset (available only -for the European Alps region, more details in [Chimani_et_al_2012]_. +OGGM can also automatically download and use the data from the `HISTALP`_ +dataset (available only for the European Alps region, more details in [Chimani_et_al_2012]_. The data is available at 5' resolution (about 0.0833°) from 1801 to 2014. However, the data is considered spurious before 1850. Therefore, we recommend to use data from 1850 onwards. @@ -431,8 +479,11 @@ recommend to use data from 1850 onwards. @savefig plot_temp_ts.png width=100% example_plot_temp_ts() # the code for these examples is posted below -User-provided climate dataset -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Any other climate dataset +~~~~~~~~~~~~~~~~~~~~~~~~~ + +It is fairly easy to add a dataset to OGGM. Recent publications have used +plenty of options, from ERA5-Land to regional reanalyses or more. You can provide any other dataset to OGGM. See the `HISTALP_oetztal.nc` data file in the OGGM `sample-data`_ folder for an example format. @@ -444,10 +495,11 @@ 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. CRU) for the reference +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 `_). @@ -612,9 +664,9 @@ global study (visit our `tutorials`_ if you are interested!). Raw data sources ---------------- -These data are used to create the pre-processed directories explained above. If you want to run your own workflow from A to Z, or if you would like -to know which data are used in OGGM, read further! +to know which data are used in OGGM before being available in the +pre-processed directories, read further! .. _outlines: @@ -779,82 +831,3 @@ reproduce this information requirements a DEM must fulfill to be helpful to OGGM. And we also explain why and how we preprocess some DEMs before we make them available to the OGGM workflow. - -Climate data -~~~~~~~~~~~~ - -**‣ CRU** - -To download CRU data you can use the -following convenience functions: - -.. code-block:: python - - from oggm.shop import cru - cru.get_cl_file() - cru.get_cru_file(var='tmp') - cru.get_cru_file(var='pre') - - -.. warning:: - - While each downloaded zip file is ~200mb in size, they are ~2.9Gb large - after decompression! - -The raw, coarse dataset (CRU TS v4.04 at 0.5° resolution) is then downscaled to -a higher resolution grid (CRU CL v2.0 at 10' resolution) following the anomaly mapping approach -described by Tim Mitchell in his `CRU faq`_ (Q25). Note that we don't expect -this downscaling to add any new information than already available at the -original resolution, but this allows us to have an elevation-dependent dataset -based on a presumably better climatology. The monthly anomalies are computed -following Harris et al., (2010): we use standard anomalies for temperature and -scaled (fractional) anomalies for precipitation. At the locations where the -monthly precipitation climatology is 0 we fall back to the standard anomalies. - -**When using these data, please refer to the original provider:** - -Harris, I., Jones, P. D., Osborn, T. J., & Lister, D. H. (2014). Updated -high-resolution grids of monthly climatic observations - the CRU TS3.10 Dataset. -International Journal of Climatology, 34(3), 623–642. https://doi.org/10.1002/joc.3711 - -.. _CRU faq: https://crudata.uea.ac.uk/~timm/grid/faq.html - -**‣ ECMWF (ERA5, CERA, ERA5-Land)** - -The data from ECMWF are used "as is", i.e. without any further downscaling. -We propose several datasets (see :py:func:`oggm.shop.ecmwf.process_ecmwf_data`) -and, with the task :py:func:`oggm.tasks.historical_delta_method`, also -allow for combinations of them. - -**When using these data, please refer to the original provider:** - -For example for ERA5: - -Hersbach, H., Bell, B., Berrisford, P., Biavati, G., Horányi, A., -Muñoz Sabater, J., Nicolas, J., Peubey, C., Radu, R., Rozum, I., -Schepers, D., Simmons, A., Soci, C., Dee, D., Thépaut, J-N. (2019): -ERA5 monthly averaged data on single levels from 1979 to present. -Copernicus Climate Change Service (C3S) Climate Data Store (CDS). -(Accessed on < 01-12-2020 >), 10.24381/cds.f17050d7 - - -**‣ User-provided dataset** - -You can provide any other dataset to OGGM by setting the ``climate_file`` -parameter in ``params.cfg``. See the HISTALP data file in the `sample-data`_ -folder for an example. - -.. _sample-data: https://github.com/OGGM/oggm-sample-data/tree/master/test-workflow - -**‣ GCM data** - -OGGM can also use climate model output to drive the mass balance model. In -this case we still rely on gridded observations (CRU) for the baseline -climatology and apply the GCM anomalies computed from a preselected reference -period. This method is sometimes called the -`delta method `_. - -Currently we can process data from the -`CESM Last Millennium Ensemble `_ -project (see :py:func:`tasks.process_cesm_data`), and CMIP5/CMIP6 -(:py:func:`tasks.process_cmip_data`).