Radiation budget: labelling plots with alias (#4292)

Co-authored-by: Emma Hogan <ehogan@users.noreply.github.com>

Author: NParsonsMO

doc/sphinx/source/recipes/recipe_radiation_budget.rst

@@ -22,19 +22,25 @@ Available recipes and diagnostics
 
 Recipes are stored in esmvaltool/recipes/
 
-    * recipe_radiation_budget.yml
+* recipe_radiation_budget.yml
 
 Diagnostics are stored in esmvaltool/diag_scripts/radiation_budget/
 
-    * radiation_budget.py: Plot the global radiation budget.
-    * seasonal_radiation_budget.py: Write the global climatological seasonal radiation budget to a text file.
+* radiation_budget.py: Plot the global radiation budget.
+* seasonal_radiation_budget.py: Write the global climatological seasonal radiation budget to a text file.
 
 
 
 User settings in recipe
 -----------------------
 
-None
+Users may specify the label to appear in the plot legend for each model, using the keyword ``alias`` in the dataset.
+For example, the following dataset entry would label the model as "HadGEM3-GC3.1 N96ORCA1" in the plot legend:
+
+.. code-block:: yaml
+
+    {dataset: HadGEM3-GC31-LL, alias: HadGEM3-GC3.1 N96ORCA1, project: ... }
+
 
 
 Variables

esmvaltool/diag_scripts/radiation_budget/radiation_budget.py

@@ -291,8 +291,8 @@ def load_obs_data():
 
 
 def plot_data(
-    model_dataset,
     model_data,
+    model_label,
     model_period,
     obs_names,
     obs_unit,
@@ -307,11 +307,11 @@ def plot_data(
 
     Parameters
     ----------
-    model_dataset : string
-        The name of the model.
     model_data : list
         Data values from the model for which this comparison plot is being
         generated.
+    model_label : string
+        An identifier for the model dataset to be used in the plot legend.
     model_period : string
         The start and end years of the model dataset.
     obs_names : list
@@ -341,7 +341,7 @@ def plot_data(
     model_minus_ceres = np.array(model_data) - np.array(ceres_data)
 
     figure, axes = plt.subplots(figsize=(12, 8))
-    title = f"Radiation budget for {model_dataset}"
+    title = f"Radiation budget for {model_label}"
     y_label = f"Difference between model output and observations [{obs_unit}]"
     y_lim = (-20, 20)
     axes.set(title=title, ylabel=y_label, ylim=y_lim)
@@ -357,7 +357,7 @@ def plot_data(
         bar_width,
         alpha=opacity,
         color="cornflowerblue",
-        label=f"{model_dataset} ({model_period}) - Stephens et al. (2012)",
+        label=f"{model_label} ({model_period}) - Stephens et al. (2012)",
         yerr=stephens_error,
     )
     axes.bar(
@@ -367,7 +367,7 @@ def plot_data(
         alpha=opacity,
         color="orange",
         label=(
-            f"{model_dataset} ({model_period}) - {ceres_dataset} "
+            f"{model_label} ({model_period}) - {ceres_dataset} "
             f"({ceres_period})"
         ),
     )
@@ -377,7 +377,7 @@ def plot_data(
         bar_width,
         alpha=opacity,
         color="darkgrey",
-        label=f"{model_dataset} ({model_period}) - Demory et al. (2014)",
+        label=f"{model_label} ({model_period}) - Demory et al. (2014)",
     )
     axes.spines["bottom"].set_position(("data", 0))
     axes.spines["top"].set_position(("data", 0))
@@ -442,16 +442,20 @@ def main(config):
 
     for model_dataset, group in datasets.items():
         # 'model_dataset' is the name of the model dataset.
-        # 'group' is a list of dictionaries containing metadata.
+        # 'group' is a list of dictionaries containing metadata for each variable.
         logger.info("Processing data for %s", model_dataset)
         filenames = [item["filename"] for item in group]
         unordered_model_data = iris.load(filenames)
         all_model_data = derive_additional_variables(unordered_model_data)
         model_data = order_data(all_model_data, obs_names, obs_unit)
+        # An assumption has been made that the start_year, end_year and alias
+        # from the first variable in the list (for a given dataset)
+        # is the same as all the others.
         model_period = f"{group[0]['start_year']} - {group[0]['end_year']}"
+        model_label = group[0]["alias"]
         figure = plot_data(
-            model_dataset,
             model_data,
+            model_label,
             model_period,
             obs_names,
             obs_unit,

esmvaltool/recipes/recipe_radiation_budget.yml

@@ -18,9 +18,9 @@ documentation:
     - hogan_emma
 
 datasets:
-  - {dataset: HadGEM3-GC31-LL, project: CMIP6, exp: historical,
+  - {dataset: HadGEM3-GC31-LL, alias: HadGEM3-GC31-LL, project: CMIP6, exp: historical,
      ensemble: r1i1p1f3, grid: gn, start_year: 1993, end_year: 2002}
-  - {dataset: UKESM1-0-LL, project: CMIP6, exp: historical,
+  - {dataset: UKESM1-0-LL, alias: UKESM1-0-LL, project: CMIP6, exp: historical,
      ensemble: r5i1p1f3, grid: gn, start_year: 1993, end_year: 2002}
 
 preprocessors:
@@ -40,7 +40,7 @@ preprocessors:
 
 diagnostics:
   single_value_radiation_budget:
-    description: Radiation budget for HadGEM3 vs UKESM1.
+    description: Radiation budget.
     variables:
       rss:
         mip: Emon
@@ -92,7 +92,7 @@ diagnostics:
         script: radiation_budget/radiation_budget.py
 
   seasonal_radiation_budget:
-    description: Seasonal radiation budget for HadGEM3 vs UKESM1.
+    description: Seasonal radiation budget.
     variables:
       rss:
         mip: Emon