pygeotypes: shape catalogues of physical response signals

Software note (CC-BY-4.0): "pygeotypes: A Dependency-Light Shape-Catalogue Library with Class-Conditional Conformal Assignment for Physical Response Signals", concept DOI 10.5281/zenodo.21511918 (source in manuscripts/shape-catalogue-conformal/). It describes the reusable library and validates the conformal layer (empirical coverage tracks the target; alien shapes flagged out-of-catalogue). The GeoTypes clustering methodology is the work of Kamel Targhi et al. (2026), cited throughout.

pygeotypes builds a catalogue of behaviour types from response signals whose shape reflects the underlying physical system, pressure transients of fractured reservoirs, hydrogeology pumping tests, thermal response tests, and assigns new signals to that catalogue with statistical guarantees. It packages the methodology of Kamel Targhi et al. (2026, Computational Geosciences, DOI 10.1007/s10596-026-10459-w) as a reusable, permissively-licensed library, and adds a conformal-prediction assignment layer on top.

Naming. pip install pygeotypes · import pygeotypes, distribution and import match. The bare name geotypes is taken on PyPI by an unrelated geospatial-utilities package; this library is unrelated to it and shares no module names with it. "GeoTypes" itself is the term of the methodology paper (the catalogue of flow-behaviour types).

Why this package exists (mid-2026 gap): scikit-learn-extra (k-medoids) is unmaintained, the fast Rust kmedoids is GPL-3, tslearn/aeon drag numba/native dependencies that do not run in Pyodide. The pygeotypes core is pure numpy/scipy, it runs unchanged offline and in the browser (Pyodide), with optional accelerated/attribution extras.

The pipeline

raw (t, p) signals
   │  preprocess: log-resample → Bourdet derivative → p'' → normalize
   ▼
curves on a common log grid
   │  distance: Sakoe-Chiba banded DTW (numpy DP; dtaidistance backend offline)
   ▼
pairwise distance matrix
   │  cluster: PAM k-medoids (BUILD+SWAP, multi-init, seeded) + silhouette K-selection
   ▼
Catalogue (medoid curves + labels + provenance; exact JSON round-trip)
   │  assign: nearest-medoid  +  split-conformal p-values / prediction sets / OOD flag
   │  attribute (extra): RF + TreeSHAP + permutation cross-check + correlation pruning
   ▼
which behaviours exist · which one is this signal · what controls each behaviour

Install

pip install pygeotypes            # pure core (numpy + scipy)
pip install pygeotypes[fast]      # + dtaidistance (C-fast offline DTW matrices)
pip install pygeotypes[attr]      # + scikit-learn + shap (attribution layer)

Quickstart

import numpy as np
from pygeotypes import (
    generate_warren_root_ensemble, prepare_curves, dtw_matrix,
    pam_kmedoids, select_k, build_catalogue, ConformalAssigner, nearest_medoid,
)
from pygeotypes.preprocess import prepare_curves

# 1. an ensemble of dual-porosity pressure responses (or bring your own curves)
ens = generate_warren_root_ensemble(200, seed=0)
t_list = [ens["tD"]] * 200
p_list = list(ens["curves"])

# 2. preprocess: common log grid + Bourdet derivative + z-score
t_grid, X = prepare_curves(t_list, p_list, n_points=96, derivative_order=1)

# 3. cluster into GeoTypes
D = dtw_matrix(X, window=10)                 # dtaidistance if installed, else numpy
diag = select_k(D, range(2, 9))              # silhouette + elbow diagnostics
res = pam_kmedoids(D, k=diag["best_k"], seed=0)

# 4. the persistent catalogue artifact
cat = build_catalogue(X, t_grid, D, k=res.k, dtw_window=10, result=res)
cat.to_json("catalogue.json")

# 5. assign a NEW curve: with conformal guarantees
assigner = ConformalAssigner(cat).fit(X_calibration, labels_calibration)
out = assigner.predict(new_curve, alpha=0.1)
out.point_prediction      # nearest medoid
out.prediction_set        # GeoTypes consistent with the curve at 90% coverage
out.out_of_catalogue      # honest "this shape is not in the catalogue" flag

Modules

Guarantees & honesty

• Determinism: every stochastic step is seeded (numpy.random.default_rng); same inputs + seed → identical catalogue, bit-for-bit.
• Conformal validity: under exchangeability, prediction sets cover the true class with probability ≥ 1−α per class (class-conditional calibration). The empty set is reported as an out-of-catalogue flag, never silently replaced by the nearest medoid. Mind the finite-sample floor: the minimum achievable p-value is 1/(n_c+1), so α below that cannot produce empty sets.
• Attribution gate: if the Random Forest cannot predict the labels from the descriptors (held-out accuracy below the gate), SHAP/permutation importances are withheld, noise is not reported as insight. SHAP and permutation rankings are cross-checked (Spearman agreement).
• Physics validation: the synthetic generators are tested against closed-form limits (homogeneous late-time 0.5(ln tD + 0.80907), derivative plateau 0.5, Warren-Root → homogeneous as ω→1, valley-depth monotonicity in ω).

Docs

• docs/theory.md: the science: PTA derivatives, DTW, PAM, conformal prediction, attribution pitfalls (with references)
• docs/quickstart.md: worked end-to-end example
• docs/design.md: package design, licensing rationale, Pyodide lane, API stability

Development

py -3.12 -m venv .venv && .venv/Scripts/pip install -e .[dev,attr,fast]
.venv/Scripts/python -m pytest    # 32 tests: physics limits, DTW properties/parity, PAM recovery,
                                  # conformal coverage + OOD, JSON round-trips, SHAP sanity

Versioning: CAOS X.XX.XXX display convention (CHANGELOG + git tags); PEP 440 in pyproject.toml. Consumed by CAOS_RES_FlowDNA (FlowDNA).