Add scenario processing

INTERFACE.yaml

@@ -12,6 +12,8 @@ pathvars:
       description: "location of module results."
   results:
     shapes:
-      default: "<results>/shapes.parquet"
+      default: "<results>/{scenario}/shapes.parquet"
       description: |
-        Harmonised geoparquet dataset with all the configured countries, including non-contested exclusive economic zones.
+        Harmonised geoparquet dataset for a configured scenario, including land and maritime non-contested EEZs.
+wildcards:
+  scenario: Scenario name from the module configuration.

README.md

@@ -26,21 +26,30 @@ Data processing steps:
 </p>
 
 
-1. The configuration file is read to identify the datasets to use as well as the specific countries and regional aggregation (`subtype` in the configuration) to process.
+1. 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](https://ec.europa.eu/eurostat/web/gisco/geodata/statistical-units/territorial-units-statistics), [GADM](https://gadm.org/), [geoBoundaries](https://www.geoboundaries.org/), and [Overture Maps](https://overturemaps.org/) are supported.
     - Exclusive Economic Zone (EEZ) data: [MarineRegions.org](https://www.marineregions.org/).
 2. 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.
-3. Each country file is combined and then clipped using its neighbours to minimise overlapping polygons.
+3. The country files requested in the scenario are combined and then clipped using their neighbours to minimise overlapping polygons.
 
 > [!TIP]
-> The `subtype` naming matches that of the source database. For example, NUTS uses 0, 1, 2 and 3 (NUTS0, NUTS1, NUTS2, etc.).
-> Use the references at the bottom of this page for more details.
+> 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]
-> To increase the replicability of your workflow, we recommend using NUTS and geoBoundaries as sources whenever possible as they have more stable hosting methods than Overture Maps and GADM.
+> Be aware of the following known issues.
+>
+>- Overture Maps replicability: this data source [does not retain versions](https://github.com/orgs/OvertureMaps/discussions/422) 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](https://geopandas.org/en/v1.1.3/about/roadmap.html#s2-geometry-engine).
+> For now, we advice to use global projections (EPSG:3857, EPSG:8857) as a way to mitigate it.
 
 ## Configuration
 <!-- Please describe how to configure this module below -->
@@ -50,7 +59,7 @@ Please consult the configuration [README](./config/README.md) and the [configura
 ## Input / output structure
 <!-- Please describe input / output file placement below -->
 
-This module only has one output: a geoparquet file with your requested geo-boundary "shapes".
+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](./INTERFACE.yaml) for more information.
 

config/config.yaml

@@ -1,33 +1,215 @@
 # A minimal example of how to configure this module
+
+# Default global settings across scenarios
 voronoi_eez:
   enabled: True
   sample_spacing: 10000 # sample every 10 km
 crs:
   projected: "epsg:3857"
   geographic: "epsg:4326"
-countries:
-  DNK:
-    subtype: "1"
-    source: "nuts"
-    resolution: 01M
-    year: 2024
-  GBR:
-    subtype: "country"
-    source: "overture"
-  NLD:
-    subtype: 0
-    source: "geoboundaries"
-    release_type: "gbOpen"
-  BEL:
-    subtype: 1
-    source: "geoboundaries"
-    release_type: "gbOpen"
-  CHE:
-    subtype: "country"
-    source: "overture"
-  ESP:
-    subtype: "2"
-    source: "nuts"
-    resolution: 01M
-    year: 2024
-    extra_eez: 8364
+
+# At least one scenario.
+# We include four cases as examples.
+scenarios:
+  mixed_example:
+    # Assorted countries
+    countries:
+      DNK:
+        subtype: "1"
+        source: "nuts"
+        resolution: 01M
+        year: 2024
+      GBR:
+        subtype: "country"
+        source: "overture"
+      NLD:
+        subtype: 0
+        source: "geoboundaries"
+        release_type: "gbOpen"
+      BEL:
+        subtype: 1
+        source: "geoboundaries"
+        release_type: "gbOpen"
+      CHE:
+        subtype: "country"
+        source: "overture"
+      ESP:
+        subtype: "2"
+        source: "nuts"
+        resolution: 01M
+        year: 2024
+        extra_eez: 8364
+  china_national:
+    # Large country at national level
+    # China has contested borders, which will be removed by the module
+    voronoi_eez:
+      enabled: False
+      sample_spacing: 10000
+    countries:
+      "CHN":
+        subtype: "country"
+        source: "overture"
+  USA_states:
+    # Example of regional disaggregation of a large country crossing the antimeridean.
+    # USA has multiple marine zones, which can be appended as extras
+    countries:
+      "USA":
+        subtype: "1"
+        source: "gadm"
+        extra_eez: [8463, 8453]
+  europe_regions:
+    # A large continental example.
+    # Europe at regional resolution.
+    crs:
+      projected: "epsg:3035"
+      geographic: "epsg:4326"
+    countries:
+      "ALB":
+        subtype: "1"
+        source: "geoboundaries"
+        release_type: "gbOpen"
+      "AUT":
+        subtype: "1"
+        source: "geoboundaries"
+        release_type: "gbOpen"
+      "BEL":
+        subtype: "1"
+        source: "geoboundaries"
+        release_type: "gbOpen"
+      "BGR":
+        subtype: "1"
+        source: "geoboundaries"
+        release_type: "gbOpen"
+      "BIH":
+        subtype: "1"
+        source: "geoboundaries"
+        release_type: "gbOpen"
+      "CHE":
+        subtype: "1"
+        source: "geoboundaries"
+        release_type: "gbOpen"
+      "CYP":
+        subtype: "1"
+        source: "geoboundaries"
+        release_type: "gbOpen"
+      "CZE":
+        subtype: "1"
+        source: "geoboundaries"
+        release_type: "gbOpen"
+      "DEU":
+        subtype: "1"
+        source: "geoboundaries"
+        release_type: "gbOpen"
+      "DNK":
+        subtype: "1"
+        source: "nuts"
+        resolution: 01M
+        year: 2024
+      "ESP":
+        subtype: "1"
+        source: "geoboundaries"
+        release_type: "gbOpen"
+        extra_eez: 8364
+      "EST":
+        subtype: "1"
+        source: "geoboundaries"
+        release_type: "gbOpen"
+      "FIN":
+        subtype: "1"
+        source: "geoboundaries"
+        release_type: "gbOpen"
+      "FRA":
+        subtype: "1"
+        source: "geoboundaries"
+        release_type: "gbOpen"
+      "GBR":
+        subtype: "region"
+        source: "overture"
+      "GGY":
+        subtype: "0"
+        source: "geoboundaries"
+        release_type: "gbOpen"
+      "GRC":
+        subtype: "1"
+        source: "geoboundaries"
+        release_type: "gbOpen"
+      "HRV":
+        subtype: "1"
+        source: "geoboundaries"
+        release_type: "gbOpen"
+      "HUN":
+        subtype: "1"
+        source: "geoboundaries"
+        release_type: "gbOpen"
+      "IMN":
+        subtype: "0"
+        source: "geoboundaries"
+        release_type: "gbOpen"
+      "IRL":
+        subtype: "region"
+        source: "overture"
+      "ITA":
+        subtype: "1"
+        source: "geoboundaries"
+        release_type: "gbOpen"
+      "LTU":
+        subtype: "1"
+        source: "geoboundaries"
+        release_type: "gbOpen"
+      "LUX":
+        subtype: "1"
+        source: "geoboundaries"
+        release_type: "gbOpen"
+      "LVA":
+        subtype: "1"
+        source: "geoboundaries"
+        release_type: "gbOpen"
+      "MKD":
+        subtype: "1"
+        source: "geoboundaries"
+        release_type: "gbOpen"
+      "MNE":
+        subtype: "1"
+        source: "geoboundaries"
+        release_type: "gbOpen"
+      "NLD":
+        subtype: "region"
+        source: "overture"
+      "NOR":
+        subtype: "1"
+        source: "geoboundaries"
+        release_type: "gbOpen"
+      "POL":
+        subtype: "1"
+        source: "geoboundaries"
+        release_type: "gbOpen"
+      "PRT":
+        subtype: "1"
+        source: "nuts"
+        resolution: 01M
+        year: 2024
+        extra_eez: [8361, 8363]
+      "ROU":
+        subtype: "1"
+        source: "geoboundaries"
+        release_type: "gbOpen"
+      "SRB":
+        subtype: "1"
+        source: "geoboundaries"
+        release_type: "gbOpen"
+      "SVK":
+        subtype: "1"
+        source: "geoboundaries"
+        release_type: "gbOpen"
+      "SVN":
+        subtype: "1"
+        source: "geoboundaries"
+        release_type: "gbOpen"
+      "SWE":
+        subtype: "1"
+        source: "geoboundaries"
+        release_type: "gbOpen"
+      "XKX":
+        subtype: "1"
+        source: "geoboundaries"
+        release_type: "gbOpen"