From f7a3d2060ff3906cfeb19ee88f09c466fac18882 Mon Sep 17 00:00:00 2001
From: Ivan Ruiz Manuel <72193617+irm-codebase@users.noreply.github.com>
Date: Thu, 16 Apr 2026 23:38:02 -0600
Subject: [PATCH 1/4] Frontload readme
---
README.md | 84 ++-
config/config.yaml | 4 +-
docs/europe_example.png | Bin 267273 -> 0 bytes
docs/index.md | 4 -
figures/.gitkeep | 1 -
figures/fossil_adjustment_MEX.png | Bin 0 -> 56830 bytes
figures/fossil_aggregation_MEX.png | Bin 0 -> 112196 bytes
figures/fossil_histogram_MEX.png | Bin 0 -> 50538 bytes
figures/powerplant_location_algorithm.svg | 593 ++++++++++++++++++++++
figures/rooftop_pv_proxy_MEX.png | Bin 0 -> 286083 bytes
figures/rulegraph.png | Bin 0 -> 111058 bytes
figures/solar_aggregation_europe.png | Bin 0 -> 207219 bytes
workflow/internal/config.schema.yaml | 6 +-
workflow/scripts/_plots.py | 85 +---
workflow/scripts/impute_ages.py | 94 +++-
workflow/scripts/impute_location.py | 4 +-
workflow/scripts/proxy.py | 21 +-
17 files changed, 786 insertions(+), 110 deletions(-)
delete mode 100644 docs/europe_example.png
delete mode 100644 docs/index.md
delete mode 100644 figures/.gitkeep
create mode 100644 figures/fossil_adjustment_MEX.png
create mode 100644 figures/fossil_aggregation_MEX.png
create mode 100644 figures/fossil_histogram_MEX.png
create mode 100644 figures/powerplant_location_algorithm.svg
create mode 100644 figures/rooftop_pv_proxy_MEX.png
create mode 100644 figures/rulegraph.png
create mode 100644 figures/solar_aggregation_europe.png
diff --git a/README.md b/README.md
index e0ac1ec..15a4b07 100644
--- a/README.md
+++ b/README.md
@@ -3,6 +3,9 @@
Aggregate global powerplant capacities into any resolution.
+
+
+
## About
@@ -18,8 +21,63 @@ and the `snakemake` [documentation](https://snakemake.readthedocs.io/en/stable/s
Data processing steps:
-1.
-2.
+
+
+
+
+
+1. Stable version-controlled global datasets are downloaded, including:
+ - Disaggregated powerplant statistics from [GEM](https://globalenergymonitor.org/), [Transition-Zero](https://www.transitionzero.org/products/solar-asset-mapper), and [GloHydroRES](https://zenodo.org/records/14526360).
+ - National-level statistics from the [EIA](https://www.eia.gov/).
+2. Individual powerplants are prepared into seven different categories (bioenergy, fossil, geothermal, hydropower, nuclear, solar, wind).
+ - Fuel-burning powerplants (fossil, bioenergy) are assigned unique fuel-classes depending on the combination of fuels they utilse.
+ - For utility-scale solar projects, satellite detected [TZ-Solar Asset Mapper](https://www.transitionzero.org/products/solar-asset-mapper) facilities are matched to [GEM-Global Solar Power Tracker](https://globalenergymonitor.org/) data to obtain a highly complete dataset of large-scale solar facilities.
+3. Powerplants are selected according to the shapes file provided by the user. Depending on the configuration, their placement may be adjusted per technology and country.
+
+
+
+
+
+4. Powerplant start and end dates are imputed per category/technology using the configuration.
+ - `lifetime_years` determines overall technology lifetime.
+ - `retirement_delay_years` determines the remaining years of powerplants currently operating beyond their expected lifetime.
+
+
+
+
+
+> [!NOTE]
+> Powerplant start/end dates are only imputed if they are not provided in the original dataset.
+
+5. Optionally, powerplant capacities are adjusted evenly per category and country to match EIA statistics.
+
+
+
+
+
+
+> [!IMPORTANT]
+> This stage may significantly inflate/deflate individual powerplants.
+> We encourage users to carefully assess if this adjustment is merited by their use-case.
+
+6. Powerplant capacity is aggregated to the provided shapes, for either adjusted or unadjusted powerplants.
+
+
+
+
+
+7. Solar is processed as a special case because rooftop PV pannels are not covered in GEM or Transition-Zero data.
+ 1. Per country: $solar_{rooftop\_PV} = solar_{national\_statistics} - solar_{large\_scale}$.
+ 2. A user-provided proxy raster is used to determine how to disaggregate $solar_{rooftop\_PV}$.
+ 3. This proxy is used to determine the aggregated rooftop PV capacity per-shape.
+
+
+
+
+
+> [!NOTE]
+> Due to this assumption, the lifetime of rooftop PV capacity is left undetermined.
+
## Configuration
@@ -60,7 +118,21 @@ snakemake --use-conda --cores 2 # run the workflow!
## References
-This module is based on the following research and datasets:
-
-*
-*
+This module is based on the following research and datasets.
+For specific versions please consult our [stable dataset repository](https://doi.org/10.5281/zenodo.16779120).
+
+* **Global Energy Monitor datasets.** . License: CC BY 4.0.
+ - Global Bioenergy Power Tracker
+ - Global Coal Plant Tracker
+ - Global Geothermal Power Tracker
+ - Global Nuclear Power Tracker
+ - Global Oil and Gas Plant Tracker
+ - Global Solar Power Tracker
+ - Global Wind Power Tracker
+* **Global Hydropower powerplants.**
+Shah, J., Hu, J., Edelenbosch, O., & van Vliet, M. T. H. (2024). GloHydroRes - a global dataset combining open-source hydropower plant and reservoir data [Data set]. Zenodo. . License: CC BY 4.0.
+* **National capacity dataset.**
+U.S. Energy Information Administration (Oct 2008).
+* **Satellite Utility-scale PV dataset.**
+TransitionZero Solar Asset Mapper, TransitionZero. .
+License: CC BY-NC 4.0.
diff --git a/config/config.yaml b/config/config.yaml
index 0edf014..8bbfe30 100644
--- a/config/config.yaml
+++ b/config/config.yaml
@@ -95,8 +95,8 @@ imputation:
remove_shape_overlaps: false
inner_distance: 100 # matches projected CRS unit.
on_overlap: "raise" # either 'split_capacity', or 'raise'
- on_forced_class_error: "drop" # either 'drop', 'ignore', or 'raise'
- forced_class:
+ on_shape_class_error: "drop" # either 'drop', 'ignore', or 'raise'
+ shape_class:
bioenergy turbine: "land"
ccgt: "land"
coal turbine: "land"
diff --git a/docs/europe_example.png b/docs/europe_example.png
deleted file mode 100644
index c63e9a3504ce42a4fe6fd97d2f61f1c8479ec70b..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001
literal 267273
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