seasonal_forecast_tools.core.seasonal_statistics

This script is part of the seasonal forecast module developed within the U-CLIMADAPT project. It provides functionality for accessing, processing, and analyzing seasonal forecast data from the Copernicus Climate Data Store (CDS), with an emphasis on computing heat-related climate indices and supporting impact-based forecasting.

The module is designed to interface with CLIMADA but can also be used independently. The design is modular and flexible, allowing it to be easily adapted to support new climate indices or to serve individual steps in the workflow — such as data download, index calculation, or hazard generation — depending on the user’s needs.

This module is distributed under the terms of the GNU General Public License version 3 (GPLv3). It is provided without any warranty — not even the implied warranty of merchantability or fitness for a particular purpose. For more details, see the GNU General Public License. A copy of the GNU General Public License should have been provided with this module. If not, it is available at https://www.gnu.org/licenses/.

—

File to calculate different seasonal forecast indices.

Module Contents

seasonal_forecast_tools.core.seasonal_statistics.LOGGER
seasonal_forecast_tools.core.seasonal_statistics.calculate_heat_indices_metrics(input_file_name, index_metric, index_window='monthly', tr_threshold=20, hw_threshold=27, hw_min_duration=3, hw_max_gap=0)

Computes heat indices or temperature-related metrics based on the specified climate index.

Parameters:

  • input_file_name (str) – Path to the input data file containing the variables required for the computation of the selected index. The file should be in NetCDF (.nc) or GRIB format and contain relevant atmospheric data such as temperature, dewpoint temperature, humidity, or wind speed. Information on the required variables for each index can be found in the index_definitions class.

  • index_metric (str) – The climate index to be processed. Supported indices include: - “Tmean” : Mean daily temperature - “Tmax” : Maximum daily temperature - “Tmin” : Minimum daily temperature - “HIS” : Simplified Heat Index - “HIA” : Adjusted Heat Index - “RH” : Relative Humidity - “HUM” : Humidex - “AT” : Apparent Temperature - “WBGT”: Wet Bulb Globe Temperature (Simple)

  • index_window (str or int) – Time window for the calculation of the index. If int, time window in days. If “monthly”, time window are months. Defaults to “monthly”.

  • tr_threshold (float, optional) – Temperature threshold (°C) for computing tropical nights (TR). Default is 20°C, meaning nights with Tmin > 20°C are considered tropical.

  • hw_threshold (float, optional) – Temperature threshold (°C) for detecting a heatwave (HW). Default is 27°C, meaning a heatwave occurs if the temperature remains above this threshold for multiple days.

  • hw_min_duration (int, optional) – Minimum consecutive days for a heatwave event to be detected. Default is 3 days.

  • hw_max_gap (int, optional) – Maximum allowable gap (in days) between heatwave days for them to still be considered part of the same event. Default is 0 days, meaning no gaps are allowed.

Returns:

A tuple containing three xarray.Dataset objects: - daily index : The calculated daily index values. - index_window index : Mean values of the index over the time window index_window. - index statistics : Ensemble statistics calculated from the index.

Return type:

tuple

Raises:

  • ValueError – If an unsupported index is provided.

  • FileNotFoundError – If the specified input file does not exist.

seasonal_forecast_tools.core.seasonal_statistics.calculate_aggregated_dataset(da_index, index_metric, method)

Calculate means from daily data

Parameters:

  • da_index (xr.Dataset) – Dataset containing daily data

  • index_metric (str) – index to be computed

  • method (str) – method to combine daily data aggregated to period as defined in da_index. Available are “mean” and “count”.

Returns:

Dataset of monthly averages

Return type:

xr.DataSet

seasonal_forecast_tools.core.seasonal_statistics.calculate_statistics_from_index(dataarray)

Calculates a set of ensemble statistics for the given data array, including mean, median, standard deviation, and selected percentiles.

Parameters:

dataarray (xarray.DataArray) – Input data array representing climate index values across multiple ensemble members. It should have a dimension named “number” corresponding to the different ensemble members.

Returns:

A dataset containing the calculated statistics: - ensemble_mean: The mean value across the ensemble members. - ensemble_median: The median value across the ensemble members. - ensemble_max: The maximum value across the ensemble members. - ensemble_min: The minimum value across the ensemble members. - ensemble_std: The standard deviation across the ensemble members. - ensemble_p05, ensemble_p25, ensemble_p50, ensemble_p75, ensemble_p95: Percentile values (5th, 25th, 50th, 75th, and 95th) across the ensemble members.

Return type:

xarray.Dataset