seasonal_forecast_tools.utils.path_utils

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/.

— Path utility functions for seasonal forecast pipelines. Provides helpers to generate and check file paths used across the seasonal forecast download, processing, and hazard generation modules.

Module Contents

seasonal_forecast_tools.utils.path_utils.get_file_path(base_dir: str | pathlib.Path, originating_centre: str, year: int | str, initiation_month_str: str, valid_period_str: str, data_type: str, index_metric: str, bounds_str: str, system: str, index_window='monthly', data_format: str = 'grib') → pathlib.Path | dict

Construct the file path or path dictionary for a given forecast dataset.

Based on forecast metadata (provider, date, system, index, format, etc.), this function builds the expected path or dictionary of paths (for indices) that follow CLIMADA’s seasonal forecast directory structure.

Parameters:

  • base_dir (str or Path) – Base directory where Copernicus seasonal data is stored.

  • originating_centre (str) – Data provider (e.g., ‘dwd’).

  • year (int or str) – Forecast initiation year.

  • initiation_month_str (str) – Forecast initiation month in two-digit string format (e.g., ‘03’).

  • valid_period_str (str) – Valid period formatted as ‘<start>_<end>’ (e.g., ‘06_08’).

  • data_type (str) – Type of data, one of: ‘downloaded_data’, ‘processed_data’, ‘indices’, ‘hazard’.

  • index_metric (str) – Name of the climate index (e.g., ‘HW’, ‘TR’, ‘Tmax’).

  • bounds_str (str) – Bounding box string (e.g., ‘W4_S44_E11_N48’).

  • system (str) – Forecast system (e.g., ‘21’).

  • 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”.

  • data_format (str, optional) – File format: ‘grib’, ‘netcdf’, or ‘hdf5’ (autodetected by data_type if not provided).

Returns:

A single file path (for non-index types) or a dictionary of paths (for ‘indices’).

Return type:

pathlib.Path or dict

Raises:

ValueError – If an unknown data_type is provided.

Notes

  • The returned path follows the CLIMADA forecast folder structure.

  • Index files return a dict with ‘daily’, ‘index_window’, and ‘stats’ keys.

seasonal_forecast_tools.utils.path_utils.check_existing_files(base_dir: str | pathlib.Path, originating_centre: str, index_metric: str, year: int, initiation_month: str, valid_period: List[str], bounds_str: str, system: str, index_window='monthly', download_format: str = 'grib', print_flag: bool = False) → str

Inspect the existence of forecast data files for a given configuration.

A manual debugging utility, this function checks whether the expected files (downloaded, processed, index, hazard) exist in the configured directory tree.

Parameters:

  • base_dir (str or Path) – Base directory where Copernicus seasonal data is stored.

  • originating_centre (str) – Forecast data provider (e.g., ‘dwd’).

  • index_metric (str) – Climate index to check (e.g., ‘HW’, ‘TR’, ‘Tmax’).

  • year (int) – Forecast initiation year.

  • initiation_month (str) – Initiation month as string (e.g., ‘March’).

  • valid_period (list of str) – Valid forecast months, exactly two (e.g., [‘June’, ‘August’]).

  • bounds_str (str) – Spatial bounds string used in filenames.

  • system (str) – Forecast system version (e.g., ‘21’).

  • 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”.

  • download_format (str, optional) – Format of the downloaded data. Default is ‘grib’.

  • print_flag (bool, optional) – Whether to print the existence check report.

Returns:

Summary report indicating which files exist.

Return type:

str

Raises:

ValueError – If valid_period is not exactly two months long.

Notes

  • This is a utility function for developers and users to validate pipeline outputs.

  • It is not called by the main forecast processing pipeline.