Fix docs and some warnings (#1629)

docs/_code/prepare_hef.py

@@ -58,7 +58,6 @@
 # For thickness plot
 tasks.distribute_thickness_per_altitude(gdir)
 
-
 # plot functions
 def example_plot_temp_ts():
     d = xr.open_dataset(gdir.get_filepath('climate_historical'))

docs/api.rst

@@ -431,23 +431,22 @@ Access
 
 The easiest and most common way to access the model flowlines of a glacier is
 with its GlacierDirectory. For this we initialize a minimal working example
-including the model flowlines. This is achieved by choosing preprocessing level
-4.
+including the model flowlines. This is achieved by choosing preprocessing
+level 5.
 
 .. ipython:: python
 
     import os
     import oggm
-    from oggm import cfg, workflow
+    from oggm import cfg, workflow, DEFAULT_BASE_URL
     from oggm.utils import gettempdir
     cfg.initialize()  # always initialize before an OGGM task
     # The working directory is where OGGM will store the run's data
     cfg.PATHS['working_dir'] = os.path.join(gettempdir(), 'Docs_GlacierDir2')
-    # The base url is where to find the pre-processed directories
-    base_url = 'https://cluster.klima.uni-bremen.de/~oggm/gdirs/oggm_v1.6/L3-L5_files/2023.1/elev_bands/W5E5'
+    # The prepro_base_url is where to find the pre-processed directories
     gdirs = workflow.init_glacier_directories('RGI60-11.00897',
                                               from_prepro_level=5,
-                                              prepro_base_url=base_url,
+                                              prepro_base_url=DEFAULT_BASE_URL,
                                               prepro_border=80)
     gdir = gdirs[0]  # init_glacier_directories always returns a list
 

docs/climate-data.rst

@@ -11,15 +11,13 @@ one of the following functions to pre-process the climate data:
     from oggm.tasks import import process_histalp_data
     from oggm.tasks import import process_ecmwf_data
 
-.. warning::
-
 .. _climate-w5e5:
 
 W5E5
 ~~~~
 
 GSWP3-W5E5
-~~~~
+~~~~~~~~~~
 
 As of v1.6, GSWP3-W5E5 [Lange_et_al_2021]_ is the standard baseline climate dataset used by OGGM
 for all preprocessed directories. GSWP3-W5E5 is a combination of W5E5 v2.0 [Lange_et_al_2021]_ for
@@ -28,59 +26,48 @@ url file paths are only named `W5E5` to make it shorter, however they include bo
 
 GSWP3-W5E5 has a spatial resolution of 0.5° over the entire globe and is also the observational
 climate input data for the impact assessments in phase 3a of the Inter-Sectoral Impact Model
-Intercomparison Project (ISIMIP3a)[https://www.isimip.org/protocol/3/]. Over land, W5E5 uses
+Intercomparison Project ` ISIMIP3a <https://www.isimip.org/protocol/3>`_. Over land, W5E5 uses
 the WATCH Forcing Data methodology version 2 which they applied on ERA5 data
 (WFDE5; Weedon et al., 2014, [Cuchi_2020]_). W5E5 precipitation is based on WFDE5 rainfall and
 snowfall bias-adjusted using version 2.3 of the Global Precipitation Climatology Project
 (GPCP; Adler et al., 2003) monthly precipitation.
 
 One of the reasons, why we chose W5E5 for all preprocessed directories is that the climate input data for the
-(ISIMIP3b CMIP6 GCMs)[https://www.isimip.org/protocol/3/ have been bias-corrected using this dataset.
-Normally, we need to bias-correct the GCMs ourselves to approximately coincide with the applied climate dataset
+`ISIMIP3b CMIP6 GCMs <https://www.isimip.org/protocol/3>`_ have been bias-corrected using this dataset.
+Usually, we need to bias-correct the GCMs ourselves to approximately coincide with the applied climate dataset
 used for model calibration. If we use W5E5 for the calibration of the mass-balance model and the ISIMIP3b
 GCMs for projections, no additional bias-correction from OGGM is needed, as the statistically downscaled GCMs
 from ISIMIP3b (0.5° resolution) are already internally bias-adjusted to W5E5 over the period
 1979–2014 [Lange_2019]_. This is a big advantage, as their quantile-mapping bias correction
-approach is more robust for extreme values than the "delta"-method commonly applied in OGGM.
-
-Note, that per-default, the preprocessed directories [](https://cluster.klima.uni-bremen.de/~oggm/climate/gswp3-w5e5/),
+approach is more robust for extreme values than the "delta-methof" commonly applied in OGGM.
 
 **When using this data, please refer to the original providers:**
 
 *if you only use W5E5 data (1979-2019):*
 
-Lange, S., Menz, C., Gleixner, S., Cucchi, M., Weedon, G. P., Amici, A., Bellouin, N.,
-Müller Schmied, H., Hersbach, H., Buontempo, C. & Cagnazzo, C. (2021). WFDE5 over land
-merged with ERA5 over the ocean (W5E5 v2.0). ISIMIP Repository.
-https://doi.org/10.48364/ISIMIP.342217
+.. [Lange_et_al_2021] Lange, S., Menz, C., Gleixner, S., Cucchi, M., Weedon, G. P., Amici,
+   A., Bellouin, N., Müller Schmied, H., Hersbach, H., Buontempo, C. & Cagnazzo, C. (2021).
+   WFDE5 over land merged with ERA5 over the ocean (W5E5 v2.0). ISIMIP Repository.
+   https://doi.org/10.48364/ISIMIP.342217
 
-Cucchi, M., Weedon, G. P., Amici, A., Bellouin, N., Lange, S., Müller Schmied, H., Hersbach, H. and Buontempo, C. (2020).
-WFDE5: bias-adjusted ERA5 reanalysis data for impact studies. Earth System Science Data, 12, 2097–2120
+.. [Cuchi_2020] Cucchi, M., Weedon, G. P., Amici, A., Bellouin, N., Lange, S.,
+   Müller Schmied, H., Hersbach, H. and Buontempo, C. (2020). WFDE5: bias-adjusted
+   ERA5 reanalysis data for impact studies. Earth System Science Data, 12, 2097–2120
 
 *if you also use the GSWP3 part of the GSWP3-W5E5 data (1901-1978):*
 
 Dirmeyer, P. A., Gao, X., Zhao, M., Guo, Z., Oki, T. and Hanasaki, N. (2006). GSWP-2: Multimodel Analysis
 and Implications for Our Perception of the Land Surface. Bulletin of the American Meteorological Society, 87(10), 1381–98.
 
-Kim, H. (2017). Global Soil Wetness Project Phase 3 Atmospheric Boundary Conditions (Experiment 1)
-[Data set]. Data Integration and Analysis System (DIAS). https://doi.org/10.20783/DIAS.501
-
-
 .. [Kim_2017] Kim, H. (2017). Global Soil Wetness Project Phase 3 Atmospheric Boundary Conditions (Experiment 1)
-[Data set]. Data Integration and Analysis System (DIAS). https://doi.org/10.20783/DIAS.501
-
-.. [Lange_et_al_2021] Lange, S., Menz, C., Gleixner, S., Cucchi, M., Weedon, G. P., Amici,
-A., Bellouin, N., Müller Schmied, H., Hersbach, H., Buontempo, C. & Cagnazzo, C. (2021).
-WFDE5 over land merged with ERA5 over the ocean (W5E5 v2.0). ISIMIP Repository.
-https://doi.org/10.48364/ISIMIP.342217
+   [Data set]. Data Integration and Analysis System (DIAS). https://doi.org/10.20783/DIAS.501
 
-.. [Cuchi_2019] Cucchi, M., Weedon, G. P., Amici, A., Bellouin, N., Lange, S.,
-Müller Schmied, H., Hersbach, H. and Buontempo, C. (2020). WFDE5: bias-adjusted
-ERA5 reanalysis data for impact studies. Earth System Science Data, 12, 2097–2120
+*for more info:*
 
 .. [Lange_2019] Trend-preserving bias adjustment and statistical downscaling
-with ISIMIP3BASD (v1.0). Geoscientific Model Development 12(7), 3055–3070.
-https://doi:10.5194/gmd-12-3055-2019
+   with ISIMIP3BASD (v1.0). Geoscientific Model Development 12(7), 3055–3070.
+   https://doi:10.5194/gmd-12-3055-2019
+
 
 CRU
 ~~~
@@ -116,18 +103,10 @@ 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 providers:**
-
-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
-
-New, M., Lister, D., Hulme, M., & Makin, I (2002). A high-resolution data
-set of surface climate over global land areas. Climate Research, 21(715), 1–25.
-https://doi.org/10.3354/cr021001
-
 .. _CRU faq: https://crudata.uea.ac.uk/~timm/grid/faq.html
 
+**When using these data, please refer to the original providers:**
+
 .. [Harris_et_al_2010] 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),
@@ -187,6 +166,7 @@ recommend to use data from 1850 onwards.
    :okwarning:
 
     @savefig plot_temp_ts.png width=100%
+    example_plot_temp_ts()
 
 Any other climate dataset
 ~~~~~~~~~~~~~~~~~~~~~~~~~

docs/download-projections.rst

@@ -1,53 +1,54 @@
 OGGM standard projections
 =========================
 
-Since OGGM v1.6.1, we provide for a range of climate projections the corresponding global glacier projections. These 
-simulations are and will be done with the most recent released default version of OGGM. We call these state-of-the-art 
-simulations our "standard projections". Here we give a brief introduction to the available data and show were you can 
-find all the details.
-
-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 corresponding jupyter notebooks are in the `OGGM/oggm-standard-projections-csv-files repository <https://github.com/OGGM/oggm-standard-projections-csv-files/tree/main>`_.  
-These projections use `elevation-band flowlines <https://docs.oggm.org/en/stable/flowlines.html#elevation-bands-flowlines>`_, include the `dynamical spinup <https://docs.oggm.org/en/latest/dynamic-spinup.html>`_, the `new informed 3-step per-glacier geodetic calibration method <https://docs.oggm.org/en/latest/mass-balance-monthly.html>`_, and use the W5E5v2.0 climate dataset `(Lange and others, 2021) <https://doi.org/10.48364/ISIMIP.342217>`_ for calibration and a border of 160. 
-
-We have driven OGGM with a range of climate projections from different GCMs until 2100 and where available in a different run again until 2300. All the climate projections that are available on our cluster have been used. There are three categories projections available: CMIP6, CMIP6 GCMs from the bias-corrected CMIP6 ISIMIP3b GCMs <https://www.isimip.org/gettingstarted/isimip3b-bias-adjustment/>_, and CMIP5 GCMs. An overview of the amount of GCMs per scenario and the resulting global volume changes is given in the figures below. Feel free to make a selection that suites your purpose when using the data.
+Since OGGM v1.6.1, each version of OGGM now provides a set of global glacier
+projections realized with the default set-up of OGGM for that version.
+We provide an OGGM simulation for all climate models we are aware of and have
+access to.
+
+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>`_.
+
+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,
+and use the W5E5v2.0 climate dataset `(Lange et al., 2021) <https://doi.org/10.48364/ISIMIP.342217>`_
+for the historical climate.
+
+We have driven OGGM with a range of climate projections from different GCMs until 2100 and,
+where available, once more until 2300. All the climate projections products that are available
+on our cluster have been used.
+
+There are three categories available: CMIP6, CMIP6 GCMs from the
+`bias-corrected ISIMIP3b GCMs <https://www.isimip.org/gettingstarted/isimip3b-bias-adjustment/>`_,
+and CMIP5 GCMs. An overview of the number of GCMs per scenario and the resulting
+global glacier volume changes is given in the figures below.
+Feel free to make a selection of GCMs that suits your purpose when using the data.
 
 .. figure:: _static/global_glacier_volume_until2100_common_running_2100_oggm_v16.png
-   :width: 80%
-   :align: left
+    :width: 100%
+    :align: left
 
-    Global glacier volume from 2000 to 2100 relative to 2020 (in %) for the different CMIP options using the common running glaciers until 2100. The amount of GCMs per scenario is given in the legend.
+    Global glacier volume from 2000 to 2100 relative to 2020 (in %) for the different CMIP options using the common running glaciers in all experiments until 2100. The amount of GCMs per scenario is given in the legend.
 
 
 .. figure:: _static/global_glacier_volume_oggm_v16_2300.png
-   :width: 60%
-   :align: center
-
-    Global glacier volume in 2300 relative to 2020 (in %) using all available climate scenarios by using the common running glaciers until 2100 and 2300. The amount of GCMs per scenario is given in the xtick labels.
-    Attention: the GCMs until 2300 do not represent very well the ensemble until 2100. For example, the CMIP6 GCMs until 2300 are rather hotter until 2100 compared to the entire CMIP6 GCM ensemble. 
-
-
-Currently we make these future CMIP forced global glacier simulations available in two different formats, raw and aggregated data.
-- Aggregated data is provided for both glacier volume and area evolution in csv-files, aggregated globally and for every RGI region separately. 
-    - Failing glaciers have been removed for the aggregation, a summary table is given here <https://github.com/OGGM/oggm-standard-projections-csv-files/blob/main/notebooks/missing_glacier_area_stats.png>_
-    - A further explanation on the failing glaciers and aggregation in general can be found in the README <https://github.com/OGGM/oggm-standard-projections-csv-files/blob/main/README.md>_ file.
-    - files available on the `OGGM/oggm-standard-projections-csv-files repository <https://github.com/OGGM/oggm-standard-projections-csv-files/tree/main>`_ which is also linked to citable Zenodo repository. On the OGGM cluster, you can also access the data directly from `https://cluster.klima.uni-bremen.de/~oggm/oggm-standard-projections/oggm-standard-projections-csv-files/ <https://cluster.klima.uni-bremen.de/~oggm/oggm-standard-projections/oggm-standard-projections-csv-files/>`_. 
-
-- raw data is provided per-glacier for all interesting variables on netCDF files with 1000 glaciers each (e.g. monthly or annual runoff components, volume below sea-level, ... ).
-    - `extended README <https://github.com/OGGM/oggm-standard-projections-csv-files/blob/main/README_extended_per_glacier_files.md>`_
-    - files available from the OGGM cluster:
-        - for OGGM v1.6.1, it is: `https://cluster.klima.uni-bremen.de/~oggm/oggm-standard-projections/oggm_v16/2023.3/ <https://cluster.klima.uni-bremen.de/~oggm/oggm-standard-projections/oggm_v16/2023.3/>`_
+    :width: 100%
+    :align: left
 
-The following jupyter notebooks give additional informations:
-- analysis of aggregated files is in `this notebook <https://github.com/OGGM/oggm-standard-projections-csv-files/blob/main/notebooks/analyse_csv_files_1.6.1.ipynb>`_
-- regional or global aggregation workflow and analysis of the common running glaciers that run for all glaciers until 2100 or until 2100 and 2300 is `here <https://github.com/OGGM/oggm-standard-projections-csv-files/blob/main/notebooks/aggregate_csv_files_1.6.1.ipynb>`_
-- comparison to Rounce et al., 2023 is `here <https://github.com/OGGM/oggm-standard-projections-csv-files/blob/main/notebooks/compare_oggm_1.6.1_to_rounce_et_al_2023.ipynb>`_
-- some example analysis of the additional provided data raw oggm-output is `here <https://nbviewer.org/urls/cluster.klima.uni-bremen.de/~oggm/oggm-standard-projections/analysis_notebooks/workflow_to_analyse_per_glacier_projection_files.ipynb?flush_cache=true>`_. 
+    Global glacier volume in 2300 relative to 2020 (in %) using all available climate scenarios for all common running glaciers until 2100 and 2300. The amount of GCMs per scenario is given in the xtick labels. Note that the GCMs until 2300 do not represent very well the ensemble until 2100. For example, the CMIP6 GCMs until 2300 are rather hotter until 2100 compared to the entire CMIP6 GCM ensemble.
 
+For more information and access to the data, visit the
+`OGGM/oggm-standard-projections-csv-files <https://github.com/OGGM/oggm-standard-projections-csv-files>`_
+reposity.
 
 Data usage requirements
 -----------------------
 
-When you use the aggregated or the raw per-glacier data, please cite the dataset via:
+When using the aggregated or the raw per-glacier data, please cite the dataset via:
 - TODO: zenodo-link ...
 
-In addition, cite `OGGM <https://doi.org/10.5194/gmd-12-909-2019>`_ and the CMIP option that you are using (references in this `README <https://github.com/OGGM/oggm-standard-projections-csv-files/blob/main/README.md>`_).
+In addition, refer to `OGGM <https://doi.org/10.5194/gmd-12-909-2019>`_
+and the CMIP option that you are using
+(references in this `README <https://github.com/OGGM/oggm-standard-projections-csv-files/blob/main/README.md>`_).