Framework

JSON-driven process definitions called from Jupyter notebooks. No code changes needed to reconfigure workflows — edit a JSON file and re-run.

Read more

Database setup

Step-by-step guide to installing PostgreSQL, creating an Anaconda environment, and defining schemas and tables using Xspatula from a Jupyter notebook.

Read more

AI4SoilHealth database

Step-by-step guide to seeding the EU-funded AI4SoilHealth (AI4SH) PostgreSQL database — 9 schemas covering soil observations, eDNA, landscape, and more — using the Xspatula framework.

Read more

Open source

Code under MIT License, data under CC-BY. Clone the framework from GitHub and adapt it to your own domain.

View on GitHub

What is Xspatula?

Xspatula is a Python framework for building database-integrated modelling workflows. The core idea is simple: all execution logic lives in JSON files, not in code. You define schemes, jobs, pilots, and processes in JSON; a Jupyter notebook calls the framework; the framework reads the JSON and runs the pipeline.

This separation makes it straightforward to:

  • swap datasets without touching Python
  • version-control your experimental configurations separately from the codebase
  • hand workflows to non-programmers who edit JSON rather than code

The framework uses PostgreSQL as its backbone. Every result, parameter set, and process definition is stored in the database, which gives you full audit trails and makes it easy to query what ran, when, and with what inputs.

Documentation

The full documentation is at xspatula.github.io/setup_core_db_docs and covers:

  • Framework architecture — scheme files, job files, pilot files, process files, notebook interface
  • Database setup — PostgreSQL, Anaconda, .netrc credentials, schemas and tables

AI4SoilHealth case study

xspatula.github.io/seed_ai4sh_db_docs documents seeding the EU Horizon-funded AI4SoilHealth database using the Xspatula framework:

  • Setup DB — defines 9 schemas and all tables (utility, community, process, landscape, observation, eDNA and their utility schemas)
  • Setup processes — registers all framework processes in the database

Licenses