Copernicus Seasonal Forecast Tools

This repository hosts the copernicus-seasonal-forecast-tools, a Python package developed to manage seasonal forecast data from the Copernicus Climate Data Store (CDS) as part of the U-CLIMADAPT project.

It offers comprehensive tools for downloading, processing, computing climate indices, and generating hazard objects based on seasonal forecast datasets, particularly Seasonal forecast daily and subdaily data on single levels. The packge is tailored to integrate seamlessly with the CLIMADA (CLIMate ADAptation) platform, supporting climate risk assessment and the development of effective adaptation strategies.

Users can:

• Automatically download of high-resolution seasonal forecast data via the CDS API
• Preprocess sub-daily fields into daily aggregates
• Compute heat-related indices (e.g., heatwave days, tropical nights, TX30)
• Generate CLIMADA hazard objects
• Benefit from the modular design for extending to new indices or forecast products

Documentation

For full documentation of all features and functions, please refer to the Copernicus Seasonal Forecast Tools documentation on ReadTheDocs.

Getting Started

To use this package, you must first configure access to the Copernicus Climate Data Store (CDS), which provides the seasonal forecast datasets.

We've prepared a comprehensive CDS API setup guide to walk you through each step of the process. Once configured, you'll be ready to explore and analyze seasonal forecast data.

Installation

The package requires Python 3.10, but versions 3.11 and 3.12 are also supported. Make sure your environment is using a compatible Python version before installation.

You can install copernicus-seasonal-forecast-tools in three ways, depending on your setup and preferences.

Note: If you want to generate CLIMADA hazard objects, you must install the optional CLIMADA dependency.
For full installation instructions, see the online documentation.

1. Install via pip (recommended for most users)

pip install copernicus-seasonal-forecast-tools
git clone https://github.com/DahyannAraya/copernicus-seasonal-forecast-tools.git (optional)
pip install -r docs/requirements.txt (optional)

2. Install via environment.yml (Conda or Mamba):

git clone https://github.com/DahyannAraya/copernicus-seasonal-forecast-tools.git
conda env create -f environment.yml
conda activate venv_forecast

3. Install directly from GitHub

git clone https://github.com/DahyannAraya/copernicus-seasonal-forecast-tools.git
cd copernicus-seasonal-forecast-tools
pip install .
pip install -r docs/requirements.txt (optional)

CLIMADA Installation

CLIMADA is required to generate hazard layers.

• If you installed via environment.yml, CLIMADA is already included.
• If you installed from PyPI and then ran pip install -r docs/requirements.txt, CLIMADA is also installed.

Note
If you want to have all the functionalities of CLIMADA, you must install the full version.
👉 For detailed instructions, follow the official CLIMADA installation guide:
CLIMADA Installation Guide

Example of use

This section provides practical example to help users understand how to work with the copernicus-seasonal-forecast-tools package. The notebooks demonstrate key steps including downloading data, computing climate indices, and generating CLIMADA hazard objects.

• DEMO_copernicus_forecast_seasonal.ipynb: This is the first notebook to run. It demonstrates how to install and use the seasonal_forecast_tools to download, process, and convert seasonal forecast data into a CLIMADA hazard object.

Notebooks

Notebook	Open in Colab	GitHub (Documentation)
DEMO Copernicus Seasonal Forecast		View in Docs
Download and Process Data		View in Docs
Calculate Climate Indices		View in Docs
Calculate a Hazard Object		View in Docs
Example for Reading and Plotting Hazard		View in Docs

You can find further material in , where we provide an extended demonstration.

License

GPL-3.0 license

Resources

• U-CLIMADAPT Project
• Copernicus Seasonal Forecas Tools package on CLIMADA
• Copernicus Seasonal Forecast Tools package extended demostration
• Seasonal forecast daily and subdaily data on single levels
• Copernicus Climate Data Store
• CLIMADA Documentation