home.md

@@ -587,30 +587,35 @@ The Visualization module provides a few basic plots to visualize the data loaded
 - For 'S2S4E', the "bluered" palette is used.
 - For 'Scorecards', "purpleorange" is used.
 
-**Visualization()** is the main wrapper function for this module. It generates the plots and saves them to the same output directory described in the Saving module section, under `plots/`.
+`Visualization()` is the main wrapper function for this module. It generates the plots and saves them to the same output directory described in the Saving module section, under `plots/`.
 
 This function's parameters are similar to those in the Saving module: 
 
-`recipe` (the recipe) and `data` (the list obtained from the Loading module) are mandatory arguments. The rest of the arguments (`skill_metrics`, `probabilities`, and `significance`) are optional:
-- `skill_metrics`: List in the format of the Skill module output, containing the skill metrics as named arrays.
-- `probabilities`: List in the format of the Skill module output, containing the 33rd and 66th percentiles.
+- `recipe`: The user-defined recipe. Mandatory argument.
+- `data`: The list obtained from the Loading module. Mandatory argument. 
+- `skill_metrics`: List in the format of the Skill module output, containing the skill metrics as named arrays. Required for `skill_metrics` plot.
+- `statistics`: List in the format of the Statistics module output, containing the statistics as named arrays. Required when `statistics` is listed under `plots:` in the recipe. 
+- `probabilities`: List in the format of the Skill module output, containing the 33rd and 66th percentiles. Required for the `most_likely_terciles` and the `extreme_probabilities` plots.
 - If `significance = TRUE` (default), the statistical significance dots will be displayed in the plot, when available. It defaults to FALSE.
+- `output_conf`: configuration YAML file that allows customization of the appearance of plots based on the selected region, projection type, and plot type. It provides control over visual elements such as plot dimensions, font sizes, color bar margins, dot sizes, and other layout settings. This parameter is optional and the values defined here override the default plot settings. The file is located at `modules/Visualization/output_size.yml`, and users are encouraged to modify it according to their needs. If a region, projection, or plot type is not defined in the YAML file, the default plotting values will be used. If `output_conf` is defined in the repository, it does not need to be passed explicitly to the Visualization() function - it will be automatically loaded from the corresponding directory.
+- `logo`: Path to a `.jpg` image file to be added as a logo to the generated plots. SUNSET includes a BSC logo at `tools/BSC_logo_95.jpg`. To use it, pass the path to the Visualization() function as: `logo = "tools/BSC_logo_95.jpg"`. Optional parameter. If not provided, plots will be generated without a logo. 
 
-`Visualization()` attempts to generate:
+`Visualization()` generates the plots specified in the `plots:` field of the recipe, which can be:
 
-- Plots of all the skill metrics provided in `skill_metrics`.
-- A plot of the forecast ensemble mean, if a forecast has been provided.
-- A Most Likely Terciles plot, if the `probabilities` include the terciles (percentiles 33 and 66).
+- Plots of all the skill metrics provided in `skill_metrics`. To generate this, add `skill_metrics` in the `plots` field of the recipe.
+- A plot of the forecast map, if a forecast has been provided (`plots: forecast_map` in recipe). To generate this, add `forecast_map` in the `plots` field of the recipe. You can also specify the statistical method(s) used to compute the forecast values using the `forecast_method` field. Supported options are mean, median and/or IQR.  
+- A most likely terciles plot, if the `probabilities` include the terciles (percentiles 33 and 66). To generate this, add `most_likely_terciles` in the `plots` field of the recipe.
+- A plot of binary probabilities (ex: above and below the 10th percentile). To generate this, add `extreme_probabilities` in the `plots` field of the recipe.
 
-The three functions that `Visualization()` calls can also be called independently. In this case, archive configuration file and the the output directory for the plots will have to be provided explicitly as arguments to :
+The four plotting functions used by `Visualization()` can also be called independently. In this case, the archive configuration file and the output directory for the plots must be explicitly provided as arguments. Information on the parameters is available in each function’s documentation. The functions are as follows: 
 
-**plot_skill_metrics(recipe, archive, data_cube, skill_metrics, outdir, significance = F)**: Generates, for each metric in skill_metrics, a figure with one plot per time step, and saves each figure to the output directory `outdir` as `<metric>.png`.
+- **plot_metrics(recipe = recipe, data_cube = data_cube, metrics = skill_metrics, outdir = outdir, significance = F, output_conf = output_conf)**: Generates, for each metric in skill_metrics, a figure with one plot per time step, and saves each figure to the output directory `outdir` as `<metric>.png`. `data_cube` is an s2dv_cube containing the appropriate metadata, for example the hcst object that was passed to the Skill module.
 
-`data_cube` is an s2dv_cube containing the appropriate metadata, for example the hcst object that was passed to the Skill module.
+- **plot_forecast_map(recipe, fcst, outdir)**: Computes the forecast ensemble mean and generates a figure with one plot per time step, and saves it to the output directory `outdir` as `forecast_ensemble_mean.png`
 
-**plot_ensemble_mean(recipe, archive, fcst, outdir)**: Computes the forecast ensemble mean and generates a figure with one plot per time step, and saves it to the output directory `outdir` as `forecast_ensemble_mean.png`
+- **plot_most_likely_terciles(recipe, fcst, percentiles, outdir)**: Computes the forecast tercile probability bins with respect to the terciles provided in 'percentiles', then generates a figure with one plot per time step and saves it to the directory `outdir` as `forecast_most_likely_terciles.png`
 
-**plot_most_likely_terciles(recipe, archive, fcst, percentiles, outdir)**: Computes the forecast tercile probability bins with respect to the terciles provided in 'percentiles', then generates a figure with one plot per time step and saves it to the directory `outdir` as `forecast_most_likely_terciles.png`
+- **plot_extreme_probs(recipe, fcst, probabilities, outdir, output_conf, brks_min, brks_max)**: generates probability plots for binary extremes (e.g. 10th percentile). For each requested threshold two plots are created: one for the probability of falling below and another for above. One plot is generated per forecast time step and saved to the output directory `outdir` as `forecast_probability_<threshold>-<init_date>_ft<time>.png`. 
 
 ### How to call it
 
@@ -619,17 +624,27 @@ Visualization(recipe = recipe, data = data,
               skill_metrics = skill_metrics,
               statistics = statistics,
               probabilities = probabilities,
-              significance = TRUE)
+              significance = TRUE,
+              output_conf = output_conf,
+              logo = logo)
 ```
 
 ### Recipe template:
 
 ```yaml
     Visualization:
-      plots: skill_metrics, most_likely_terciles, forecast_ensemble_mean # Types of plots to generate (Optional, str)
+      plots: skill_metrics, most_likely_terciles, forecast_map, extreme_probabilities # Types of plots to generate (Optional, str)
+      forecast_method: mean, median, iqr # One or more methods for the 'forecast_map' plot. Available methods are: 'mean', 'median', 'IQR'. Default is 'median'. (Optional, str)
       multi_panel: yes # Multi-panel plot or single-panel plots. Default is 'no/false'. (Optional, bool)
       projection: 'cylindrical_equidistant' # Options: 'cylindrical_equidistant', 'robinson', 'lambert_europe'. Default is cylindrical equidistant. (Optional, str)
       significance: 'dots' # Type of mask for statistical significance. Options are 'dots', and yes/no. 'dots'. 'mask' and 'both' options are not available for projections other than cylindrical_equidistant.
       mask_terciles: no # Whether to mask the non-significant points by rpss in the most likely tercile plot. yes/true, no/false or 'both'. Default is no/false. (Optional, str)
       dots_terciles: yes # Whether to dot the non-significant by rpss in the most likely tercile plot. yes/true, no/false or 'both'. Default is no/false. (Optional, str)
-```
+      mask_ens: no # Whether to mask the non-significant points by rpss in the forecast ensemble mean plot. yes/true, no/false or 'both'. Default is no/false. (Optional, str)
\ No newline at end of file
+      shapefile: # path to a shapefile (*.shp) to include in the plots. Only available for the cylindrical equidistant projection. (Optional, str)
+      logo: tools/BSC_logo_95.jpg # path to a logo (*.png or *.jpg/jpeg) to include in the plots. (Optional, str)
+      file_format: 'PNG' # Final file format of the plots. Formats available: PNG, JPG, JPEG, EPS. Defaults to PDF. (Optional, str)
+      custom_dictionary: 'MyCase' # Name of the desired custom dictionary entry in modules/Visualization/var_long_names.yml. This allows the user to define custom long names for each variable to be displayed in the plots. (Optional, str)
+      brks_min: 5 # The lower bound for the range used to generate breaks for the color bar in the extreme probabilities plot. Default is 5.
+      brks_max: 95 # The upper bound for the range used to generate breaks for the color bar in the extreme probabilities plot. Default is 95.
+```