Feature modelblocks

.copier-answers.yml

@@ -1,13 +1,13 @@
 # Changes here will be overwritten by Copier
-# DO NOT MANUALLY MODIFY THIS FILE
+# !!!!! DO NOT MANUALLY MODIFY THIS FILE !!!!!
 _commit: latest
-_src_path: https://github.com/calliope-project/data-module-template.git
+_src_path: https://github.com/modelblocks-org/data-module-template.git
 author_email: i.ruizmanuel@tudelft.nl
 author_family_name: Ruiz Manuel
 author_given_name: Ivan
-github_org: calliope-project
+github_org: modelblocks-org
 license: Apache-2.0
 module_description: A module to create arbitrary regional boundary datasets for energy
     systems modelling
-module_long_name: clio - Geo-boundaries module
+module_long_name: Modelblocks - Geo-boundaries module
 module_short_name: module_geo_boundaries

.github/ISSUE_TEMPLATE/bug_report.md

@@ -24,7 +24,7 @@ A clear and concise description of what you expected to happen.
 If applicable, add screenshots to help explain your problem.
 
 **Desktop (please complete the following information):**
- - OS: [e.g. Linux Fedora 41, Windows 10...]
+ - OS: [e.g. Linux Fedora 43, Windows 11...]
  - Version [e.g. v0.1.1]
 
 **Additional context**

.github/ISSUE_TEMPLATE/config.yaml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: General information
+    url: https://www.modelblocks.org/
+    about: Please consult our website for general information on the Modelblocks methodology.

.github/pull_request_template.md

@@ -8,6 +8,11 @@ Fixes #
 
 ## Reviewer checklist
 
-* [ ] `INTERFACE.yaml` is up-to-date with all relevant user resources and results.
-* [ ] The integration example is up-to-date with a minimal use-case of the module.
-* [ ] Module documentation is up-to-date.
+* [ ] There are no `pip` dependencies in the module's environment files (`workflow/envs/`).
+* [ ] All rules use `pathvars` (e.g., `<results>`) in their inputs and outputs.
+* [ ] The integration test-suite is successful, including:
+    * [ ] `pre-commit.ci` tests pass.
+    * [ ] tests pass for all relevant OS configurations (linux, osx, windows).
+* [ ] Module documentation is up-to-date, including:
+    * [ ] `INTERFACE.yaml` mentions all relevant `pathvars` and `wildcards`.
+    * [ ] `README.md` describes how to use the module and has the necessary citations.

.github/workflows/check-version.yml

@@ -6,4 +6,4 @@ on:
 
 jobs:
   copier-update:
-    uses: calliope-project/data-module-template/.github/workflows/template-check-version.yml@latest
+    uses: modelblocks-org/data-module-template/.github/workflows/template-check-version.yml@latest

.github/workflows/pr-ci.yml

@@ -1,9 +1,41 @@
-name: CI
+# !!!!! DO NOT MODIFY UNLESS ABSOLUTELY NECESSARY !!!!!
+# This workflow helps standardise integration tests across data modules
+name: Pull Request CI tests for Modelblocks data modules
 on:
   pull_request:
     branches:
       - "main"
-
 jobs:
-  ci-tests:
-    uses: calliope-project/data-module-template/.github/workflows/template-pr-ci.yml@latest
+  build:
+    name: Build
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup pixi
+        uses: prefix-dev/setup-pixi@v0.8.3
+      - name: Run integration tests
+        id: tests
+        run: pixi run test-integration
+        continue-on-error: true
+      - name: Run snakemake linting
+        id: linting
+        run: |
+          pixi run snakemake --lint --snakefile workflow/Snakefile
+          pixi run snakemake --lint --snakefile tests/integration/Snakefile
+        continue-on-error: true
+      - name: Save integration logs
+        if: ${{ always() }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: integration-test-logs-${{ matrix.os }}
+          path: tests/integration/results/integration_test/logs
+          if-no-files-found: ignore
+          retention-days: 30
+      - name: Fail if integration or linting failed
+        if: ${{ steps.tests.outcome == 'failure' || steps.linting.outcome == 'failure' }}
+        run: exit 1

.github/workflows/release.yml

@@ -6,4 +6,6 @@ on:
 
 jobs:
   release-workflow:
-    uses: calliope-project/data-module-template/.github/workflows/template-release.yml@latest
+    permissions:
+      contents: write
+    uses: modelblocks-org/data-module-template/.github/workflows/template-release.yml@latest

.pre-commit-config.yaml

@@ -12,6 +12,7 @@ repos:
       # Repo quality
       - id: check-added-large-files
         args: [--enforce-all]
+        exclude: ^pixi\.lock$
       - id: forbid-submodules
       - id: check-case-conflict
       - id: check-illegal-windows-names
@@ -44,4 +45,4 @@ repos:
         files: .*\.(py|smk|md)$|^Snakefile$
 
 ci:  # https://pre-commit.ci/
-  autoupdate_schedule: monthly
+  autoupdate_schedule: quarterly

INTERFACE.yaml

@@ -1,4 +1,17 @@
 # Module Input-Output structure for automated doc. generation
-results:
-  "shapes.parquet": "Harmonised geodata for all configured countries, including non-contested exclusive economic zones."
-  "shapes.png": "Figure depicting the resulting shapes."
+pathvars:
+  snakemake_defaults:
+    logs:
+      default: "<logs>"
+      description: location of rule log files.
+    resources:
+      default: "<resources>"
+      description: "location of module resource files."
+    results:
+      default: "<results>"
+      description: "location of module results."
+  results:
+    shapes:
+      default: "<results>/shapes.parquet"
+      description: |
+        Harmonised geoparquet dataset with all the configured countries, including non-contested exclusive economic zones.

LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2025 AUTHORS
+   Copyright 2026 AUTHORS
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

README.md

@@ -1,35 +1,66 @@
-# clio - Geo-boundaries module
+# Modelblocks - Geo-boundaries module
 
-A data module to create arbitrary regional boundaries for energy systems modelling.
+A module to create arbitrary regional boundary datasets for energy systems modelling
 
-![Example of European shapes](./docs/europe_example.png)
+<!-- Place an attractive image of module outputs here -->
+<p align="center">
+  <img src="./figures/shapes.png" width="60%">
+</p>
 
-A modular `snakemake` workflow built for [`clio`](https://clio.readthedocs.io/) data modules.
+## About
+<!-- Please do not modify this templated section -->
 
-## Steps
+This is a modular `snakemake` workflow created as part of the [Modelblocks project](https://www.modelblocks.org/). It can be imported directly into any `snakemake` workflow.
 
-1. Data is downloaded and harmonized using a common schema.
-    - Country area data: [GADM](https://gadm.org/), [Overture Maps](https://overturemaps.org/) and [NUTS](https://ec.europa.eu/eurostat/web/gisco/geodata/statistical-units/territorial-units-statistics) divisions are supported as datasources.
-    - [Marine regions](https://www.marineregions.org/) Exclusive Economic Zone (EEZ) data.
-2. Country area is clipped using the marine regions to accurately approximate their landmass.
-3. The marine data and the clipped land mass data are combined following the schema.
-Contested EEZ's (e.g., Taiwan, Falkland islands) are removed during this step.
+For more information, please consult the Modelblocks [documentation](https://modelblocks.readthedocs.io/en/latest/),
+the [integration example](./tests/integration/Snakefile),
+and the `snakemake` [documentation](https://snakemake.readthedocs.io/en/stable/snakefiles/modularization.html).
+
+## Overview
+<!-- Please describe the processing stages of this module here -->
+
+Data processing steps:
+
+<p align="center">
+  <img src="./figures/rulegraph.png" width="60%">
+</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.
+    - Country area data: [GADM](https://gadm.org/), [Overture Maps](https://overturemaps.org/) and [NUTS](https://ec.europa.eu/eurostat/web/gisco/geodata/statistical-units/territorial-units-statistics) divisions are supported.
+    - Exclusive Economic Zone (EEZ) data: [Marine regions](https://www.marineregions.org/).
+2. Individual country files are downloaded and harmonised to fit a standardised schema.
+Contested regions are removed at this stage.
+3. Land is clipped using maritime Exclusive Economic Zones (EEZ).
+4. Each polygon is clipped using its 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.
 
 > [!CAUTION]
-> To increase the replicability of your workflow, recommend using NUTS and GADM as sources whenever possible as they are more stable than Overture Maps.
+> To increase the replicability of your workflow, we recommend using NUTS and GADM as sources whenever possible as they are more stable than Overture Maps.
+
+## Configuration
+<!-- Please describe how to configure this module below -->
+
+Please consult the configuration [README](./config/README.md) and the [configuration example](./config/config.yaml) for a general overview on the configuration options of this module.
 
-## Using this module
+## Input / output structure
+<!-- Please describe input / output file placement below -->
 
-This module can be imported directly into any `snakemake` workflow.
-Please consult the integration example in `tests/integration/Snakefile` for more information.
+This module only has one output: a geoparquet file with your requested geo-boundary "shapes".
+
+Please consult the [interface file](./INTERFACE.yaml) for more information.
 
 ## Development
+<!-- Please do not modify this templated section -->
 
 We use [`pixi`](https://pixi.sh/) as our package manager for development.
-Once installed, run the following to clone this repo and install all dependencies.
+Once installed, run the following to clone this repository and install all dependencies.
 
 ```shell
-git clone git@github.com:calliope-project/module_geo_boundaries.git
+git clone git@github.com:modelblocks-org/module_geo_boundaries.git
 cd module_geo_boundaries
 pixi install --all
 ```
@@ -40,16 +71,25 @@ For testing, simply run:
 pixi run test-integration
 ```
 
-To view the documentation locally, use:
-
-```shell
-pixi run serve-docs
-```
-
 To test a minimal example of a workflow using this module:
 
 ```shell
 pixi shell    # activate this project's environment
 cd tests/integration/  # navigate to the integration example
 snakemake --use-conda --cores 2  # run the workflow!
 ```
+
+## References
+<!-- Please provide thorough referencing below -->
+
+This module is based on the following research and datasets.
+We encourage users to cite both the original source and our workflow.
+
+- 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>.
+- 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>
+- 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.
+- Marine Regions World EEZ v12 (2023). Flanders Marine Institute (MarineRegions.org).
+    - License: CC-By. See <https://www.marineregions.org/disclaimer.php>.

config/README.md

@@ -1,9 +1,8 @@
-# Configuration
+We recommend consulting the following before using this module:
+- `config/config.yaml`: a generic example configuration of this module.
+- `workflow/internal/config.schema.yaml`: a schematic overview of all the configuration options of this module.
+- `INTERFACE.yaml`: lists module input and output files, and their default locations.
+- `tests/integration/Snakefile`: an example of how to call this module from another workflow.
 
-This workflow is part of the [clio project](https://clio.readthedocs.io/en/latest/).
-Please consult our documentation for more details.
-Other useful resources are:
-
-- `INTERFACE.yaml`: user input files (placed in `resources/user`) and module output files (placed in `results`).
-- `workflow/internal/config.schema.yaml`: general configuration options.
-- `tests/integration/`: a simple example of how to use this module.
+This data module is part of the [Modelblocks](https://www.modelblocks.org/) project.
+Please consult the [Modelblocks documentation](https://modelblocks.readthedocs.io/) for more details.

mypy.ini

@@ -1,3 +1,4 @@
 [mypy]
 disable_error_code = import-untyped
 exclude = (^|/)\.(snakemake|pixi)(/|$)
+exclude_gitignore = True