A module to create arbitrary regional boundary datasets for energy systems modelling
This is a modular snakemake workflow created as part of the Modelblocks project. It can be imported directly into any snakemake workflow.
For more information, please consult the Modelblocks documentation,
the integration example,
and the snakemake documentation.
Data processing steps:
- The configuration file is read to identify which requested geopolitical combination (
scenarios) was requested. These can be any number of nations (countries), each coming from a distinct dataset (source) and with its own subnational aggregation (subtype).- Country landmass data: eurostat NUTS, GADM, geoBoundaries, and Overture Maps are supported.
- Exclusive Economic Zone (EEZ) data: MarineRegions.org.
- Individual country files are downloaded and harmonised to fit a standardised schema.
- If identified, contested regions are removed at this stage.
- Land is clipped using maritime Exclusive Economic Zones (EEZ).
- Optionally, a Voronoi algorithm is run to separate EEZ areas to fit subnational regions.
- The country files requested in the scenario are combined and then clipped using their neighbours to minimise overlapping polygons.
Tip
Keep in mind the following
- All downloaded data is kept locally for future reuse across scenarios to minimise stress on the data sources the module relies on.
- Data source availability can vary. Always consult the data source website to identify if a country is available at the desired resolution.
Caution
Be aware of the following known issues.
- Overture Maps replicability: this data source does not retain versions for long. If replicability is important to you, we suggest configuring other sources.
- Anti-meridian distortions: regions near the 180/-180 line (e.g., Fiji, Hawaii, New Zealand, Alaska) might be distorted during processing.
This is a known issue in the libraries we rely on (
geopandas,GDAL) and something that is being actively worked on at the moment. For now, we advice to use global projections (EPSG:3857, EPSG:8857) as a way to mitigate it.
Please consult the configuration README and the configuration example for a general overview on the configuration options of this module.
This module only has one output: a geoparquet file with your requested geo-boundary "shapes" for each of the the configured scenarios.
Please consult the interface file for more information.
We use pixi as our package manager for development.
Once installed, run the following to clone this repository and install all dependencies.
git clone git@github.com:modelblocks-org/module_geo_boundaries.git
cd module_geo_boundaries
pixi install --allFor testing, simply run:
pixi run test-integrationTo test a minimal example of a workflow using this module:
pixi shell # activate this project's environment
cd tests/integration/ # navigate to the integration example
snakemake --use-conda --cores 2 # run the workflow!This module is based on the following research and datasets. We encourage users to cite both the original source and our workflow.
- eurostat NUTS (various years). Nomenclature of territorial units for statistics (NUTS).
- License: reuse is authorised provided the source is acknowledged. https://ec.europa.eu/eurostat/statistics-explained/index.php?title=Copyright/licence_policy
- GADM 4.1. (2018). Global Administrative Areas (GADM).
- License: GADM data is freely available for academic and non-commercial use. https://gadm.org/license.html.
- geoBoundaries (most recent version). William & Mary geoLab.
- License: varies per dataset type (from CC-BY 4.0 compliant to non-commercial use only). Consult their documentation for details. https://www.geoboundaries.org/.
- Marine Regions World EEZ v12 (2023). Flanders Marine Institute (MarineRegions.org).
- License: CC-By. See https://www.marineregions.org/disclaimer.php.
- Overture Maps Divisions database (most recent version). Overture Maps Foundation.
- License: ODbL. See https://docs.overturemaps.org/attribution/ and https://opendatacommons.org/licenses/odbl/summary/ for details.