
SUNSET: SUbseasoNal to decadal climate forecast post-processing and asSEssmenT suite
======================

This is the Git project for the SUNSET, a collaborative in-house tool developed at BSC-ES for research projects and operational workflows involving subseasonal to seasonal to decadal forecast verification.

This is the Git project for SUNSET, an collaborative R-based tool developed in-house at BSC-ES that aims to provide climate services for sub-seasonal, seasonal and decadal climate forecast time scales. The tool post-processes climate forecast outputs by applying state-of-the-art methodologies to tailor climate products for each application and sector (e.g.: agriculture, energy, water management, or health).

Its modular design allows flexibility in defining the required post-processing steps, as well as the products definition by deciding on the forecast system and reference datasets, variables, and forecast horizon among others. The tool also allows for the creation and visualization of climate forecast products, such as maps for the most likely terciles, and performs the verification of the products, which can be visualized on maps and scorecards. The inclusion of a launcher script provides a user-friendly way to parallelize the computation on HPC machines.

Victòria Agudetse (@vagudets) is the maintainer of the SUNSET repository.


How to install SUNSET
---------

1. For BSC-ES users:

The first step to use SUNSET is to create a copy of the code in your local environment. Open a terminal and `cd` to the directory where you would like to store your local copy of SUNSET. For example: `/esarchive/scratch/<your_username>/git/`. If a directory does not exist yet, you can create it with the `mkdir` shell command.

```shell
# Clone the GitLab repository to create a local copy of the code
git clone https://earth.bsc.es/gitlab/es/sunset.git
```

If you are using BSC infrastructure, all of the software dependencies are already installed within our common environment. You can load them by going to the main folder of the repository and running the following lines:

```shell
source MODULES
```

2. For external users:

If you are running SUNSET outside of the BSC facilities, you can install the dependencies by creating a conda environment.

The first step is to clone the repository in your local computer. A script to install the conda environment is provided in the repository; you can install it by running the following line from the main folder:

```shell
bash conda_installation/load_sunset.bash <conda_dir>
```

After a successful installation, the terminal will show instructions on how to activate the environment.


Getting started with SUNSET
--------

The basic elements a user needs to create in order to do a climate forecast verification with SUNSET are:

- A recipe: A YAML file that includes the information about the data to be loaded (which models? which variables? which years?...), the details of the different steps of the analysis, and any other information necessary to handle the inputs and outputs. You can use the [recipe template](https://earth.bsc.es/gitlab/es/sunset/-/tree/master/recipe_template.yml) and modify it according to your needs.

- A script: Lines of R code to read the recipe, load the data and perform the analysis. SUNSET provides some pre-defined functions that you can use on their own or combine with your own code. Some examples are available in the [example scripts folder](https://earth.bsc.es/gitlab/es/sunset/-/tree/master/example_scripts).

SUNSET has two different modes: 

- A 'debug mode' which you can run in an interactive R session. See an example here: [Use case 1.1](https://earth.bsc.es/gitlab/es/sunset/-/blob/master/use_cases/ex1_1_single_analysis_terminal/ex1_1-handson.md)

- A 'job launch' mode which you can use to run one or more jobs on an HPC platform. In this way, you can run the same analysis for multiple models, initialization dates, variables or regions at the same time, from one recipe. See an example here: [Use case 1.3](https://earth.bsc.es/gitlab/es/sunset/-/blob/master/use_cases/ex1_3_nino_indices_comparison/ex1_3-handson.md)

You can find a summary of the differences between the two modes in this presentation: [Steps to use SUNSET](https://docs.google.com/presentation/d/1FdW25b4JZLxXDkVRVIOz-P_2A1WXLWDXhxZvisrVdqU/edit#slide=id.g308472768fe_0_124)

Documentation and Use Cases
---------

You can access the documentation through the wiki:
[SUNSET Wiki](https://earth.bsc.es/gitlab/es/sunset/-/wikis/home?target=_blank)

Use cases and hands-on tutorials are available in the repository for you to follow:

[SUNSET Use Cases](https://earth.bsc.es/gitlab/es/sunset/-/tree/master/use_cases/)

Other resources
---------

You may also find useful information in the slides from past user meetings:

[R-tools Climate Forecast Analysis Training session 2023](https://earth.bsc.es/wiki/lib/exe/fetch.php?media=tools:day2_04_handson_r_tools.pdf)

[User meeting March 2023](https://docs.google.com/presentation/d/18VoqgJCzcZTmqNyXL3op_KecsPxsWRkf/edit#slide=id.p1?target=_blank)

[User meeting September 2022](https://docs.google.com/presentation/d/14-qq__fblMt7xvJDaqS5UqfQMXWCf3Ju/edit#slide=id.p1?target=_blank)

[User meeting June 2022](https://docs.google.com/presentation/d/1R8Gcz5R_NTgcBQvXBkCPG3jY31BVPDur/edit#slide=id.p1?target=_blank)

Branching strategy
------------------

Branches containing developments that are to be merged into the tool must contain "dev-" at the beginning of the name, followed by a short, meaningful description of the development in question. E.g. "dev-loading-subseasonal" for the branch containing developments related to the loading of subseasonal datasets.

Users that wish to incorporate their own developments into the core of the tool are encouraged to create a local copy repository to work on their projects and push their changes to a new branch. Please contact Victòria Agudetse (@vagudets) or Núria Pérez-Zanón (@nperez) to discuss the first steps.

Mailing list
------------

User meetings, internal releases and news are announced through the mailing list. You can send an email to victoria.agudetse@bsc.es to request subscription.
