Resource Preparation

Scripts for preparing renewable resources, power plants, and demand profiles.

---

build_cutout

Create cutouts with atlite <https://atlite.readthedocs.io/en/latest/>_.

For this rule to work you must have

• installed the Copernicus Climate Data Store <https://cds.climate.copernicus.eu>_ cdsapi package (install withpip``) and
• registered and setup your CDS API key as described on their website <https://cds.climate.copernicus.eu/api-how-to>_. The CDS API allows an automatic filedownload by executing this script

.. seealso:: For details on the weather data read the atlite documentation <https://atlite.readthedocs.io/en/latest/>. If you need help specifically for creating cutouts the corresponding section in the atlite documentation <https://atlite.readthedocs.io/en/latest/examples/create_cutout.html> should be helpful.

Relevant Settings

.. code:: yaml

atlite:
    nprocesses:
    cutouts:
        {cutout}:

.. seealso:: Documentation of the configuration file config.yaml at :ref:atlite_cf

Inputs

None

Outputs

• cutouts/{cutout}: weather data from either the ERA5 <https://www.ecmwf.int/en/forecasts/datasets/reanalysis-datasets/era5> reanalysis weather dataset or SARAH-2 <https://wui.cmsaf.eu/safira/action/viewProduktSearch> satellite-based historic weather data with the following structure:

ERA5 cutout:

===================  ==========  ==========  =========================================================
Field                Dimensions  Unit        Description
===================  ==========  ==========  =========================================================
pressure             time, y, x  Pa          Surface pressure
-------------------  ----------  ----------  ---------------------------------------------------------
temperature          time, y, x  K           Air temperature 2 meters above the surface.
-------------------  ----------  ----------  ---------------------------------------------------------
soil temperature     time, y, x  K           Soil temperature between 1 meters and 3 meters
                                             depth (layer 4).
-------------------  ----------  ----------  ---------------------------------------------------------
influx_toa           time, y, x  Wm**-2      Top of Earth's atmosphere TOA incident solar radiation
-------------------  ----------  ----------  ---------------------------------------------------------
influx_direct        time, y, x  Wm**-2      Total sky direct solar radiation at surface
-------------------  ----------  ----------  ---------------------------------------------------------
runoff               time, y, x  m           `Runoff <https://en.wikipedia.org/wiki/Surface_runoff>`_
                                             (volume per area)
-------------------  ----------  ----------  ---------------------------------------------------------
roughness            y, x        m           Forecast surface roughness
                                             (`roughness length <https://en.wikipedia.org/wiki/Roughness_length>`_)
-------------------  ----------  ----------  ---------------------------------------------------------
height               y, x        m           Surface elevation above sea level
-------------------  ----------  ----------  ---------------------------------------------------------
albedo               time, y, x  --          `Albedo <https://en.wikipedia.org/wiki/Albedo>`_
                                             measure of diffuse reflection of solar radiation.
                                             Calculated from relation between surface solar radiation
                                             downwards (Jm**-2) and surface net solar radiation
                                             (Jm**-2). Takes values between 0 and 1.
-------------------  ----------  ----------  ---------------------------------------------------------
influx_diffuse       time, y, x  Wm**-2      Diffuse solar radiation at surface.
                                             Surface solar radiation downwards minus
                                             direct solar radiation.
-------------------  ----------  ----------  ---------------------------------------------------------
wnd100m              time, y, x  ms**-1      Wind speeds at 100 meters (regardless of direction)
===================  ==========  ==========  =========================================================

.. image:: /img/era5.png
    :width: 40 %

A SARAH-2 cutout can be used to amend the fields temperature, influx_toa, influx_direct, albedo, influx_diffuse of ERA5 using satellite-based radiation observations.

.. image:: /img/sarah.png
    :width: 40 %

Description

build_natura_raster

Builds a rasterized Natura and environmental exclusion mask from vector geometries. The geometries are sourced from Protected Planet Data and filtered for the required regions.

Relevant Settings

countries:

enable:
    build_natura_raster:
    progress_bar:

crs:
    area_crs:

natura:
    natura_size:
    natura_resolution:
    window_size:
    buffer_size:

renewable:
    {technology}:
        cutout:

Inputs

• data/landcover/world_protected_areas/*.shp: Vectorized shapefiles representing the world protected areas from Protected Planet Data.
• cutouts/{CDIR}/{cutout}.nc: Atlite cutout specified in renewable: {technology}: cutout for each technology. The cutout(s) are used to determine geographic coverage and resolution alignment.
• resources/{RDIR}/shapes/country_shapes.geojson: Onshore country geometries used to determine the spatial extent of the rasterization.
• resources/{RDIR}/shapes/offshore_shapes.geojson: Offshore regions associated with the selected countries.

Outputs

• resources/{RDIR}/natura.tiff: Rasterized version of the world protected areas.

Description

The rule build_natura_raster converts large collections of vector-based environmental exclusion geometries into a rasterized binary mask containing:

• 1 for raster cells intersecting exclusion geometries, and
• 0 elsewhere.

First, the rule determines the spatial extent of the rasterization which is configured through natura: natura_size and can be based on:

• the full global extent,
• the combined extent of all configured renewable technology cutouts (renewable: {technology}: cutout), or
• the combined extent of all selected country (countries) and their offshore regions.

In case of the countries extent, the country and offshore geometries are reprojected into (crs: area_crs). Additionally, a buffer (natura: buffer_size) is applied to the geometries to ensure that all regions of interest are fully included in the rasterization.

The rasterization is performed as follows:

• an empty GeoTIFF is created using the extent determined above and a grid resolution defined by natura: natura_resolution,
• the extent is split into smaller windows with a maximum width and height of natura: window_size,
• each input .shp file is processed independently and rasterized window by window.

This windowed processing strategy reduces memory usage and allows the rule to run efficiently on standard compute environments.

Notes

This script only runs in the current PyPSA-Earth workflow if enable: build_natura_raster is true. Otherwise, the workflow will use the general data/natura/natura.tiff file, which is copied using the rule copy_defaultnatura_tiff.

There are two main differences between the two options, the data source and the license:

• The rule build_natura_raster uses data from Protected Planet Data which is generally more up-to-date. However, the Protected Planet License is less permissive and might not be applicable for your use case.
• The rule copy_defaultnatura_tiff uses data from Harvard Dataverse Protected areas (WDPA), which was last updated in 2022. This dataset is licensed under the CC0 1.0 license.

get_relevant_regions(country_shapes, offshore_shapes, natura_crs, buffer)

Load and merge country and offshore regions into a unified geometry.

The resulting geometry is buffered to ensure all relevant nearby regions are included.

Parameters

country_shapes : str Path to the vector file containing the country geometries. offshore_shapes : str Path to the vector file containing the offshore geometries. natura_crs : str Coordinate reference system used for all geometries. buffer : float Buffer distance applied to both country and offshore geometries. Units are determined by natura_crs.

Returns

gpd.GeoDataFrame GeoDataFrame containing a single merged geometry representing the buffered union of all country and offshore regions.

Notes

Both input datasets are reprojected to natura_crs before merging.

Examples

regions = get_relevant_regions(
    "resources/shapes/country_shapes.geojson",
    "resources/shapes/offshore_shapes.geojson",
    "ESRI:54009",
    10000,
)
len(regions)
# 1
regions.crs.to_string()
# "ESRI:54009"

get_fileshapes(list_paths, accepted_formats=('.shp',))

Function to parse the list of paths and identify the ones with one of the accepted file formats.

Parameters

list_paths : list[str] List of paths to check. accepted_formats : str | tuple[str, ...], optional File format(s) to accepted. If a string is provided, only that extension is accepted. If a tuple is provided, any of the extensions are accepted. Default is (".shp",).

Returns

list[str] List of all paths which are of one of the accepted formats.

Examples

paths = ["shape_file.shp", "shape_index.shi"]
get_fileshapes(paths)
# ["shape_file.shp"]
get_fileshapes(paths, ".shi")
# ["shape_index.shi"]

determine_region_xXyY(cutout_name, regions, natura_size, out_logging)

Determine the bounds of the analyzed regions.

Parameters

cutout_name : str Path of the cutout file. regions : gpd.GeoDataFrame | None GeoDataFrame containing the analyzed regions. Required if natura_size is "countries", otherwise ignored. natura_size : str Flag to determine which region should be used. "global" includes the entire world, "cutout" the extent of the cutout, and "countries" only includes the bounds of the requested countries and their offshore regions. out_logging : bool If True, emits progress information via the module logger.

Returns

list[float] Bounding box of the region in the format: [min_lon, max_lon, min_lat, max_lat].

Examples

cutout_path = "cutouts/cutout-2013-era5.nc"
regions = None

# Global extent:
determine_region_xXyY(cutout_path, regions, "global", False)
# [-180, 180, -90, 90]

# Cutout extent (Africa):
determine_region_xXyY(cutout_path, regions, "cutout", False)
# [-19.8, 67.8, -37.8, 39.6]

# Countries extent:
import geopandas as gpd
from shapely.geometry import Polygon

regions = gpd.GeoDataFrame(
    geometry=[Polygon([(0, 0), (10, 0), (10, 10), (0, 10)])],
    crs="EPSG:4326",
)
determine_region_xXyY(cutout_path, regions, "countries", False)
# [0.0, 10.0, 0.0, 10.0]

get_transform_and_shape(bounds, res, out_logging)

Compute an affine transform and raster shape from spatial bounds and resolution.

Parameters

bounds : list[float] Bounding box in the format: [min_lon, min_lat, max_lon, max_lat]. res : float Spatial resolution of the grid (in coordinate units, e.g. degrees). out_logging : bool If True, emits progress information via the module logger.

Returns

transform : rio.Affine Affine transform mapping raster indices (row, col) to spatial coordinates. shape : tuple[int, int] Raster shape as (n_lat, n_lon), corresponding to (rows, cols).

Examples

import rasterio as rio

# [min_lon, min_lat, max_lon, max_lat]
bounds = [0.0, 50.0, 3.0, 52.0]
res = 1.0

transform, shape = get_transform_and_shape(bounds, res, False)
shape
# (2, 3)
transform
# Affine(1.0, 0.0, 0.0,
# 0.0, -1.0, 52.0)

decide_bigtiff_flag(out_shape, dtype='uint8', safety_factor=1.1)

Decide whether a raster requires BIGTIFF storage based on raster shape.

BIGTIFF is required for GeoTIFF files larger than approximately 4 GB.

Parameters

out_shape : tuple[int, int] Raster shape as (n_rows, n_cols). dtype : str, optional Data type of the raster values. Default is "uint8". safety_factor : float, optional Multiplicative buffer applied to the estimated size to account for metadata, compression inefficiencies, and file overhead. Default is 1.1.

Returns

str "YES" if the estimated size is larger than the BIGTIFF threshold, otherwise "NO".

Notes

The size estimate is computed as:

n_rows * n_cols * bytes_per_pixel * safety_factor

The BIGTIFF threshold is fixed at 4,000,000,000 bytes (~4 GB).

Examples

decide_bigtiff_flag((100, 100), dtype="uint8")
# "NO"

build_renewable_profiles

Calculates for each network node the (i) installable capacity (based on land- use), (ii) the available generation time series (based on weather data), and (iii) the average distance from the node for onshore wind, AC-connected offshore wind, DC-connected offshore wind and solar PV generators. For hydro generators, it calculates the expected inflows. In addition for offshore wind it calculates the fraction of the grid connection which is under water.

Relevant settings

.. code:: yaml

snapshots:

atlite:
    nprocesses:

renewable:
    {technology}:
        cutout:
        copernicus:
            grid_codes:
            distance:
            distance_grid_codes:
        natura:
        max_depth:
        max_shore_distance:
        min_shore_distance:
        capacity_per_sqkm:
        correction_factor:
        potential:
        min_p_max_pu:
        clip_p_max_pu:
        resource:
        clip_min_inflow:

.. seealso:: Documentation of the configuration file config.yaml at :ref:snapshots_cf, :ref:atlite_cf, :ref:renewable_cf

Inputs

• data/copernicus/PROBAV_LC100_global_v3.0.1_2019-nrt_Discrete-Classification-map_EPSG-4326.tif: Copernicus Land Service <https://land.copernicus.eu/global/products/lc> inventory on 23 land use classes (e.g. forests, arable land, industrial, urban areas) based on UN-FAO classification. See Table 4 in the PUM <https://land.copernicus.eu/global/sites/cgls.vito.be/files/products/CGLOPS1_PUM_LC100m-V3_I3.4.pdf> for a list of all classes.

  .. image:: /img/copernicus.png :width: 33 %

• data/gebco/GEBCO_2021_TID.nc: A bathymetric <https://en.wikipedia.org/wiki/Bathymetry> data set with a global terrain model for ocean and land at 15 arc-second intervals by the General Bathymetric Chart of the Oceans (GEBCO) <https://www.gebco.net/data_and_products/gridded_bathymetry_data/>.

  .. image:: /img/gebco_2021_grid_image.jpg :width: 50 %

  Source: GEBCO <https://www.gebco.net/data_and_products/images/gebco_2019_grid_image.jpg>_

• resources/natura.tiff: confer :ref:natura

• resources/offshore_shapes.geojson: confer :ref:shapes
• resources/.geojson: (if not offshore wind), confer :ref:busregions
• resources/regions_offshore.geojson: (if offshore wind), :ref:busregions
• "cutouts/" + config["renewable"][{technology}]['cutout']: :ref:cutout
• networks/base.nc: :ref:base

Outputs

• resources/profile_{technology}.nc, except hydro technology, with the following structure

  =================== ========== ========================================================= Field Dimensions Description =================== ========== ========================================================= profile bus, time the per unit hourly availability factors for each node

  ---

  weight bus sum of the layout weighting for each node

  ---

  p_nom_max bus maximal installable capacity at the node (in MW)

  ---

  potential y, x layout of generator units at cutout grid cells inside the Voronoi cell (maximal installable capacity at each grid cell multiplied by capacity factor)

  ---

  average_distance bus average distance of units in the Voronoi cell to the grid node (in km)

  ---

  underwater_fraction bus fraction of the average connection distance which is under water (only for offshore) =================== ========== =========================================================

• resources/profile_hydro.nc for the hydro technology =================== ================ ======================================================== Field Dimensions Description =================== ================ ======================================================== inflow plant, time Inflow to the state of charge (in MW), e.g. due to river inflow in hydro reservoir. =================== ================ ========================================================

  • profile

  .. image:: /img/profile_ts.png :width: 33 % :align: center

  • p_nom_max

  .. image:: /img/p_nom_max_hist.png :width: 33 % :align: center

  • potential

  .. image:: /img/potential_heatmap.png :width: 33 % :align: center

  • average_distance

  .. image:: /img/distance_hist.png :width: 33 % :align: center

  • underwater_fraction

  .. image:: /img/underwater_hist.png :width: 33 % :align: center

Description

This script leverages on atlite function to derivate hourly time series for an entire year for solar, wind (onshore and offshore), and hydro data.

This script functions at two main spatial resolutions: the resolution of the network nodes and their Voronoi cells <https://en.wikipedia.org/wiki/Voronoi_diagram>_, and the resolution of the cutout grid cells for the weather data. Typically the weather data grid is finer than the network nodes, so we have to work out the distribution of generators across the grid cells within each Voronoi cell. This is done by taking account of a combination of the available land at each grid cell and the capacity factor there.

This uses the Copernicus land use data, Natura2000 nature reserves and GEBCO bathymetry data.

.. image:: /img/eligibility.png :width: 50 % :align: center

To compute the layout of generators in each node's Voronoi cell, the installable potential in each grid cell is multiplied with the capacity factor at each grid cell. This is done since we assume more generators are installed at cells with a higher capacity factor.

.. image:: /img/offwinddc-gridcell.png :width: 50 % :align: center

.. image:: /img/offwindac-gridcell.png :width: 50 % :align: center

.. image:: /img/onwind-gridcell.png :width: 50 % :align: center

.. image:: /img/solar-gridcell.png :width: 50 % :align: center

This layout is then used to compute the generation availability time series from the weather data cutout from atlite.

Two methods are available to compute the maximal installable potential for the node (p_nom_max): simple and conservative:

• simple adds up the installable potentials of the individual grid cells. If the model comes close to this limit, then the time series may slightly overestimate production since it is assumed the geographical distribution is proportional to capacity factor.

• conservative ascertains the nodal limit by increasing capacities proportional to the layout until the limit of an individual grid cell is reached.

get_irena_annual_hydro_generation(fn, countries)

Load annual renewable hydropower generation data from the IRENA Country sheet. Convert ISO3 country codes to ISO2 and annual generation from GWh to MWh.

Original source: https://www.irena.org/-/media/Files/IRENA/Agency/Publication/2025/Jul/IRENA_Statistics_Extract_2025H2.xlsx

Note

IRENA energy statistics dataset is available for non-commercial use only. Users are responsible for ensuring compliance with the dataset’s licensing terms.

check_cutout_completness(cf)

Check if a cutout contains missed values.

That may be the case due to some issues with accessibility of ERA5 data See for details https://confluence.ecmwf.int/display/CUSF/Missing+data+in+ERA5T Returns share of cutout cells with missed data

estimate_bus_loss(data_column, tech)

Calculated share of buses with data loss due to flaws in the cutout data.

Returns share of the buses with missed data

filter_cutout_region(cutout, regions)

Filter the cutout to focus on the region of interest.

rescale_hydro(plants, runoff, normalize_using_yearly, normalization_year)

Function used to rescale the inflows of the hydro capacities to match country statistics.

Parameters

plants : DataFrame Run-of-river plants orf dams with lon, lat, countries, installed_hydro columns. Countries and installed_hydro column are only used with normalize_using_yearly installed_hydro column shall be a boolean vector specifying whether that plant is currently installed and used to normalize the inflows runoff : xarray object Runoff at each bus normalize_using_yearly : DataFrame Dataframe that specifies for every country the total hydro production year : int Year used for normalization

check_flag(d, field)

Check if a string is contained in keys of a dictionary and is either True or non-boolean

build_powerplants

Retrieves conventional powerplant capacities and locations from powerplantmatching <https://github.com/FRESNA/powerplantmatching>_, assigns these to buses and creates a .csv file. It is possible to merge the powerplant database with, or replace it using, one or more custom powerplant files.

Relevant Settings

.. code:: yaml

electricity:
  powerplants_filter:
  custom_powerplants:
    filepaths:
    method:

.. seealso:: Documentation of the configuration file config.yaml at :ref:electricity

Inputs

• networks/base.nc: confer :ref:base.
• Files listed under custom_powerplants.filepaths: custom powerplants in the same format as powerplantmatching <https://github.com/FRESNA/powerplantmatching>_ provides or as the OSM extractor generates.

Outputs

• resource/powerplants.csv: A list of conventional power plants (i.e. neither wind nor solar) with fields for name, fuel type, technology, country, capacity in MW, duration, commissioning year, retrofit year, latitude, longitude, and dam information as documented in the powerplantmatching README <https://github.com/FRESNA/powerplantmatching/blob/master/README.md>_; additionally it includes information on the closest substation/bus in networks/base.nc.

  .. image:: /img/powerplantmatching.png :width: 30 %

  Source: powerplantmatching on GitHub <https://github.com/FRESNA/powerplantmatching>_

Description

The configuration option electricity: powerplants_filter specifies a pandas.query command applied to the complete powerplant dataset, including both powerplantmatching and custom powerplants.

The electricity: custom_powerplants section specifies the custom files and how they are applied. method accepts false, merge, or replace and is applied once to the complete set of configured files. merge appends all configured custom powerplants to the filtered powerplantmatching dataset, while replace discards the complete powerplantmatching dataset and uses all configured custom files instead.

1. Using only powerplantmatching data:

   .. code:: yaml

   custom_powerplants:
     filepaths:
     - data/custom_powerplants.csv
     method: false
   

2. Adding all powerplants from a custom file:

   .. code:: yaml

   custom_powerplants:
     filepaths:
     - data/custom_powerplants.csv
     method: merge
   

3. Replacing the complete powerplantmatching dataset:

   .. code:: yaml

   custom_powerplants:
     filepaths:
     - data/custom_powerplants.csv
     method: replace
   

4. Combining multiple custom files:

Multiple custom powerplant files can be provided. A single method is applied to the complete set of configured files.

.. code:: yaml

   custom_powerplants:
     filepaths:
     - data/custom_powerplants_US.csv
     - data/custom_powerplants_CA.csv
     method: merge

The available methods are:

• false: ignore the custom files and use only powerplantmatching data.
• merge: add all configured custom files to the filtered powerplantmatching dataset.

• replace: discard the complete powerplantmatching dataset and use only the configured custom files.

• Obtaining different outcomes for different countries:

Country-specific replacement can be achieved by excluding the corresponding country from powerplants_filter and then merging the custom files.

.. code:: yaml

   powerplants_filter: (DateOut >= 2022 or DateOut != DateOut) and (DateIn <= 2023 or DateIn != DateIn) and Country != 'United States'

   custom_powerplants:
     filepaths:
     - data/custom_powerplants_US.csv
     - data/custom_powerplants_CA.csv
     method: merge

In this example:

• US plants are taken only from custom_powerplants_US.csv because US plants are excluded from powerplantmatching.
• CA plants from custom_powerplants_CA.csv are added to the existing powerplantmatching data.
• Countries without a custom file, such as MX, use only powerplantmatching data.

Custom powerplant file format _~~~~~~~~~~~

Custom powerplant CSV files should follow the powerplantmatching format, with some additional considerations.

Required columns:

id, Name, Fueltype, Technology, Set, Country, Capacity, Efficiency, DateIn, DateRetrofit, DateOut, lat, lon, Duration, Volume_Mm3, DamHeight_m, StorageCapacity_MWh, EIC, and projectID.

Considerations for column values:

• Fueltype should use the corresponding powerplantmatching fuel category, such as Natural Gas.
• Natural-gas plants should specify OCGT or CCGT in the Technology column.
• Hydro plants with Technology set to Reservoir are represented as storage units. Use ror for hydro plants that should be represented as generators.
• Country values are converted to ISO 3166-1 alpha-2 codes after the custom files have been applied. Both full country names and alpha-2 codes are therefore accepted in custom files.

OSM mapping assumptions _~~~~~~~~~

The following assumptions were made when mapping custom OSM-extracted power plants to the powerplantmatching format:

1. The benchmark powerplantmatching values were taken as follows:

2. Fueltype: Hydro, Hard Coal, Natural Gas, Lignite, Nuclear, Oil, Bioenergy, Wind, Geothermal, Solar, Waste, and Other.

3. Technology: Reservoir, Pumped Storage, Run-Of-River, Steam Turbine, CCGT, OCGT, PV, CCGT, Thermal, Offshore, and Storage Technologies.

4. Set: Store, PP, and CHP.

5. OSM-extracted features were mapped to powerplantmatching values using the following rules:

6. coal -> Hard Coal

7. wind_turbine -> Onshore
8. horizontal_axis -> Onshore
9. vertical_axis -> Offshore

10. nuclear -> Steam Turbine

11. All hydro objects extracted from OSM were interpreted as generation technologies, although Run-Of-River, Pumped Storage, and Reservoir may also belong to Storage Technologies in powerplantmatching.

12. The OSM extraction was assumed to ignore non-generation features such as CHP plants and natural-gas storage, unlike powerplantmatching.

add_custom_powerplants(ppl, custom_powerplants_files, method)

Merge or replace powerplantmatching data with custom powerplant files.

Parameters

ppl : pd.DataFrame Powerplantmatching dataframe. custom_powerplants_files : list[str] Paths to custom powerplant CSV files. method : bool or str Method applied to all custom files together. Accepted values are False, "merge", and "replace".

Returns

pd.DataFrame Powerplant dataframe after applying the custom files.

replace_natural_gas_technology(df)

Maps and replaces gas technologies in the powerplants.csv onto model compliant carriers.

build_demand_profiles

Creates electric demand profile csv.

Relevant Settings

.. code:: yaml

load:
    scale:
    ssp:
    weather_year:
    prediction_year:
    region_load:

Inputs

• networks/base.nc: confer :ref:base, a base PyPSA Network
• resources/bus_regions/regions_onshore.geojson: confer :mod:build_bus_regions
• load_data_paths: paths to load profiles, e.g. hourly country load profiles produced by GEGIS
• resources/shapes/gadm_shapes.geojson: confer :ref:shapes, file containing the gadm shapes

Outputs

• resources/demand_profiles.csv: the content of the file is the electric demand profile associated to each bus. The file has the snapshots as rows and the buses of the network as columns.

Description

The rule :mod:build_demand creates load demand profiles in correspondence of the buses of the network. It creates the load paths for GEGIS outputs by combining the input parameters of the countries, weather year, prediction year, and SSP scenario. Then with a function that takes in the PyPSA network "base.nc", region and gadm shape data, the countries of interest, a scale factor, and the snapshots, it returns a csv file called "demand_profiles.csv", that allocates the load to the buses of the network according to GDP and population.

get_gegis_regions(countries)

Get the GEGIS region from the config file.

Parameters

region : str The region of the bus

Returns

str The GEGIS region

get_load_paths_gegis(ssp_parentfolder, config)

Create load paths for GEGIS outputs.

The paths are created automatically according to included country, weather year, prediction year and ssp scenario

Example

["/data/ssp2-2.6/2030/era5_2013/Africa.nc", "/data/ssp2-2.6/2030/era5_2013/Africa.nc"]

shapes_to_shapes(orig, dest)

Adopted from vresutils.transfer.Shapes2Shapes()

compose_gegis_load(load_paths, countries)

Read and merge GEGIS electricity demand data from multiple input files.

Parameters

load_paths : str or list[str] Paths to demand input files. countries : str or list[str] Region codes used to look for the demand data.

Returns

gegis_load : pd.DataFrame Electricity load with time index, and containing the columns region_code, region_name, and Electricity demand.

read_demcast_load(load_paths, weather_year, countries)

Load electricity demand data from DemandCast dataset for selected countries and a given weather year.

Parameters

load_paths : str Path to the parquet file with Demcast demand data. weather_year : int Weather year for which demand profile should be extracted. countries : str or list Country name or list of country names to subset the demand dataset.

Returns

demcast_load : pd.DataFrame Electricity load with time index, and containing the columns region_code, region_name, and Electricity demand.

References

Kevin Steijn, Vamsi Priya Goli, Enrico Antonini (2025) "DemandCast: Global hourly electricity demand forecasting" https://arxiv.org/abs/2510.08000

build_demand_profiles(n, load_source, load_paths, regions, admin_shapes, countries, scale, weather_year, start_date, end_date, out_path)

Create csv file of electric demand time series.

Parameters

n : pypsa network load_source : str Type of data source to be used for electricity demand load_paths: paths of the load files regions : .geojson Contains bus_id of low voltage substations and bus region shapes (voronoi cells) admin_shapes : .geojson contains subregional gdp, population and shape data countries : list List of countries that is config input scale : float The scale factor is multiplied with the load (1.3 = 30% more load) start_date: parameter The start_date is the first hour of the first day of the snapshots end_date: parameter The end_date is the last hour of the last day of the snapshots

Returns

demand_profiles.csv : csv file containing the electric demand time series

build_co2_emissions

Process global EDGAR CO2 emission data from the raw Excel file into a clean CSV.

Reads the EDGAR CO2 fossil fuel emission Excel file, filters to 'Public electricity and heat production' entries, and saves the result as a CSV with country identifier columns (country_code_a3, country_code_a2, country_name) and year columns for use by prepare_network.

process_edgar_emission_data(excel_file, target_sheet='v6.0_EM_CO2_fossil_IPCC2006')

Process EDGAR CO2 emission Excel data into a clean DataFrame.

Detects the CO2 fossil fuel emissions sheet automatically, filters to 'Public electricity and heat production' rows, and returns a DataFrame with country identifier columns (country_code_a3, country_code_a2, country_name) and year columns (Y_YYYY).

Parameters

excel_file : str Path to the EDGAR CO2 emission Excel file (.xls or .xlsx). target_sheet : str, optional Name of the sheet in the Excel file to process. Defaults to 'v6.0_EM_CO2_fossil_IPCC2006'.

Returns

pd.DataFrame DataFrame with columns country_code_a3 (three-letter ISO code), country_code_a2 (two-letter ISO code), country_name (full country name), and Y_YYYY columns for each available year.