Add Seaborn diagnostic

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

@@ -0,0 +1,9 @@
+.. _api.esmvaltool.diag_scripts.seaborn_diag:
+
+Seaborn Diagnostic
+==================
+
+.. automodule:: esmvaltool.diag_scripts.seaborn_diag
+   :no-members:
+   :no-inherited-members:
+   :no-show-inheritance:

doc/sphinx/source/api/esmvaltool.rst

@@ -28,3 +28,4 @@ Diagnostic Scripts
    esmvaltool.diag_scripts.monitor
    esmvaltool.diag_scripts.ocean
    esmvaltool.diag_scripts.psyplot_diag
+   esmvaltool.diag_scripts.seaborn_diag

doc/sphinx/source/faq.rst

@@ -121,3 +121,10 @@ Moreover, recipe :ref:`recipes_psyplot_diag` and the corresponding diagnostic
 :ref:`psyplot_diag.py <api.esmvaltool.diag_scripts.psyplot_diag>` provide a
 high-level interface to the `Psyplot <https://psyplot.github.io/>`__ package
 which can be used to create a large variety of different plots.
+
+Similarly, recipe :ref:`recipes_seaborn_diag` and the corresponding diagnostic
+:ref:`seaborn_diag.py <api.esmvaltool.diag_scripts.seaborn_diag>` provide a
+high-level interface to the `Seaborn <https://seaborn.pydata.org>`__ package
+which can also be used to create a large variety of different plots.
+
+See also :ref:`general_purpose_diags`.

doc/sphinx/source/recipes/index.rst

@@ -10,6 +10,21 @@ ESMValTool for all available recipes can be accessed `here
 .. toctree::
    :maxdepth: 1
 
+.. _general_purpose_diags:
+
+General-purpose diagnostics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Recipes that use highly costumizable diagnostics which are designed to plot a
+large variety of input data.
+
+.. toctree::
+   :maxdepth: 1
+
+   recipe_monitor
+   recipe_psyplot
+   recipe_seaborn
+
 Atmosphere
 ^^^^^^^^^^
 .. toctree::
@@ -121,9 +136,7 @@ Other
    recipe_ensclus
    recipe_esacci_lst
    recipe_examples
-   recipe_monitor
    recipe_multimodel_products
-   recipe_psyplot
    recipe_pv_capacity_factor
    recipe_rainfarm
    recipe_seaice

doc/sphinx/source/recipes/recipe_bock20jgr.rst

@@ -82,7 +82,7 @@ User settings in recipe
    * time_avg: type of time average (currently only "yearly" and "monthly" are
      available).
    * ts_anomaly: calculates anomalies with respect to the defined reference
-     period; for each gird point by removing the mean for the given
+     period; for each grid point by removing the mean for the given
      calendar month (requiring at least 50% of the data to be
      non-missing)
    * ref_start: start year of reference period for anomalies
@@ -151,7 +151,7 @@ User settings in recipe
 
    * Required settings (variables)*
 
-   * reference_dataset: name of reference datatset
+   * reference_dataset: name of reference dataset
 
    *Optional settings (variables)*
 
@@ -229,8 +229,8 @@ User settings in recipe
      large multi-dimensional datasets, this might significantly reduce the
      computation time if only the multi-model mean dataset is relevant.
    * output_attributes: *dict*. Write additional attributes to netcdf files.
-   * seaborn_settings: *dict*. Options for :func:`seaborn.set` (affects all
-     plots).
+   * seaborn_settings: *dict*. Options for :func:`seaborn.set_theme` (affects
+     all plots).
 
 
 Variables
@@ -375,20 +375,20 @@ Example plots
    :align:   center
    :width:   9cm
 
-   Relative space-time root-mean-square deviation (RMSD) calculated from the 
-   climatological seasonal cycle of the CMIP3, CMIP5, and CMIP6 simulations 
-   (1980-1999) compared to observational data sets (Table 5). A relative 
-   performance is displayed, with blue shading being better and red shading 
-   worse than the median RMSD of all model results of all ensembles. A diagonal 
-   split of a grid square shows the relative error with respect to the reference 
-   data set (lower right triangle) and the alternative data set (upper left 
-   triangle) which are marked in Table 5. White boxes are used when data are not 
+   Relative space-time root-mean-square deviation (RMSD) calculated from the
+   climatological seasonal cycle of the CMIP3, CMIP5, and CMIP6 simulations
+   (1980-1999) compared to observational data sets (Table 5). A relative
+   performance is displayed, with blue shading being better and red shading
+   worse than the median RMSD of all model results of all ensembles. A diagonal
+   split of a grid square shows the relative error with respect to the reference
+   data set (lower right triangle) and the alternative data set (upper left
+   triangle) which are marked in Table 5. White boxes are used when data are not
    available for a given model and variable (Fig. 6).
 
 .. _fig_bock20jgr_5:
 .. figure::  /recipes/figures/bock20jgr/patterncor.png
    :align:   center
    :width:   9cm
 
-   Centered pattern correlations between models and observations for the annual 
-   mean climatology over the period 1980–1999 (Fig. 7). 
+   Centered pattern correlations between models and observations for the annual
+   mean climatology over the period 1980–1999 (Fig. 7).

doc/sphinx/source/recipes/recipe_ecs.rst

@@ -54,8 +54,8 @@ User settings in recipe
      script or as absolute path.
    * ``savefig_kwargs``, *dict*, optional: Keyword arguments for
      :func:`matplotlib.pyplot.savefig`.
-   * ``seaborn_settings``, *dict*, optional: Options for :func:`seaborn.set`
-     (affects all plots).
+   * ``seaborn_settings``, *dict*, optional: Options for
+     :func:`seaborn.set_theme` (affects all plots).
    * ``sep_year``, *int*, optional (default: ``20``): Year to separate
      regressions of complex Gregory plot. Only effective if
      ``complex_gregory_plot`` is ``True``.
@@ -79,8 +79,8 @@ User settings in recipe
      data.
    * ``savefig_kwargs``, *dict*, optional: Keyword arguments for
      :func:`matplotlib.pyplot.savefig`.
-   * ``seaborn_settings``, *dict*, optional: Options for :func:`seaborn.set`
-     (affects all plots).
+   * ``seaborn_settings``, *dict*, optional: Options for
+     :func:`seaborn.set_theme` (affects all plots).
    * ``sort_ascending``, *bool*, optional (default: ``False``): Sort bars in
      ascending order.
    * ``sort_descending``, *bool*, optional (default: ``False``): Sort bars in
@@ -98,8 +98,8 @@ User settings in recipe
    * ``dataset_style``, *str*, optional: Name of the style file (located in
      :mod:`esmvaltool.diag_scripts.shared.plot.styles_python`).
    * ``pattern``, *str*, optional: Pattern to filter list of input files.
-   * ``seaborn_settings``, *dict*, optional: Options for :func:`seaborn.set`
-     (affects all plots).
+   * ``seaborn_settings``, *dict*, optional: Options for
+     :func:`seaborn.set_theme` (affects all plots).
    * ``y_range``, *list of float*, optional: Range for the Y axis of the plot.
 
 

doc/sphinx/source/recipes/recipe_ipccwg1ar5ch9.rst

@@ -14,8 +14,8 @@ rather than constantly having to "re-invent the wheel".
 
 .. note::
 
-    Please note that most recipes have been modified to include only models that are 
-    (still) readily available via ESGF. Plots produced may therefore look different 
+    Please note that most recipes have been modified to include only models that are
+    (still) readily available via ESGF. Plots produced may therefore look different
     than the original figures from IPCC AR5.
 
 The plots are produced collecting the diagnostics from individual recipes. The
@@ -95,16 +95,16 @@ following figures from Flato et al. (2013) can currently be reproduced:
       calculated as the standard deviation of the annual means over the period
       1986–2005.
 
-    * Figure 9.38: Seasonal cycle for the surface temperature or precipitation 
-      over land within defined regions multi-model mean and difference to 
+    * Figure 9.38: Seasonal cycle for the surface temperature or precipitation
+      over land within defined regions multi-model mean and difference to
       reference dataset or absolute annual cycle can be chosen.
 
-    * Figure 9.39: Seasonal bias box and whiskers plot 
+    * Figure 9.39: Seasonal bias box and whiskers plot
       for surface temperature or precipitation within
       SREX (IPCC Special Report on Managing the Risks of Extreme Events and
       Disasters to Advance Climate Change Adaptation) regions.
 
-    * Figure 9.40: Seasonal bias box and whiskers plot for surface 
+    * Figure 9.40: Seasonal bias box and whiskers plot for surface
       temperature or precipitation within defined polar and ocean regions.
 
     * Figure 9.41b: Comparison between observations and models for variable
@@ -246,7 +246,7 @@ User settings in recipe
    * time_avg: type of time average (currently only "yearly" and "monthly" are
      available).
    * ts_anomaly: calculates anomalies with respect to the defined period; for
-     each gird point by removing the mean for the given calendar month
+     each grid point by removing the mean for the given calendar month
      (requiring at least 50% of the data to be non-missing)
    * ref_start: start year of reference period for anomalies
    * ref_end: end year of reference period for anomalies
@@ -360,7 +360,7 @@ User settings in recipe
    * fig938_mip_MMM: mip to average, default "Amon"
    * fig938_names_MMM: names in legend  i.e. (["CMIP5","CMIP3"]), default fig938_project_MMM
    * fig938_colors_MMM: Color for multi-model mean (e.g. ["red"]), default "red"
-   * If set fig938_mip_MMM, fig938_experiment_MMM, fig938_project_MMM, fig938_names_MMM, and fig938_colors_MMM must 
+   * If set fig938_mip_MMM, fig938_experiment_MMM, fig938_project_MMM, fig938_names_MMM, and fig938_colors_MMM must
      have the same number of elements
 
    * fig938_refModel: Reference data set for differences default "ERA-Interim"
@@ -453,7 +453,8 @@ User settings in recipe
      :mod:`esmvaltool.diag_scripts.shared.plot.styles_python.matplotlib`).
    * save: :obj:`dict` containing keyword arguments for the function
      :func:`matplotlib.pyplot.savefig`.
-   * seaborn_settings: Options for :func:`seaborn.set` (affects all plots).
+   * seaborn_settings: Options for :func:`seaborn.set_theme` (affects all
+     plots).
 
 .. _ch09_fig09_42b.py:
 
@@ -476,7 +477,8 @@ User settings in recipe
      ``marker_column``).  If a relative path is given, assumes that this is a
      pattern to search for ancestor files.
    * savefig_kwargs: Keyword arguments for :func:`matplotlib.pyplot.savefig`.
-   * seaborn_settings: Options for :func:`seaborn.set` (affects all plots).
+   * seaborn_settings: Options for :func:`seaborn.set_theme` (affects all
+     plots).
    * x_lim: Plot limits for X axis (ECS).
    * y_lim: Plot limits for Y axis (TCR).
 
@@ -573,12 +575,12 @@ References
   Tignor, M., and Midgley, P. M., Cambridge University Press, Cambridge, UK,
   and New York, NY, USA, 109-230.
 
-* Weigel, K., Bock, L., Gier, B. K., Lauer, A., Righi, M., Schlund, M., Adeniyi, K., 
-  Andela, B., Arnone, E., Berg, P., Caron, L.-P., Cionni, I., Corti, S., Drost, N., 
-  Hunter, A., Lledó, L., Mohr, C. W., Paçal, A., Pérez-Zanón, N., Predoi, V., Sandstad, 
-  M., Sillmann, J., Sterl, A., Vegas-Regidor, J., von Hardenberg, J., and Eyring, V.: 
-  Earth System Model Evaluation Tool (ESMValTool) v2.0 - diagnostics for extreme events, 
-  regional and impact evaluation, and analysis of Earth system models in CMIP, 
+* Weigel, K., Bock, L., Gier, B. K., Lauer, A., Righi, M., Schlund, M., Adeniyi, K.,
+  Andela, B., Arnone, E., Berg, P., Caron, L.-P., Cionni, I., Corti, S., Drost, N.,
+  Hunter, A., Lledó, L., Mohr, C. W., Paçal, A., Pérez-Zanón, N., Predoi, V., Sandstad,
+  M., Sillmann, J., Sterl, A., Vegas-Regidor, J., von Hardenberg, J., and Eyring, V.:
+  Earth System Model Evaluation Tool (ESMValTool) v2.0 - diagnostics for extreme events,
+  regional and impact evaluation, and analysis of Earth system models in CMIP,
   Geosci. Model Dev., 14, 3159-3184, https://doi.org/10.5194/gmd-14-3159-2021, 2021.
 
 
@@ -701,7 +703,7 @@ Example plots
    :align: center
 
    Figure 9.38tas: Mean seasonal cycle for surface temperature (tas)
-   as multi model mean of 38 CMIP5 and 22 CMIP6 models as well as 
+   as multi model mean of 38 CMIP5 and 22 CMIP6 models as well as
    CRU and ERA-Interim reanalysis data averaged
    for 1980-2005 over land in different regions:
    Western North America (WNA), Eastern North America (ENA),
@@ -710,15 +712,15 @@ Example plots
    North Africa (NAF), Central Africa (CAF), South Africa (SAF),
    North Asia (NAS), Central Asia (CAS), East Asia (EAS),
    South Asia (SAS), Southeast Asia (SEA), and Australia (AUS).
-   Similar to Fig. 9.38a from Flato et al. (2013), CMIP6 instead of CMIP3 and 
+   Similar to Fig. 9.38a from Flato et al. (2013), CMIP6 instead of CMIP3 and
    set of CMIP5 models used different.
 
 
 .. figure:: /recipes/figures/ipccwg1ar5ch9/fig-9-38-pr.png
    :align: center
 
    Figure 9.38pr: Mean seasonal cycle for precipitation (pr)
-   as multi model mean of 38 CMIP5 and 22 CMIP6 models as well as 
+   as multi model mean of 38 CMIP5 and 22 CMIP6 models as well as
    CRU and ERA-Interim reanalysis data averaged
    for 1980-1999 over land in different regions:
    Western North America (WNA), Eastern North America (ENA),
@@ -727,7 +729,7 @@ Example plots
    North Africa (NAF), Central Africa (CAF), South Africa (SAF),
    North Asia (NAS), Central Asia (CAS), East Asia (EAS),
    South Asia (SAS), Southeast Asia (SEA), and Australia (AUS).
-   Similar to Fig. 9.38b from Flato et al. (2013), CMIP6 instead of CMIP3 and 
+   Similar to Fig. 9.38b from Flato et al. (2013), CMIP6 instead of CMIP3 and
    set of CMIP5 models used different.
 
 .. figure:: /recipes/figures/ipccwg1ar5ch9/fig-9-38_regions.png
@@ -740,7 +742,7 @@ Example plots
 
    Figure 9.39tas: Box and whisker plots showing the 5th, 25th, 50th, 75th
    and 95th percentiles of the seasonal- and annual mean biases for
-   surface temperature (tas) for 1980-2005 between 38 CMIP5 models 
+   surface temperature (tas) for 1980-2005 between 38 CMIP5 models
    (box and whiskers) or 22 CMIP6 models (crosses) and CRU data.
    The regions are: Alaska/NW Canada (ALAs),
    Eastern Canada/Greenland/Iceland (CGIs), Western North America(WNAs),
@@ -756,15 +758,15 @@ Example plots
    Southern Australia/New Zealand (SAUs).
    The positions of these regions are defined following
    (Seneviratne et al., 2012) and differ from the ones in Fig. 9.38.
-   Similar to Fig. 9.39 a,c,e from Flato et al. (2013), CMIP6 instead of CMIP3 and 
+   Similar to Fig. 9.39 a,c,e from Flato et al. (2013), CMIP6 instead of CMIP3 and
    set of CMIP5 models used different.
 
 .. figure:: /recipes/figures/ipccwg1ar5ch9/fig-9-39-pr.png
    :align: center
 
    Figure 9.39pr: Box and whisker plots showing the 5th, 25th, 50th, 75th
    and 95th percentiles of the seasonal- and annual mean biases for
-   precipitation (pr) for 1980-2005 between 38 CMIP5 models 
+   precipitation (pr) for 1980-2005 between 38 CMIP5 models
    (box and whiskers) or 22 CMIP6 models (crosses) and CRU data.
    The regions are: Alaska/NW Canada (ALAs),
    Eastern Canada/Greenland/Iceland (CGIs), Western North America(WNAs),
@@ -780,7 +782,7 @@ Example plots
    Southern Australia/New Zealand (SAUs).
    The positions of these regions are defined following
    (Seneviratne et al., 2012) and differ from the ones in Fig. 9.38.
-   Similar to Fig. 9.39 b,d,f from Flato et al. (2013), CMIP6 instead of CMIP3 and 
+   Similar to Fig. 9.39 b,d,f from Flato et al. (2013), CMIP6 instead of CMIP3 and
    set of CMIP5 models used different.
 
 .. figure:: /recipes/figures/ipccwg1ar5ch9/fig-9-39_regions.png

doc/sphinx/source/recipes/recipe_seaborn.rst

@@ -0,0 +1,66 @@
+.. _recipes_seaborn_diag:
+
+Seaborn Diagnostics
+===================
+
+Overview
+--------
+
+These recipes showcase the use of the Seaborn diagnostic that provides a
+high-level interface to `Seaborn <https://seaborn.pydata.org>`__ for ESMValTool
+recipes.
+
+
+Available recipes and diagnostics
+---------------------------------
+
+Recipes are stored in recipes/
+
+   * recipe_seaborn.yml
+
+Diagnostics are stored in diag_scripts/
+
+   * :ref:`seaborn_diag.py <api.esmvaltool.diag_scripts.seaborn_diag>`
+
+
+Variables
+---------
+
+Arbitrary variables are supported.
+
+
+Observations and reformat scripts
+---------------------------------
+
+Arbitrary datasets are supported.
+
+
+References
+----------
+
+* Waskom, M. L. (2021), seaborn: statistical data visualization, Journal of
+  Open Source Software, 6(60), 3021, doi:10.21105/joss.03021.
+
+
+Example plots
+-------------
+
+.. _fig_seaborn_1:
+.. figure:: /recipes/figures/seaborn/ta_vs_lat.jpg
+   :align: center
+   :width: 50%
+
+   Monthly and zonal mean temperatures vs. latitude in the period 1991-2014 for
+   two Earth system models (CESM2-WACCM and GFDL-ESM4).
+   Colors visualize the corresponding pressure levels.
+
+.. _fig_seaborn_2:
+.. figure:: /recipes/figures/seaborn/regional_pr_hists.jpg
+   :align: center
+   :width: 50%
+
+   Spatiotemporal distribution of daily precipitation in the period 2005-2014
+   for six IPCC AR6 regions simulated by two Earth system models (CESM2-WACCM
+   and GFDL-ESM4).
+   Each day in each grid cell in the corresponding regions is considered with
+   equal weight.

doc/sphinx/source/recipes/recipe_tcr.rst

@@ -51,8 +51,8 @@ User settings in recipe
      path can be given relative to this diagnostic script or as absolute path.
    * ``savefig_kwargs``, *dict*, optional: Keyword arguments for
      :func:`matplotlib.pyplot.savefig`.
-   * ``seaborn_settings``, *dict*, optional: Options for :func:`seaborn.set`
-     (affects all plots).
+   * ``seaborn_settings``, *dict*, optional: Options for
+     :func:`seaborn.set_theme` (affects all plots).
 
 * Script climate_metrics/create_barplot.py