gp3bayes

gp3bayes is an independent R package for transparent, contract-first Bayesian workflows for repeated-measures and hierarchical behavioural data.

Scope

The package currently provides:

• explicit contracts and model-readiness audits;
• deterministic binary and positive-duration simulation with stored truth;
• recorded outcome, condition, unit, missing-value, and scaling decisions;
• inspectable backend-independent prior specifications and prior checks;
• restricted Bernoulli-logit and lognormal formula construction;
• optional full-MCMC fitting through the fixed brms and rstan route;
• R-hat, bulk/tail ESS, divergence, treedepth, and energy diagnostics;
• posterior summaries and family-specific posterior predictive checks;
• prior-scale sensitivity and simulation-based parameter recovery;
• conservative structured reporting without automatic adequacy claims.

The initial development scope is restricted to:

1. hierarchical Bernoulli-logit models for binary trial-level outcomes;
2. hierarchical lognormal models for strictly positive uncensored durations.

Core contract, validation, simulation, preparation, specification, and prior-predictive functionality does not require Gazepoint hardware, Gazepoint exports, gp3tools, proprietary software, private data, or a Bayesian backend. Binary fitting requires the optional brms and rstan packages.

Model contracts

create_model_contract() records the approved methodological specification and neutral column mappings for one initial model family. Creating a contract does not validate data, fit a model, or establish model adequacy.

binary_contract <- create_model_contract(
  family = "binary",
  outcome_col = "selected",
  participant_col = "participant_id",
  item_col = "stimulus_id",
  trial_col = "trial_id",
  condition_col = "condition"
)

binary_contract

## <gp3bayes_model_contract>
##   Family: binary
##   Likelihood: Bernoulli
##   Link: logit
##   Outcome: selected
##   Participant: participant_id
##   Item: stimulus_id
##   Condition: condition
##   Random slope requested: FALSE
##   Fitting performed: FALSE

Readiness audits

audit_model_readiness() evaluates observable data requirements before formula construction or model fitting. Failures block progression, whereas warnings identify structures requiring review.

binary_data <- data.frame(
  participant_id = rep(c("p1", "p2"), each = 4),
  stimulus_id = rep(paste0("s", 1:4), times = 2),
  trial_id = rep(1:4, times = 2),
  condition = rep(c("control", "treatment"), times = 4),
  selected = c(0, 1, 0, 1, 1, 0, 1, 0)
)

readiness_audit <- audit_model_readiness(
  binary_data,
  binary_contract
)

readiness_audit

## <gp3bayes_readiness_audit>
##   Family: binary
##   Rows: 8
##   Status: ready
##   Ready: TRUE
##   Checks: 18 passed, 0 warnings, 0 failures

Model specifications

build_model_formula() translates the approved contract into an R formula, while create_prior_specification() records family-appropriate priors without creating backend-specific objects. A ready audit, formula, contract, and validated priors can then be combined into one inspectable model specification.

binary_priors <- create_prior_specification(
  binary_contract,
  baseline = 0.5
)

binary_specification <- create_model_specification(
  binary_contract,
  readiness_audit,
  binary_priors
)

binary_specification

## <gp3bayes_model_specification>
##   Family: binary
##   Formula: selected ~ condition + (1 | participant_id) + (1 | stimulus_id)
##   Readiness status: ready
##   Readiness warnings: 0
##   Prior classes: Intercept, b, sd
##   Backend: none
##   Fit performed: FALSE

Hierarchical binary workflow foundation

The backend-independent binary workflow can simulate known hierarchical data-generating processes, prepare neutral long-format data, construct a restricted model specification, and evaluate prior predictive plausibility. No model is fitted and no posterior draws are produced.

binary_simulation <- simulate_hierarchical_binary_data(
  n_participants = 12,
  trials_per_participant = 8,
  n_items = 6,
  random_slope_sd = 0,
  seed = 2026
)

binary_workflow_contract <- create_model_contract(
  family = "binary",
  outcome_col = "selected",
  participant_col = "participant_id",
  item_col = "item_id",
  trial_col = "trial_id",
  condition_col = "condition",
  predictors = "trial_covariate"
)

binary_prepared <- prepare_hierarchical_binary_data(
  binary_simulation$data,
  binary_workflow_contract,
  condition_levels = c("control", "treatment"),
  scale_predictors = "trial_covariate"
)

binary_workflow_specification <- specify_binary_model(
  binary_prepared,
  baseline = 0.35
)

binary_prior_check <- check_binary_prior_predictive(
  binary_workflow_specification,
  draws = 100,
  seed = 2027
)

binary_prior_check

## <gp3bayes_binary_prior_predictive_check>
##   Adequate: TRUE
##   Draws: 100
##   Failed checks: 0
##   Backend: none
##   Fit performed: FALSE

Restricted binary model fitting

translate_binary_model_to_brms() converts an approved package specification into a fixed Bernoulli-logit brms representation without compiling or fitting a model. fit_binary_model() optionally runs full MCMC sampling through the fixed brms and rstan route. Neither function accepts an unrestricted formula, family, backend, algorithm, Stan extension, or arbitrary backend arguments.

if (requireNamespace("brms", quietly = TRUE)) {
  backend_specification <- translate_binary_model_to_brms(
    binary_workflow_specification
  )

  backend_specification
}

A returned fit does not by itself establish convergence, posterior adequacy, causal identification, or substantive validity. Those assessments require separate diagnostic and reporting gates.

Binary posterior validation

Approved binary fits can be assessed with conservative numerical sampling diagnostics, posterior summaries, posterior predictive checks, prior-scale sensitivity, simulation-based recovery, and structured Markdown reports. A threshold pass is not an automatic convergence or posterior-adequacy claim.

diagnostics <- diagnose_binary_fit(binary_fit)
posterior <- summarise_binary_posterior(binary_fit)
predictive <- check_binary_posterior_predictive(binary_fit)

Hierarchical lognormal duration workflow

The duration workflow supports strictly positive, finite, uncensored durations with an explicit recorded unit. It provides deterministic simulation, preparation, inspectable priors, prior predictive checks, and restricted optional full-MCMC fitting through brms and rstan.

duration_simulation <- simulate_hierarchical_duration_data(seed = 2026)
duration_contract <- create_model_contract(
  family = "duration",
  outcome_col = "duration",
  participant_col = "participant_id",
  item_col = "item_id",
  trial_col = "trial_id",
  condition_col = "condition",
  outcome_unit = "milliseconds"
)
duration_prepared <- prepare_hierarchical_duration_data(
  duration_simulation$data,
  duration_contract,
  condition_levels = c("control", "treatment")
)
duration_specification <- specify_duration_model(
  duration_prepared,
  baseline = 500
)

Duration posterior validation

Approved lognormal duration fits support the same conservative diagnostic contract as binary fits, together with positive-scale posterior predictive checks, prior sensitivity, simulation-based recovery, and structured reports. Exponentiated population coefficients are conditional median ratios, not automatically causal effects.

duration_diagnostics <- diagnose_duration_fit(duration_fit)
duration_posterior <- summarise_duration_posterior(duration_fit)
duration_predictive <- check_duration_posterior_predictive(duration_fit)

Citation

Citation metadata are provided in both CITATION.cff and inst/CITATION. After installing the package, obtain the current R-formatted citation with:

citation("gp3bayes")

For exact reproducibility, cite the archived software version:

• Version 0.1.0 DOI: 10.5281/zenodo.21518699
• Concept DOI for all releases: 10.5281/zenodo.21518698

Release status

gp3bayes 0.1.0 is the first stable release.

The public API provides restricted Bernoulli-logit and lognormal-duration workflows, including optional full-MCMC fitting through brms and rstan.

Interpretation boundaries

Behavioural, gaze, pupil, and physiological measurements do not directly reveal emotion, stress, cognition, comprehension, personality, diagnosis, deception, intention, or other latent psychological states.

Associations must not be described as causal effects unless the study design and target estimand justify causal interpretation.

Licence

gp3bayes is released under the MIT License.