Package {gp3bayes}

Title:	Contract-First Bayesian Workflows for Hierarchical Behavioural Data
Version:	0.5.0
Description:	Provides transparent, contract-first infrastructure for Bayesian analysis of repeated-measures and hierarchical behavioural data. It supports approved Bernoulli-logit, positive lognormal duration, and governed Gaussian dynamic-pupillometry workflows with strict readiness auditing, deterministic simulation, explicit preparation and transformation replay, inspectable scale-aware priors, prior and posterior predictive checks, restricted optional fitting through 'brms' with either 'rstan' or 'cmdstanr', sampling and temporal diagnostics, explicit posterior estimands, sensitivity analysis, target-specific predictive validation, simulation-based calibration, and conservative reporting. Core contracts and validation remain backend-independent. Version 0.5 adds governed robust and distributional dynamic pupillometry, bounded ARMA residual structures, Gaussian-process trajectories, explicit measurement uncertainty and missing-data models, joint binocular analysis, predictive model comparison, functional posterior estimands, and experimental nonlinear response-shape models while preserving explicit scientific and computational governance boundaries.
License:	MIT + file LICENSE
URL:	https://stefanosbalaskas.github.io/gp3bayes/, https://github.com/stefanosbalaskas/gp3bayes
BugReports:	https://github.com/stefanosbalaskas/gp3bayes/issues
Encoding:	UTF-8
RoxygenNote:	8.0.0
Imports:	withr, stats
Suggests:	ggplot2, SBC, bayesplot, brms, cmdstanr, detectseparation, knitr, loo, posterior, priorsense, rmarkdown, rstan, testthat (≥ 3.0.0)
Config/testthat/edition:	3
VignetteBuilder:	knitr
Additional_repositories:	https://stan-dev.r-universe.dev, https://r-multiverse.r-universe.dev
NeedsCompilation:	no
Packaged:	2026-08-18 09:10:21 UTC; Stefanos-PC
Author:	Stefanos Balaskas [aut, cre, cph]
Maintainer:	Stefanos Balaskas <s.balaskas@ac.upatras.gr>
Repository:	CRAN
Date/Publication:	2026-08-23 10:40:44 UTC

gp3bayes: Contract-First Bayesian Workflows for Hierarchical Behavioural Data

Description

gp3bayes provides package-neutral infrastructure for transparent, contract-first Bayesian workflows for repeated-measures and hierarchical behavioural data. It implements approved Bernoulli-logit, positive lognormal duration, and governed Gaussian dynamic-pupillometry workflows with deterministic simulation, recorded preparation, scale-aware priors, restricted optional full-MCMC fitting, sampling and temporal diagnostics, posterior predictive checks, sensitivity analysis, target-specific validation, and conservative structured reporting. Fitting or passing a numerical threshold does not by itself establish convergence, posterior adequacy, causal identification, or validity.

Approved model families

The approved model-family scope is restricted to:

• hierarchical Bernoulli-logit models for binary trial-level outcomes;

• hierarchical lognormal models for strictly positive uncensored durations;

• governed Gaussian hierarchical dynamic pupil time-course models with scale-aware priors and declared temporal dependence.

Additional outcome families require separate methodological approval.

Backend policy

Core validation, contract, simulation, preparation, transformation, specification, and prior-predictive functionality remains usable without a Bayesian backend. Restricted full-MCMC fitting uses the brms interface. The original fit_binary_model(), fit_duration_model(), and fit_pupil_model() interfaces retain a fixed rstan route, while the backend-portable fit_binary_model_backend(), fit_duration_model_backend(), and fit_pupil_model_backend() interfaces support either rstan or cmdstanr. Model families, formulas, priors, and algorithms remain contract-restricted.

Interpretation boundaries

Behavioural 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 design and estimand justify that language.

Author(s)

Maintainer: Stefanos Balaskas s.balaskas@ac.upatras.gr (ORCID) [copyright holder]

Authors:

• Stefanos Balaskas s.balaskas@ac.upatras.gr (ORCID) [copyright holder]

See Also

Useful links:

• https://stefanosbalaskas.github.io/gp3bayes/

• https://github.com/stefanosbalaskas/gp3bayes

• Report bugs at https://github.com/stefanosbalaskas/gp3bayes/issues

Summarise an advanced pupil trajectory

Description

Summarise an advanced pupil trajectory

Usage

advanced_pupil_trajectory_table(prediction, probability = 0.95)

Arguments

Value

A data frame.

Analysis-Bundle Status Table

Description

Analysis-Bundle Status Table

Usage

analysis_bundle_table(x)

Arguments

Value

Component availability and captured errors.

Summarise Manifest Components

Description

Summarise Manifest Components

Usage

analysis_manifest_table(manifest)

Arguments

Value

A data frame of key provenance components.

Apply a Recorded Transformation Recipe

Description

Apply a Recorded Transformation Recipe

Usage

apply_transformation_recipe(
  new_data,
  recipe,
  input_scale = c("raw", "prepared"),
  require_outcome = FALSE,
  input_unit = NULL
)

Arguments

Value

A transformed data frame with a recipe attribute.

Convert a pupil contract to a transparent table

Description

Convert a pupil contract to a transparent table

Usage

## S3 method for class 'gp3bayes_pupil_contract'
as.data.frame(x, ...)

Arguments

Value

A data frame of contract fields.

Convert a pupil estimand to a data frame

Description

Convert a pupil estimand to a data frame

Usage

## S3 method for class 'gp3bayes_pupil_estimand'
as.data.frame(x, ...)

Arguments

Value

The estimand table.

Create a lightweight pupil prediction object from frozen draws

Description

Wraps already-computed posterior prediction draws for examples, reporting, and reproducible post-fit analysis without pretending that fitting occurred in the current session.

Usage

as_pupil_prediction_draws(
  draws,
  grid,
  unit,
  type = c("expected", "posterior_predictive", "linear"),
  max_cells = 5000000L
)

Arguments

Value

A gp3bayes_pupil_prediction.

Examples

grid <- expand.grid(
  .event_time = seq(0, 1, length.out = 5),
  .condition = factor(c("control", "treatment"))
)
draws <- matrix(rnorm(1000), nrow = 100, ncol = nrow(grid))
prediction <- as_pupil_prediction_draws(
  draws, grid, unit = "millimetres"
)

Assess Binary Prior Sensitivity

Description

Refits the approved binary model under prespecified tighter and wider prior scales and compares population-level posterior medians.

Usage

assess_binary_prior_sensitivity(
  fit,
  scale_multipliers = c(tighter = 0.5, wider = 2),
  chains = fit$sampling$chains,
  iter = fit$sampling$iter,
  warmup = fit$sampling$warmup,
  cores = fit$sampling$cores,
  seed = fit$sampling$seed + 1000L,
  adapt_delta = fit$sampling$adapt_delta,
  max_treedepth = fit$sampling$max_treedepth,
  refresh = 0L,
  maximum_standardized_shift = 0.25,
  review_standardized_shift = 0.5,
  retain_fits = FALSE
)

Arguments

Details

This function is computationally expensive. Sensitivity status describes stability under the declared scale changes only; it does not prove prior robustness under all defensible priors.

Value

A gp3bayes_binary_prior_sensitivity object.

Assess Duration Prior Sensitivity

Description

Refits the approved duration model under prespecified tighter and wider prior scales and compares population-level and residual posterior medians.

Usage

assess_duration_prior_sensitivity(
  fit,
  scale_multipliers = c(tighter = 0.5, wider = 2),
  chains = fit$sampling$chains,
  iter = fit$sampling$iter,
  warmup = fit$sampling$warmup,
  cores = fit$sampling$cores,
  seed = fit$sampling$seed + 2000L,
  adapt_delta = fit$sampling$adapt_delta,
  max_treedepth = fit$sampling$max_treedepth,
  refresh = 0L,
  maximum_standardized_shift = 0.25,
  review_standardized_shift = 0.5,
  retain_fits = FALSE
)

Arguments

Value

A gp3bayes_duration_prior_sensitivity.

Assess Power-Scaled Prior and Likelihood Sensitivity

Description

Delegates to priorsense while retaining a conservative review status. Low local sensitivity does not prove that prior choices are irrelevant or that a model is robust.

Usage

assess_powerscaled_sensitivity(
  fit,
  variable = NULL,
  prior_selection = NULL,
  likelihood_selection = NULL
)

Arguments

Value

A gp3bayes_powerscale_sensitivity.

Audit empirical support for an advanced pupil model specification

Description

This audit is deliberately heuristic. It identifies weakly supported design configurations before sampling but does not certify model identifiability or posterior adequacy.

Usage

audit_advanced_pupil_identifiability(specification)

Arguments

Value

A gp3bayes_pupil_identifiability_audit object.

Audit Posterior Parity Across rstan and cmdstanr

Description

Compares posterior summaries from two independently sampled fits. Mean differences are evaluated relative to the combined Monte Carlo standard error rather than requiring identical draws. Standard-deviation differences are reported separately. A parity pass is a computational consistency check, not evidence that either model is statistically or substantively adequate.

Usage

audit_backend_parity(
  rstan_fit,
  cmdstanr_fit,
  variables = NULL,
  mcse_multiplier = 3,
  absolute_tolerance = 0,
  relative_sd_tolerance = 0.1
)

Arguments

Value

A gp3bayes_backend_parity_audit.

Examples

rstan_summary <- data.frame(
  variable = c("b_Intercept", "b_conditiontreatment"),
  mean = c(-0.6, 0.4), sd = c(0.20, 0.15),
  mcse_mean = c(0.01, 0.01)
)
cmdstanr_summary <- data.frame(
  variable = c("b_Intercept", "b_conditiontreatment"),
  mean = c(-0.59, 0.41), sd = c(0.21, 0.15),
  mcse_mean = c(0.01, 0.01)
)
audit_backend_parity(rstan_summary, cmdstanr_summary)

Audit binocular pupil availability and agreement descriptively

Description

Audit binocular pupil availability and agreement descriptively

Usage

audit_binocular_pupil_readiness(prepared)

Arguments

Value

A gp3bayes_binocular_pupil_audit object.

Audit Overall Design Support

Description

Combines missingness, fixed-effects design, random-effects support, standard readiness, and optional binary separation screening into one pre-fit audit.

Usage

audit_design_support(
  x,
  contract = NULL,
  separation = FALSE,
  strict_readiness = TRUE
)

Arguments

Value

A gp3bayes_design_support_audit.

Audit Duration Range and Censoring Boundaries

Description

Checks an explicitly declared plausible measurement range and an explicitly supplied censoring indicator. Candidate censoring-like column names are only reported when no indicator is supplied; they are not interpreted silently.

Usage

audit_duration_boundaries(
  data,
  contract,
  allowed_range = NULL,
  censor_col = NULL,
  detect_candidate_columns = TRUE
)

Arguments

Value

A gp3bayes_duration_boundary_audit object.

Audit Duration-Unit Invariance

Description

Checks the unit-free median and predictive-quantile ratios and the expected scaling of absolute predictive quantities after a known unit conversion.

Usage

audit_duration_unit_invariance(
  reference,
  converted,
  multiplier,
  tolerance = 0.02
)

Arguments

Value

A gp3bayes_duration_unit_invariance_audit.

Audit Estimand Invariance Against a Declared Tolerance

Description

Audit Estimand Invariance Against a Declared Tolerance

Usage

audit_estimand_invariance(
  reference,
  alternative,
  quantity = reference$primary_quantity,
  tolerance
)

Arguments

Value

A gp3bayes_estimand_invariance_audit.

Audit the Fixed-Effects Design Matrix

Description

Checks rank, singular values, condition number, invariant columns and extreme leverage before fitting Stan. The audit never rewrites a formula or drops a predictor automatically.

Usage

audit_fixed_effect_design(
  x,
  contract = NULL,
  condition_number_review = 30,
  condition_number_fail = 100,
  leverage_multiplier = 3
)

Arguments

Value

A gp3bayes_fixed_effect_design_audit.

Audit Missingness Structure Before Model Fitting

Description

Summarises missing values in declared analysis columns and, where possible, by participant, item, and condition. This is a reporting audit; no rows are dropped or imputed.

Usage

audit_missingness_structure(
  x,
  contract = NULL,
  review_fraction = 0.05,
  fail_fraction = 0.2
)

Arguments

Value

A gp3bayes_missingness_audit.

Examples

data <- data.frame(
  participant_id = rep(c("p1", "p2"), each = 4),
  trial_id = rep(1:4, 2),
  condition = rep(c("control", "treatment"), 4),
  selected = c(0, 1, NA, 1, 1, 0, 1, 0)
)
contract <- create_model_contract(
  "binary", "selected", "participant_id",
  trial_col = "trial_id", condition_col = "condition"
)
audit_missingness_structure(data, contract)

Audit Data Readiness for an Approved Model Contract

Description

Audits whether a data frame satisfies the observable data requirements of an existing model contract created by create_model_contract(). The audit is backend-independent and does not construct a formula, define executable priors, fit a model, or establish model adequacy.

Usage

audit_model_readiness(data, contract)

Arguments

Details

A readiness audit evaluates observable data properties only. Passing the audit does not establish convergence, model adequacy, predictive validity, causal identification, or substantive validity.

Failures block progression to a later model-building gate. Warnings identify weak or unusual structures that require review but do not automatically block progression.

Binary outcomes must be logical or numeric values encoded exclusively as zero and one, with both classes observed. Duration outcomes must be numeric, finite, strictly positive, uncensored, and variable.

Value

An object of class gp3bayes_readiness_audit. The object records:

• whether the data are ready to proceed to a later model-building gate;

• pass, warning, and failure counts;

• one structured row per readiness check;

• declared and observed column summaries; and

• the audited model contract.

The input data are not retained in the returned object.

Interpretation boundaries

Readiness checks cannot determine whether a model is scientifically justified. Behavioural measurements must not be interpreted as direct measures of latent psychological or protected attributes.

Examples

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

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

audit_model_readiness(binary_data, binary_contract)

Run a Strict Model-Readiness Audit

Description

Extends audit_model_readiness() with explicit overall condition balance, binary within-group outcome variation, identifier-like predictor review, fixed-effects rank, duration extremes and boundaries, and optional binary separation screening.

Usage

audit_model_readiness_strict(
  data,
  contract,
  condition_warning_fraction = 0.1,
  condition_failure_fraction = 0.02,
  identifier_unique_fraction = 0.9,
  duration_allowed_range = NULL,
  censor_col = NULL,
  run_separation = TRUE
)

Arguments

Value

A gp3bayes_strict_readiness_audit object.

Audit Prediction Support

Description

Compares requested prediction rows with the observed model-building support. It reports extrapolation and novel levels but never removes prediction rows.

Usage

audit_prediction_support(fit, newdata)

Arguments

Value

A gp3bayes_prediction_support object.

Audit computational complexity before fitting an advanced pupil model

Description

Audit computational complexity before fitting an advanced pupil model

Usage

audit_pupil_computational_budget(x)

Arguments

Value

A gp3bayes_pupil_complexity_audit object.

Audit pupil measurement and confound context

Description

Summarises declared blink/interpolation, baseline, PFE/gaze, luminance, contrast, and sampling context without correcting or excluding observations.

Usage

audit_pupil_measurement_context(x)

Arguments

Value

A gp3bayes_pupil_measurement_audit.

Examples

# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.

Audit a declared measurement model against data

Description

Audit a declared measurement model against data

Usage

audit_pupil_measurement_model(specification)

Arguments

Value

A gp3bayes_pupil_measurement_audit_05 object.

Audit missingness in an advanced pupil specification

Description

Audit missingness in an advanced pupil specification

Usage

audit_pupil_missingness(specification)

Arguments

Value

A gp3bayes_pupil_missingness_audit object.

Audit posterior predictive calibration on explicit evaluation data

Description

Audit posterior predictive calibration on explicit evaluation data

Usage

audit_pupil_predictive_calibration(
  fit,
  newdata,
  ndraws = 500L,
  probability = 0.9,
  population_only = FALSE,
  allow_new_levels = FALSE
)

Arguments

Value

A predictive-score object with evaluation metadata.

Audit pupil-timecourse readiness

Description

Produces observable evidence about hierarchy, sampling, missingness, baseline support, measurement flags, gaze/PFE context, luminance, and preprocessing provenance. Review signals are not exclusion decisions.

Usage

audit_pupil_readiness(x, contract = NULL)

Arguments

Value

A gp3bayes_pupil_readiness object with summary and stratified tables.

Examples

# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.

Audit empirical temporal dependence before model fitting

Description

Computes descriptive within-series autocorrelation and spacing diagnostics. The audit is diagnostic only and does not select an ARMA order.

Usage

audit_pupil_temporal_dependence(x, max_lag = 10L)

Arguments

Value

A gp3bayes_pupil_temporal_dependence_audit object.

Audit Random-Effects Support

Description

Audits participant repetition, item crossing, and within-participant condition support for a requested random slope.

Usage

audit_random_effects_support(
  x,
  contract = NULL,
  minimum_repeated_rows = 2L,
  minimum_group_levels = 2L,
  minimum_condition_cell_rows = 2L
)

Arguments

Value

A gp3bayes_random_effects_support_audit.

Report Bayesian Backend Capabilities

Description

Provides a stable 0.2.0-facing capability table for the two approved Stan backends. It augments the existing package capability report with package versions, CmdStan installation information, and explicit readiness fields. No model is compiled or fitted.

Usage

backend_capabilities()

Value

A gp3bayes_backend_capabilities_v2 data frame.

Examples

backend_capabilities()

Backend-Environment Table

Description

Backend-Environment Table

Usage

backend_environment_table(x)

Arguments

Value

Backend environment checks.

Backend-Parity Table

Description

Backend-Parity Table

Usage

backend_parity_table(x)

Arguments

Value

The parameter-level backend-parity table.

Report Optional Bayesian Backend Capabilities

Description

Audits package availability and, where possible, runtime usability for the optional Bayesian extensions.

Usage

bayesian_backend_capabilities()

Value

A gp3bayes_backend_capabilities data frame.

Binary Calibration Error

Description

Binary Calibration Error

Usage

binary_calibration_error(x, observed = NULL, bins = 10L)

Arguments

Value

A one-row table with expected and maximum absolute calibration error.

Examples

binary_calibration_error(c(0.1, 0.8, 0.7, 0.2), c(0, 1, 1, 0), bins = 2)

Binary Calibration Table

Description

Binary Calibration Table

Usage

binary_calibration_table(x, bins = 10L, probs = c(0.025, 0.5, 0.975))

Arguments

Value

A data frame comparing observed event rates with posterior mean event probabilities by bin.

Binary Calibration Uncertainty

Description

Equal-width bins are defined from posterior-mean predicted probabilities.

Usage

binary_calibration_uncertainty(
  fit,
  newdata = NULL,
  bins = 10L,
  include_group_effects = FALSE,
  ndraws = 1000L,
  probs = c(0.025, 0.5, 0.975)
)

Arguments

Value

A gp3bayes_binary_calibration_uncertainty.

Binary Calibration-Uncertainty Table

Description

Binary Calibration-Uncertainty Table

Usage

binary_calibration_uncertainty_table(x)

Arguments

Value

Bin-level summaries.

Binary Confusion Table

Description

Binary Confusion Table

Usage

binary_confusion_table(x, observed = NULL, threshold = 0.5)

Arguments

Value

A four-row confusion table plus rates as attributes.

Examples

binary_confusion_table(c(0.1, 0.8, 0.7, 0.2), c(0, 1, 1, 0))

Grouped Binary Calibration

Description

Grouped Binary Calibration

Usage

binary_group_calibration(x, group)

Arguments

Value

A group-level calibration summary.

Binary Precision-Recall Curve

Description

Binary Precision-Recall Curve

Usage

binary_precision_recall_curve(x, observed = NULL, thresholds = NULL)

Arguments

Value

A data frame containing recall and precision.

Examples

binary_precision_recall_curve(
  c(0.1, 0.8, 0.7, 0.2),
  c(0, 1, 1, 0)
)

Binary Prediction Scores

Description

Binary Prediction Scores

Usage

binary_prediction_scores(x, observed = NULL, threshold = 0.5, epsilon = 1e-12)

Arguments

Value

A one-row data frame of descriptive predictive scores.

Examples

binary_prediction_scores(c(0.1, 0.8, 0.7, 0.2), c(0, 1, 1, 0))

Binary ROC Curve

Description

Binary ROC Curve

Usage

binary_roc_curve(x, observed = NULL, thresholds = NULL)

Arguments

Value

A data frame containing false-positive and true-positive rates.

Examples

binary_roc_curve(c(0.1, 0.8, 0.7, 0.2), c(0, 1, 1, 0))

Binary Threshold-Metric Curve

Description

Binary Threshold-Metric Curve

Usage

binary_threshold_metrics(
  x,
  observed = NULL,
  thresholds = seq(0.1, 0.9, by = 0.05)
)

Arguments

Value

A data frame with accuracy, sensitivity, specificity, and balanced accuracy over the supplied thresholds.

Examples

binary_threshold_metrics(
  c(0.1, 0.8, 0.7, 0.2),
  c(0, 1, 1, 0),
  thresholds = c(0.3, 0.5, 0.7)
)

Build an Approved Model Formula

Description

Constructs a backend-independent R formula from a create_model_contract() result. The formula records the approved fixed effects, one optional interaction, the participant grouping structure, an optional participant-level random slope, and an optional crossed item intercept.

Usage

build_model_formula(contract)

Arguments

Details

The participant random intercept is always included. When contract$random_slope is TRUE, it is replaced by a correlated participant intercept-and-condition-slope term. A declared item identifier adds a crossed item random intercept.

The trial identifier is treated as a row key and is not added as a predictor or grouping factor. A declared time column is included as a linear population-level term only.

Value

An R formula. The formula is a specification only and has not been translated to, validated by, or fitted with a Bayesian backend.

Examples

contract <- create_model_contract(
  family = "binary",
  outcome_col = "selected",
  participant_col = "participant_id",
  item_col = "stimulus_id",
  condition_col = "condition",
  predictors = "age_z"
)

build_model_formula(contract)

Capture the Structural Schema of a gp3bayes Object

Description

Captures classes, types, lengths, and field names without storing the object's values. The result is intended for release compatibility auditing, not for validating numerical or statistical equivalence.

Usage

capture_gp3bayes_schema(x, max_depth = 3L)

Arguments

Value

A gp3bayes_object_schema.

Examples

contract <- create_model_contract(
  family = "binary",
  outcome_col = "selected",
  participant_col = "participant_id",
  condition_col = "condition"
)
capture_gp3bayes_schema(contract)

Check advanced pupil priors through prior-only simulation

Description

This optional backend gate samples only from priors using brms. It does not establish model adequacy.

Usage

check_advanced_pupil_prior_predictive(
  specification,
  backend = c("rstan", "cmdstanr"),
  chains = 2L,
  iter = 800L,
  warmup = 400L,
  cores = min(2L, chains),
  seed = 2026
)

Arguments

Value

A gp3bayes_pupil_advanced_prior_predictive object.

Check Binary Posterior Predictive Behaviour

Description

Compares observed binary summaries with replicated outcomes from the fitted posterior predictive distribution.

Usage

check_binary_posterior_predictive(
  fit,
  draws = 500,
  seed = 1,
  pass_probability = 0.8,
  review_probability = 0.95
)

Arguments

Details

The check evaluates prespecified descriptive summaries. It does not prove that the likelihood, link, random-effects structure, or substantive model is adequate.

Value

A gp3bayes_binary_posterior_predictive_check.

Run Detailed Binary Posterior Predictive Checks

Description

Adds calibration bins, participant/item rate checks, focal-condition rates, sparse participant-condition cells, and all-zero/all-one participant patterns to the existing binary PPC workflow.

Usage

check_binary_ppc_details(
  fit,
  draws = 300L,
  seed = 1L,
  calibration_bins = 10L,
  sparse_cell_min = 3L
)

Arguments

Value

A gp3bayes_binary_ppc_detail.

Check Binary Prior Predictive Behaviour

Description

Simulates replicated binary outcomes from the declared prior specification and prepared design without calling a Bayesian fitting backend.

Usage

check_binary_prior_predictive(
  specification,
  draws = 500,
  seed = 1,
  plausible_rate = c(0.01, 0.99),
  boundary_probability = c(0.01, 0.99),
  extreme_contrast = 0.8,
  maximum_degenerate_participant_fraction = 0.5,
  maximum_boundary_mass = 0.5,
  maximum_extreme_probability = 0.25
)

Arguments

Details

Failure does not select or alter priors automatically. It indicates that the declared priors and design generate outcomes that require substantive review. This check assesses prior implications, not posterior adequacy or model fit.

Value

A gp3bayes_binary_prior_predictive_check containing replicated summaries, structured checks, thresholds, and the seed.

Examples

simulation <- simulate_hierarchical_binary_data(
  n_participants = 12,
  trials_per_participant = 8,
  seed = 2026
)

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

prepared <- prepare_hierarchical_binary_data(
  simulation$data,
  contract,
  condition_levels = c("control", "treatment")
)

specification <- specify_binary_model(
  prepared,
  baseline = 0.35
)

check_binary_prior_predictive(
  specification,
  draws = 100,
  seed = 2027
)

Check the CmdStanR Backend

Description

Checks package availability, the C++ toolchain, and a configured CmdStan installation. No installation or repair is performed automatically.

Usage

check_cmdstan_backend(strict = FALSE)

Arguments

Value

A list with status, version, path, and diagnostic detail.

Check Duration Posterior Predictive Behaviour

Description

Compares observed positive-duration summaries with replicated outcomes from the fitted posterior predictive distribution.

Usage

check_duration_posterior_predictive(
  fit,
  draws = 500L,
  seed = 1L,
  pass_probability = 0.8,
  review_probability = 0.95
)

Arguments

Details

The check covers median, mean, upper-tail, dispersion, condition-ratio, and grouping summaries. It does not prove global model adequacy.

Value

A gp3bayes_duration_posterior_predictive_check.

Run Detailed Duration Posterior Predictive Checks

Description

Adds raw/log-scale distributions, median and upper-quantile summaries, tail exceedance, group medians, and within-participant focal-condition median ratios.

Usage

check_duration_ppc_details(
  fit,
  draws = 300L,
  seed = 1L,
  quantiles = c(0.5, 0.9, 0.95),
  tail_threshold = NULL
)

Arguments

Value

A gp3bayes_duration_ppc_detail.

Check Duration Prior Predictive Behaviour

Description

Simulates positive-duration data from the declared prior specification and prepared design without fitting a model.

Usage

check_duration_prior_predictive(
  specification,
  draws = 500L,
  seed = 1L,
  plausible_median = NULL,
  maximum_q99 = NULL,
  maximum_cv = 5,
  maximum_condition_ratio = 10,
  maximum_extreme_probability = 0.25
)

Arguments

Details

Failure requests substantive prior review; it does not select or alter priors automatically.

Value

A gp3bayes_duration_prior_predictive_check.

Check Posterior Predictive Behaviour

Description

Family-neutral wrapper around the approved family-specific posterior predictive checks. Passing this check is not a global adequacy claim.

Usage

check_model_ppc(fit, ...)

Arguments

Value

A family-specific gp3bayes_posterior_predictive_check.

Run pupil-specific posterior predictive checks

Description

Compares observed and replicated trajectories, distributional features, whole-support peak/latency and AUC, optional declared-window response, lag-one serial structure, participant/trial heterogeneity, residual trajectories, and blink/interpolation context. The object reports evidence and never declares a model adequate.

Usage

check_pupil_posterior_predictive(
  fit,
  ndraws = 200L,
  probability = 0.9,
  window = NULL,
  max_cells = 3000000L
)

Arguments

Value

A gp3bayes_pupil_ppc.

Examples

# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.

Check the approved pupil priors predictively

Description

Creates a governed prior-predictive plan by default. With execute = TRUE, draws from the prior-only approved Gaussian brms model and compares replicated pupil values with the observed model-scale range. The check reports evidence only and never changes priors automatically.

Usage

check_pupil_prior_predictive(
  specification,
  execute = FALSE,
  backend = c("rstan", "cmdstanr"),
  draws = 200L,
  chains = 2L,
  iter = 1000L,
  warmup = 500L,
  cores = min(2L, chains),
  seed = 2026,
  probability = 0.95,
  max_cells = 3000000L
)

Arguments

Value

A gp3bayes_pupil_prior_predictive evidence object.

Governance boundary

This operation does not tune priors, select a favourable prior scale, or certify a model as scientifically adequate. execute = FALSE performs no compilation or fitting.

Examples

# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.

Collect Model Evidence Without Declaring Model Adequacy

Description

Collects already-computed design, diagnostics, posterior summaries, posterior predictive checks, estimands, predictive validation, sensitivity, and reproducibility provenance into a single review object.

Usage

collect_model_evidence(
  fit = NULL,
  design = NULL,
  diagnostics = NULL,
  posterior = NULL,
  ppc = NULL,
  estimands = NULL,
  loo = NULL,
  kfold = NULL,
  sensitivity = NULL,
  manifest = NULL,
  compute = character()
)

Arguments

Value

A gp3bayes_model_evidence.

Compare Analysis Manifests

Description

Compares analysis-defining fields without interpreting any difference as automatically problematic.

Usage

compare_analysis_manifests(x, y)

Arguments

Value

A gp3bayes_manifest_comparison.

Compare Estimand Sensitivity Across Alternative Fits

Description

Compare Estimand Sensitivity Across Alternative Fits

Usage

compare_estimand_sensitivity(
  reference,
  alternatives,
  quantity = reference$primary_quantity
)

Arguments

Value

A gp3bayes_estimand_sensitivity.

Compare gp3bayes Object Schemas

Description

Compare gp3bayes Object Schemas

Usage

compare_gp3bayes_schemas(x, y, compare_lengths = FALSE)

Arguments

Value

A gp3bayes_schema_comparison.

Compare Models with PSIS-LOO

Description

Compare Models with PSIS-LOO

Usage

compare_psis_loo(models, moment_match = FALSE, reloo = FALSE, cores = 1L)

Arguments

Value

A gp3bayes_loo_comparison. The result never selects a model.

Compare residual autocorrelation across fitted advanced models

Description

This function does not choose a winner. It summarises lag-specific residual dependence after subtracting posterior expected means.

Usage

compare_pupil_autocorrelation(..., max_lag = 10L, ndraws = 300L)

Arguments

Value

A gp3bayes_pupil_autocorrelation_comparison object.

Compare executed leave-future-out validations

Description

Compare executed leave-future-out validations

Usage

compare_pupil_lfo(...)

Arguments

Value

A gp3bayes_pupil_lfo_comparison object.

Compare fitted pupil models predictively

Description

Compare fitted pupil models predictively

Usage

compare_pupil_models(
  model_set,
  criterion = c("loo", "kfold"),
  K = 10L,
  group = NULL,
  moment_match = FALSE,
  save_psis = TRUE
)

Arguments

Value

A gp3bayes_pupil_model_comparison object.

Compare declared pupil sensitivity estimands

Description

Combines already-computed pupil estimands by named scenario. No scenario is ranked or selected.

Usage

compare_pupil_sensitivity_estimands(results)

Arguments

Value

A gp3bayes_pupil_sensitivity_comparison.

Examples

# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.

Compute Governed Exact K-Fold Cross-Validation

Description

Uses brms::kfold() as an explicit fallback or complement to PSIS-LOO. Grouped folds may use only the declared participant or item grouping column. No model is selected automatically.

Usage

compute_kfold_cv(
  fit,
  K = 10L,
  folds = c("random", "stratified", "grouped"),
  group = NULL,
  joint = c("obs", "fold", "group"),
  save_fits = FALSE,
  seed = 1L
)

Arguments

Value

A gp3bayes_kfold_cv.

Compute LOO Model-Averaging Weights

Description

Compute LOO Model-Averaging Weights

Usage

compute_loo_model_weights(x, method = c("stacking", "pseudobma"), cores = 1L)

Arguments

Value

A gp3bayes_loo_weights object.

Compute PSIS-LOO for a gp3bayes Fit

Description

Compute PSIS-LOO for a gp3bayes Fit

Usage

compute_psis_loo(
  fit,
  moment_match = FALSE,
  reloo = FALSE,
  cores = 1L,
  save_psis = TRUE
)

Arguments

Value

A conservative gp3bayes_psis_loo result.

Compute PSIS-LOO from a Log-Likelihood Matrix

Description

This function supports deterministic tests and advanced workflows that already possess pointwise log-likelihood draws.

Usage

compute_psis_loo_from_log_lik(
  log_lik,
  chain_id = NULL,
  cores = 1L,
  save_psis = TRUE
)

Arguments

Value

A gp3bayes_psis_loo.

Create an advanced pupil prior specification

Description

Constructs the governed default prior specification used when translating an advanced pupil time-course model to brms. This function defines prior scales only; it does not compile or fit a model and does not establish model adequacy.

Usage

create_advanced_pupil_prior_specification(specification)

Arguments

Value

A gp3bayes_pupil_advanced_prior_specification object.

Create a Structured Post-Fit Analysis Bundle

Description

Collects reusable posterior, diagnostic, prediction, calibration, scoring, and optionally PSIS-LOO tables without making an automatic adequacy or model selection decision.

Usage

create_analysis_bundle(
  fit,
  newdata = NULL,
  ndraws = 1000L,
  include_group_effects = FALSE,
  include_loo = FALSE
)

Arguments

Value

A gp3bayes_analysis_bundle.

Create Publication Figures from an Analysis Bundle

Description

Produces only figures supported by available bundle components.

Usage

create_analysis_figure_set(x)

Arguments

Value

A gp3bayes_figure_set.

Create an Analysis Manifest

Description

Records the declared analysis contract, transformations, estimands, sensitivity plan, random seed, data fingerprint, package versions, and optional sampling specification in one backend-independent provenance object. The manifest stores a data fingerprint rather than a duplicate copy of the analysis data.

Usage

create_analysis_manifest(
  specification = NULL,
  fit = NULL,
  data = NULL,
  estimands = character(),
  sensitivity_plan = NULL,
  seed = NULL,
  label = NULL,
  notes = character()
)

Arguments

Value

A gp3bayes_analysis_manifest.

Examples

simulation <- simulate_hierarchical_binary_data(
  n_participants = 8,
  trials_per_participant = 6,
  n_items = 4,
  random_slope_sd = 0,
  seed = 2026
)
contract <- create_model_contract(
  family = "binary",
  outcome_col = "selected",
  participant_col = "participant_id",
  item_col = "item_id",
  trial_col = "trial_id",
  condition_col = "condition"
)
prepared <- prepare_hierarchical_binary_data(
  simulation$data,
  contract,
  condition_levels = c("control", "treatment")
)
specification <- specify_binary_model(prepared, baseline = 0.35)
manifest <- create_analysis_manifest(
  specification = specification,
  estimands = "standardized_probability_contrast",
  seed = 2026
)
manifest

Create a Structured Binary Model Report

Description

Writes a conservative Markdown report for an approved fitted binary model.

Usage

create_binary_model_report(
  fit,
  diagnostics = NULL,
  posterior_summary = NULL,
  posterior_predictive = NULL,
  prior_sensitivity = NULL,
  recovery = NULL,
  file,
  overwrite = FALSE
)

Arguments

Details

The report never converts diagnostic or predictive statuses into an automatic statement that the model converged or is substantively valid.

Value

A gp3bayes_binary_model_report containing the normalized path and section-status registry.

Create a brms-Based Simulation-Based Calibration Plan

Description

Constructs a complete SBC generator/backend pair using the restricted gp3bayes brms translation. Because the generator and backend share brms implementation code, this plan is mainly a computational-calibration check; custom independent generators remain preferable for detecting shared implementation errors.

Usage

create_brms_sbc_plan(
  specification,
  n_sims = 20L,
  backend = c("rstan", "cmdstanr"),
  chains = 2L,
  iter = 1000L,
  warmup = 500L,
  thin = 1L,
  seed = 1L,
  generator_iter = 3000L,
  generator_warmup = 2000L
)

Arguments

Value

A gp3bayes_sbc_plan.

Create a Complete Evidence Inventory

Description

Create a Complete Evidence Inventory

Usage

create_complete_evidence_inventory(..., label = NULL)

Arguments

Value

A gp3bayes_evidence_inventory.

Create a Contrast-Coding Sensitivity Specification

Description

Replays the prepared data back to the recorded raw scale, applies an alternative two-level condition coding, and rebuilds the approved specification. Because the intercept meaning changes with coding, an explicit new baseline is required.

Usage

create_contrast_coding_sensitivity_specification(
  specification,
  condition_coding,
  baseline
)

Arguments

Value

An approved alternative specification.

Create an Expert Custom SBC Plan

Description

Wraps an independently coded generator function and a user-supplied SBC backend. The generator must return variables and generated elements as required by SBC.

Usage

create_custom_sbc_plan(
  generator_function,
  backend,
  n_sims = 20L,
  generator_args = list(),
  seed = 1L
)

Arguments

Value

A gp3bayes_sbc_plan.

Create a Diagnostic Dashboard Object

Description

Expensive analyses are never launched implicitly. Supply already-computed evidence objects.

Usage

create_diagnostic_dashboard(
  fit = NULL,
  analysis_bundle = NULL,
  model_card = NULL,
  loo = NULL,
  prior_posterior = NULL,
  sensitivity = NULL,
  recovery = NULL,
  sbc = NULL,
  label = NULL
)

Arguments

Value

A gp3bayes_diagnostic_dashboard.

Create Diagnostic Dashboard Figures

Description

Create Diagnostic Dashboard Figures

Usage

create_diagnostic_dashboard_figures(x)

Arguments

Value

A gp3bayes_figure_set for supported evidence components.

Create a Structured Duration Model Report

Description

Writes a conservative Markdown report for an approved fitted lognormal duration model.

Usage

create_duration_model_report(
  fit,
  diagnostics = NULL,
  posterior_summary = NULL,
  posterior_predictive = NULL,
  prior_sensitivity = NULL,
  recovery = NULL,
  file,
  overwrite = FALSE
)

Arguments

Value

A gp3bayes_duration_model_report.

Create a Duration-Unit Sensitivity Specification

Description

Re-expresses an approved prepared duration outcome in a new unit by a positive multiplicative conversion, shifts the baseline median accordingly, and retains all dimensionless prior scales.

Usage

create_duration_unit_sensitivity_specification(
  specification,
  multiplier,
  new_unit
)

Arguments

Value

An approved duration sensitivity specification.

Create a Named Figure Set

Description

Create a Named Figure Set

Usage

create_figure_set(..., title = "gp3bayes figure set")

Arguments

Value

A gp3bayes_figure_set.

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  p <- ggplot2::ggplot(data.frame(x = 1:3, y = 1:3), ggplot2::aes(x, y)) +
    ggplot2::geom_point()
  create_figure_set(example = p)
}

Create a Group-Deletion Sensitivity Plan

Description

Create a Group-Deletion Sensitivity Plan

Usage

create_group_deletion_sensitivity_plan(
  specification,
  group = c("participant", "item"),
  units = NULL,
  max_units = 20L
)

Arguments

Value

A gp3bayes_group_deletion_sensitivity_plan.

Create a LOO Influence Atlas

Description

Create a LOO Influence Atlas

Usage

create_loo_influence_atlas(x, data = NULL, threshold = 0.7)

Arguments

Value

A gp3bayes_loo_influence_atlas.

Create a gp3bayes Model Card

Description

Creates a compact, structured record of model identity, computational diagnostics, prediction evidence, provenance, and interpretation boundaries. The card is documentation; it does not issue a model-adequacy certificate.

Usage

create_model_card(fit, analysis_bundle = NULL, manifest = NULL, label = NULL)

Arguments

Value

A gp3bayes_model_card.

Create an Approved Bayesian Model Contract

Description

Creates an inspectable model-contract object for one of the two model families approved for the initial gp3bayes development scope. The function records neutral data-column mappings while preserving the approved likelihood, link, estimands, assumptions, diagnostics, sensitivity requirements, and interpretation boundaries.

Usage

create_model_contract(
  family,
  outcome_col,
  participant_col,
  item_col = NULL,
  trial_col = NULL,
  condition_col = NULL,
  time_col = NULL,
  predictors = character(),
  interaction = NULL,
  random_slope = FALSE,
  outcome_unit = NULL,
  notes = character()
)

Arguments

Details

The returned object is a specification and audit record. It does not validate a data frame, construct a backend formula, fit a model, or imply that the proposed analysis is appropriate. Those gates are handled by separate workflows.

The binary contract uses a Bernoulli likelihood with a logit link. The duration contract uses a lognormal likelihood for strictly positive, finite, uncensored durations.

Value

An object of class gp3bayes_model_contract. It is a named list containing the approved methodological specification, neutral column mappings, requested model structure, assumptions, diagnostics, sensitivity requirements, limitations, and unsupported uses.

Interpretation boundaries

Contract creation does not establish causal identification, model adequacy, convergence, predictive validity, or substantive validity. Behavioural measurements must not be interpreted as direct measures of latent psychological or protected attributes.

Examples

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

duration_contract <- create_model_contract(
  family = "duration",
  outcome_col = "response_time",
  participant_col = "participant_id",
  trial_col = "trial_id",
  condition_col = "condition",
  outcome_unit = "milliseconds"
)

duration_contract

Create a Model Evidence Report

Description

Writes an explicit Markdown inventory of available evidence components.

Usage

create_model_evidence_report(evidence, file, overwrite = FALSE)

Arguments

Value

The normalized output path, invisibly.

Create a Complete Model Specification

Description

Combines a model contract, a successful readiness audit, an approved formula, and a validated prior specification into one backend-independent model specification.

Usage

create_model_specification(contract, audit, priors)

Arguments

Value

An object of class gp3bayes_model_specification.

Create a Prediction Contrast Profile

Description

Create a Prediction Contrast Profile

Usage

create_prediction_contrast_profile(
  fit,
  variable,
  contrast_variable,
  contrast_levels = NULL,
  values = NULL,
  n = 40L,
  at = list(),
  measure = c("difference", "ratio", "odds_ratio"),
  include_group_effects = FALSE,
  ndraws = NULL,
  probs = c(0.025, 0.5, 0.975)
)

Arguments

Value

A gp3bayes_prediction_contrast_profile.

Create a Governed Prediction Grid

Description

Creates a Cartesian prediction grid from declared model predictors. Numeric covariates are held at an observed typical value unless values are supplied explicitly through at.

Usage

create_prediction_grid(
  x,
  variables = NULL,
  at = list(),
  numeric_at = c("median", "mean"),
  max_rows = 5000L
)

Arguments

Value

A data frame suitable for predict_model().

Create a Numeric Prediction Profile

Description

Create a Numeric Prediction Profile

Usage

create_prediction_profile(
  fit,
  variable,
  values = NULL,
  n = 50L,
  at = list(),
  type = c("expected", "predictive", "linear", "median"),
  include_group_effects = FALSE,
  allow_new_levels = FALSE,
  ndraws = NULL,
  probs = c(0.025, 0.5, 0.975),
  seed = 1L
)

Arguments

Value

A gp3bayes_prediction_profile.

Create a Two-Dimensional Prediction Surface

Description

Create a Two-Dimensional Prediction Surface

Usage

create_prediction_surface(
  fit,
  x,
  y,
  x_values = NULL,
  y_values = NULL,
  n = 30L,
  at = list(),
  type = c("expected", "predictive", "linear", "median"),
  include_group_effects = FALSE,
  allow_new_levels = FALSE,
  ndraws = NULL,
  probs = c(0.025, 0.5, 0.975),
  seed = 1L,
  max_rows = 2500L
)

Arguments

Value

A gp3bayes_prediction_surface.

Create a Posterior-Predictive Distribution Atlas

Description

Create a Posterior-Predictive Distribution Atlas

Usage

create_predictive_distribution_atlas(
  fit,
  ndraws = 500L,
  include_group_effects = TRUE,
  seed = 1L
)

Arguments

Value

A gp3bayes_predictive_distribution_atlas.

Create a Predictor-Scaling Sensitivity Specification

Description

Changes one already-scaled predictor by a declared scale factor and requires an explicit coefficient-prior scale for the new parameterisation. This avoids pretending that a common coefficient prior is automatically invariant to predictor scaling.

Usage

create_predictor_scaling_sensitivity_specification(
  specification,
  predictor,
  scale_factor,
  coefficient_scale,
  interaction_scale = NULL
)

Arguments

Value

An approved alternative specification.

Create a Backend-Independent Prior Specification

Description

Creates an inspectable prior table for one approved model family. The returned object contains no backend-specific prior objects and performs no sampling.

Usage

create_prior_specification(
  contract,
  baseline = NULL,
  intercept_scale = NULL,
  coefficient_scale = NULL,
  group_sd_scale = 1,
  residual_scale = NULL,
  correlation_eta = 2,
  student_df = 3
)

Arguments

Details

Binary baseline probabilities are transformed with the logit function. Duration baseline medians are transformed with the natural logarithm.

Value

An object of class gp3bayes_prior_specification.

Examples

binary_contract <- create_model_contract(
  family = "binary",
  outcome_col = "selected",
  participant_col = "participant_id"
)

create_prior_specification(
  binary_contract,
  baseline = 0.35
)

Create a Publication Registry

Description

Create a Publication Registry

Usage

create_publication_registry(label = NULL)

Arguments

Value

A gp3bayes_publication_registry.

Extract Publication Tables from an Analysis Bundle

Description

Extract Publication Tables from an Analysis Bundle

Usage

create_publication_table_set(x)

Arguments

Value

A named list of data frames suitable for downstream formatting.

Create a pre-fit advanced pupillometry sensitivity suite

Description

The suite materializes scientifically interpretable alternative model specifications without fitting, ranking, or choosing among them.

Usage

create_pupil_advanced_sensitivity_suite(
  specification,
  include = c("likelihood", "residual_scale", "autocorrelation", "temporal", "gp_kernel")
)

Arguments

Value

A gp3bayes_pupil_advanced_sensitivity_suite object.

Create an explicit bounded ARMA configuration

Description

Create an explicit bounded ARMA configuration

Usage

create_pupil_arma_spec(p = 1L, q = 0L, covariance = FALSE)

Arguments

Value

A gp3bayes_pupil_arma_spec object.

Create a governed pupil-timecourse contract

Description

Records the measurement and analysis declarations required for the restricted Gaussian hierarchical pupil-timecourse family. Contract creation performs no preprocessing, exclusion, correction, model fitting, or psychological interpretation.

Usage

create_pupil_contract(
  outcome_col,
  participant_col,
  trial_col,
  time_col,
  pupil_unit,
  sampling_frequency,
  time_unit = c("seconds", "milliseconds"),
  item_col = NULL,
  condition_col = NULL,
  timestamp_col = NULL,
  eye = c("unknown", "left", "right", "combined"),
  left_pupil_col = NULL,
  right_pupil_col = NULL,
  channel_audit_unit = NULL,
  validity_col = NULL,
  interpolation_col = NULL,
  blink_col = NULL,
  gaze_x_col = NULL,
  gaze_y_col = NULL,
  luminance_col = NULL,
  contrast_col = NULL,
  screen_width = NA_real_,
  screen_height = NA_real_,
  baseline_window = NULL,
  baseline_method = c("unknown", "none", "subtract", "divide", "proportion_change",
    "percent_change"),
  baseline_applied = FALSE,
  pfe_corrected = FALSE,
  pfe_method = NULL,
  source_vendor = NA_character_,
  device_model = NA_character_,
  preprocessing_provenance = NA_character_,
  upstream_package = NA_character_,
  upstream_version = NA_character_,
  notes = character()
)

Arguments

Value

A gp3bayes_pupil_contract.

Governance boundary

The contract records decisions but does not detect blinks, interpolate, smooth, correct PFE, correct luminance, choose a baseline, or exclude data. gp3bayes does not automatically correct blink/data-loss, PFE, gaze-position, luminance, contrast, or baseline decisions recorded upstream. gp3bayes does not infer cognitive load, attention, arousal, stress, emotion, surprise, or effort from a pupil measurement or posterior pupil contrast. Interpretation remains the researcher's responsibility and must be justified by the study design, measurement context, and substantive scientific argument.

Examples

contract <- create_pupil_contract(
  outcome_col = "pupil_mm",
  participant_col = "participant_id",
  trial_col = "trial_id",
  time_col = "event_time",
  pupil_unit = "millimetres",
  sampling_frequency = 60,
  condition_col = "condition",
  eye = "combined"
)
contract

Create a Gaussian-process configuration for pupil trajectories

Description

Create a Gaussian-process configuration for pupil trajectories

Usage

create_pupil_gp_spec(
  kernel = c("matern32", "matern52", "exp_quad"),
  basis = c("approximate", "exact"),
  k = 30L,
  scale = TRUE
)

Arguments

Value

A gp3bayes_pupil_gp_spec object.

Create an explicit leave-future-out validation plan

Description

The plan defines sequential training cut-points within a single ordered series. Execution is deliberately separate because it requires refitting.

Usage

create_pupil_lfo_plan(
  fit,
  initial_fraction = 0.6,
  horizon = 5L,
  step = 5L,
  max_refits = 8L
)

Arguments

Value

A gp3bayes_pupil_lfo_plan object.

Create a governed measurement-uncertainty specification

Description

Declares known standard-error columns for pupil covariates and/or the pupil response. The object records uncertainty; it does not alter or impute data.

Usage

create_pupil_measurement_model(
  baseline_error = NULL,
  luminance_error = NULL,
  gaze_error = NULL,
  response_error = NULL,
  covariate_errors = NULL
)

Arguments

Value

A gp3bayes_pupil_measurement_model object.

Create a governed missingness specification

Description

Create a governed missingness specification

Usage

create_pupil_missingness_spec(
  response = c("exclude", "model"),
  predictors = character(),
  assumptions = "MAR",
  auxiliary_predictors = character()
)

Arguments

Value

A gp3bayes_pupil_missingness_spec object.

Create a named set of fitted pupil models

Description

Create a named set of fitted pupil models

Usage

create_pupil_model_set(
  ...,
  predictive_target = c("new_trial_known_participant", "new_participant",
    "future_segment", "new_sample_known_trial")
)

Arguments

Value

A gp3bayes_pupil_model_set object.

Create a governed pupil sensitivity suite

Description

Declares scientifically consequential alternatives without choosing the alternative that produces the largest effect. The suite is inert until a scenario is explicitly materialized or results are supplied for comparison.

Usage

create_pupil_sensitivity_suite(
  specification,
  baseline_windows = list(),
  baseline_window_operation = NULL,
  baseline_operations = character(),
  interpolation_policy = character(),
  blink_adjacent_margins = numeric(),
  gaze_adjustment = character(),
  luminance_adjustment = character(),
  pfe_prepared = list(),
  smooth_basis_dimensions = integer(),
  autocorrelation = character(),
  analysis_windows = list()
)

Arguments

Value

A gp3bayes_pupil_sensitivity plan.

Examples

# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.

Create an explicit pupil predictive-validation plan

Description

Defines the prediction target before choosing a partition. The plan distinguishes observation-level known-trial prediction, new trials for known participants, new participants, and finite future time segments. Only non-missing model-outcome rows enter validation partitions.

Usage

create_pupil_validation_plan(
  x,
  target = c("new_trial_known_participant", "new_participant", "future_segment",
    "new_sample_known_trial"),
  K = 5L,
  future_fraction = 0.2,
  seed = 2026
)

Arguments

Value

A gp3bayes_pupil_validation_plan with explicit fold/split membership and leakage checks.

Interpretation

Observation-wise validation is not presented as a universal default for temporally dependent pupil samples. The declared prediction target determines the partition.

Examples

# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.

Create a Random-Slope Sensitivity Plan

Description

Constructs approved random-intercept and random-slope specifications from a common prepared design. No model is fitted and neither structure is selected.

Usage

create_random_slope_sensitivity_plan(specification)

Arguments

Value

A gp3bayes_random_slope_sensitivity_plan.

Create a Reporting Checklist

Description

Create a Reporting Checklist

Usage

create_reporting_checklist(x)

Arguments

Value

A data frame describing evidence that is available for reporting.

Create a Sensitivity Suite Plan

Description

Creates a declarative plan for sensitivity analyses already supported by gp3bayes. Expensive refits are opt-in and are never started merely by creating a plan.

Usage

create_sensitivity_suite_plan(
  prior_scale = FALSE,
  powerscale = FALSE,
  psis_loo = FALSE,
  random_slope_plan = NULL,
  group_deletion_plan = NULL,
  alternative_estimands = list(),
  duration_unit = NULL,
  prior_scale_args = list(),
  powerscale_args = list(),
  psis_args = list(),
  random_slope_args = list(),
  group_deletion_args = list()
)

Arguments

Value

A gp3bayes_sensitivity_plan.

Create a Reusable Transformation Recipe

Description

Extracts the recorded condition coding, outcome mapping or unit conversion, numeric scaling registry, fixed-effects formula, and model-matrix columns from a prepared gp3bayes object.

Usage

create_transformation_recipe(prepared)

Arguments

Value

A gp3bayes_transformation_recipe.

Design-Support Table

Description

Design-Support Table

Usage

design_support_table(x)

Arguments

Value

The design-support component table.

Detect Separation in the Binary Fixed-Effects Screen

Description

Runs detectseparation::detect_separation() as a pre-fit fixed-effects screen. This screen does not replace the hierarchical model or prove that the Bayesian posterior is adequate.

Usage

detect_binary_separation(x, formula = NULL, data = NULL)

Arguments

Value

A gp3bayes_separation_screen.

Diagnose an advanced pupil fit

Description

Diagnose an advanced pupil fit

Usage

diagnose_advanced_pupil_fit(fit, rhat_threshold = 1.01, ess_threshold = 400)

Arguments

Value

A gp3bayes_pupil_advanced_diagnostics object.

Diagnose a Fitted Binary Model

Description

Computes rank-normalized R-hat, bulk and tail effective sample sizes, divergent-transition counts, maximum-treedepth saturation, and chain-level energy diagnostics for an approved binary fit.

Usage

diagnose_binary_fit(
  fit,
  rhat_pass = 1.01,
  rhat_fail = 1.05,
  ess_per_chain_pass = 100,
  ess_per_chain_fail = 50,
  maximum_treedepth_fraction = 0.01,
  ebfmi_pass = 0.3,
  ebfmi_fail = 0.2
)

Arguments

Details

The overall status is "fail" when any component fails, "review" when any component requires review or cannot be assessed, and "pass" only when every component passes. A pass does not automatically establish convergence or posterior adequacy.

Value

A gp3bayes_binary_diagnostics object containing parameter, component, and chain-level diagnostic tables.

Diagnose a Fitted Duration Model

Description

Applies the package sampling-diagnostic contract to an approved hierarchical lognormal duration fit.

Usage

diagnose_duration_fit(
  fit,
  rhat_pass = 1.01,
  rhat_fail = 1.05,
  ess_per_chain_pass = 100,
  ess_per_chain_fail = 50,
  maximum_treedepth_fraction = 0.01,
  ebfmi_pass = 0.3,
  ebfmi_fail = 0.2
)

Arguments

Details

The returned status reports prespecified numerical sampling thresholds. It does not automatically establish convergence or posterior adequacy.

Value

A gp3bayes_duration_diagnostics object.

Diagnose an Approved gp3bayes Fit

Description

Family-neutral wrapper around diagnose_binary_fit() and diagnose_duration_fit().

Usage

diagnose_model_fit(fit, ...)

Arguments

Value

A family-specific gp3bayes_sampling_diagnostics object.

Diagnose temporal and sampling behaviour of a pupil fit

Description

Reports posterior R-hat/ESS summaries, NUTS sampler evidence when available, residual temporal drift, and residual autocorrelation. Thresholds are numerical review gates, not adequacy certification.

Usage

diagnose_pupil_fit(fit, ndraws = 200L, max_lag = 10L, max_cells = 3000000L)

Arguments

Value

A gp3bayes_pupil_diagnostics.

Examples

# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.

Diagnostic Dashboard Table

Description

Diagnostic Dashboard Table

Usage

diagnostic_dashboard_table(x)

Arguments

Value

Component availability and status.

Duration Probability-Integral-Transform Table

Description

Duration Probability-Integral-Transform Table

Usage

duration_pit_table(x)

Arguments

Value

Observation-level empirical posterior predictive PIT values.

Duration Prediction Scores

Description

Duration Prediction Scores

Usage

duration_prediction_scores(x, observed = NULL)

Arguments

Value

A one-row table of absolute and squared prediction errors on the response and log scales.

Examples

duration_prediction_scores(c(100, 120, 90), c(110, 115, 100))

Duration Predictive Q-Q Table

Description

Duration Predictive Q-Q Table

Usage

duration_qq_table(x, probs = seq(0.05, 0.95, by = 0.05))

Arguments

Value

A quantile-comparison table.

Duration Quantile Calibration

Description

Duration Quantile Calibration

Usage

duration_quantile_calibration(x, quantiles = c(0.1, 0.25, 0.5, 0.75, 0.9))

Arguments

Value

A table comparing nominal predictive quantiles with empirical coverage below those quantiles.

Duration Tail Check

Description

Duration Tail Check

Usage

duration_tail_check(x, threshold)

Arguments

Value

A one-row table comparing observed and posterior predictive tail rates.

Estimand Sensitivity Table

Description

Estimand Sensitivity Table

Usage

estimand_sensitivity_table(x)

Arguments

Value

Alternative-versus-reference estimand summaries.

Estimate joint binocular posterior trajectories

Description

Estimate joint binocular posterior trajectories

Usage

estimate_binocular_pupil_trajectory(
  fit,
  newdata = NULL,
  ndraws = 500L,
  probability = 0.95
)

Arguments

Value

A gp3bayes_binocular_pupil_trajectory object.

Estimate the Approved Primary Estimands

Description

Dispatches to design-standardised probability contrasts for binary fits and duration estimands for positive lognormal fits.

Usage

estimate_model_estimands(fit, ...)

Arguments

Value

A gp3bayes_estimand.

Estimate area under a declared pupil-response window

Description

Estimate area under a declared pupil-response window

Usage

estimate_pupil_auc(prediction, window, probability = 0.95)

Arguments

Value

A pupil estimand. AUC units are pupil-unit times time-unit.

Examples

grid <- data.frame(.event_time = seq(0, 1, length.out = 5))
draws <- matrix(rnorm(500), nrow = 100)
prediction <- as_pupil_prediction_draws(draws, grid, "millimetres")
estimate_pupil_auc(prediction, c(0.2, 0.8))

Estimate a dynamic posterior contrast between two pupil conditions

Description

The contrast is evaluated pointwise on an explicitly supplied posterior trajectory (or its derivative). No favorable time window is selected.

Usage

estimate_pupil_dynamic_contrast(
  prediction,
  contrast,
  threshold = 0,
  probability = 0.95
)

Arguments

Value

A gp3bayes_pupil_dynamic_contrast object.

Estimate posterior peak pupil response inside a declared window

Description

Estimate posterior peak pupil response inside a declared window

Usage

estimate_pupil_peak(prediction, window, probability = 0.95)

Arguments

Value

A pupil estimand with posterior uncertainty in the peak.

Examples

grid <- data.frame(.event_time = seq(0, 1, length.out = 5))
draws <- matrix(rnorm(500), nrow = 100)
prediction <- as_pupil_prediction_draws(draws, grid, "millimetres")
estimate_pupil_peak(prediction, c(0.2, 0.8))

Estimate posterior peak latency inside a declared window

Description

Estimate posterior peak latency inside a declared window

Usage

estimate_pupil_peak_latency(prediction, window, probability = 0.95)

Arguments

Value

A pupil estimand with posterior uncertainty in peak latency.

Examples

grid <- data.frame(.event_time = seq(0, 1, length.out = 5))
draws <- matrix(rnorm(500), nrow = 100)
prediction <- as_pupil_prediction_draws(draws, grid, "millimetres")
estimate_pupil_peak_latency(prediction, c(0.2, 0.8))

Estimate the residual-scale trajectory from a distributional model

Description

Estimate the residual-scale trajectory from a distributional model

Usage

estimate_pupil_residual_scale(
  fit,
  newdata = NULL,
  ndraws = 500L,
  probability = 0.95
)

Arguments

Value

A gp3bayes_pupil_residual_scale object.

Estimate nonlinear response-shape parameters

Description

Estimate nonlinear response-shape parameters

Usage

estimate_pupil_response_parameters(fit, probability = 0.95)

Arguments

Value

A gp3bayes_pupil_response_parameters object.

Estimate posterior duration above a prespecified dynamic threshold

Description

Duration is computed draw-by-draw from the dynamic contrast on its existing time grid. The threshold and direction must be supplied before interpretation; the function performs no threshold or window optimization.

Usage

estimate_pupil_threshold_duration(
  contrast,
  direction = c("above", "below", "absolute"),
  threshold = contrast$threshold,
  probability = 0.95
)

Arguments

Value

A gp3bayes_pupil_threshold_duration object.

Estimate posterior pupil trajectories

Description

Summarises a finite, declared prediction grid with pointwise or grid-wise simultaneous posterior bands.

Usage

estimate_pupil_trajectory(
  prediction,
  probability = 0.95,
  interval = c("pointwise", "simultaneous")
)

Arguments

Value

A gp3bayes_pupil_trajectory.

Uncertainty

"simultaneous" constructs a grid-wise band from the empirical posterior maximum standardized deviation over the supplied finite grid. It is not a universal continuous-time confidence band.

Examples

grid <- data.frame(.event_time = seq(0, 1, length.out = 5))
draws <- matrix(rnorm(500), nrow = 100)
prediction <- as_pupil_prediction_draws(draws, grid, "millimetres")
estimate_pupil_trajectory(prediction)

Estimate posterior temporal derivatives of a pupil trajectory

Description

Computes finite-difference posterior derivatives on the prediction grid. This is a descriptive functional estimand: it does not automatically define physiological onset, changepoints, or cognitively meaningful phases.

Usage

estimate_pupil_trajectory_derivative(
  prediction,
  order = 1L,
  probability = 0.95
)

Arguments

Value

A gp3bayes_pupil_trajectory_derivative object.

Estimate a declared-window mean pupil response

Description

Estimate a declared-window mean pupil response

Usage

estimate_pupil_window(prediction, window, probability = 0.95)

Arguments

Value

A gp3bayes_pupil_estimand.

Examples

grid <- data.frame(.event_time = seq(0, 1, length.out = 5))
draws <- matrix(rnorm(500), nrow = 100)
prediction <- as_pupil_prediction_draws(draws, grid, "millimetres")
estimate_pupil_window(prediction, c(0.2, 0.8))

Estimate Design-Standardised Duration Estimands

Description

Produces posterior draws of average conditional medians, their difference and ratio, the average log-duration contrast, and a posterior predictive upper quantile under each focal-condition level.

Usage

estimate_standardized_duration_estimands(
  fit,
  target_data = NULL,
  target_scale = c("prepared", "raw"),
  predictive_quantile = 0.9,
  ndraws = NULL,
  include_group_effects = FALSE,
  seed = 1L
)

Arguments

Value

A gp3bayes_estimand.

Estimate a Design-Standardised Binary Probability Contrast

Description

Replaces the focal-condition value across a declared target covariate distribution, obtains population-level expected probabilities using brms::posterior_epred(), and averages within each posterior draw.

Usage

estimate_standardized_probability_contrast(
  fit,
  target_data = NULL,
  target_scale = c("prepared", "raw"),
  ndraws = NULL,
  include_group_effects = FALSE
)

Arguments

Value

A gp3bayes_estimand with probability-difference draws.

Evaluate a Pathological Simulation Against the Contract Gate

Description

Evaluate a Pathological Simulation Against the Contract Gate

Usage

evaluate_pathological_simulation(x)

Arguments

Value

A gp3bayes_pathology_evaluation.

Evidence Inventory Table

Description

Evidence Inventory Table

Usage

evidence_inventory_table(x)

Arguments

Value

Inventory metadata.

Extract Expected Posterior Predictions

Description

Extract Expected Posterior Predictions

Usage

extract_expected_predictions(
  fit,
  newdata = NULL,
  include_group_effects = FALSE,
  allow_new_levels = FALSE,
  ndraws = NULL
)

Arguments

Value

A numeric matrix of conditional expected-response draws.

Extract Linear-Predictor Draws

Description

Extract Linear-Predictor Draws

Usage

extract_linear_predictions(
  fit,
  newdata = NULL,
  include_group_effects = FALSE,
  allow_new_levels = FALSE,
  ndraws = NULL
)

Arguments

Value

A numeric matrix on the model linear-predictor scale.

Extract Pointwise Log-Likelihood Draws

Description

Extract Pointwise Log-Likelihood Draws

Usage

extract_log_likelihood(
  fit,
  newdata = NULL,
  include_group_effects = TRUE,
  ndraws = NULL
)

Arguments

Value

A numeric matrix with posterior draws in rows and observations in columns.

Extract Posterior Draws from a gp3bayes Fit

Description

Converts the fitted brms posterior into a standard posterior draws representation without changing the fitted model.

Usage

extract_posterior_draws(
  fit,
  variables = NULL,
  regex = NULL,
  format = c("array", "matrix", "df", "rvars")
)

Arguments

Value

A posterior draws object in the requested format.

Extract Posterior Predictive Draws

Description

Extract Posterior Predictive Draws

Usage

extract_posterior_predictions(
  fit,
  newdata = NULL,
  include_group_effects = FALSE,
  allow_new_levels = FALSE,
  ndraws = NULL,
  seed = 1L
)

Arguments

Value

A numeric matrix of new-outcome posterior predictive draws.

Extract NUTS Sampler Diagnostics

Description

Extract NUTS Sampler Diagnostics

Usage

extract_sampler_diagnostics(fit)

Arguments

Value

A data frame returned from brms::nuts_params().

Fit an advanced pupil model using rstan

Description

Fit an advanced pupil model using rstan

Usage

fit_advanced_pupil_model(
  specification,
  chains = 4L,
  iter = 2000L,
  warmup = 1000L,
  cores = min(2L, chains),
  seed = 2026,
  adapt_delta = 0.95,
  max_treedepth = 12L,
  refresh = 0L
)

Arguments

Fit an advanced pupil model through an approved brms backend

Description

Fit an advanced pupil model through an approved brms backend

Usage

fit_advanced_pupil_model_backend(
  specification,
  backend = c("rstan", "cmdstanr"),
  chains = 4L,
  iter = 2000L,
  warmup = 1000L,
  cores = min(2L, chains),
  seed = 2026,
  adapt_delta = 0.95,
  max_treedepth = 12L,
  refresh = 0L
)

Arguments

Value

A gp3bayes_pupil_advanced_fit object.

Fit an advanced pupil model using cmdstanr

Description

Fit an advanced pupil model using cmdstanr

Usage

fit_advanced_pupil_model_cmdstanr(
  specification,
  chains = 4L,
  iter = 2000L,
  warmup = 1000L,
  cores = min(2L, chains),
  seed = 2026,
  adapt_delta = 0.95,
  max_treedepth = 12L,
  refresh = 0L
)

Arguments

Fit an Approved Hierarchical Binary Model

Description

Fits an approved binary model specification using full MCMC sampling through the fixed brms and rstan route.

Usage

fit_binary_model(
  specification,
  chains = 4L,
  iter = 2000L,
  warmup = 1000L,
  cores = .gp3b_default_cores(chains),
  seed = 1L,
  adapt_delta = 0.95,
  max_treedepth = 12L,
  refresh = 0L
)

Arguments

Details

The function fixes the likelihood to Bernoulli, the link to logit, the interface to brms, the sampling backend to rstan, and the algorithm to full MCMC sampling. It does not expose arbitrary backend arguments.

A returned fit is not evidence of convergence, posterior adequacy, causal identification, or substantive validity. Those assessments require separate diagnostic and reporting gates.

Value

A gp3bayes_binary_fit containing the fitted backend object, original specification, restricted translation, and recorded sampling settings.

Examples

if (
  requireNamespace("brms", quietly = TRUE) &&
    requireNamespace("rstan", quietly = TRUE) &&
    identical(
      validate_backend_environment(
        "rstan",
        compile_test = FALSE,
        strict = FALSE
      )$status,
      "pass"
    )
) {
  simulation <- simulate_hierarchical_binary_data(
    n_participants = 8,
    trials_per_participant = 6,
    n_items = 4,
    random_slope_sd = 0,
    seed = 2026
  )

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

  prepared <- prepare_hierarchical_binary_data(
    simulation$data,
    contract,
    condition_levels = c("control", "treatment")
  )

  specification <- specify_binary_model(prepared, baseline = 0.35)

  fit <- fit_binary_model(
    specification,
    chains = 2,
    iter = 200,
    warmup = 100,
    cores = 2,
    seed = 2026,
    refresh = 0
  )
}

Fit a Binary Model with a Selected Full-MCMC Backend

Description

The formula and family remain contract-restricted. The only selectable implementation detail is whether brms delegates full MCMC sampling to rstan or CmdStanR.

Usage

fit_binary_model_backend(
  specification,
  backend = c("rstan", "cmdstanr"),
  chains = 4L,
  iter = 2000L,
  warmup = 1000L,
  cores = .gp3b_default_cores(chains),
  seed = 1L,
  adapt_delta = 0.95,
  max_treedepth = 12L,
  refresh = 0L
)

fit_binary_model_cmdstanr(
  specification,
  chains = 4L,
  iter = 2000L,
  warmup = 1000L,
  cores = .gp3b_default_cores(chains),
  seed = 1L,
  adapt_delta = 0.95,
  max_treedepth = 12L,
  refresh = 0L
)

Arguments

Value

A gp3bayes_backend_portable_fit.

Fit a joint binocular pupil model

Description

Fit a joint binocular pupil model

Usage

fit_binocular_pupil_model(
  specification,
  backend = c("rstan", "cmdstanr"),
  chains = 4L,
  iter = 2000L,
  warmup = 1000L,
  cores = min(2L, chains),
  seed = 2026,
  adapt_delta = 0.95,
  max_treedepth = 12L,
  refresh = 0L
)

Arguments

Fit an Approved Hierarchical Lognormal Duration Model

Description

Fits an approved strictly positive uncensored duration model using full MCMC through the fixed brms and rstan route.

Usage

fit_duration_model(
  specification,
  chains = 4L,
  iter = 2000L,
  warmup = 1000L,
  cores = .gp3b_default_cores(chains),
  seed = 1L,
  adapt_delta = 0.95,
  max_treedepth = 12L,
  refresh = 0L
)

Arguments

Details

The likelihood is fixed to lognormal, the link to identity on the mean-log parameter, the interface to brms, the backend to rstan, and the algorithm to full MCMC sampling. A returned fit does not establish convergence or posterior adequacy.

Value

A gp3bayes_duration_fit.

Fit a Duration Model with a Selected Full-MCMC Backend

Description

Fit a Duration Model with a Selected Full-MCMC Backend

Usage

fit_duration_model_backend(
  specification,
  backend = c("rstan", "cmdstanr"),
  chains = 4L,
  iter = 2000L,
  warmup = 1000L,
  cores = .gp3b_default_cores(chains),
  seed = 1L,
  adapt_delta = 0.95,
  max_treedepth = 12L,
  refresh = 0L
)

fit_duration_model_cmdstanr(
  specification,
  chains = 4L,
  iter = 2000L,
  warmup = 1000L,
  cores = .gp3b_default_cores(chains),
  seed = 1L,
  adapt_delta = 0.95,
  max_treedepth = 12L,
  refresh = 0L
)

Arguments

Value

A gp3bayes_backend_portable_fit.

Fit a pupil model through the fixed rstan route

Description

Fit a pupil model through the fixed rstan route

Usage

fit_pupil_model(
  specification,
  chains = 4L,
  iter = 2000L,
  warmup = 1000L,
  cores = min(2L, chains),
  seed = 2026,
  adapt_delta = 0.95,
  max_treedepth = 12L,
  refresh = 0L
)

Arguments

Value

A gp3bayes_pupil_fit.

Examples

# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.

Fit the restricted pupil time-course model with an approved backend

Description

Fits only a specify_pupil_timecourse_model() specification through brms using full MCMC sampling and either rstan or cmdstanr.

Usage

fit_pupil_model_backend(
  specification,
  backend = c("rstan", "cmdstanr"),
  chains = 4L,
  iter = 2000L,
  warmup = 1000L,
  cores = min(2L, chains),
  seed = 2026,
  adapt_delta = 0.95,
  max_treedepth = 12L,
  refresh = 0L
)

Arguments

Value

A gp3bayes_pupil_fit.

Governance boundary

This interface accepts no arbitrary formula, family, Stan program, inference algorithm, or unrestricted backend arguments. A returned fit does not establish convergence, adequacy, predictive validity, or psychological interpretation.

Examples

# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.

Fit a pupil model through the fixed cmdstanr route

Description

Fit a pupil model through the fixed cmdstanr route

Usage

fit_pupil_model_cmdstanr(
  specification,
  chains = 4L,
  iter = 2000L,
  warmup = 1000L,
  cores = min(2L, chains),
  seed = 2026,
  adapt_delta = 0.95,
  max_treedepth = 12L,
  refresh = 0L
)

Arguments

Value

A gp3bayes_pupil_fit.

Examples

# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.

Fit the experimental nonlinear response-shape model

Description

Fit the experimental nonlinear response-shape model

Usage

fit_pupil_response_shape_model(
  specification,
  backend = c("rstan", "cmdstanr"),
  chains = 4L,
  iter = 2500L,
  warmup = 1250L,
  cores = min(2L, chains),
  seed = 2026,
  adapt_delta = 0.97,
  max_treedepth = 13L,
  refresh = 0L
)

Arguments

Freeze an Analysis Manifest

Description

Computes a deterministic hash over analysis-defining fields. When file is supplied the frozen manifest is written explicitly to that path. No file is written when file = NULL.

Usage

freeze_analysis_manifest(manifest, file = NULL, overwrite = FALSE)

Arguments

Value

A frozen gp3bayes_analysis_manifest.

Freeze a gp3bayes Object Schema

Description

Marks a captured schema as frozen and optionally writes it to an explicit RDS path. When file = NULL, no file is written.

Usage

freeze_gp3bayes_schema(schema, file = NULL, overwrite = FALSE)

Arguments

Value

The frozen schema, invisibly when written.

Return the Gazepoint pupil mapping audit table

Description

Return the Gazepoint pupil mapping audit table

Usage

gazepoint_pupil_mapping_table(x)

Arguments

Value

A data frame with documented fields, roles, units, eye, and presence.

Examples

# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.

Specification-Closure Traceability Matrix

Description

Returns an auditable mapping between the Phase-0 closure requirements and their first-class implementation points.

Usage

gp3bayes_specification_traceability()

Value

A data frame.

Group-Deletion Sensitivity Table

Description

Group-Deletion Sensitivity Table

Usage

group_deletion_sensitivity_table(x)

Arguments

Value

Omitted-unit estimand summaries.

Group-Level Posterior Draw Table

Description

Group-Level Posterior Draw Table

Usage

group_effect_draws_table(
  fit,
  groups = NULL,
  coefficients = NULL,
  ndraws = NULL,
  seed = 1L,
  max_rows = 1000000L
)

Arguments

Value

A long posterior draw table on the model linear-predictor scale.

Group-Level Rank-Probability Table

Description

Group-Level Rank-Probability Table

Usage

group_effect_rank_probability_table(
  fit,
  group,
  coefficient = "Intercept",
  ndraws = 1000L,
  seed = 1L
)

Arguments

Value

Descriptive posterior rank probabilities. Rank 1 is the largest group-level deviation.

Group-Level Effect Table

Description

Group-Level Effect Table

Usage

group_effect_table(fit, groups = NULL, probs = c(0.025, 0.975))

Arguments

Value

A tidy data frame of estimated group-level deviations.

Group Prediction Summary

Description

Aggregates posterior prediction draws over one or more columns already present in the prediction data.

Usage

group_prediction_summary(x, by, probs = c(0.025, 0.5, 0.975))

Arguments

Value

A group-level posterior prediction table.

Grouped Posterior Predictive Check

Description

Grouped Posterior Predictive Check

Usage

grouped_prediction_check(
  fit,
  group,
  ndraws = 1000L,
  probs = c(0.025, 0.5, 0.975),
  seed = 1L
)

Arguments

Value

A gp3bayes_group_prediction_check.

Identify Identifier-Like Numeric Predictors

Description

Applies conservative heuristics to declared numeric predictors. A flagged predictor is a review signal only; explicit declaration in a contract is never silently overridden.

Usage

identify_identifier_like_predictors(
  data,
  contract,
  unique_fraction = 0.9,
  integer_fraction = 0.98,
  monotone_correlation = 0.98
)

Arguments

Value

A gp3bayes_identifier_predictor_audit object.

Identify Influential PSIS-LOO Observations

Description

Identify Influential PSIS-LOO Observations

Usage

identify_loo_influential_observations(x, threshold = NULL, data = NULL)

Arguments

Value

A data frame of flagged observations.

Identify MCMC Diagnostic Flags

Description

Identify MCMC Diagnostic Flags

Usage

identify_mcmc_issues(
  x,
  rhat_threshold = 1.01,
  min_bulk_ess = 400,
  min_tail_ess = 400,
  max_mcse_fraction = 0.1
)

Arguments

Value

A parameter-level flag table. Flags request review; they do not establish or negate model adequacy.

Examples

d <- data.frame(
  variable = c("a", "b"),
  sd = c(1, 1),
  rhat = c(1.00, 1.03),
  ess_bulk = c(1000, 150),
  ess_tail = c(900, 120),
  mcse_mean = c(0.02, 0.15)
)
identify_mcmc_issues(d)

Inspect verified Gazepoint pupil and gaze fields

Description

Compares column names with the documented Open Gaze API field identifiers. The inspector reports candidates and ambiguity but never chooses a pupil channel automatically. Export variants that use other names remain unrecognized rather than being guessed.

Usage

inspect_gazepoint_pupil_schema(data)

Arguments

Details

LPD and RPD are documented pixel diameters. LPUPILD and RPUPILD are documented in metres. These scales are intentionally kept distinct.

Value

A gp3bayes_gazepoint_pupil_schema with detected fields, pupil-channel candidates, and an audit table.

Governance boundary

Recognition is schema evidence only. The function does not establish device validity, select an eye, convert units, correct PFE, or infer preprocessing history.

Examples

x <- data.frame(TIME = 0:2 / 60, LPD = c(32, 33, 31), LPV = 1)
inspect_gazepoint_pupil_schema(x)

Summarise Separate Interaction Prior Metadata

Description

Summarise Separate Interaction Prior Metadata

Usage

interaction_prior_summary(specification)

Arguments

Value

A one-row data frame.

Invert a Recorded Transformation Recipe

Description

Reconstructs a raw-scale representation from prepared data when the recorded transformations are invertible. This is intended for replay tests and controlled sensitivity construction, not recovery of discarded rows.

Usage

invert_transformation_recipe(data, recipe)

Arguments

Value

A raw-scale data frame.

LOO Diagnostic Table

Description

LOO Diagnostic Table

Usage

loo_diagnostic_table(x)

Arguments

Value

Observation-level Pareto-k diagnostics.

Flagged LOO Observation Data

Description

Flagged LOO Observation Data

Usage

loo_flagged_data(x, threshold = 0.7)

Arguments

Value

Rows meeting the requested threshold.

Aggregate LOO Influence by a Declared Group

Description

Aggregate LOO Influence by a Declared Group

Usage

loo_group_influence_table(x, group, data = NULL)

Arguments

Value

A descriptive group-level influence table.

LOO Influence Atlas Table

Description

LOO Influence Atlas Table

Usage

loo_influence_atlas_table(x)

Arguments

Value

The complete pointwise atlas table.

LOO Influence Summary

Description

LOO Influence Summary

Usage

loo_influence_summary(x)

Arguments

Value

A one-row influence summary.

Pointwise LOO Table

Description

Pointwise LOO Table

Usage

loo_pointwise_table(x, data = NULL)

Arguments

Value

Pointwise LOO estimates and Pareto-k diagnostics.

LOO Summary Table

Description

LOO Summary Table

Usage

loo_summary_table(x)

Arguments

Value

A tidy table of LOO estimates and standard errors.

Manifest-Comparison Table

Description

Manifest-Comparison Table

Usage

manifest_comparison_table(x)

Arguments

Value

Manifest component comparisons.

Materialize one advanced sensitivity scenario

Description

Materialize one advanced sensitivity scenario

Usage

materialize_pupil_advanced_sensitivity_scenario(suite, scenario)

Arguments

Value

An advanced pupil specification.

Materialize one declared pupil sensitivity scenario

Description

Creates the alternate prepared/specification state for a declared scenario. This does not fit the model. Analysis-window scenarios are returned as estimand instructions. PFE scenarios select only a user-supplied upstream prepared alternative; no PFE correction is performed by gp3bayes.

Usage

materialize_pupil_sensitivity_scenario(suite, scenario_id)

Arguments

Value

A list containing the materialized specification and/or declared estimand window.

Examples

# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.

Modern MCMC Diagnostic Table

Description

Computes rank-normalised R-hat, bulk ESS, tail ESS, and Monte Carlo standard error summaries through the posterior package.

Usage

mcmc_diagnostic_table(fit, variables = NULL, regex = NULL)

Arguments

Value

A data frame with posterior diagnostics by variable.

Missingness-Audit Table

Description

Missingness-Audit Table

Usage

missingness_audit_table(x)

Arguments

Value

Column-level missingness diagnostics.

Model-Card Evidence Table

Description

Model-Card Evidence Table

Usage

model_card_table(x)

Arguments

Value

The model-card evidence inventory.

LOO Model-Comparison Table

Description

LOO Model-Comparison Table

Usage

model_comparison_table(x)

Arguments

Value

A data frame retaining ELPD differences and their standard errors.

Model-Evidence Table

Description

Model-Evidence Table

Usage

model_evidence_table(x)

Arguments

Value

The model-evidence inventory table.

LOO Model-Weight Table

Description

LOO Model-Weight Table

Usage

model_weights_table(x)

Arguments

Value

A data frame of model weights. The table does not select a model.

Summarise Workflow Stage Completion

Description

Creates an inspectable stage map for a gp3bayes object. Stage completion is descriptive only and is not an adequacy or validity declaration.

Usage

model_workflow_status(x)

Arguments

Value

A gp3bayes_workflow_status data frame.

Plot Governed Exact K-Fold Results

Description

Delegates plotting to the LOO-compatible object returned by brms::kfold().

Usage

## S3 method for class 'gp3bayes_kfold_cv'
plot(x, ...)

Arguments

Value

x, invisibly.

Plot a Strict Readiness Audit

Description

Plot a Strict Readiness Audit

Usage

## S3 method for class 'gp3bayes_strict_readiness_audit'
plot(x, type = c("status", "condition", "duration_extremes"), ...)

Arguments

Value

x, invisibly.

Plot simulated advanced pupil trajectories

Description

Plot simulated advanced pupil trajectories

Usage

plot_advanced_pupil_simulation(x, observed = TRUE, ...)

Arguments

Plot an advanced posterior pupil trajectory

Description

Plot an advanced posterior pupil trajectory

Usage

plot_advanced_pupil_trajectory(x, probability = 0.95, ...)

Arguments

Autocorrelation Diagnostic Plot

Description

Autocorrelation Diagnostic Plot

Usage

plot_autocorrelation(fit, variables = NULL, regex = "^b_", lags = 20L)

Arguments

Value

A ggplot object.

Plot Backend Environment Checks with ggplot2

Description

Plot Backend Environment Checks with ggplot2

Usage

plot_backend_environment_gg(x)

Arguments

Value

A ggplot.

Plot Backend Parity with ggplot2

Description

Plot Backend Parity with ggplot2

Usage

plot_backend_parity_gg(x)

Arguments

Value

A ggplot.

Binary Calibration Plot

Description

Binary Calibration Plot

Usage

plot_binary_calibration(x, bins = 10L)

Arguments

Value

A ggplot object.

Plot Binary Calibration Uncertainty

Description

Plot Binary Calibration Uncertainty

Usage

plot_binary_calibration_uncertainty(x)

Arguments

Value

A ggplot.

Grouped Binary Calibration Plot

Description

Grouped Binary Calibration Plot

Usage

plot_binary_group_calibration(x, group = NULL)

Arguments

Value

A ggplot.

Binary Precision-Recall Plot

Description

Binary Precision-Recall Plot

Usage

plot_binary_precision_recall(x, observed = NULL)

Arguments

Value

A ggplot.

Binary ROC Plot

Description

Binary ROC Plot

Usage

plot_binary_roc(x, observed = NULL)

Arguments

Value

A ggplot.

Binary Threshold-Metric Plot

Description

Binary Threshold-Metric Plot

Usage

plot_binary_threshold_metrics(
  x,
  observed = NULL,
  thresholds = seq(0.1, 0.9, by = 0.05)
)

Arguments

Value

A ggplot object.

Plot binocular posterior trajectories

Description

Plot binocular posterior trajectories

Usage

plot_binocular_pupil_trajectory(x, probability = x$probability, ...)

Arguments

Plot Design-Support Components with ggplot2

Description

Plot Design-Support Components with ggplot2

Usage

plot_design_support_gg(x)

Arguments

Value

A ggplot.

Plot Diagnostic Dashboard Availability

Description

Plot Diagnostic Dashboard Availability

Usage

plot_diagnostic_dashboard(x)

Arguments

Value

A ggplot.

Duration PIT Plot

Description

Duration PIT Plot

Usage

plot_duration_pit(x, bins = 10L)

Arguments

Value

A ggplot object.

Duration Predictive Q-Q Plot

Description

Duration Predictive Q-Q Plot

Usage

plot_duration_qq(x)

Arguments

Value

A ggplot.

Duration Quantile-Calibration Plot

Description

Duration Quantile-Calibration Plot

Usage

plot_duration_quantile_calibration(x)

Arguments

Value

A ggplot object.

Duration Tail-Check Plot

Description

Duration Tail-Check Plot

Usage

plot_duration_tail(x)

Arguments

Value

A ggplot.

Estimand Interval Plot

Description

Estimand Interval Plot

Usage

plot_estimand_intervals(x, quantities = NULL, probs = c(0.025, 0.5, 0.975))

Arguments

Value

A ggplot object.

Plot Estimand Sensitivity with ggplot2

Description

Plot Estimand Sensitivity with ggplot2

Usage

plot_estimand_sensitivity_gg(x)

Arguments

Value

A ggplot.

Prediction Exceedance-Probability Plot

Description

Prediction Exceedance-Probability Plot

Usage

plot_exceedance_probability(x)

Arguments

Value

A ggplot object.

Plot Group-Deletion Sensitivity

Description

Plot Group-Deletion Sensitivity

Usage

plot_group_deletion_sensitivity(x)

Arguments

Value

A ggplot.

Plot Group-Effect Posterior Distributions

Description

Plot Group-Effect Posterior Distributions

Usage

plot_group_effect_distribution(x, max_levels = 20L)

Arguments

Value

A faceted ggplot.

Plot Group-Effect Rank Probabilities

Description

Plot Group-Effect Rank Probabilities

Usage

plot_group_effect_rank_probability(x)

Arguments

Value

A ggplot.

Group-Effect Plot

Description

Group-Effect Plot

Usage

plot_group_effects(x, groups = NULL)

Arguments

Value

A faceted ggplot object.

Group Prediction Plot

Description

Group Prediction Plot

Usage

plot_group_predictions(x, group_column)

Arguments

Value

A ggplot.

Grouped Posterior Predictive Plot

Description

Grouped Posterior Predictive Plot

Usage

plot_grouped_prediction_check(x)

Arguments

Value

A ggplot object.

Plot Grouped Pointwise ELPD Contribution

Description

Plot Grouped Pointwise ELPD Contribution

Usage

plot_loo_group_elpd(x)

Arguments

Value

A ggplot.

Plot Grouped LOO Influence

Description

Plot Grouped LOO Influence

Usage

plot_loo_group_influence(x)

Arguments

Value

A ggplot.

LOO Influence Plot

Description

LOO Influence Plot

Usage

plot_loo_influence(x)

Arguments

Value

A ggplot object.

Plot Ranked LOO Influence

Description

Plot Ranked LOO Influence

Usage

plot_loo_influence_rank(x)

Arguments

Value

A ggplot.

Plot Pareto-k versus Pointwise ELPD

Description

Plot Pareto-k versus Pointwise ELPD

Usage

plot_loo_pareto_vs_elpd(x)

Arguments

Value

A ggplot.

Plot Pointwise LOO ELPD

Description

Plot Pointwise LOO ELPD

Usage

plot_loo_pointwise_elpd(x)

Arguments

Value

A ggplot.

Plot Manifest Differences with ggplot2

Description

Plot Manifest Differences with ggplot2

Usage

plot_manifest_comparison_gg(x)

Arguments

Value

A ggplot.

MCMC Review-Flag Plot

Description

MCMC Review-Flag Plot

Usage

plot_mcmc_quality(x)