Governance-first predictive modelling
Build models whose validation logic matches the scientific claim.
Leakage-resistant, group-aware modelling for Gazepoint research workflows in Python — with explicit generalization targets, auditable predictors, governed decisions, external validation, and reproducible release evidence.
Predictive modelling with explicit scientific contracts¶
gp3mlpy is the Python port of gp3ml 0.3.0. Instead of treating validation as a generic train/test operation, it makes the target of generalization, feature provenance, fitted operations, uncertainty, and reporting evidence visible parts of the analysis.
01
Declare what must generalize¶
Choose new participants, new stimuli, or both from the scientific claim. Splits that violate that target are rejected.
02
Keep fitted operations local¶
Preprocessing, tuning, calibration, thresholds, and related operations remain inside the correct analysis or fold structure.
03
Make predictors auditable¶
Feature manifests record source, role, and permission before model performance is known.
04
Leave an evidence trail¶
Diagnostics, model cards, external-validation reports, checksums, environment capture, handoffs, and release evidence remain inspectable.
The governed lifecycle¶
New to the package? The Quickstart takes you from installation to a validated grouped workflow, then points to the next layer only when you need it.
Choose the route that matches your study¶
Model selection
Nested grouped resampling¶
Separate inner tuning from outer assessment while retaining grouping.
Transportability
External validation¶
Declare an external dataset, quantify shift, and report transportability explicitly.
Decision layer
Governed thresholds¶
Keep threshold origin, error costs, calibration source, and abstention visible.
A validated release, not just a feature list¶
Python quality floor
100% statement and branch coverage¶
- 4,020 / 4,020 executable statements
- 1,700 / 1,700 measured branches
- 0 partial branches
- 125 passing Python tests
- Ubuntu, Windows, macOS × Python 3.11, 3.12, 3.13
- Ruff, mypy, strict MkDocs, build/Twine, installed-wheel API checks
CI permanently enforces --cov-branch --cov-fail-under=100.
Frozen stable API
67 PASS · 4 expected differences · 0 FAIL¶
All 71 stable exports were exercised against the SHA-256-verified gp3ml 0.3.0 release archive.
The four expected differences preserve safer or functioning Python behavior instead of reproducing frozen-R recycling or reference defects.
Diagnostics are part of the evidence¶
The documentation build regenerates synthetic plot fixtures from the current package. The plots visualize declared analysis objects; plotting does not perform hidden model selection.
Inspect declared candidate thresholds and decision consequences.
Separate predictor shift from calibration and performance change.
Surface controls with evidence and controls that still need review.
Where to go next¶
Hard scientific boundary
gp3mlpy is for explicitly observed, non-sensitive outcomes. It must not be used for person identification, biometric authentication, health/diagnosis inference, protected-attribute inference, or direct/indirect inference of emotion, stress, personality, deception, cognition, comprehension, intent, or other mental states.