UK_SSPA v2 — Overview¶
UK_SSPA v2 (Universal Kriging with Specified Spatial Polynomial and AEM drift) is a Python program for producing spatially interpolated groundwater level maps from point observation data. It implements Universal Kriging with user-specified drift terms, including polynomial trend functions and Analytic Element Method (AEM) linesink potentials derived from river geometry.
🔬 Validation & Verification¶
This software has been formally validated and verified. The complete V&V report documents 10 validation tests covering all core modules including variogram models, drift terms, anisotropy transformations, and kriging accuracy. Includes direct comparison against PyKrige to verify wrapper equivalence and anisotropy consistency.
📥 Download V&V Report (PDF) 🔍 Browse V&V Scripts & Results
What It Does¶
Given a set of observation wells with measured water levels, UK_SSPA v2:
- Fits a geostatistical model (variogram) to the spatial structure of the data
- Optionally applies a coordinate transformation to handle directional anisotropy in spatial correlation
- Constructs a drift matrix from polynomial terms and/or AEM linesink potentials
- Solves the Universal Kriging system to produce a predicted water level surface on a regular grid
- Exports the result as a map, contour shapefile, or point shapefile
The program is driven entirely by a single config.json file — no code changes are required to switch between configurations.
Key Capabilities¶
Variogram Models¶
Four variogram models are supported: spherical, exponential, gaussian, and linear. Parameters (sill, range, nugget) are specified in the config. See docs/theory/variogram-models.md.
Polynomial Drift Terms¶
Regional groundwater gradients can be captured using polynomial drift terms: linear_x, linear_y, quadratic_x, quadratic_y. These are rescaled for numerical stability using a factor derived from the variogram sill and data extent. See docs/theory/polynomial-drift.md.
AEM Linesink Drift¶
The hydraulic influence of rivers can be represented as a drift term using the Analytic Element Method. Each river (or group of river segments) generates a potential field that is included as a column in the drift matrix. Scaling factors computed during model training are persisted and reused during grid prediction. See docs/theory/aem-linesink.md.
Geometric Anisotropy¶
When spatial correlation is stronger in one direction than another, the coordinate system can be transformed (rotated and scaled) to make the field isotropic before kriging. The angle convention is azimuth (clockwise from North). See docs/theory/anisotropy.md.
Leave-One-Out Cross-Validation (LOOCV)¶
When enabled, the program performs leave-one-out cross-validation and reports RMSE, MAE, and standardized error statistics (Q1, Q2). See docs/api/kriging.md.
Grid Prediction and Export¶
Predictions are made on a regular grid defined by bounding box and resolution in the config. Output options include a matplotlib map, a contour line shapefile, and an auxiliary point shapefile.
Target Audience¶
UK_SSPA v2 is designed for:
- Hydrogeologists who need to produce groundwater level maps from monitoring well networks, with the ability to incorporate river boundary conditions as drift terms
- Spatial analysts working with geostatistical interpolation who need explicit control over drift terms and anisotropy
Users are expected to have: - A projected point shapefile of observation wells with a numeric water level column - Knowledge of approximate variogram parameters for their dataset (or results from a variogram fitting tool) - Optionally: a line shapefile representing rivers, with segment strength values
Architecture¶
UK_SSPA v2 is a config-driven, modular pipeline. All execution logic lives in main.py; each module handles a single concern:
| Module | Responsibility |
|---|---|
data.py |
Config loading, shapefile I/O, data preparation |
variogram.py |
Variogram model definition and evaluation |
transform.py |
Anisotropy coordinate transformation (forward and inverse) |
drift.py |
Polynomial drift computation and diagnostics |
AEM_drift.py |
AEM linesink potential computation |
kriging.py |
Universal Kriging model building, prediction, cross-validation |
The pipeline is a linear sequence of stages: load → transform → build drift → build model → predict → export. See docs/workflow.md for the complete stage-by-stage description.
Documentation Index¶
| Document | Contents |
|---|---|
| Quickstart | Install, configure, and run in 5 minutes |
| Configuration Reference | Every config.json key documented |
| Workflow Reference | Complete pipeline stage-by-stage |
| Data Contracts | Input shapefile requirements, null handling |
| Glossary | All domain terms and angle/coordinate conventions |
| 📥 V&V Report (PDF) | Formal validation report — 10 tests, PyKrige comparison |
| V&V: Tested Behaviors | Summary of all validation test cases |
| V&V: Scripts & Results | Browse validation scripts and output |
| Theory: Variogram Models | Model equations and parameter effects |
| Theory: Anisotropy | Coordinate transformation math and conventions |
| Theory: Polynomial Drift | Universal Kriging drift formulation |
| Theory: AEM Linesink Drift | Complex potential formula and scaling |
| API: data.py | Function signatures and contracts |
| API: variogram.py | Class attributes, methods, validation |
| API: transform.py | Transform functions and orientation |
| API: drift.py | Drift computation and diagnostics |
| API: AEM_drift.py | Linesink potential and scaling |
| API: kriging.py | Model building, prediction, cross-validation |
| Example: Ordinary Kriging | Simplest end-to-end usage |
| Example: Linear Drift | Modeling a regional gradient |
| Example: Linesink Drift | Incorporating river influence |
| Example: Anisotropy | Directional spatial correlation |