home.md

+
 ## Introduction
 
 This the GitLab repository for the SUNSET (SUbseasoNal to decadal climate forecast post-processIng and asSEmenT suite), a modular tool for subseasonal to seasonal to decadal forecast verification workflows. It is intended to have a modularized structure, where each module is a separate part of the code that performs a specific task, so that parts of the workflow can be skipped or reordered.
@@ -16,16 +17,20 @@ This tool is in the early stages of development, so the code and the information
 
 Some use cases are available as hands-on examples of how to use SUNSET:
 
+0. Sample dataset - no data files needed
+- [Hands-on 0.1: Loading a sample dataset](https://gitlab.earth.bsc.es/es/sunset/-/blob/master/use_cases/ex0_1_sample_dataset/ex0_1-handson.md)
 1. General usage
 - [Hands-on 1.1: Single Verification Workflow on the Terminal](https://earth.bsc.es/gitlab/es/sunset/-/blob/master/use_cases/ex1_1_single_analysis_terminal/ex1_1-handson.md)
 - [Hands-on 1.2: Computation of Scorecards with Autosubmit](https://earth.bsc.es/gitlab/es/sunset/-/blob/master/use_cases/ex1_2_autosubmit_scorecards/ex1_2-handson.md)
 - [Hands-on 1.3: Computation of El Niño indices for two seasonal models](https://earth.bsc.es/gitlab/es/sunset/-/blob/master/use_cases/ex1_3_nino_indices_comparison/ex1_3-handson.md)
+- [Hands-on 1.4: Obtaining a map for the probability of exceeding 50 mm](https://gitlab.earth.bsc.es/es/sunset/-/blob/master/use_cases/ex1_4_abs_threshold/ex1_4-handson.md)
+- [Hands-on 1.5: Blending observations and forecasts for climate indicators](https://gitlab.earth.bsc.es/es/sunset/-/blob/master/use_cases/ex1_5_blending/ex1_5-handson.md)
 
 ## Recipes
 
-In order to use SUNSET, users must define a recipe containing all the information pertaining to their workflow.
+In order to use SUNSET, users must define a recipe containing all the information pertaining to their workflow. The complete list of recipe parameters, along with their descriptions, can be found in this [recipe template](https://gitlab.earth.bsc.es/es/sunset/-/blob/master/recipe_template.yml).
 
-Here is an example of a recipe to load monthly mean ECMWF System 5 data from `/esarchive/`, with a 1993 to 2016 hindcast period, the corresponding ERA5 observations, and a 2020 forecast for the November initialization, for the months of November and December. 
+Below is an example of a recipe to load monthly mean ECMWF System 5 data from `/esarchive/`, with a 1993 to 2016 hindcast period, the corresponding ERA5 observations, and a 2020 forecast for the November initialization, for the months of November and December. 
 
 Following this recipe, the observations will be interpolated to the experiment grid (Regrid type: 'to_system') using bilinear interpolation. The hindcast and forecast will be calibrated using Quantile Mapping, and the Ranked Probability Skill Score (RPSS) and Continuous Ranked Probability Skill Score (CRPSS) will be computed. 
 The terciles (1/3, 2/3), quartiles (1/4, 2/4, 3/4), extremes (1/10, 9/10) and their corresponding probability bins will also be computed. Any output files will be saved inside the output directory.
@@ -107,38 +112,46 @@ Run:
 
 ## List of /esarchive/ datasets
 
-Here is a list of the datasets that can currently be loaded by the tool. To request that an additional dataset be added, please [open an issue](https://earth.bsc.es/gitlab/es/sunset/-/issues).
+Here is a list of the datasets stored in BSC-ES's `esarchive` that can currently be loaded by the tool. To request that an additional dataset be added, please [open an issue](https://earth.bsc.es/gitlab/es/sunset/-/issues).
+
+### Subseasonal datasets
+
+File: `conf/archive_subseasonal.yml`
+
+Systems:
+|  Forecast System           | Weekly mean     | Daily mean | /esarchive/exp/ path    |
+|----------------------------|-----------------|------------|-------------------------|
+| **NCEP-CFSv2**             | Yes             | No         |        ncep/cfs-v2/     |
 
 ### Seasonal datasets
 
+File: `conf/archive_seasonal.yml`
+
 Systems:
 |  Forecast System           | Monthly mean    | Daily mean | /esarchive/exp/ path    |
 |----------------------------|-----------------|------------|-------------------------|
 | **ECMWF-SEAS5**            | Yes             | Yes        | ecmwf/system5c3s/       |
 | **ECMWF-SEAS5.1**          | Yes             | Yes        | ecmwf/system51c3s/      |
-| **DWD-GCFS2.1**            | Yes             | No         | dwd/system21_m1/        |
+| **DWD-GCFS2.1**            | Yes             | No         | dwd/system21c3s/        |
+| **DWD-GCFS2.2**            | Yes             | No         | dwd/system22c3s/        |
 | **CMCC-SPS3.5**            | Yes             | No         | cmcc/system35c3s/       |
+| **CMCC-SPS4.0**            | Yes             | No         | cmcc/system4c3s/       |
 | **Meteo-France-System7**   | Yes             | No         | meteofrance/system7c3s/ |
 | **Meteo-France-System8**   | Yes             | No         | meteofrance/system8c3s/ |
+| **Meteo-France-System9**   | Yes             | No         | meteofrance/system9c3s/ |
 | **JMA-CPS2**               | Yes             | No         | jma/system2c3s/         |
-| **JMA-CPS3**               | Yes             | No         | jma/system2c3s/         |
-| **ECCC-CanCM4i (v3)**      | Yes             | No         | eccc/eccc3/             |
-| **GEM5.2-NEMO**            | Yes             | No         | eccc/eccc5/             |
+| **JMA-MRI-CPS3**           | Yes             | No         | exp/jma/system3c3s/     |
+| **ECCC-CanCM4i**           | Yes             | No         | eccc/eccc1/             |
+| **ECCC-GEM5.2-NEMO**       | Yes             | No         | eccc/eccc5/             |
 | **UK-MetOffice-GloSea600** | Yes             | No         | ukmo/glosea6_system600-c3s/ |
 | **UK-MetOffice-GloSea601** | Yes             | No         | ukmo/glosea6_system601-c3s/ |
 | **UK-MetOffice-GloSea602** | Yes             | No         | ukmo/glosea6_system602-c3s/ |
 | **UK-MetOffice-GloSea603** | Yes             | No         | ukmo/glosea6_system603-c3s/ |
+| **UK-MetOffice-GloSea604** | Yes             | No         | ukmo/glosea6_system603-c3s/ |
 | **NCEP-CFSv2**             | Yes             | No         | ncep/cfs-v2/           |
-| **NCEP System 2*           | Yes             | No         | ncep/system2c3s/        |
-
-Observations:
-|  Reference    | Monthly mean | Daily mean | /esarchive/recon/ path |
-|---------------|--------------|------------|------------------------|
-| **ERA5**      | Yes          | Yes        | ecmwf/era5/            |
-| **ERA5-Land** | `tas` only   | Yes        | ecmwf/era5land/        |
-| **UERRA**     | No           | `tas` only | ecmwf/uerra_mescan/    |
 
 ### Decadal datasets
+File: `conf/archive_decadal.yml`
 
 Systems:
 |  Forecast System       | Monthly mean | Daily mean | forecast (DCPP-B)? |
@@ -159,15 +172,24 @@ Systems:
 | **NorCPM1-i1**         | Yes          | Yes        | No                 |
 | **NorCPM1-i2**         | Yes          | Yes        | No                 |
 
-Observations:
-|  Reference    | Monthly mean | Daily mean |
-|---------------|--------------|------------|
-|  **GHCNv4**   | Yes          | No         |
-| **ERA5**      | Yes          | Yes        |
-| **JRA-55**    | Yes          | Yes        |
-| **GISTEMPv4** | Yes          | No         |
-| **HadCRUT4**  | Yes          | No         |
-| **HadSLP2**   | Yes          | No         |
+
+### Reference datasets
+
+File: `conf/archive_reference.yml`
+
+|  Reference    | Monthly mean | Weekly mean |Daily mean | /esarchive/ path |
+|---------------|--------------|------------|------------|------------------------|
+| **ERA5**      | Yes          | Yes        | Yes        | recon/ecmwf/era5/            |
+| **ERA5-Land** | Yes          | No         | Yes        | recon/ecmwf/era5land/        |
+| **UERRA**     | Yes          | No         | Yes        | recon/ecmwf/uerra_mescan/    |
+| **CERRA**     | Yes          | No         | Yes        | recon/ecmwf/cerra/           |
+| **HadCRUT4**  | Yes          | No         | Yes        | obs/ukmo/hadcrut_v4.6/       |
+| **HadCRUT5**  | Yes          | No         | Yes        | obs/ukmo/hadcrut_v5.0_analysis/   |
+| **BEST**      | Yes          | No         | Yes        | obs/berkeleyearth/berkeleyearth/   |
+| **GHCNv4**    | Yes          | No         | Yes        | obs/noaa/ghcn_v4/   |
+| **JRA55**     | Yes          | No         | Yes        | recon/jma/jra55/  |
+| **GISTEMPv4** | Yes          | No         | Yes        | obs/noaa-nasa/ghcnersstgiss/  |
+| **HadSLP2**   | Yes          | No         | Yes        | obs/ukmo/hadslp_v2/  |
 
 ## The first steps
 
@@ -288,6 +310,49 @@ data <- Anomalies(recipe = recipe, data = data)
       cross_validation: no # Either yes/true or no/false (Mandatory if 'compute: yes', bool)
       save: 'fcst_only' # Options: 'all', 'none', 'exp_only', 'fcst_only' (Mandatory if 'compute: yes', str) 
 ```
+## Indicators module
+
+The Calibration module performs bias correction on the loaded data. It accepts the output of the Loading module as input, and also requires the recipe. It applies the selected bias correction method to the hindcast and forecast data using the observations as a reference, and returns the calibrated data and its metadata as an `s2dv_cube` object.
+
+The output of the main function, `Calibration()`, is a list containing the calibrated hindcast and forecast, named hcst and fcst respectively. fcst will be `NULL` if no forecast years have been requested.
+
+### How to call it
+
+```r
+data <- Indicators(recipe = recipe, data = data)
+```
+
+### Indicators currently available:
+
+Indicators may be requested by name in the `Workflow:Indicators:name` section of the recipe. **The user can only request one tyoe of indicator per recipe.** This is a list of the indicators currently available:
+
+- **Heat Index**: Request as `"HeatIndex"`. Requires temperature and relative humidity. It is computed via `modules/Indicators/R/Heat_Index.R`.
+
+- Mosquito-borne disease suitability indicators: Request any of the following: `"aedesaegypti", "aedesalbopictus", "culexpipiens", "leishmaniasisphlebotomus", "malariavivax", "malariafalciparum", "ticksixodes", "tickshyalomma"`.  May require temperature, relative humidity and/or precipitation. Calculated via `modules/Indicators/R/MosquitoBinaryProbabilities.R` 
+
+### Recipe template:
+
+```yaml
+ Indicators:
+   name:  HeatIndex  # name of the indicator to be computed
+   method:  mean  #aggregation function applied over the time dimension
+   #      - NULL : no temporal aggregation (original time resolution)(period must be NULL as well)
+   #      - mean, max, min, sd, IQR
+   #      - quantile-based functions (e.g. p90 = quantile(x, 0.9), p66, p50)
+   period:  2monthly  #temporal period over which the aggregation is computed
+   #      - NULL    : full available period
+   #      - XXmonthly : monthly aggregation every XX month
+   # period and start/end cannot be selecetd at the same time
+   start: 
+   #      - Character string in format: 'monthday' as: '0601'
+   end:
+   #      - Character string in format: 'monthday' as: '0631'
+   user_def:  # To be defined, not available yet
+   cal_window_size:  2  # size of the calibration window. (Integer)
+   #                  Used for Crossval_indicators.R if data frequency is daily/daily_mean.
+   save:  'all'  # Options: 'all', 'none', 'exp_only', 'fcst_only' (Mandatory, str)str) 
+```
+
 
 ## Downscaling Module
 
@@ -633,18 +698,39 @@ Visualization(recipe = recipe, data = data,
 
 ```yaml
  Visualization:
-      plots: skill_metrics, most_likely_terciles, forecast_map, extreme_probabilities # Types of plots to generate (Optional, str)
+   plots:  skill_metrics,  forecast_map,  most_likely_terciles,  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)
-      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)
+   # skill_metrics:
+   significance:  'dots'  # Type of mark for statistical non-significance/significance in plot_metrics.  Options are 'dots', and 'yes'/'no'. Options 'mask' and 'both' are available for the cylindrical_equidistant projection.
+   dots_on_points_significance:  "non-significant"  # Which grid points to dot in skill_metrics, if dots are requested. Either 'significant' or 'non-significant'. Requires 'significance' to be 'dots' or 'both'. Default is 'non-significant'.
+   # forecast_map:
+   mask_ens:  no  # Whether to mask the negatively correlated points in the forecast_map mean plot. yes/true, no/false or 'both'. Default is no/false. (Optional, str)
+   dots_ens:  no  # Whether to dot the negatively/positively correlated points in the forecast_map plot. yes/true, no/false or 'both'. Default is no/false. (Optional, str)
+   dots_on_points_ens:  "negative"  # Which grid points to dot by ensemble correlation in forecast_map. Either 'negative' or 'positive'. Requires 'dots_ens' to be true.
+   # most_likely_terciles and extreme_probabilities:
+   mask_rpss:  no  # Whether to mask the negative rpss points in the most_likely_tercile and extreme_probabilities plots. yes/true, no/false or 'both'. Default is no/false. (Optional, str)
+   dots_rpss:  yes  # Whether to dot the negative/positive rpss points in the most_likely_tercile and extreme_probabilities plots. yes/true, no/false or 'both'. Default is no/false. (Optional, str)
+   dots_on_points_rpss:  "negative"  # Which grid points to dot by rpss in most_likely_terciles and extreme_probabilities. Either 'negative' or 'positive'. Requires 'dots_rpss' to be true.
+   # extreme_probabilities:
    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.
+   location_plots:
+     execute:  yes  # Whether to execute the location plots
+     type:  bar_plot  # Types of location plots to be included. Options: bar_plot. (str)
+     probability_sets:
+       # List of probability sets to include in the bar plots. 
+       # The names in 'probs' and 'extremes' must match the names of probability
+       # categories specified in the 'Probabilities' section.
+       -  set1:  {probs:  "Terciles",  extremes:  ["P10",  "P90"],  category_names:  ["Below normal",  "Normal",  "Above normal"]}
+       # - set2: {probs: "Terciles", category_names: ["Below normal", "Normal", "Above normal"]}
+       # - set3: {probs: "Quintiles", category_names: ["Very below normal", "Below normal", "Normal", "Above normal", "Very above normal"]}
+     points:
+       # List of point locations.
+       -  {name:  'Kuwait City',  lat:  29.3,  lon:  47.6,  region:  "Kuwait"} # Region name is mandatory and should match one of the regions defined in the 'Region' section.
+      # - {name: 'Barcelona', lat: 40.4, lon: -3.7, region: "Iberia"}
 ```