Skip to content

heiplanet_data.nuts_aggregation module⚓︎

heiplanet_data.nuts_aggregation ⚓︎

Aggregation of gridded NetCDF data over NUTS regions.

This module reduces preprocessed gridded data to one value per NUTS region and time step:

  • aggregate_data_by_nuts is the public entry point: it reads one or more NetCDF files, aggregates each data variable over the NUTS polygons from a shape file, merges the results, and writes them to a NetCDF file indexed by NUTS_ID and time,
  • two aggregation backends are available: exactextract (default, area-weighted, suited for large datasets) and geopandas (point-in- polygon spatial join, memory-hungry on fine global grids).

This is the only module that imports exactextract.

Functions:

Attributes:

CRS module-attribute ⚓︎

CRS = 4326

logger module-attribute ⚓︎

logger = getLogger(__name__)

aggregate_data_by_nuts ⚓︎

aggregate_data_by_nuts(netcdf_files, nuts_file, normalize_time=True, output_dir=None, agg_lib='exactextract')

Aggregate data from NetCDF files by NUTS regions, data variable names, and time. The aggregated data is saved to a NetCDF file with coordinates "NUTS_ID", "time", and data variables include aggregated data variables.

Parameters:

  • netcdf_files (dict[str, tuple[Path, Dict | None]]) –

    Dictionary of NetCDF files. Keys are dataset names and values are tuples of (file path, agg_dict). The agg_dict can contain aggregation options for each data variable. For example, {"t2m": "mean", "tp": "sum"}. If agg_dict is None, default aggregation (i.e. mean) is used. NetCDF files must contain "latitude", "longitude", and "time" coordinates.

  • nuts_file (Path) –

    Path to the NUTS regions shape file. The shape file has columns such as "NUTS_ID" and "geometry".

  • normalize_time (bool, default: True ) –

    If True, normalize time to the beginning of the day. e.g. 2025-10-01T12:00:00 becomes 2025-10-01T00:00:00. Default is True.

  • output_dir (Path | None, default: None ) –

    Directory to save the aggregated NetCDF file. If None, the output file is saved in the same directory as the NUTS file. Default is None.

  • agg_lib (Literal['geopandas', 'exactextract'], default: 'exactextract' ) –

    Library to use for aggregation. Options are "geopandas" or "exactextract". Default is "exactextract".

Returns:

  • Path ( Path ) –

    Path to the aggregated NetCDF file.