Add general model evaluation recipes (for Changelog: authors: @axel-lauer, @hb326, @Paulinebonnet111, @LisaBock, @schlunma)

doc/sphinx/source/api/esmvaltool.diag_scripts.monitor.rst

@@ -11,6 +11,7 @@ Examples
 --------
 
 * :ref:`recipe_monitor`
+* :ref:`recipe_model_evaluation`
 
 
 Diagnostic scripts

doc/sphinx/source/faq.rst

@@ -113,9 +113,15 @@ a symbolic link to it so it gets picked up at every re-run iteration:
 Can ESMValTool plot arbitrary model output?
 ===========================================
 
-Recipe :ref:`recipe_monitor` allows for the plotting of any preprocessed model.
-The plotting parameters are set through a yaml configuration file, and the
-type of plots to be generated are determined in the recipe.
+:ref:`recipe_model_evaluation` provides a set of recipes that can be used for a
+basic climate model evaluation with observational data.
+This is especially useful to get an overview of the general performance of a
+simulation.
+
+Furthermore, recipe :ref:`recipe_monitor` allows for the plotting of any
+preprocessed model.
+The plotting parameters are set through a yaml configuration file, and the type
+of plots to be generated are determined in the recipe.
 
 Moreover, recipe :ref:`recipes_psyplot_diag` and the corresponding diagnostic
 :ref:`psyplot_diag.py <api.esmvaltool.diag_scripts.psyplot_diag>` provide a

doc/sphinx/source/recipes/index.rst

@@ -21,6 +21,7 @@ large variety of input data.
 .. toctree::
    :maxdepth: 1
 
+   recipe_model_evaluation
    recipe_monitor
    recipe_psyplot
    recipe_seaborn

doc/sphinx/source/recipes/recipe_model_evaluation.rst

@@ -0,0 +1,98 @@
+.. _recipe_model_evaluation:
+
+General model evaluation
+========================
+
+Overview
+--------
+
+These recipes and diagnostics provide a basic climate model evaluation with
+observational data.
+This is especially useful to get an overview of the performance of a
+simulation.
+The diagnostics used here allow plotting arbitrary preprocessor output, i.e.,
+arbitrary variables from arbitrary datasets.
+
+
+Available recipes and diagnostics
+---------------------------------
+
+Recipes are stored in `recipes/model_evaluation`
+
+* recipe_model_evaluation_basics.yml
+* recipe_model_evaluation_clouds_clim.yml
+* recipe_model_evaluation_clouds_cycles.yml
+* recipe_model_evaluation_precip_zonal.yml
+
+Diagnostics are stored in `diag_scripts/monitor/`
+
+* :ref:`multi_datasets.py
+  <api.esmvaltool.diag_scripts.monitor.multi_datasets>`:
+  Monitoring diagnostic to show multiple datasets in one plot (incl. biases).
+
+
+User settings
+-------------
+
+It is recommended to use a vector graphic file type (e.g., SVG) for the output
+format when running this recipe, i.e., run the recipe with the command line
+option ``--output_file_type=svg`` or use ``output_file_type: svg`` in your
+:ref:`esmvalcore:user configuration file`.
+Note that map and profile plots are rasterized by default.
+Use ``rasterize: false`` in the recipe to disable
+this.
+
+
+Recipe settings
+~~~~~~~~~~~~~~~
+
+A list of all possible configuration options that can be specified in the
+recipe is given for each diagnostic individually (see links given for the
+available diagnostics in the previous section).
+
+
+Variables
+---------
+
+Any, but the variables' number of dimensions should match the ones expected by
+each diagnostic (see links given for the available diagnostics in the previous
+section).
+
+
+Example plots
+-------------
+
+.. _fig_1:
+.. figure::  /recipes/figures/model_evaluation/map_tas_MPI-ESM1-2-HR_Amon.jpg
+   :align:   center
+   :width:   14cm
+
+Global climatology of 2m near-surface air temperature.
+
+.. _fig_2:
+.. figure::  /recipes/figures/model_evaluation/map_swcre_MPI-ESM1-2-HR_Amon.jpg
+   :align:   center
+   :width:   14cm
+
+Global climatology of the shortwave cloud radiative effect (SWCRE).
+
+.. _fig_3:
+.. figure::  /recipes/figures/model_evaluation/timeseries_rtnt_ambiguous_dataset_Amon.jpg
+   :align:   center
+   :width:   14cm
+
+Time series of the global mean top-of-the-atmosphere net radiative flux.
+
+.. _fig_4:
+.. figure::  /recipes/figures/model_evaluation/variable_vs_lat_pr_Amon.jpg
+   :align:   center
+   :width:   14cm
+
+Zonal mean precipitation.
+
+.. _fig_5:
+.. figure::  /recipes/figures/model_evaluation/annual_cycle_clt_southerocean_Amon.jpg
+   :align:   center
+   :width:   14cm
+
+Annual cycle of Southern Ocean total cloud cover.

doc/sphinx/source/recipes/recipe_monitor.rst

@@ -18,19 +18,18 @@ Available recipes and diagnostics
 
 Recipes are stored in `recipes/monitor`
 
-   * recipe_monitor.yml
-   * recipe_monitor_with_refs.yml
+* recipe_monitor.yml
+* recipe_monitor_with_refs.yml
 
 Diagnostics are stored in `diag_scripts/monitor/`
 
-   * :ref:`monitor.py <api.esmvaltool.diag_scripts.monitor.monitor>`:
-     Monitoring diagnostic to plot arbitrary preprocessor output.
-   * :ref:`compute_eofs.py <api.esmvaltool.diag_scripts.monitor.compute_eofs>`:
-     Monitoring diagnostic to plot EOF maps and associated PC timeseries.
-   * :ref:`multi_datasets.py
-     <api.esmvaltool.diag_scripts.monitor.multi_datasets>`:
-     Monitoring diagnostic to show multiple datasets in one plot (incl.
-     biases).
+* :ref:`monitor.py <api.esmvaltool.diag_scripts.monitor.monitor>`:
+  Monitoring diagnostic to plot arbitrary preprocessor output.
+* :ref:`compute_eofs.py <api.esmvaltool.diag_scripts.monitor.compute_eofs>`:
+  Monitoring diagnostic to plot EOF maps and associated PC timeseries.
+* :ref:`multi_datasets.py
+  <api.esmvaltool.diag_scripts.monitor.multi_datasets>`:
+  Monitoring diagnostic to show multiple datasets in one plot (incl. biases).
 
 
 User settings