gp3bayes is an independent R package for transparent, contract-first
Bayesian workflows for repeated-measures and hierarchical behavioural
data.
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
brmsandrstanroute; - 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:
- hierarchical Bernoulli-logit models for binary trial-level outcomes;
- 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.
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
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
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
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
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.
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)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
)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 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
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.
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.
gp3bayes is released under the MIT License.