gp3bayespy

Contract-first Bayesian workflows for hierarchical behavioural data in Python

Documentation · PyPI · Examples · Articles · Migration guide · Release v0.6.1 · Archived v0.5.0 DOI

gp3bayespy is the Python port of the R package gp3bayes. It provides governed Bayesian workflows for repeated-measures and hierarchical behavioural data, with first-class support for model contracts, posterior and predictive diagnostics, sensitivity analysis, PSIS-LOO model comparison, reproducibility, and dynamic pupillometry.

Version 0.5.0 is the first public Python release frozen against gp3bayes 0.5.0.

Version 0.6.1 adds contract-first Bayesian multilevel gaze mediation while preserving the frozen gp3bayes 0.5.0 parity baseline.

v0.6.0 is retained only as a withdrawn GitHub audit release; it was never published to PyPI.

Why gp3bayespy?

Installation

Core

python -m pip install gp3bayespy

Bayesian backends and plotting

python -m pip install "gp3bayespy[bayes,plots]"

Complete environment

python -m pip install "gp3bayespy[all]"

The core installation contains NumPy, pandas, and SciPy workflows. PyMC, CmdStanPy, ArviZ/xarray, and Matplotlib are optional and installed through the corresponding extras.

Quick start

import pandas as pd
from gp3bayespy import (
    audit_model_readiness,
    create_model_contract,
    create_model_specification,
    create_prior_specification,
)

data = pd.DataFrame(
    {
        "participant_id": ["p1"] * 4 + ["p2"] * 4,
        "trial_id": [1, 2, 3, 4] * 2,
        "condition": ["control", "treatment"] * 4,
        "selected": [0, 1, 0, 1, 1, 0, 1, 0],
    }
)

contract = create_model_contract(
    family="binary",
    outcome_col="selected",
    participant_col="participant_id",
    trial_col="trial_id",
    condition_col="condition",
)

audit = audit_model_readiness(data, contract)
priors = create_prior_specification(contract, baseline=0.5)
specification = create_model_specification(contract, audit, priors)

print(specification.formula_text)

The package separates data readiness, prior declaration, model specification, fitting, diagnostics, estimands, and sensitivity rather than hiding those decisions inside a single convenience call.

Workflow map

Documentation

The documentation site is the primary user guide:

• Getting started — package orientation and first workflow.
• API reference — public Python API.
• 59 articles — Python-facing ports of the canonical gp3bayes vignettes.
• Executable examples — thirteen executable scripts spanning the core and mediation workflows.
• Plot gallery — publication-oriented plotting workflows.
• Migration guide — R-to-Python mapping for gp3bayes users.

Parity and validation

The 0.5.0 release is frozen against the CRAN source archive gp3bayes_0.5.0.tar.gz.

The machine-readable parity ledger is dev/parity/function_map.csv, the article map is dev/parity/articles.json, and the final freeze record is dev/parity/final_deep_freeze_0.5.0.json.

537eb05f949de1bcc1d6f8234066f064597951ecfa9cbbdf938d0a895ce5dd8a

Governance

gp3bayespy intentionally separates statistical evidence from analyst conclusions. Creating or fitting a model does not automatically establish convergence, model adequacy, causal identification, robustness, a preferred model, participant/group exclusion, or psychological/cognitive/emotional interpretation.

Automatic-selection and automatic-adequacy fields remain explicit and conservative where relevant.

Citation

If you use gp3bayespy, cite the archived software record for the version you used. The DOI for gp3bayespy 0.5.0 is 10.5281/zenodo.22150746. Repository citation metadata are provided in CITATION.cff. Cite the gp3bayes R reference where it is methodologically relevant.

License

MIT License. See LICENSE.

October 2026 research article and figure

Pupil visual covariates and Bayesian qualification documents experimental, source-only validation methods and reproducible synthetic examples. It is available in the website navigation, while independently qualified external empirical claims and stable PyPI APIs remain separate (scientific acceptance criteria).