| Title: | Contract-First Bayesian Workflows for Hierarchical Behavioural Data |
|---|---|
| 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. Version 0.6 adds retention-first Bayesian SCR responsivity accountability and governed trial-level multilevel gaze mediation with explicit within- and between-participant estimands, serial and moderated extensions, convergence gating, and observation-aligned predictive model comparison. |
| Authors: | Stefanos Balaskas [aut, cre, cph] (ORCID: <https://orcid.org/0000-0003-2444-9796>) |
| Maintainer: | Stefanos Balaskas <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.6.0 |
| Built: | 2026-10-09 21:28:45 UTC |
| Source: | https://github.com/stefanosbalaskas/gp3bayes |
Summarise an advanced pupil trajectory
advanced_pupil_trajectory_table(prediction, probability = 0.95)advanced_pupil_trajectory_table(prediction, probability = 0.95)
prediction |
An advanced trajectory prediction. |
probability |
Central posterior interval probability. |
A data frame.
Analysis-Bundle Status Table
analysis_bundle_table(x)analysis_bundle_table(x)
x |
A |
Component availability and captured errors.
Summarise Manifest Components
analysis_manifest_table(manifest)analysis_manifest_table(manifest)
manifest |
An analysis manifest. |
A data frame of key provenance components.
Apply a Recorded Transformation Recipe
apply_transformation_recipe( new_data, recipe, input_scale = c("raw", "prepared"), require_outcome = FALSE, input_unit = NULL )apply_transformation_recipe( new_data, recipe, input_scale = c("raw", "prepared"), require_outcome = FALSE, input_unit = NULL )
new_data |
New data to transform. |
recipe |
A |
input_scale |
Either |
require_outcome |
Whether the outcome column must be present. |
input_unit |
Optional source duration unit used to guard duration replay. |
A transformed data frame with a recipe attribute.
Wraps already-computed posterior prediction draws for examples, reporting, and reproducible post-fit analysis without pretending that fitting occurred in the current session.
as_pupil_prediction_draws( draws, grid, unit, type = c("expected", "posterior_predictive", "linear"), max_cells = 5000000L )as_pupil_prediction_draws( draws, grid, unit, type = c("expected", "posterior_predictive", "linear"), max_cells = 5000000L )
draws |
Numeric matrix with posterior draws in rows and grid points in columns. |
grid |
Data frame with one row per draw column. It should contain
|
unit |
Declared pupil unit. |
type |
Prediction type label. |
max_cells |
Maximum draw-by-grid cells. |
A gp3bayes_pupil_prediction.
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" )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" )
Convert a pupil contract to a transparent table
## S3 method for class 'gp3bayes_pupil_contract' as.data.frame(x, ...)## S3 method for class 'gp3bayes_pupil_contract' as.data.frame(x, ...)
x |
A |
... |
Ignored. |
A data frame of contract fields.
Convert a pupil estimand to a data frame
## S3 method for class 'gp3bayes_pupil_estimand' as.data.frame(x, ...)## S3 method for class 'gp3bayes_pupil_estimand' as.data.frame(x, ...)
x |
A |
... |
Ignored. |
The estimand table.
Refits the approved binary model under prespecified tighter and wider prior scales and compares population-level posterior medians.
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 )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 )
fit |
A |
scale_multipliers |
Named positive numeric multipliers applied to the intercept, coefficient, and group-scale priors. |
chains, iter, warmup, cores, seed, adapt_delta, max_treedepth, refresh
|
Restricted sampling controls passed to |
maximum_standardized_shift |
Maximum absolute posterior-median shift, divided by the reference posterior standard deviation, for a pass. |
review_standardized_shift |
Maximum standardized shift for review. |
retain_fits |
Whether alternative fitted objects should be retained. |
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.
A gp3bayes_binary_prior_sensitivity object.
Refits the approved duration model under prespecified tighter and wider prior scales and compares population-level and residual posterior medians.
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 )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 )
fit |
A |
scale_multipliers |
Named positive prior-scale multipliers. |
chains, iter, warmup, cores, seed, adapt_delta, max_treedepth, refresh
|
Restricted sampling controls passed to |
maximum_standardized_shift |
Maximum standardized median shift for pass. |
review_standardized_shift |
Maximum standardized median shift for review. |
retain_fits |
Whether alternative fits are retained. |
A gp3bayes_duration_prior_sensitivity.
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.
assess_powerscaled_sensitivity( fit, variable = NULL, prior_selection = NULL, likelihood_selection = NULL )assess_powerscaled_sensitivity( fit, variable = NULL, prior_selection = NULL, likelihood_selection = NULL )
fit |
A gp3bayes fit or |
variable |
Optional posterior variables to inspect. |
prior_selection |
Optional tagged priors to perturb. |
likelihood_selection |
Optional likelihood subset. |
A gp3bayes_powerscale_sensitivity.
This audit is deliberately heuristic. It identifies weakly supported design configurations before sampling but does not certify model identifiability or posterior adequacy.
audit_advanced_pupil_identifiability(specification)audit_advanced_pupil_identifiability(specification)
specification |
An advanced pupil specification. |
A gp3bayes_pupil_identifiability_audit object.
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.
audit_backend_parity( rstan_fit, cmdstanr_fit, variables = NULL, mcse_multiplier = 3, absolute_tolerance = 0, relative_sd_tolerance = 0.1 )audit_backend_parity( rstan_fit, cmdstanr_fit, variables = NULL, mcse_multiplier = 3, absolute_tolerance = 0, relative_sd_tolerance = 0.1 )
rstan_fit |
A gp3bayes rstan fit, or a compatible posterior-summary data frame for testing/auditing. |
cmdstanr_fit |
A gp3bayes cmdstanr fit, or a compatible summary table. |
variables |
Optional parameter names to compare. When omitted, the package's approved population/group-scale parameter set is used. |
mcse_multiplier |
Multiplier applied to the combined MCSE of posterior means to define a sampling-noise comparison band. |
absolute_tolerance |
Minimum absolute tolerance for mean differences. |
relative_sd_tolerance |
Review threshold for relative posterior-SD differences. |
A gp3bayes_backend_parity_audit.
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)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
audit_binocular_pupil_readiness(prepared)audit_binocular_pupil_readiness(prepared)
prepared |
A binocular prepared object. |
A gp3bayes_binocular_pupil_audit object.
Combines missingness, fixed-effects design, random-effects support, standard readiness, and optional binary separation screening into one pre-fit audit.
audit_design_support( x, contract = NULL, separation = FALSE, strict_readiness = TRUE )audit_design_support( x, contract = NULL, separation = FALSE, strict_readiness = TRUE )
x |
A data frame, prepared object, model specification, or fit. |
contract |
Required when |
separation |
Whether to run |
strict_readiness |
Whether to include |
A gp3bayes_design_support_audit.
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.
audit_duration_boundaries( data, contract, allowed_range = NULL, censor_col = NULL, detect_candidate_columns = TRUE )audit_duration_boundaries( data, contract, allowed_range = NULL, censor_col = NULL, detect_candidate_columns = TRUE )
data |
A data frame. |
contract |
An approved duration contract. |
allowed_range |
Optional positive lower and upper bounds in the contract's recorded outcome unit. |
censor_col |
Optional censoring-indicator column. |
detect_candidate_columns |
Whether common censoring/truncation names should be reported for review. |
A gp3bayes_duration_boundary_audit object.
Checks the unit-free median and predictive-quantile ratios and the expected scaling of absolute predictive quantities after a known unit conversion.
audit_duration_unit_invariance( reference, converted, multiplier, tolerance = 0.02 )audit_duration_unit_invariance( reference, converted, multiplier, tolerance = 0.02 )
reference, converted
|
Comparable duration estimands. |
multiplier |
Conversion factor applied to the outcome unit. |
tolerance |
Absolute tolerance for unit-free ratios and relative tolerance for scaled absolute quantities. |
A gp3bayes_duration_unit_invariance_audit.
Audit Estimand Invariance Against a Declared Tolerance
audit_estimand_invariance( reference, alternative, quantity = reference$primary_quantity, tolerance )audit_estimand_invariance( reference, alternative, quantity = reference$primary_quantity, tolerance )
reference, alternative
|
Comparable gp3bayes estimands. |
quantity |
Quantity to compare. |
tolerance |
Maximum absolute median difference considered invariant for the declared scientific use. |
A gp3bayes_estimand_invariance_audit.
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.
audit_fixed_effect_design( x, contract = NULL, condition_number_review = 30, condition_number_fail = 100, leverage_multiplier = 3 )audit_fixed_effect_design( x, contract = NULL, condition_number_review = 30, condition_number_fail = 100, leverage_multiplier = 3 )
x |
A data frame, prepared object, model specification, or fit. |
contract |
Required when |
condition_number_review |
Condition number triggering review. |
condition_number_fail |
Condition number triggering fail. |
leverage_multiplier |
Review observations whose hat value is above
|
A gp3bayes_fixed_effect_design_audit.
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.
audit_missingness_structure( x, contract = NULL, review_fraction = 0.05, fail_fraction = 0.2 )audit_missingness_structure( x, contract = NULL, review_fraction = 0.05, fail_fraction = 0.2 )
x |
A data frame, prepared object, model specification, or fit. |
contract |
Required when |
review_fraction |
Column-level missing fraction above which a component is marked for review. |
fail_fraction |
Column-level missing fraction above which a component is marked fail. A fail does not automatically exclude data. |
A gp3bayes_missingness_audit.
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)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)
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.
audit_model_readiness(data, contract)audit_model_readiness(data, contract)
data |
A data frame containing the declared outcome, grouping identifiers, predictors, and optional design columns. |
contract |
A |
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.
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.
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.
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)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)
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.
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 )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 )
data |
A data frame. |
contract |
An approved model contract. |
condition_warning_fraction, condition_failure_fraction
|
Condition balance thresholds. |
identifier_unique_fraction |
Identifier-like uniqueness threshold. |
duration_allowed_range |
Optional positive duration bounds. |
censor_col |
Optional duration censoring indicator. |
run_separation |
Whether to run the optional fixed-effects separation screen when the family is binary. |
A gp3bayes_strict_readiness_audit object.
Compares requested prediction rows with the observed model-building support. It reports extrapolation and novel levels but never removes prediction rows.
audit_prediction_support(fit, newdata)audit_prediction_support(fit, newdata)
fit |
A fitted |
newdata |
Data to audit. |
A gp3bayes_prediction_support object.
Audit computational complexity before fitting an advanced pupil model
audit_pupil_computational_budget(x)audit_pupil_computational_budget(x)
x |
An advanced specification. |
A gp3bayes_pupil_complexity_audit object.
Summarises declared blink/interpolation, baseline, PFE/gaze, luminance, contrast, and sampling context without correcting or excluding observations.
audit_pupil_measurement_context(x)audit_pupil_measurement_context(x)
x |
A prepared pupil object. |
A gp3bayes_pupil_measurement_audit.
# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.
Audit a declared measurement model against data
audit_pupil_measurement_model(specification)audit_pupil_measurement_model(specification)
specification |
An advanced specification containing a measurement model. |
A gp3bayes_pupil_measurement_audit_05 object.
Audit missingness in an advanced pupil specification
audit_pupil_missingness(specification)audit_pupil_missingness(specification)
specification |
An advanced specification. |
A gp3bayes_pupil_missingness_audit object.
Audit posterior predictive calibration on explicit evaluation data
audit_pupil_predictive_calibration( fit, newdata, ndraws = 500L, probability = 0.9, population_only = FALSE, allow_new_levels = FALSE )audit_pupil_predictive_calibration( fit, newdata, ndraws = 500L, probability = 0.9, population_only = FALSE, allow_new_levels = FALSE )
fit |
An advanced fitted model. |
newdata |
Evaluation data containing the pupil response. |
ndraws |
Number of posterior predictive draws. |
probability |
Interval probability. |
population_only |
Exclude group-level effects if TRUE. |
allow_new_levels |
Passed to brms prediction. |
A predictive-score object with evaluation metadata.
Produces observable evidence about hierarchy, sampling, missingness, baseline support, measurement flags, gaze/PFE context, luminance, and preprocessing provenance. Review signals are not exclusion decisions.
audit_pupil_readiness(x, contract = NULL)audit_pupil_readiness(x, contract = NULL)
x |
A |
contract |
Required only when |
A gp3bayes_pupil_readiness object with summary and stratified
tables.
# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.
Computes descriptive within-series autocorrelation and spacing diagnostics. The audit is diagnostic only and does not select an ARMA order.
audit_pupil_temporal_dependence(x, max_lag = 10L)audit_pupil_temporal_dependence(x, max_lag = 10L)
x |
A prepared pupil object, data frame, or advanced specification. |
max_lag |
Maximum lag for descriptive ACF summaries. |
A gp3bayes_pupil_temporal_dependence_audit object.
Audits participant repetition, item crossing, and within-participant condition support for a requested random slope.
audit_random_effects_support( x, contract = NULL, minimum_repeated_rows = 2L, minimum_group_levels = 2L, minimum_condition_cell_rows = 2L )audit_random_effects_support( x, contract = NULL, minimum_repeated_rows = 2L, minimum_group_levels = 2L, minimum_condition_cell_rows = 2L )
x |
A data frame, prepared object, model specification, or fit. |
contract |
Required when |
minimum_repeated_rows |
Minimum observations per participant. |
minimum_group_levels |
Minimum participant/item levels. |
minimum_condition_cell_rows |
Minimum rows in each observed participant-condition cell when a random slope is requested. |
A gp3bayes_random_effects_support_audit.
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.
backend_capabilities()backend_capabilities()
A gp3bayes_backend_capabilities_v2 data frame.
backend_capabilities()backend_capabilities()
Backend-Environment Table
backend_environment_table(x)backend_environment_table(x)
x |
A |
Backend environment checks.
Backend-Parity Table
backend_parity_table(x)backend_parity_table(x)
x |
A |
The parameter-level backend-parity table.
Audits package availability and, where possible, runtime usability for the optional Bayesian extensions.
bayesian_backend_capabilities()bayesian_backend_capabilities()
A gp3bayes_backend_capabilities data frame.
Binary Calibration Error
binary_calibration_error(x, observed = NULL, bins = 10L)binary_calibration_error(x, observed = NULL, bins = 10L)
x |
A binary expected prediction or numeric probabilities. |
observed |
Optional observed outcomes. |
bins |
Number of equal-frequency bins. |
A one-row table with expected and maximum absolute calibration error.
binary_calibration_error(c(0.1, 0.8, 0.7, 0.2), c(0, 1, 1, 0), bins = 2)binary_calibration_error(c(0.1, 0.8, 0.7, 0.2), c(0, 1, 1, 0), bins = 2)
Binary Calibration Table
binary_calibration_table(x, bins = 10L, probs = c(0.025, 0.5, 0.975))binary_calibration_table(x, bins = 10L, probs = c(0.025, 0.5, 0.975))
x |
A binary expected-response |
bins |
Number of equal-frequency calibration bins. |
probs |
Posterior interval probabilities. |
A data frame comparing observed event rates with posterior mean event probabilities by bin.
Equal-width bins are defined from posterior-mean predicted probabilities.
binary_calibration_uncertainty( fit, newdata = NULL, bins = 10L, include_group_effects = FALSE, ndraws = 1000L, probs = c(0.025, 0.5, 0.975) )binary_calibration_uncertainty( fit, newdata = NULL, bins = 10L, include_group_effects = FALSE, ndraws = 1000L, probs = c(0.025, 0.5, 0.975) )
fit |
A fitted binary |
newdata |
Optional data containing observed outcomes. |
bins |
Number of equal-width probability bins. |
include_group_effects |
Whether fitted group effects are included. |
ndraws |
Expected-probability posterior draws. |
probs |
Three interval probabilities. |
A gp3bayes_binary_calibration_uncertainty.
Binary Calibration-Uncertainty Table
binary_calibration_uncertainty_table(x)binary_calibration_uncertainty_table(x)
x |
A binary calibration-uncertainty object. |
Bin-level summaries.
Binary Confusion Table
binary_confusion_table(x, observed = NULL, threshold = 0.5)binary_confusion_table(x, observed = NULL, threshold = 0.5)
x |
A binary expected prediction or numeric probabilities. |
observed |
Optional observed binary outcomes. |
threshold |
Classification threshold from 0 to 1. |
A four-row confusion table plus rates as attributes.
binary_confusion_table(c(0.1, 0.8, 0.7, 0.2), c(0, 1, 1, 0))binary_confusion_table(c(0.1, 0.8, 0.7, 0.2), c(0, 1, 1, 0))
Grouped Binary Calibration
binary_group_calibration(x, group)binary_group_calibration(x, group)
x |
A binary expected-response |
group |
Name of a column in |
A group-level calibration summary.
Binary Precision-Recall Curve
binary_precision_recall_curve(x, observed = NULL, thresholds = NULL)binary_precision_recall_curve(x, observed = NULL, thresholds = NULL)
x |
A binary expected prediction or numeric probabilities. |
observed |
Optional observed binary outcomes. |
thresholds |
Optional thresholds. By default all finite empirical breakpoints are used. |
A data frame containing recall and precision.
binary_precision_recall_curve( c(0.1, 0.8, 0.7, 0.2), c(0, 1, 1, 0) )binary_precision_recall_curve( c(0.1, 0.8, 0.7, 0.2), c(0, 1, 1, 0) )
Binary Prediction Scores
binary_prediction_scores(x, observed = NULL, threshold = 0.5, epsilon = 1e-12)binary_prediction_scores(x, observed = NULL, threshold = 0.5, epsilon = 1e-12)
x |
A binary expected-response |
observed |
Optional binary outcomes when |
threshold |
Classification threshold used only for threshold summaries. |
epsilon |
Probability truncation used for finite log loss. |
A one-row data frame of descriptive predictive scores.
binary_prediction_scores(c(0.1, 0.8, 0.7, 0.2), c(0, 1, 1, 0))binary_prediction_scores(c(0.1, 0.8, 0.7, 0.2), c(0, 1, 1, 0))
Binary ROC Curve
binary_roc_curve(x, observed = NULL, thresholds = NULL)binary_roc_curve(x, observed = NULL, thresholds = NULL)
x |
A binary expected prediction or numeric probabilities. |
observed |
Optional observed binary outcomes. |
thresholds |
Optional thresholds. By default all finite empirical breakpoints are used. |
A data frame containing false-positive and true-positive rates.
binary_roc_curve(c(0.1, 0.8, 0.7, 0.2), c(0, 1, 1, 0))binary_roc_curve(c(0.1, 0.8, 0.7, 0.2), c(0, 1, 1, 0))
Binary Threshold-Metric Curve
binary_threshold_metrics( x, observed = NULL, thresholds = seq(0.1, 0.9, by = 0.05) )binary_threshold_metrics( x, observed = NULL, thresholds = seq(0.1, 0.9, by = 0.05) )
x |
A binary expected-response prediction or numeric probabilities. |
observed |
Optional observed binary outcomes. |
thresholds |
Numeric thresholds between 0 and 1, inclusive. |
A data frame with accuracy, sensitivity, specificity, and balanced accuracy over the supplied thresholds.
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) )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) )
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.
build_model_formula(contract)build_model_formula(contract)
contract |
A |
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.
An R formula. The formula is a specification only and has not been translated to, validated by, or fitted with a Bayesian backend.
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)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)
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.
capture_gp3bayes_schema(x, max_depth = 3L)capture_gp3bayes_schema(x, max_depth = 3L)
x |
A gp3bayes object. |
max_depth |
Maximum nested list depth to record. |
A gp3bayes_object_schema.
contract <- create_model_contract( family = "binary", outcome_col = "selected", participant_col = "participant_id", condition_col = "condition" ) capture_gp3bayes_schema(contract)contract <- create_model_contract( family = "binary", outcome_col = "selected", participant_col = "participant_id", condition_col = "condition" ) capture_gp3bayes_schema(contract)
This optional backend gate samples only from priors using brms. It does not establish model adequacy.
check_advanced_pupil_prior_predictive( specification, backend = c("rstan", "cmdstanr"), chains = 2L, iter = 800L, warmup = 400L, cores = min(2L, chains), seed = 2026 )check_advanced_pupil_prior_predictive( specification, backend = c("rstan", "cmdstanr"), chains = 2L, iter = 800L, warmup = 400L, cores = min(2L, chains), seed = 2026 )
specification |
An advanced specification. |
backend |
|
chains, iter, warmup, cores, seed
|
Sampling controls. |
A gp3bayes_pupil_advanced_prior_predictive object.
Compares observed binary summaries with replicated outcomes from the fitted posterior predictive distribution.
check_binary_posterior_predictive( fit, draws = 500, seed = 1, pass_probability = 0.8, review_probability = 0.95 )check_binary_posterior_predictive( fit, draws = 500, seed = 1, pass_probability = 0.8, review_probability = 0.95 )
fit |
A |
draws |
Number of posterior predictive replications. |
seed |
Non-negative integer seed used to select predictive draws. |
pass_probability |
Central predictive interval used for a pass. |
review_probability |
Wider central predictive interval used for review. |
The check evaluates prespecified descriptive summaries. It does not prove that the likelihood, link, random-effects structure, or substantive model is adequate.
A gp3bayes_binary_posterior_predictive_check.
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.
check_binary_ppc_details( fit, draws = 300L, seed = 1L, calibration_bins = 10L, sparse_cell_min = 3L )check_binary_ppc_details( fit, draws = 300L, seed = 1L, calibration_bins = 10L, sparse_cell_min = 3L )
fit |
Approved binary fit. |
draws |
Number of posterior predictive draws. |
seed |
Random seed. |
calibration_bins |
Number of probability calibration bins. |
sparse_cell_min |
Cell size below which participant-condition cells are reported as sparse. |
A gp3bayes_binary_ppc_detail.
Simulates replicated binary outcomes from the declared prior specification and prepared design without calling a Bayesian fitting backend.
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 )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 )
specification |
A |
draws |
Number of prior predictive data sets. |
seed |
Non-negative integer random-number seed. |
plausible_rate |
Increasing lower and upper limits for plausible overall and condition-specific event rates. |
boundary_probability |
Probability thresholds used to identify prior mass close to zero and one. |
extreme_contrast |
Absolute probability-scale condition contrast considered extreme. |
maximum_degenerate_participant_fraction |
Maximum participant fraction allowed to have all-zero or all-one replicated outcomes in a draw. |
maximum_boundary_mass |
Maximum fraction of row probabilities allowed beyond the declared boundary thresholds in a draw. |
maximum_extreme_probability |
Maximum acceptable fraction of prior predictive draws violating each criterion. |
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.
A gp3bayes_binary_prior_predictive_check containing replicated
summaries, structured checks, thresholds, and the seed.
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 )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 )
Checks package availability, the C++ toolchain, and a configured CmdStan installation. No installation or repair is performed automatically.
check_cmdstan_backend(strict = FALSE)check_cmdstan_backend(strict = FALSE)
strict |
Whether to stop instead of returning a failed audit. |
A list with status, version, path, and diagnostic detail.
Compares observed positive-duration summaries with replicated outcomes from the fitted posterior predictive distribution.
check_duration_posterior_predictive( fit, draws = 500L, seed = 1L, pass_probability = 0.8, review_probability = 0.95 )check_duration_posterior_predictive( fit, draws = 500L, seed = 1L, pass_probability = 0.8, review_probability = 0.95 )
fit |
A |
draws |
Number of posterior predictive data sets. |
seed |
Non-negative integer seed. |
pass_probability |
Central predictive interval used for pass. |
review_probability |
Wider predictive interval used for review. |
The check covers median, mean, upper-tail, dispersion, condition-ratio, and grouping summaries. It does not prove global model adequacy.
A gp3bayes_duration_posterior_predictive_check.
Adds raw/log-scale distributions, median and upper-quantile summaries, tail exceedance, group medians, and within-participant focal-condition median ratios.
check_duration_ppc_details( fit, draws = 300L, seed = 1L, quantiles = c(0.5, 0.9, 0.95), tail_threshold = NULL )check_duration_ppc_details( fit, draws = 300L, seed = 1L, quantiles = c(0.5, 0.9, 0.95), tail_threshold = NULL )
fit |
Approved duration fit. |
draws |
Number of posterior predictive draws. |
seed |
Random seed. |
quantiles |
Predictive quantiles to report. |
tail_threshold |
Optional substantive tail threshold in the analysis unit. If omitted, the observed 95th percentile is used descriptively. |
A gp3bayes_duration_ppc_detail.
Simulates positive-duration data from the declared prior specification and prepared design without fitting a model.
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 )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 )
specification |
A |
draws |
Number of prior predictive data sets. |
seed |
Non-negative integer seed. |
plausible_median |
Optional increasing pair for plausible overall medians in the prepared outcome unit. |
maximum_q99 |
Maximum plausible 99th percentile. |
maximum_cv |
Maximum plausible coefficient of variation. |
maximum_condition_ratio |
Maximum plausible ratio between condition medians in either direction. |
maximum_extreme_probability |
Maximum fraction of prior predictive draws allowed to violate each criterion. |
Failure requests substantive prior review; it does not select or alter priors automatically.
A gp3bayes_duration_prior_predictive_check.
Family-neutral wrapper around the approved family-specific posterior predictive checks. Passing this check is not a global adequacy claim.
check_model_ppc(fit, ...)check_model_ppc(fit, ...)
fit |
A |
... |
Family-specific diagnostic arguments. |
A family-specific gp3bayes_posterior_predictive_check.
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.
check_pupil_posterior_predictive( fit, ndraws = 200L, probability = 0.9, window = NULL, max_cells = 3000000L )check_pupil_posterior_predictive( fit, ndraws = 200L, probability = 0.9, window = NULL, max_cells = 3000000L )
fit |
A fitted pupil model. |
ndraws |
Posterior predictive draws. |
probability |
Predictive envelope probability. |
window |
Optional user-declared event-time window in canonical seconds. |
max_cells |
Maximum draw-by-observation cells. |
A gp3bayes_pupil_ppc.
# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.
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.
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 )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 )
specification |
Approved pupil model specification. |
execute |
Whether to run prior-only MCMC. Defaults to |
backend |
Approved backend, |
draws |
Number of prior predictive replicated draws to retain. |
chains, iter, warmup, cores, seed
|
Sampling controls. Package-controlled cores are capped at two. |
probability |
Central predictive interval probability. |
max_cells |
Maximum retained draw-by-observation cells. |
A gp3bayes_pupil_prior_predictive evidence object.
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.
# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.
Collects already-computed design, diagnostics, posterior summaries, posterior predictive checks, estimands, predictive validation, sensitivity, and reproducibility provenance into a single review object.
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() )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() )
fit |
Optional gp3bayes fit. |
design, diagnostics, posterior, ppc, estimands, loo, kfold, sensitivity
|
Optional evidence components. |
manifest |
Optional |
compute |
Character vector selecting inexpensive components to compute
from |
A gp3bayes_model_evidence.
Compares analysis-defining fields without interpreting any difference as automatically problematic.
compare_analysis_manifests(x, y)compare_analysis_manifests(x, y)
x, y
|
Analysis manifests. |
A gp3bayes_manifest_comparison.
Compare Estimand Sensitivity Across Alternative Fits
compare_estimand_sensitivity( reference, alternatives, quantity = reference$primary_quantity )compare_estimand_sensitivity( reference, alternatives, quantity = reference$primary_quantity )
reference |
Reference |
alternatives |
Named list of alternative estimands. |
quantity |
Quantity to compare; defaults to the reference primary quantity. |
A gp3bayes_estimand_sensitivity.
Compare gp3bayes Object Schemas
compare_gp3bayes_schemas(x, y, compare_lengths = FALSE)compare_gp3bayes_schemas(x, y, compare_lengths = FALSE)
x |
A gp3bayes object or captured schema. |
y |
A gp3bayes object or captured schema. |
compare_lengths |
Whether vector/list lengths are part of the structural
compatibility rule. The default is |
A gp3bayes_schema_comparison.
Compare Models with PSIS-LOO
compare_psis_loo(models, moment_match = FALSE, reloo = FALSE, cores = 1L)compare_psis_loo(models, moment_match = FALSE, reloo = FALSE, cores = 1L)
models |
Named list of gp3bayes fits, |
moment_match |
Whether to request moment matching. |
reloo |
Whether to request exact refits for problematic observations. |
cores |
Number of cores. |
A gp3bayes_loo_comparison. The result never selects a model.
This function does not choose a winner. It summarises lag-specific residual dependence after subtracting posterior expected means.
compare_pupil_autocorrelation(..., max_lag = 10L, ndraws = 300L)compare_pupil_autocorrelation(..., max_lag = 10L, ndraws = 300L)
... |
Two or more named advanced fits, or one named list. |
max_lag |
Maximum residual ACF lag. |
ndraws |
Draws used for posterior expected means. |
A gp3bayes_pupil_autocorrelation_comparison object.
Compare executed leave-future-out validations
compare_pupil_lfo(...)compare_pupil_lfo(...)
... |
Two or more named executed LFO validation objects, or one named list. |
A gp3bayes_pupil_lfo_comparison object.
Compare fitted pupil models predictively
compare_pupil_models( model_set, criterion = c("loo", "kfold"), K = 10L, group = NULL, moment_match = FALSE, save_psis = TRUE )compare_pupil_models( model_set, criterion = c("loo", "kfold"), K = 10L, group = NULL, moment_match = FALSE, save_psis = TRUE )
model_set |
A named model set. |
criterion |
|
K |
Number of folds for exact K-fold CV. |
group |
Optional grouping column passed to brms K-fold. |
moment_match |
Use brms/loo moment matching for PSIS-LOO where supported. |
save_psis |
Save PSIS objects. |
A gp3bayes_pupil_model_comparison object.
Combines already-computed pupil estimands by named scenario. No scenario is ranked or selected.
compare_pupil_sensitivity_estimands(results)compare_pupil_sensitivity_estimands(results)
results |
Named list of |
A gp3bayes_pupil_sensitivity_comparison.
# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.
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.
compute_kfold_cv( fit, K = 10L, folds = c("random", "stratified", "grouped"), group = NULL, joint = c("obs", "fold", "group"), save_fits = FALSE, seed = 1L )compute_kfold_cv( fit, K = 10L, folds = c("random", "stratified", "grouped"), group = NULL, joint = c("obs", "fold", "group"), save_fits = FALSE, seed = 1L )
fit |
Approved gp3bayes fit. |
K |
Number of folds for random or stratified splitting. |
folds |
One of |
group |
Optional declared grouping column used by stratified/grouped splitting. |
joint |
One of |
save_fits |
Whether cross-validation refits are retained. |
seed |
Random seed. |
A gp3bayes_kfold_cv.
Compute LOO Model-Averaging Weights
compute_loo_model_weights(x, method = c("stacking", "pseudobma"), cores = 1L)compute_loo_model_weights(x, method = c("stacking", "pseudobma"), cores = 1L)
x |
A |
method |
Either stacking or pseudo-BMA. |
cores |
Number of cores. |
A gp3bayes_loo_weights object.
Compute PSIS-LOO for a gp3bayes Fit
compute_psis_loo( fit, moment_match = FALSE, reloo = FALSE, cores = 1L, save_psis = TRUE )compute_psis_loo( fit, moment_match = FALSE, reloo = FALSE, cores = 1L, save_psis = TRUE )
fit |
A gp3bayes fit or |
moment_match |
Whether to request moment matching. |
reloo |
Whether to request exact refits for problematic observations. |
cores |
Number of cores. |
save_psis |
Whether to retain the PSIS object. |
A conservative gp3bayes_psis_loo result.
This function supports deterministic tests and advanced workflows that already possess pointwise log-likelihood draws.
compute_psis_loo_from_log_lik( log_lik, chain_id = NULL, cores = 1L, save_psis = TRUE )compute_psis_loo_from_log_lik( log_lik, chain_id = NULL, cores = 1L, save_psis = TRUE )
log_lik |
Matrix with posterior draws in rows and observations in columns. |
chain_id |
Optional chain identifier for each row. |
cores |
Number of cores. |
save_psis |
Whether to retain the PSIS object. |
A gp3bayes_psis_loo.
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.
create_advanced_pupil_prior_specification(specification)create_advanced_pupil_prior_specification(specification)
specification |
A |
A gp3bayes_pupil_advanced_prior_specification object.
Collects reusable posterior, diagnostic, prediction, calibration, scoring, and optionally PSIS-LOO tables without making an automatic adequacy or model selection decision.
create_analysis_bundle( fit, newdata = NULL, ndraws = 1000L, include_group_effects = FALSE, include_loo = FALSE )create_analysis_bundle( fit, newdata = NULL, ndraws = 1000L, include_group_effects = FALSE, include_loo = FALSE )
fit |
A fitted |
newdata |
Optional prediction data. |
ndraws |
Posterior draws used for prediction-facing components. |
include_group_effects |
Whether prediction summaries include recorded group-level effects. |
include_loo |
Whether PSIS-LOO is computed. |
A gp3bayes_analysis_bundle.
Produces only figures supported by available bundle components.
create_analysis_figure_set(x)create_analysis_figure_set(x)
x |
A |
A gp3bayes_figure_set.
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.
create_analysis_manifest( specification = NULL, fit = NULL, data = NULL, estimands = character(), sensitivity_plan = NULL, seed = NULL, label = NULL, notes = character() )create_analysis_manifest( specification = NULL, fit = NULL, data = NULL, estimands = character(), sensitivity_plan = NULL, seed = NULL, label = NULL, notes = character() )
specification |
Optional approved gp3bayes model specification. |
fit |
Optional gp3bayes fit. When supplied, the specification and prepared data are derived from the fit unless explicitly supplied. |
data |
Optional analysis data frame. When omitted it is derived from the specification or fit where possible. |
estimands |
Character vector or structured list describing the prespecified estimands. |
sensitivity_plan |
Optional sensitivity-plan object or list. |
seed |
Optional non-negative integer seed. When omitted and |
label |
Optional human-readable analysis label. |
notes |
Optional character notes. |
A gp3bayes_analysis_manifest.
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 ) manifestsimulation <- 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
Writes a conservative Markdown report for an approved fitted binary model.
create_binary_model_report( fit, diagnostics = NULL, posterior_summary = NULL, posterior_predictive = NULL, prior_sensitivity = NULL, recovery = NULL, file, overwrite = FALSE )create_binary_model_report( fit, diagnostics = NULL, posterior_summary = NULL, posterior_predictive = NULL, prior_sensitivity = NULL, recovery = NULL, file, overwrite = FALSE )
fit |
A |
diagnostics |
Optional result from |
posterior_summary |
Optional result from
|
posterior_predictive |
Optional result from
|
prior_sensitivity |
Optional result from
|
recovery |
Optional result from |
file |
Explicit output Markdown path. The caller must supply the destination; the function has no default output path. |
overwrite |
Whether an existing file may be replaced. |
The report never converts diagnostic or predictive statuses into an automatic statement that the model converged or is substantively valid.
A gp3bayes_binary_model_report containing the normalized path and
section-status registry.
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.
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 )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 )
specification |
An approved binary or duration specification. |
n_sims |
Number of simulated datasets. |
backend |
Either rstan or cmdstanr. |
chains |
Number of chains used per SBC fit. |
iter |
Total iterations per SBC fit. |
warmup |
Warmup iterations. |
thin |
Thinning interval. |
seed |
Seed used when datasets are generated. |
generator_iter |
Total prior-only generator iterations. |
generator_warmup |
Prior-only generator warmup. |
A gp3bayes_sbc_plan.
Create a Complete Evidence Inventory
create_complete_evidence_inventory(..., label = NULL)create_complete_evidence_inventory(..., label = NULL)
... |
Named evidence objects. |
label |
Optional label. |
A gp3bayes_evidence_inventory.
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.
create_contrast_coding_sensitivity_specification( specification, condition_coding, baseline )create_contrast_coding_sensitivity_specification( specification, condition_coding, baseline )
specification |
An approved model specification. |
condition_coding |
Two distinct numeric condition codes. |
baseline |
Explicit baseline probability or median under the new coding. |
An approved alternative specification.
Wraps an independently coded generator function and a user-supplied SBC
backend. The generator must return variables and generated elements as
required by SBC.
create_custom_sbc_plan( generator_function, backend, n_sims = 20L, generator_args = list(), seed = 1L )create_custom_sbc_plan( generator_function, backend, n_sims = 20L, generator_args = list(), seed = 1L )
generator_function |
Function producing one SBC dataset. |
backend |
A valid SBC backend object. |
n_sims |
Number of datasets. |
generator_args |
Named list passed to the generator constructor. |
seed |
Seed used for dataset generation. |
A gp3bayes_sbc_plan.
Expensive analyses are never launched implicitly. Supply already-computed evidence objects.
create_diagnostic_dashboard( fit = NULL, analysis_bundle = NULL, model_card = NULL, loo = NULL, prior_posterior = NULL, sensitivity = NULL, recovery = NULL, sbc = NULL, label = NULL )create_diagnostic_dashboard( fit = NULL, analysis_bundle = NULL, model_card = NULL, loo = NULL, prior_posterior = NULL, sensitivity = NULL, recovery = NULL, sbc = NULL, label = NULL )
fit |
Optional fitted model. |
analysis_bundle |
Optional analysis bundle. |
model_card |
Optional model card. |
loo |
Optional PSIS-LOO or LOO influence atlas. |
prior_posterior |
Optional prior-posterior bridge. |
sensitivity |
Optional sensitivity result. |
recovery |
Optional recovery result. |
sbc |
Optional SBC result. |
label |
Optional label. |
A gp3bayes_diagnostic_dashboard.
Create Diagnostic Dashboard Figures
create_diagnostic_dashboard_figures(x)create_diagnostic_dashboard_figures(x)
x |
A diagnostic dashboard. |
A gp3bayes_figure_set for supported evidence components.
Writes a conservative Markdown report for an approved fitted lognormal duration model.
create_duration_model_report( fit, diagnostics = NULL, posterior_summary = NULL, posterior_predictive = NULL, prior_sensitivity = NULL, recovery = NULL, file, overwrite = FALSE )create_duration_model_report( fit, diagnostics = NULL, posterior_summary = NULL, posterior_predictive = NULL, prior_sensitivity = NULL, recovery = NULL, file, overwrite = FALSE )
fit |
A |
diagnostics |
Optional result from |
posterior_summary |
Optional result from
|
posterior_predictive |
Optional result from
|
prior_sensitivity |
Optional result from
|
recovery |
Optional result from |
file |
Explicit output Markdown path. The caller must supply the destination; the function has no default output path. |
overwrite |
Whether an existing file may be replaced. |
A gp3bayes_duration_model_report.
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.
create_duration_unit_sensitivity_specification( specification, multiplier, new_unit )create_duration_unit_sensitivity_specification( specification, multiplier, new_unit )
specification |
An approved duration specification. |
multiplier |
Positive conversion factor from the current analysis unit to the new unit. |
new_unit |
New non-empty unit label. |
An approved duration sensitivity specification.
Create a Named Figure Set
create_figure_set(..., title = "gp3bayes figure set")create_figure_set(..., title = "gp3bayes figure set")
... |
Named plot objects. |
title |
Optional figure-set title. |
A gp3bayes_figure_set.
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) }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
create_group_deletion_sensitivity_plan( specification, group = c("participant", "item"), units = NULL, max_units = 20L )create_group_deletion_sensitivity_plan( specification, group = c("participant", "item"), units = NULL, max_units = 20L )
specification |
An approved binary or duration specification. |
group |
Either participant or item. |
units |
Optional explicit group levels. If omitted all levels are used
only when their count does not exceed |
max_units |
Maximum automatic number of omission fits. |
A gp3bayes_group_deletion_sensitivity_plan.
Create a LOO Influence Atlas
create_loo_influence_atlas(x, data = NULL, threshold = 0.7)create_loo_influence_atlas(x, data = NULL, threshold = 0.7)
x |
A gp3bayes PSIS-LOO or raw |
data |
Optional observation-level data. |
threshold |
Pareto-k threshold used for the flagged table. |
A gp3bayes_loo_influence_atlas.
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.
create_model_card(fit, analysis_bundle = NULL, manifest = NULL, label = NULL)create_model_card(fit, analysis_bundle = NULL, manifest = NULL, label = NULL)
fit |
A fitted |
analysis_bundle |
Optional |
manifest |
Optional |
label |
Optional human-readable label. |
A gp3bayes_model_card.
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.
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() )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() )
family |
Character scalar identifying the approved model family.
Supported values are |
outcome_col |
Character scalar naming the outcome column. |
participant_col |
Character scalar naming the participant identifier column. |
item_col |
Optional character scalar naming an item or stimulus identifier column. |
trial_col |
Optional character scalar naming a trial identifier column. |
condition_col |
Optional character scalar naming the focal condition column. |
time_col |
Optional character scalar naming a linear time or trial order column. This does not define a time-course or autocorrelation model. |
predictors |
Character vector naming additional predictors. |
interaction |
Optional character vector of length two naming one prespecified two-way interaction. Higher-order or multiple interactions are not supported by the initial contract. |
random_slope |
Logical scalar indicating whether one participant-level random slope for the focal condition is requested. Readiness must be assessed separately before fitting. |
outcome_unit |
Optional character scalar recording the outcome unit.
It is required for the duration family and must be |
notes |
Optional character vector containing user-supplied design or analysis notes. Notes do not override the approved model contract. |
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.
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.
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.
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_contractbinary_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
Writes an explicit Markdown inventory of available evidence components.
create_model_evidence_report(evidence, file, overwrite = FALSE)create_model_evidence_report(evidence, file, overwrite = FALSE)
evidence |
A |
file |
Explicit Markdown output path. |
overwrite |
Whether an existing file may be replaced. |
The normalized output path, invisibly.
Combines a model contract, a successful readiness audit, an approved formula, and a validated prior specification into one backend-independent model specification.
create_model_specification(contract, audit, priors)create_model_specification(contract, audit, priors)
contract |
A |
audit |
A |
priors |
A |
An object of class gp3bayes_model_specification.
Create a Prediction Contrast Profile
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) )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) )
fit |
A fitted |
variable |
Numeric profile variable. |
contrast_variable |
Variable defining two contrasted levels. |
contrast_levels |
Optional two levels. |
values |
Optional profile values. |
n |
Number of values when |
at |
Named values for other predictors. |
measure |
|
include_group_effects |
Whether group effects are included. |
ndraws |
Optional posterior draws. |
probs |
Three interval probabilities. |
A gp3bayes_prediction_contrast_profile.
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.
create_prediction_grid( x, variables = NULL, at = list(), numeric_at = c("median", "mean"), max_rows = 5000L )create_prediction_grid( x, variables = NULL, at = list(), numeric_at = c("median", "mean"), max_rows = 5000L )
x |
A gp3bayes fit or approved model specification. |
variables |
Optional variables to vary. By default the declared condition and non-identifier predictors are considered. |
at |
Named list of explicit values for selected variables. |
numeric_at |
One of |
max_rows |
Maximum permitted grid size. |
A data frame suitable for predict_model().
Create a Numeric Prediction Profile
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 )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 )
fit |
A fitted |
variable |
Numeric predictor to vary. |
values |
Optional explicit predictor values. |
n |
Number of values when |
at |
Named values holding other predictors fixed. |
type |
Prediction quantity. |
include_group_effects |
Whether group effects are included. |
allow_new_levels |
Whether new grouping levels are permitted. |
ndraws |
Optional posterior draws. |
probs |
Three interval probabilities. |
seed |
Predictive simulation seed where applicable. |
A gp3bayes_prediction_profile.
Create a Two-Dimensional Prediction Surface
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 )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 )
fit |
A fitted |
x, y
|
Numeric predictors. |
x_values, y_values
|
Optional explicit predictor values. |
n |
Values per predictor when explicit values are omitted. |
at |
Named values holding other predictors fixed. |
type |
Prediction quantity. |
include_group_effects |
Whether group effects are included. |
allow_new_levels |
Whether new grouping levels are permitted. |
ndraws |
Optional posterior draws. |
probs |
Three interval probabilities. |
seed |
Predictive simulation seed. |
max_rows |
Maximum grid rows. |
A gp3bayes_prediction_surface.
Create a Posterior-Predictive Distribution Atlas
create_predictive_distribution_atlas( fit, ndraws = 500L, include_group_effects = TRUE, seed = 1L )create_predictive_distribution_atlas( fit, ndraws = 500L, include_group_effects = TRUE, seed = 1L )
fit |
A fitted |
ndraws |
Number of posterior predictive draws. |
include_group_effects |
Whether fitted group effects are included. |
seed |
Predictive seed. |
A gp3bayes_predictive_distribution_atlas.
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.
create_predictor_scaling_sensitivity_specification( specification, predictor, scale_factor, coefficient_scale, interaction_scale = NULL )create_predictor_scaling_sensitivity_specification( specification, predictor, scale_factor, coefficient_scale, interaction_scale = NULL )
specification |
An approved model specification. |
predictor |
A declared predictor that was scaled during preparation. |
scale_factor |
New scale divided by the original recorded scale. Values above one make the transformed predictor numerically smaller. |
coefficient_scale |
Explicit population-coefficient prior scale under the alternative parameterisation. |
interaction_scale |
Optional explicit interaction prior scale when the advanced separate-interaction prior is used. |
An approved alternative specification.
Creates an inspectable prior table for one approved model family. The returned object contains no backend-specific prior objects and performs no sampling.
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 )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 )
contract |
A |
baseline |
Numeric scalar describing the expected baseline outcome.
For binary models this is a probability strictly between zero and one.
The default is |
intercept_scale |
Optional positive numeric scalar for the normal
intercept prior. Defaults to |
coefficient_scale |
Optional positive numeric scalar for normal
population-level coefficient priors. Defaults to |
group_sd_scale |
Positive numeric scalar for half-Student-t group-level standard-deviation priors. |
residual_scale |
Optional positive numeric scalar for the
half-Student-t residual standard-deviation prior. It applies only to the
duration family and defaults to |
correlation_eta |
Numeric scalar greater than or equal to one for the LKJ prior used when a participant-level random slope is requested. |
student_df |
Positive numeric scalar giving the degrees of freedom for half-Student-t scale priors. |
Binary baseline probabilities are transformed with the logit function. Duration baseline medians are transformed with the natural logarithm.
An object of class gp3bayes_prior_specification.
binary_contract <- create_model_contract( family = "binary", outcome_col = "selected", participant_col = "participant_id" ) create_prior_specification( binary_contract, baseline = 0.35 )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
create_publication_registry(label = NULL)create_publication_registry(label = NULL)
label |
Optional registry label. |
A gp3bayes_publication_registry.
Extract Publication Tables from an Analysis Bundle
create_publication_table_set(x)create_publication_table_set(x)
x |
A |
A named list of data frames suitable for downstream formatting.
The suite materializes scientifically interpretable alternative model specifications without fitting, ranking, or choosing among them.
create_pupil_advanced_sensitivity_suite( specification, include = c("likelihood", "residual_scale", "autocorrelation", "temporal", "gp_kernel") )create_pupil_advanced_sensitivity_suite( specification, include = c("likelihood", "residual_scale", "autocorrelation", "temporal", "gp_kernel") )
specification |
Baseline advanced specification. |
include |
Character subset of |
A gp3bayes_pupil_advanced_sensitivity_suite object.
Create an explicit bounded ARMA configuration
create_pupil_arma_spec(p = 1L, q = 0L, covariance = FALSE)create_pupil_arma_spec(p = 1L, q = 0L, covariance = FALSE)
p |
Autoregressive order, constrained to 0–3. |
q |
Moving-average order, constrained to 0–2. |
covariance |
Logical; request covariance-form ARMA. In gp3bayes 0.5 this is permitted only for order (1,0), (0,1), or (1,1). |
A gp3bayes_pupil_arma_spec object.
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.
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() )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() )
outcome_col |
Numeric pupil-response column to model. |
participant_col |
Participant identifier column. |
trial_col |
Trial identifier column. |
time_col |
Event-relative time column. |
pupil_unit |
One of |
sampling_frequency |
Declared nominal sampling frequency in Hz. |
time_unit |
Unit of |
item_col |
Optional item/stimulus identifier. |
condition_col |
Optional experimental condition. |
timestamp_col |
Optional absolute or recording timestamp. |
eye |
Declared channel: |
left_pupil_col, right_pupil_col
|
Optional paired pupil channels retained
only for left/right disagreement auditing. Either may equal |
channel_audit_unit |
Unit for paired audit channels; defaults to
|
validity_col, interpolation_col, blink_col
|
Optional measurement-quality indicator columns. |
gaze_x_col, gaze_y_col
|
Optional gaze-position columns. |
luminance_col, contrast_col
|
Optional visual-stimulus nuisance columns. |
screen_width, screen_height
|
Optional screen dimensions in declared
screen units; use |
baseline_window |
Optional two-element event-relative baseline window
expressed in |
baseline_method |
Declared upstream/current baseline state: |
baseline_applied |
Whether baseline correction has already been applied. |
pfe_corrected |
Whether pupil-foreshortening correction was applied upstream. |
pfe_method |
Optional description of the upstream PFE method. |
source_vendor, device_model
|
Optional source metadata. Missing metadata remain explicitly unknown. |
preprocessing_provenance |
Optional free-text provenance. |
upstream_package, upstream_version
|
Optional upstream package metadata. |
notes |
Optional user notes. |
A gp3bayes_pupil_contract.
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.
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" ) contractcontract <- 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
create_pupil_gp_spec( kernel = c("matern32", "matern52", "exp_quad"), basis = c("approximate", "exact"), k = 30L, scale = TRUE )create_pupil_gp_spec( kernel = c("matern32", "matern52", "exp_quad"), basis = c("approximate", "exact"), k = 30L, scale = TRUE )
kernel |
GP covariance kernel. |
basis |
|
k |
Number of Hilbert-space basis functions when |
scale |
Whether brms should internally scale GP predictors. |
A gp3bayes_pupil_gp_spec object.
The plan defines sequential training cut-points within a single ordered series. Execution is deliberately separate because it requires refitting.
create_pupil_lfo_plan( fit, initial_fraction = 0.6, horizon = 5L, step = 5L, max_refits = 8L )create_pupil_lfo_plan( fit, initial_fraction = 0.6, horizon = 5L, step = 5L, max_refits = 8L )
fit |
An advanced fitted model. |
initial_fraction |
Initial fraction of each series available for the earliest training set. |
horizon |
Number of future samples scored at each refit. |
step |
Number of samples by which the training cut moves. |
max_refits |
Maximum refits per model. |
A gp3bayes_pupil_lfo_plan object.
Declares known standard-error columns for pupil covariates and/or the pupil response. The object records uncertainty; it does not alter or impute data.
create_pupil_measurement_model( baseline_error = NULL, luminance_error = NULL, gaze_error = NULL, response_error = NULL, covariate_errors = NULL )create_pupil_measurement_model( baseline_error = NULL, luminance_error = NULL, gaze_error = NULL, response_error = NULL, covariate_errors = NULL )
baseline_error, luminance_error, gaze_error
|
Optional standard-error column names for common adjustment variables. |
response_error |
Optional known standard-error column for the pupil response. |
covariate_errors |
Optional named character vector mapping arbitrary covariate names to standard-error columns. |
A gp3bayes_pupil_measurement_model object.
Create a governed missingness specification
create_pupil_missingness_spec( response = c("exclude", "model"), predictors = character(), assumptions = "MAR", auxiliary_predictors = character() )create_pupil_missingness_spec( response = c("exclude", "model"), predictors = character(), assumptions = "MAR", auxiliary_predictors = character() )
response |
Either |
predictors |
Character vector of predictor columns whose missing values should be modelled jointly. |
assumptions |
Currently only |
auxiliary_predictors |
Optional fully observed columns to use in the missing-predictor submodels. |
A gp3bayes_pupil_missingness_spec object.
Create a named set of fitted pupil models
create_pupil_model_set( ..., predictive_target = c("new_trial_known_participant", "new_participant", "future_segment", "new_sample_known_trial") )create_pupil_model_set( ..., predictive_target = c("new_trial_known_participant", "new_participant", "future_segment", "new_sample_known_trial") )
... |
Fitted advanced or compatible brms-backed pupil models, or one named list of models. |
predictive_target |
Declared target for interpreting comparison. |
A gp3bayes_pupil_model_set object.
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.
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() )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() )
specification |
Baseline pupil model specification. |
baseline_windows |
List of alternative two-element baseline windows. |
baseline_window_operation |
Optional baseline transformation to pair
with |
baseline_operations |
Alternative baseline transformations. |
interpolation_policy |
|
blink_adjacent_margins |
Non-negative margins in seconds; zero means no blink-adjacent deletion. |
gaze_adjustment |
|
luminance_adjustment |
|
pfe_prepared |
Optional named list of explicitly prepared alternative pupil series (for example upstream corrected and uncorrected versions). gp3bayes does not perform PFE correction. |
smooth_basis_dimensions |
Alternative approved basis dimensions. |
autocorrelation |
Alternative |
analysis_windows |
List of declared estimand windows in canonical event-time seconds. |
A gp3bayes_pupil_sensitivity plan.
# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.
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.
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 )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 )
x |
A prepared pupil object, pupil specification, or pupil fit. |
target |
One of |
K |
Number of folds for K-fold targets. |
future_fraction |
Fraction at the end of each trial series held out for the future-segment target. |
seed |
Reproducibility seed. |
A gp3bayes_pupil_validation_plan with explicit fold/split
membership and leakage checks.
Observation-wise validation is not presented as a universal default for temporally dependent pupil samples. The declared prediction target determines the partition.
# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.
Constructs approved random-intercept and random-slope specifications from a common prepared design. No model is fitted and neither structure is selected.
create_random_slope_sensitivity_plan(specification)create_random_slope_sensitivity_plan(specification)
specification |
An approved binary or duration specification. |
A gp3bayes_random_slope_sensitivity_plan.
Create a Reporting Checklist
create_reporting_checklist(x)create_reporting_checklist(x)
x |
A fitted |
A data frame describing evidence that is available for reporting.
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.
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() )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() )
prior_scale |
Whether to run the family-specific prior-scale refit. |
powerscale |
Whether to run local power-scaling through |
psis_loo |
Whether to compute PSIS-LOO for the reference fit. |
random_slope_plan |
Optional result of
|
group_deletion_plan |
Optional result of
|
alternative_estimands |
Optional named list of already-computed estimands from coding/scaling/unit or other approved sensitivity fits. |
duration_unit |
Optional list containing |
prior_scale_args |
Named argument list passed to the family-specific prior-scale sensitivity function. |
powerscale_args |
Named argument list passed to
|
psis_args |
Named argument list passed to |
random_slope_args |
Named argument list passed to
|
group_deletion_args |
Named argument list passed to
|
A gp3bayes_sensitivity_plan.
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.
create_transformation_recipe(prepared)create_transformation_recipe(prepared)
prepared |
A binary or duration prepared object. |
A gp3bayes_transformation_recipe.
Design-Support Table
design_support_table(x)design_support_table(x)
x |
A |
The design-support component table.
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.
detect_binary_separation(x, formula = NULL, data = NULL)detect_binary_separation(x, formula = NULL, data = NULL)
x |
An approved binary specification, or a data frame when |
formula |
Optional fixed-effects binomial formula. |
data |
Optional data frame. It overrides data extracted from |
A gp3bayes_separation_screen.
Diagnose an advanced pupil fit
diagnose_advanced_pupil_fit(fit, rhat_threshold = 1.01, ess_threshold = 400)diagnose_advanced_pupil_fit(fit, rhat_threshold = 1.01, ess_threshold = 400)
fit |
An advanced pupil fit. |
rhat_threshold |
Maximum preferred R-hat. |
ess_threshold |
Minimum preferred bulk/tail ESS. |
A gp3bayes_pupil_advanced_diagnostics object.
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.
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 )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 )
fit |
A fitted |
rhat_pass |
R-hat value at or below which the component passes. |
rhat_fail |
R-hat value above which the component fails. |
ess_per_chain_pass |
Bulk or tail ESS per chain at or above which the component passes. |
ess_per_chain_fail |
Bulk or tail ESS per chain below which the component fails. |
maximum_treedepth_fraction |
Maximum fraction of post-warmup draws that may reach the configured maximum treedepth before the component fails. |
ebfmi_pass |
E-BFMI value at or above which the energy component passes. |
ebfmi_fail |
E-BFMI value below which the energy component fails. |
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.
A gp3bayes_binary_diagnostics object containing parameter,
component, and chain-level diagnostic tables.
Applies the package sampling-diagnostic contract to an approved hierarchical lognormal duration fit.
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 )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 )
fit |
A |
rhat_pass |
R-hat value at or below which the component passes. |
rhat_fail |
R-hat value above which the component fails. |
ess_per_chain_pass |
Bulk or tail ESS per chain at or above which the component passes. |
ess_per_chain_fail |
Bulk or tail ESS per chain below which the component fails. |
maximum_treedepth_fraction |
Maximum fraction of post-warmup draws that may reach the configured maximum treedepth before the component fails. |
ebfmi_pass |
E-BFMI value at or above which the energy component passes. |
ebfmi_fail |
E-BFMI value below which the energy component fails. |
The returned status reports prespecified numerical sampling thresholds. It does not automatically establish convergence or posterior adequacy.
A gp3bayes_duration_diagnostics object.
Family-neutral wrapper around diagnose_binary_fit() and
diagnose_duration_fit().
diagnose_model_fit(fit, ...)diagnose_model_fit(fit, ...)
fit |
A |
... |
Family-specific diagnostic arguments. |
A family-specific gp3bayes_sampling_diagnostics object.
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.
diagnose_pupil_fit(fit, ndraws = 200L, max_lag = 10L, max_cells = 3000000L)diagnose_pupil_fit(fit, ndraws = 200L, max_lag = 10L, max_cells = 3000000L)
fit |
Fitted pupil model. |
ndraws |
Draws used for expected-value residual summaries. |
max_lag |
Maximum residual ACF lag. |
max_cells |
Maximum draw-by-observation cells. |
A gp3bayes_pupil_diagnostics.
# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.
Diagnostic Dashboard Table
diagnostic_dashboard_table(x)diagnostic_dashboard_table(x)
x |
A diagnostic dashboard. |
Component availability and status.
Duration Probability-Integral-Transform Table
duration_pit_table(x)duration_pit_table(x)
x |
A duration posterior predictive |
Observation-level empirical posterior predictive PIT values.
Duration Prediction Scores
duration_prediction_scores(x, observed = NULL)duration_prediction_scores(x, observed = NULL)
x |
A duration prediction object or positive numeric predictions. |
observed |
Optional positive observed durations. |
A one-row table of absolute and squared prediction errors on the response and log scales.
duration_prediction_scores(c(100, 120, 90), c(110, 115, 100))duration_prediction_scores(c(100, 120, 90), c(110, 115, 100))
Duration Predictive Q-Q Table
duration_qq_table(x, probs = seq(0.05, 0.95, by = 0.05))duration_qq_table(x, probs = seq(0.05, 0.95, by = 0.05))
x |
A duration posterior predictive |
probs |
Quantile probabilities. |
A quantile-comparison table.
Duration Quantile Calibration
duration_quantile_calibration(x, quantiles = c(0.1, 0.25, 0.5, 0.75, 0.9))duration_quantile_calibration(x, quantiles = c(0.1, 0.25, 0.5, 0.75, 0.9))
x |
A duration posterior predictive |
quantiles |
Predictive quantiles to assess. |
A table comparing nominal predictive quantiles with empirical coverage below those quantiles.
Duration Tail Check
duration_tail_check(x, threshold)duration_tail_check(x, threshold)
x |
A duration posterior predictive |
threshold |
Positive duration threshold. |
A one-row table comparing observed and posterior predictive tail rates.
Estimand Sensitivity Table
estimand_sensitivity_table(x)estimand_sensitivity_table(x)
x |
A |
Alternative-versus-reference estimand summaries.
Estimate joint binocular posterior trajectories
estimate_binocular_pupil_trajectory( fit, newdata = NULL, ndraws = 500L, probability = 0.95 )estimate_binocular_pupil_trajectory( fit, newdata = NULL, ndraws = 500L, probability = 0.95 )
fit |
A binocular fit. |
newdata |
Optional prediction grid. |
ndraws |
Posterior draws. |
probability |
Central interval probability. |
A gp3bayes_binocular_pupil_trajectory object.
Dispatches to design-standardised probability contrasts for binary fits and duration estimands for positive lognormal fits.
estimate_model_estimands(fit, ...)estimate_model_estimands(fit, ...)
fit |
A |
... |
Family-specific diagnostic arguments. |
A gp3bayes_estimand.
Estimate area under a declared pupil-response window
estimate_pupil_auc(prediction, window, probability = 0.95)estimate_pupil_auc(prediction, window, probability = 0.95)
prediction |
A pupil prediction object. |
window |
Prespecified event-relative time window. |
probability |
Credible probability. |
A pupil estimand. AUC units are pupil-unit times time-unit.
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))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))
The contrast is evaluated pointwise on an explicitly supplied posterior trajectory (or its derivative). No favorable time window is selected.
estimate_pupil_dynamic_contrast( prediction, contrast, threshold = 0, probability = 0.95 )estimate_pupil_dynamic_contrast( prediction, contrast, threshold = 0, probability = 0.95 )
prediction |
An advanced trajectory or derivative object. |
contrast |
Character vector of exactly two condition levels: first minus second. |
threshold |
Prespecified scientifically meaningful contrast threshold. |
probability |
Central posterior interval probability. |
A gp3bayes_pupil_dynamic_contrast object.
Estimate posterior peak pupil response inside a declared window
estimate_pupil_peak(prediction, window, probability = 0.95)estimate_pupil_peak(prediction, window, probability = 0.95)
prediction |
A pupil prediction object. |
window |
Prespecified event-relative time window. |
probability |
Credible probability. |
A pupil estimand with posterior uncertainty in the peak.
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))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
estimate_pupil_peak_latency(prediction, window, probability = 0.95)estimate_pupil_peak_latency(prediction, window, probability = 0.95)
prediction |
A pupil prediction object. |
window |
Prespecified event-relative time window. |
probability |
Credible probability. |
A pupil estimand with posterior uncertainty in peak latency.
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))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
estimate_pupil_residual_scale( fit, newdata = NULL, ndraws = 500L, probability = 0.95 )estimate_pupil_residual_scale( fit, newdata = NULL, ndraws = 500L, probability = 0.95 )
fit |
An advanced fit. |
newdata |
Optional prediction data. |
ndraws |
Number of posterior draws. |
probability |
Central interval probability. |
A gp3bayes_pupil_residual_scale object.
Estimate nonlinear response-shape parameters
estimate_pupil_response_parameters(fit, probability = 0.95)estimate_pupil_response_parameters(fit, probability = 0.95)
fit |
A response-shape fit. |
probability |
Central interval probability. |
A gp3bayes_pupil_response_parameters object.
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.
estimate_pupil_threshold_duration( contrast, direction = c("above", "below", "absolute"), threshold = contrast$threshold, probability = 0.95 )estimate_pupil_threshold_duration( contrast, direction = c("above", "below", "absolute"), threshold = contrast$threshold, probability = 0.95 )
contrast |
A dynamic-contrast object. |
direction |
|
threshold |
Optional threshold overriding the contrast's stored threshold. |
probability |
Central interval probability. |
A gp3bayes_pupil_threshold_duration object.
Summarises a finite, declared prediction grid with pointwise or grid-wise simultaneous posterior bands.
estimate_pupil_trajectory( prediction, probability = 0.95, interval = c("pointwise", "simultaneous") )estimate_pupil_trajectory( prediction, probability = 0.95, interval = c("pointwise", "simultaneous") )
prediction |
A |
probability |
Credible probability. |
interval |
|
A gp3bayes_pupil_trajectory.
"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.
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)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)
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.
estimate_pupil_trajectory_derivative( prediction, order = 1L, probability = 0.95 )estimate_pupil_trajectory_derivative( prediction, order = 1L, probability = 0.95 )
prediction |
A |
order |
Derivative order, 1 (velocity/slope) or 2 (acceleration/curvature). |
probability |
Central posterior interval probability. |
A gp3bayes_pupil_trajectory_derivative object.
Estimate a declared-window mean pupil response
estimate_pupil_window(prediction, window, probability = 0.95)estimate_pupil_window(prediction, window, probability = 0.95)
prediction |
A pupil prediction object. |
window |
Prespecified event-relative time window. |
probability |
Credible probability. |
A gp3bayes_pupil_estimand.
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))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))
Estimates participant-level response probabilities with a conjugate Beta-Binomial model while preserving the conventional amplitude-threshold non-responder flag. Low-reactive participants are retained so hard exclusion can be evaluated as a sensitivity specification rather than preprocessing.
estimate_scr_responsivity_bayes( participant, amplitude, threshold = 0.02, prior_alpha = 1, prior_beta = 1, probability_cutoff = 0.5 )estimate_scr_responsivity_bayes( participant, amplitude, threshold = 0.02, prior_alpha = 1, prior_beta = 1, probability_cutoff = 0.5 )
participant |
Participant identifiers. |
amplitude |
Trial-level SCR amplitudes. |
threshold |
Conventional response threshold in microsiemens. |
prior_alpha, prior_beta
|
Positive Beta prior parameters. |
probability_cutoff |
Optional posterior-probability cutoff used only for descriptive classification. |
A data frame with posterior responsivity parameters and flags.
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.
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 )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 )
fit |
An approved gp3bayes duration fit. |
target_data |
Optional target covariate distribution. |
target_scale |
Whether supplied target data are raw or prepared. |
predictive_quantile |
Predictive quantile probability. |
ndraws |
Optional number of posterior draws. |
include_group_effects |
Whether group-level effects are included. |
seed |
Seed used for posterior predictive draws. |
A gp3bayes_estimand.
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.
estimate_standardized_probability_contrast( fit, target_data = NULL, target_scale = c("prepared", "raw"), ndraws = NULL, include_group_effects = FALSE )estimate_standardized_probability_contrast( fit, target_data = NULL, target_scale = c("prepared", "raw"), ndraws = NULL, include_group_effects = FALSE )
fit |
An approved gp3bayes binary fit. |
target_data |
Optional target covariate distribution. |
target_scale |
Whether supplied target data are raw or already prepared. |
ndraws |
Optional number of posterior draws. |
include_group_effects |
Whether recorded group-level effects are
included. The default |
A gp3bayes_estimand with probability-difference draws.
Evaluate a Pathological Simulation Against the Contract Gate
evaluate_pathological_simulation(x)evaluate_pathological_simulation(x)
x |
A |
A gp3bayes_pathology_evaluation.
Evidence Inventory Table
evidence_inventory_table(x)evidence_inventory_table(x)
x |
A |
Inventory metadata.
Extract Expected Posterior Predictions
extract_expected_predictions( fit, newdata = NULL, include_group_effects = FALSE, allow_new_levels = FALSE, ndraws = NULL )extract_expected_predictions( fit, newdata = NULL, include_group_effects = FALSE, allow_new_levels = FALSE, ndraws = NULL )
fit |
A fitted |
newdata |
Optional data frame. |
include_group_effects |
Whether fitted group-level effects are included. |
allow_new_levels |
Whether new grouping levels are permitted by brms. |
ndraws |
Optional number of posterior draws. |
A numeric matrix of conditional expected-response draws.
Extract Linear-Predictor Draws
extract_linear_predictions( fit, newdata = NULL, include_group_effects = FALSE, allow_new_levels = FALSE, ndraws = NULL )extract_linear_predictions( fit, newdata = NULL, include_group_effects = FALSE, allow_new_levels = FALSE, ndraws = NULL )
fit |
A fitted |
newdata |
Optional data frame. |
include_group_effects |
Whether fitted group-level effects are included. |
allow_new_levels |
Whether new grouping levels are permitted by brms. |
ndraws |
Optional number of posterior draws. |
A numeric matrix on the model linear-predictor scale.
Extract Pointwise Log-Likelihood Draws
extract_log_likelihood( fit, newdata = NULL, include_group_effects = TRUE, ndraws = NULL )extract_log_likelihood( fit, newdata = NULL, include_group_effects = TRUE, ndraws = NULL )
fit |
A fitted |
newdata |
Optional prediction data. |
include_group_effects |
Whether fitted group-level effects are included. |
ndraws |
Optional number of posterior draws. |
A numeric matrix with posterior draws in rows and observations in columns.
Converts the fitted brms posterior into a standard posterior draws
representation without changing the fitted model.
extract_posterior_draws( fit, variables = NULL, regex = NULL, format = c("array", "matrix", "df", "rvars") )extract_posterior_draws( fit, variables = NULL, regex = NULL, format = c("array", "matrix", "df", "rvars") )
fit |
A fitted |
variables |
Optional exact posterior variable names. |
regex |
Optional regular expression used to retain posterior variables. |
format |
One of |
A posterior draws object in the requested format.
Extract Posterior Predictive Draws
extract_posterior_predictions( fit, newdata = NULL, include_group_effects = FALSE, allow_new_levels = FALSE, ndraws = NULL, seed = 1L )extract_posterior_predictions( fit, newdata = NULL, include_group_effects = FALSE, allow_new_levels = FALSE, ndraws = NULL, seed = 1L )
fit |
A fitted |
newdata |
Optional data frame. |
include_group_effects |
Whether fitted group-level effects are included. |
allow_new_levels |
Whether new grouping levels are permitted by brms. |
ndraws |
Optional number of posterior draws. |
seed |
Non-negative seed used for posterior predictive simulation. |
A numeric matrix of new-outcome posterior predictive draws.
Extract NUTS Sampler Diagnostics
extract_sampler_diagnostics(fit)extract_sampler_diagnostics(fit)
fit |
A fitted |
A data frame returned from brms::nuts_params().
Fit an advanced pupil model using rstan
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 )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 )
specification |
An advanced pupil specification. |
chains, iter, warmup, cores, seed, adapt_delta, max_treedepth, refresh
|
Restricted MCMC controls. |
Fit an advanced pupil model through an approved brms backend
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 )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 )
specification |
An advanced pupil specification. |
backend |
|
chains, iter, warmup, cores, seed, adapt_delta, max_treedepth, refresh
|
Restricted MCMC controls. |
A gp3bayes_pupil_advanced_fit object.
Fit an advanced pupil model using cmdstanr
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 )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 )
specification |
An advanced pupil specification. |
chains, iter, warmup, cores, seed, adapt_delta, max_treedepth, refresh
|
Restricted MCMC controls. |
Fits an approved binary model specification using full MCMC sampling through
the fixed brms and rstan route.
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 )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 )
specification |
A |
chains |
Number of MCMC chains. |
iter |
Total iterations per chain, including warmup. |
warmup |
Warmup iterations per chain. |
cores |
Number of processor cores. It cannot exceed |
seed |
Non-negative integer random-number seed. |
adapt_delta |
Target acceptance probability for the No-U-Turn sampler. |
max_treedepth |
Maximum tree depth for the No-U-Turn sampler. |
refresh |
Console progress refresh interval. Use zero to suppress iteration progress output. |
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.
A gp3bayes_binary_fit containing the fitted backend object,
original specification, restricted translation, and recorded sampling
settings.
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 ) }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 ) }
The formula and family remain contract-restricted. The only selectable implementation detail is whether brms delegates full MCMC sampling to rstan or CmdStanR.
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 )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 )
specification |
An approved binary model specification. |
backend |
Either |
chains |
Number of chains. |
iter |
Total iterations per chain. |
warmup |
Warmup iterations per chain. |
cores |
Number of cores, not exceeding chains. |
seed |
Non-negative integer seed. |
adapt_delta |
NUTS target acceptance probability. |
max_treedepth |
NUTS maximum tree depth. |
refresh |
Progress refresh interval. |
A gp3bayes_backend_portable_fit.
Fit a joint binocular pupil model
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 )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 )
specification |
A binocular specification. |
backend |
rstan or cmdstanr. |
chains, iter, warmup, cores, seed, adapt_delta, max_treedepth, refresh
|
Restricted sampling controls. |
Fits an approved strictly positive uncensored duration model using full MCMC
through the fixed brms and rstan route.
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 )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 )
specification |
A |
chains |
Number of MCMC chains. |
iter |
Total iterations per chain. |
warmup |
Warmup iterations per chain. |
cores |
Processor cores, not exceeding |
seed |
Non-negative integer seed. |
adapt_delta |
Target NUTS acceptance probability. |
max_treedepth |
Maximum NUTS tree depth. |
refresh |
Console progress refresh interval. |
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.
A gp3bayes_duration_fit.
Fit a Duration Model with a Selected Full-MCMC Backend
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 )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 )
specification |
An approved duration model specification. |
backend |
Either |
chains |
Number of chains. |
iter |
Total iterations per chain. |
warmup |
Warmup iterations per chain. |
cores |
Number of cores, not exceeding chains. |
seed |
Non-negative integer seed. |
adapt_delta |
NUTS target acceptance probability. |
max_treedepth |
NUTS maximum tree depth. |
refresh |
Progress refresh interval. |
A gp3bayes_backend_portable_fit.
Fit a pupil model through the fixed rstan route
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 )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 )
specification |
Approved pupil model specification. |
chains, iter, warmup, cores, seed
|
Sampling controls. Package-controlled cores are capped at two. |
adapt_delta, max_treedepth, refresh
|
Fixed safe sampling controls. |
A gp3bayes_pupil_fit.
# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.
Fits only a specify_pupil_timecourse_model() specification through
brms using full MCMC sampling and either rstan or cmdstanr.
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 )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 )
specification |
Approved pupil model specification. |
backend |
|
chains, iter, warmup, cores, seed
|
Sampling controls. Package-controlled cores are capped at two. |
adapt_delta, max_treedepth, refresh
|
Fixed safe sampling controls. |
A gp3bayes_pupil_fit.
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.
# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.
Fit a pupil model through the fixed cmdstanr route
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 )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 )
specification |
Approved pupil model specification. |
chains, iter, warmup, cores, seed
|
Sampling controls. Package-controlled cores are capped at two. |
adapt_delta, max_treedepth, refresh
|
Fixed safe sampling controls. |
A gp3bayes_pupil_fit.
# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.
Fit the experimental nonlinear response-shape model
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 )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 )
specification |
A response-shape specification. |
backend |
rstan or cmdstanr. |
chains, iter, warmup, cores, seed, adapt_delta, max_treedepth, refresh
|
Restricted sampling controls. |
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.
freeze_analysis_manifest(manifest, file = NULL, overwrite = FALSE)freeze_analysis_manifest(manifest, file = NULL, overwrite = FALSE)
manifest |
A valid analysis manifest. |
file |
Optional explicit |
overwrite |
Whether an existing explicit output file may be replaced. |
A frozen gp3bayes_analysis_manifest.
Marks a captured schema as frozen and optionally writes it to an explicit
RDS path. When file = NULL, no file is written.
freeze_gp3bayes_schema(schema, file = NULL, overwrite = FALSE)freeze_gp3bayes_schema(schema, file = NULL, overwrite = FALSE)
schema |
A captured schema or gp3bayes object. |
file |
Optional explicit |
overwrite |
Whether an existing file may be replaced. |
The frozen schema, invisibly when written.
Return the Gazepoint pupil mapping audit table
gazepoint_pupil_mapping_table(x)gazepoint_pupil_mapping_table(x)
x |
A result from |
A data frame with documented fields, roles, units, eye, and presence.
# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.
Returns an auditable mapping between the Phase-0 closure requirements and their first-class implementation points.
gp3bayes_specification_traceability()gp3bayes_specification_traceability()
A data frame.
Group-Deletion Sensitivity Table
group_deletion_sensitivity_table(x)group_deletion_sensitivity_table(x)
x |
A |
Omitted-unit estimand summaries.
Group-Level Posterior Draw Table
group_effect_draws_table( fit, groups = NULL, coefficients = NULL, ndraws = NULL, seed = 1L, max_rows = 1000000L )group_effect_draws_table( fit, groups = NULL, coefficients = NULL, ndraws = NULL, seed = 1L, max_rows = 1000000L )
fit |
A fitted |
groups |
Optional grouping factors. |
coefficients |
Optional group-level coefficients. |
ndraws |
Optional number of draws retained. |
seed |
Seed used only for draw subsampling. |
max_rows |
Maximum permitted long-format rows. |
A long posterior draw table on the model linear-predictor scale.
Group-Level Rank-Probability Table
group_effect_rank_probability_table( fit, group, coefficient = "Intercept", ndraws = 1000L, seed = 1L )group_effect_rank_probability_table( fit, group, coefficient = "Intercept", ndraws = 1000L, seed = 1L )
fit |
A fitted |
group |
One grouping-factor name. |
coefficient |
One group-level coefficient. |
ndraws |
Number of posterior draws. |
seed |
Draw-subsampling seed. |
Descriptive posterior rank probabilities. Rank 1 is the largest group-level deviation.
Group-Level Effect Table
group_effect_table(fit, groups = NULL, probs = c(0.025, 0.975))group_effect_table(fit, groups = NULL, probs = c(0.025, 0.975))
fit |
A fitted |
groups |
Optional grouping factors to retain. |
probs |
Lower and upper credible interval probabilities. |
A tidy data frame of estimated group-level deviations.
Aggregates posterior prediction draws over one or more columns already present in the prediction data.
group_prediction_summary(x, by, probs = c(0.025, 0.5, 0.975))group_prediction_summary(x, by, probs = c(0.025, 0.5, 0.975))
x |
A |
by |
Character vector naming grouping columns in |
probs |
Three probabilities for group-level posterior intervals. |
A group-level posterior prediction table.
Grouped Posterior Predictive Check
grouped_prediction_check( fit, group, ndraws = 1000L, probs = c(0.025, 0.5, 0.975), seed = 1L )grouped_prediction_check( fit, group, ndraws = 1000L, probs = c(0.025, 0.5, 0.975), seed = 1L )
fit |
A fitted |
group |
Name of a grouping column in the prepared model data. |
ndraws |
Number of posterior predictive draws. |
probs |
Posterior interval probabilities. |
seed |
Non-negative seed. |
A gp3bayes_group_prediction_check.
Applies conservative heuristics to declared numeric predictors. A flagged predictor is a review signal only; explicit declaration in a contract is never silently overridden.
identify_identifier_like_predictors( data, contract, unique_fraction = 0.9, integer_fraction = 0.98, monotone_correlation = 0.98 )identify_identifier_like_predictors( data, contract, unique_fraction = 0.9, integer_fraction = 0.98, monotone_correlation = 0.98 )
data |
A data frame. |
contract |
An approved model contract. |
unique_fraction |
Fraction of rows that must be unique before a predictor can be considered identifier-like. |
integer_fraction |
Fraction of finite values that must be integer-like. |
monotone_correlation |
Absolute correlation with row order used as a heuristic for sequence-like identifiers. |
A gp3bayes_identifier_predictor_audit object.
Identify Influential PSIS-LOO Observations
identify_loo_influential_observations(x, threshold = NULL, data = NULL)identify_loo_influential_observations(x, threshold = NULL, data = NULL)
x |
A |
threshold |
Optional explicit Pareto-k threshold. |
data |
Optional observation-level data to append. |
A data frame of flagged observations.
Identify MCMC Diagnostic Flags
identify_mcmc_issues( x, rhat_threshold = 1.01, min_bulk_ess = 400, min_tail_ess = 400, max_mcse_fraction = 0.1 )identify_mcmc_issues( x, rhat_threshold = 1.01, min_bulk_ess = 400, min_tail_ess = 400, max_mcse_fraction = 0.1 )
x |
A fitted gp3bayes object or an MCMC diagnostic table. |
rhat_threshold |
R-hat value above which a parameter is flagged. |
min_bulk_ess |
Minimum bulk effective sample size. |
min_tail_ess |
Minimum tail effective sample size. |
max_mcse_fraction |
Maximum MCSE-to-posterior-SD fraction. |
A parameter-level flag table. Flags request review; they do not establish or negate model adequacy.
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)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)
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.
inspect_gazepoint_pupil_schema(data)inspect_gazepoint_pupil_schema(data)
data |
A data frame containing a Gazepoint export or API record table. |
LPD and RPD are documented pixel diameters. LPUPILD and
RPUPILD are documented in metres. These scales are intentionally kept
distinct.
A gp3bayes_gazepoint_pupil_schema with detected fields,
pupil-channel candidates, and an audit table.
Recognition is schema evidence only. The function does not establish device validity, select an eye, convert units, correct PFE, or infer preprocessing history.
x <- data.frame(TIME = 0:2 / 60, LPD = c(32, 33, 31), LPV = 1) inspect_gazepoint_pupil_schema(x)x <- data.frame(TIME = 0:2 / 60, LPD = c(32, 33, 31), LPV = 1) inspect_gazepoint_pupil_schema(x)
Summarise Separate Interaction Prior Metadata
interaction_prior_summary(specification)interaction_prior_summary(specification)
specification |
An advanced binary or duration specification. |
A one-row data frame.
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.
invert_transformation_recipe(data, recipe)invert_transformation_recipe(data, recipe)
data |
Prepared-scale data. |
recipe |
A transformation recipe or prepared object. |
A raw-scale data frame.
LOO Diagnostic Table
loo_diagnostic_table(x)loo_diagnostic_table(x)
x |
A |
Observation-level Pareto-k diagnostics.
Flagged LOO Observation Data
loo_flagged_data(x, threshold = 0.7)loo_flagged_data(x, threshold = 0.7)
x |
A LOO object or pointwise table. |
threshold |
Explicit Pareto-k threshold. |
Rows meeting the requested threshold.
Aggregate LOO Influence by a Declared Group
loo_group_influence_table(x, group, data = NULL)loo_group_influence_table(x, group, data = NULL)
x |
A LOO influence atlas, pointwise LOO table, gp3bayes PSIS-LOO, or
raw |
group |
Grouping-column name. |
data |
Optional observation-level data when needed. |
A descriptive group-level influence table.
LOO Influence Atlas Table
loo_influence_atlas_table(x)loo_influence_atlas_table(x)
x |
A |
The complete pointwise atlas table.
LOO Influence Summary
loo_influence_summary(x)loo_influence_summary(x)
x |
A LOO object or pointwise LOO table. |
A one-row influence summary.
Pointwise LOO Table
loo_pointwise_table(x, data = NULL)loo_pointwise_table(x, data = NULL)
x |
A gp3bayes PSIS-LOO or raw |
data |
Optional observation-level data with matching rows. |
Pointwise LOO estimates and Pareto-k diagnostics.
LOO Summary Table
loo_summary_table(x)loo_summary_table(x)
x |
A |
A tidy table of LOO estimates and standard errors.
Manifest-Comparison Table
manifest_comparison_table(x)manifest_comparison_table(x)
x |
A |
Manifest component comparisons.
Materialize one advanced sensitivity scenario
materialize_pupil_advanced_sensitivity_scenario(suite, scenario)materialize_pupil_advanced_sensitivity_scenario(suite, scenario)
suite |
A sensitivity suite. |
scenario |
Scenario name from |
An advanced pupil specification.
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.
materialize_pupil_sensitivity_scenario(suite, scenario_id)materialize_pupil_sensitivity_scenario(suite, scenario_id)
suite |
Pupil sensitivity suite. |
scenario_id |
Scenario identifier from |
A list containing the materialized specification and/or declared estimand window.
# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.
Computes rank-normalised R-hat, bulk ESS, tail ESS, and Monte Carlo standard
error summaries through the posterior package.
mcmc_diagnostic_table(fit, variables = NULL, regex = NULL)mcmc_diagnostic_table(fit, variables = NULL, regex = NULL)
fit |
A fitted |
variables |
Optional exact posterior variable names. |
regex |
Optional posterior-variable regular expression. |
A data frame with posterior diagnostics by variable.
Missingness-Audit Table
missingness_audit_table(x)missingness_audit_table(x)
x |
A |
Column-level missingness diagnostics.
Model-Card Evidence Table
model_card_table(x)model_card_table(x)
x |
A |
The model-card evidence inventory.
LOO Model-Comparison Table
model_comparison_table(x)model_comparison_table(x)
x |
A |
A data frame retaining ELPD differences and their standard errors.
Model-Evidence Table
model_evidence_table(x)model_evidence_table(x)
x |
A |
The model-evidence inventory table.
LOO Model-Weight Table
model_weights_table(x)model_weights_table(x)
x |
A |
A data frame of model weights. The table does not select a model.
Creates an inspectable stage map for a gp3bayes object. Stage completion is descriptive only and is not an adequacy or validity declaration.
model_workflow_status(x)model_workflow_status(x)
x |
A gp3bayes contract, prepared object, specification, fit, or evidence object. |
A gp3bayes_workflow_status data frame.
Contract-first Bayesian multilevel mediation workflows for trial-level behavioural and gaze-derived data prepared under an explicit upstream multilevel mediation contract. The API supports simple, serial, and moderated mediation specifications, restricted Bayesian fitting, diagnostics, posterior estimands, predictive checks, comparison guards, simulation, plotting, and conservative reporting.
create_mediation_prior_specification( intercept_sd = 2.5, coefficient_sd = 1, group_sd_scale = 1, residual_sd_scale = 1, dispersion_rate = 1, beta_precision_rate = 0.1 ) specify_multilevel_gaze_mediation( prepared, mediator_family = "gaussian", outcome_family = "bernoulli", priors = create_mediation_prior_specification(), random_slopes = "mediator_x", missingness_policy = "error" ) fit_multilevel_gaze_mediation( prepared, mediator_family = "gaussian", outcome_family = "bernoulli", priors = create_mediation_prior_specification(), random_slopes = "mediator_x", missingness_policy = "error", chains = 4, iter = 2000, warmup = 1000, cores = min(chains, 2L), seed = 1, adapt_delta = 0.95, max_treedepth = 12, backend = c("cmdstanr", "rstan"), refresh = 0 ) check_mediation_convergence( fit, rhat_max = 1.01, ess_bulk_min = 400, divergences_max = 0L, treedepth_hits_max = 0L ) prior_predictive_check_mediation(specification, ndraws = 200, seed = 1) posterior_predictive_check_mediation(fit, ndraws = 200) estimate_indirect_effect( fit, level = c("within", "between"), ... ) estimate_within_indirect_effect(fit, ...) estimate_between_indirect_effect(fit, ...) posterior_indirect_effect( fit, level = c("within", "between"), probability = 0.95, require_convergence = TRUE ) posterior_direct_effect( fit, level = c("within", "between"), probability = 0.95, require_convergence = TRUE ) posterior_total_effect( fit, level = c("within", "between"), probability = 0.95, require_convergence = TRUE ) summarise_multilevel_mediation( fit, probability = 0.95, require_convergence = TRUE ) plot_indirect_effect_distribution( fit, level = c("within", "between"), probability = 0.95, require_convergence = TRUE ) plot_mediation_posteriors( fit, probability = 0.95, require_convergence = TRUE ) plot_participant_mediation_effects(fit) compare_multilevel_mediation_models(...) report_multilevel_gaze_mediation( fit, probability = 0.95, require_convergence = TRUE ) simulate_multilevel_gaze_mediation( n_participants = 100L, trials_per_participant = 20L, a_within = 0.7, b_within = 0.8, cprime_within = 0.2, a_between = 0.2, b_between = 0.3, seed = 2026L ) specify_multilevel_serial_gaze_mediation( prepared, mediator2_family = "gaussian", mediator_family = "gaussian", outcome_family = "bernoulli", priors = create_mediation_prior_specification(), random_slopes = character(), missingness_policy = "error" ) fit_multilevel_serial_gaze_mediation( prepared, mediator2_family = "gaussian", mediator_family = "gaussian", outcome_family = "bernoulli", priors = create_mediation_prior_specification(), random_slopes = character(), missingness_policy = "error", chains = 4, iter = 2000, warmup = 1000, cores = min(chains, 2L), seed = 1, adapt_delta = 0.95, max_treedepth = 12, backend = c("cmdstanr", "rstan"), refresh = 0 ) posterior_serial_indirect_effect( fit, level = c("within", "between"), probability = 0.95, require_convergence = TRUE ) specify_multilevel_moderated_gaze_mediation( prepared, moderation_path = c("a", "b"), moderator_component = c("within", "between"), mediator_family = "gaussian", outcome_family = "bernoulli", priors = create_mediation_prior_specification(), random_slopes = character(), missingness_policy = "error" ) fit_multilevel_moderated_gaze_mediation( prepared, moderation_path = c("a", "b"), moderator_component = c("within", "between"), mediator_family = "gaussian", outcome_family = "bernoulli", priors = create_mediation_prior_specification(), random_slopes = character(), missingness_policy = "error", chains = 4, iter = 2000, warmup = 1000, cores = min(chains, 2L), seed = 1, adapt_delta = 0.95, max_treedepth = 12, backend = c("cmdstanr", "rstan"), refresh = 0 ) posterior_conditional_indirect_effect( fit, moderator_value, probability = 0.95, require_convergence = TRUE )create_mediation_prior_specification( intercept_sd = 2.5, coefficient_sd = 1, group_sd_scale = 1, residual_sd_scale = 1, dispersion_rate = 1, beta_precision_rate = 0.1 ) specify_multilevel_gaze_mediation( prepared, mediator_family = "gaussian", outcome_family = "bernoulli", priors = create_mediation_prior_specification(), random_slopes = "mediator_x", missingness_policy = "error" ) fit_multilevel_gaze_mediation( prepared, mediator_family = "gaussian", outcome_family = "bernoulli", priors = create_mediation_prior_specification(), random_slopes = "mediator_x", missingness_policy = "error", chains = 4, iter = 2000, warmup = 1000, cores = min(chains, 2L), seed = 1, adapt_delta = 0.95, max_treedepth = 12, backend = c("cmdstanr", "rstan"), refresh = 0 ) check_mediation_convergence( fit, rhat_max = 1.01, ess_bulk_min = 400, divergences_max = 0L, treedepth_hits_max = 0L ) prior_predictive_check_mediation(specification, ndraws = 200, seed = 1) posterior_predictive_check_mediation(fit, ndraws = 200) estimate_indirect_effect( fit, level = c("within", "between"), ... ) estimate_within_indirect_effect(fit, ...) estimate_between_indirect_effect(fit, ...) posterior_indirect_effect( fit, level = c("within", "between"), probability = 0.95, require_convergence = TRUE ) posterior_direct_effect( fit, level = c("within", "between"), probability = 0.95, require_convergence = TRUE ) posterior_total_effect( fit, level = c("within", "between"), probability = 0.95, require_convergence = TRUE ) summarise_multilevel_mediation( fit, probability = 0.95, require_convergence = TRUE ) plot_indirect_effect_distribution( fit, level = c("within", "between"), probability = 0.95, require_convergence = TRUE ) plot_mediation_posteriors( fit, probability = 0.95, require_convergence = TRUE ) plot_participant_mediation_effects(fit) compare_multilevel_mediation_models(...) report_multilevel_gaze_mediation( fit, probability = 0.95, require_convergence = TRUE ) simulate_multilevel_gaze_mediation( n_participants = 100L, trials_per_participant = 20L, a_within = 0.7, b_within = 0.8, cprime_within = 0.2, a_between = 0.2, b_between = 0.3, seed = 2026L ) specify_multilevel_serial_gaze_mediation( prepared, mediator2_family = "gaussian", mediator_family = "gaussian", outcome_family = "bernoulli", priors = create_mediation_prior_specification(), random_slopes = character(), missingness_policy = "error" ) fit_multilevel_serial_gaze_mediation( prepared, mediator2_family = "gaussian", mediator_family = "gaussian", outcome_family = "bernoulli", priors = create_mediation_prior_specification(), random_slopes = character(), missingness_policy = "error", chains = 4, iter = 2000, warmup = 1000, cores = min(chains, 2L), seed = 1, adapt_delta = 0.95, max_treedepth = 12, backend = c("cmdstanr", "rstan"), refresh = 0 ) posterior_serial_indirect_effect( fit, level = c("within", "between"), probability = 0.95, require_convergence = TRUE ) specify_multilevel_moderated_gaze_mediation( prepared, moderation_path = c("a", "b"), moderator_component = c("within", "between"), mediator_family = "gaussian", outcome_family = "bernoulli", priors = create_mediation_prior_specification(), random_slopes = character(), missingness_policy = "error" ) fit_multilevel_moderated_gaze_mediation( prepared, moderation_path = c("a", "b"), moderator_component = c("within", "between"), mediator_family = "gaussian", outcome_family = "bernoulli", priors = create_mediation_prior_specification(), random_slopes = character(), missingness_policy = "error", chains = 4, iter = 2000, warmup = 1000, cores = min(chains, 2L), seed = 1, adapt_delta = 0.95, max_treedepth = 12, backend = c("cmdstanr", "rstan"), refresh = 0 ) posterior_conditional_indirect_effect( fit, moderator_value, probability = 0.95, require_convergence = TRUE )
prepared |
A canonical trial-level multilevel mediation preparation object,
inheriting from |
mediator_family |
Observation family for the primary mediator. Supported families are governed by the mediation specification contract. |
mediator2_family |
Observation family for the second mediator in a serial mediation specification. |
outcome_family |
Observation family for the outcome under the governed mediation contract. |
priors |
A mediation prior specification created by
|
random_slopes |
Character vector declaring supported participant-level random slopes. Requested slopes must be estimable from the observed data. |
missingness_policy |
Explicit missingness and eligibility policy. No observations are silently reclassified or imputed by these functions. |
intercept_sd, coefficient_sd, group_sd_scale, residual_sd_scale
|
Positive scales controlling the corresponding prior distributions. |
dispersion_rate |
Positive rate used for governed dispersion priors when applicable. |
beta_precision_rate |
Positive rate used for the beta-family precision prior when applicable. |
chains |
Number of MCMC chains. |
iter |
Total iterations per chain. |
warmup |
Warmup iterations per chain. |
cores |
Number of processor cores used for fitting. |
seed |
Non-negative random seed used for deterministic simulation or fitting. |
adapt_delta |
Target acceptance probability supplied to the Bayesian sampler. |
max_treedepth |
Maximum sampler tree depth. |
backend |
Restricted |
refresh |
Sampler progress refresh interval. |
fit |
A fitted |
rhat_max |
Maximum accepted R-hat threshold for the convergence audit. |
ess_bulk_min |
Minimum accepted bulk effective sample size. |
divergences_max |
Maximum accepted number of divergent transitions. |
treedepth_hits_max |
Maximum accepted number of maximum-treedepth hits. |
specification |
A governed multilevel mediation specification object. |
ndraws |
Number of predictive draws requested for the predictive check. |
level |
Whether the requested estimand is within- or between-participant. |
probability |
Posterior interval probability. |
require_convergence |
If |
... |
For model comparison, fitted mediation objects to compare. For the convenience indirect-effect wrappers, additional arguments forwarded to the corresponding posterior estimand function. |
n_participants |
Number of participants generated by the simulator. |
trials_per_participant |
Number of simulated trials per participant. |
a_within, b_within, cprime_within
|
Declared within-participant simulation path coefficients. |
a_between, b_between
|
Declared between-participant simulation path coefficients. |
moderation_path |
Path on which moderation is declared, restricted to the supported mediation paths. |
moderator_component |
Whether moderation is represented by the within- or between-participant component of the declared moderator. |
moderator_value |
Moderator value at which the conditional indirect effect is evaluated. |
These functions implement a contract-first Bayesian mediation layer for repeated-measures data. The package does not silently perform the upstream within/between decomposition, resolve quality exclusions, impute missing observations, or broaden the requested random-effects structure.
Simple mediation separates within- and between-participant paths when supported by the prepared data. Serial and moderated specifications are available through explicitly named APIs rather than automatic model search.
Posterior products involving non-Gaussian mediator or outcome models are defined on the model's linear-predictor scale unless a function explicitly states otherwise. They must not be interpreted automatically as probability- scale, risk-ratio, causal, physiological, or cognitive effects.
compare_multilevel_mediation_models() requires competing fitted
models to contain the same mediator/outcome observations in the same
participant-trial order. Fits based on different missingness or exclusion
sets are rejected before PSIS-LOO comparison.
Convergence, predictive checks, posterior intervals, and sensitivity summaries remain separate pieces of evidence. None automatically establish model adequacy, robustness, causality, or substantive importance.
Depending on the function, a mediation prior specification, model specification, fitted model wrapper, convergence audit, predictive-check object, posterior estimand summary, simulation object, publication-oriented summary, report, model comparison, or plot is returned. Returned objects retain the model specification and relevant provenance where applicable.
estimate_scr_responsivity_bayes
## Not run: # Trial-level data must first be prepared under the upstream # multilevel mediation contract. priors <- create_mediation_prior_specification() ## End(Not run)## Not run: # Trial-level data must first be prepared under the upstream # multilevel mediation contract. priors <- create_mediation_prior_specification() ## End(Not run)
Plot simulated advanced pupil trajectories
plot_advanced_pupil_simulation(x, observed = TRUE, ...)plot_advanced_pupil_simulation(x, observed = TRUE, ...)
x |
An advanced pupil simulation. |
observed |
If TRUE, plot observed condition means; otherwise plot stored latent means. |
... |
Additional graphical arguments. |
Plot an advanced posterior pupil trajectory
plot_advanced_pupil_trajectory(x, probability = 0.95, ...)plot_advanced_pupil_trajectory(x, probability = 0.95, ...)
x |
An advanced trajectory prediction. |
probability |
Central interval probability. |
... |
Additional graphical arguments. |
Autocorrelation Diagnostic Plot
plot_autocorrelation(fit, variables = NULL, regex = "^b_", lags = 20L)plot_autocorrelation(fit, variables = NULL, regex = "^b_", lags = 20L)
fit |
A fitted |
variables |
Optional posterior variables. |
regex |
Optional posterior-variable regular expression. |
lags |
Maximum autocorrelation lag. |
A ggplot object.
Plot Backend Environment Checks with ggplot2
plot_backend_environment_gg(x)plot_backend_environment_gg(x)
x |
A |
A ggplot.
Plot Backend Parity with ggplot2
plot_backend_parity_gg(x)plot_backend_parity_gg(x)
x |
A |
A ggplot.
Binary Calibration Plot
plot_binary_calibration(x, bins = 10L)plot_binary_calibration(x, bins = 10L)
x |
A binary calibration table or binary expected prediction. |
bins |
Number of bins if |
A ggplot object.
Plot Binary Calibration Uncertainty
plot_binary_calibration_uncertainty(x)plot_binary_calibration_uncertainty(x)
x |
A binary calibration-uncertainty object or table. |
A ggplot.
Grouped Binary Calibration Plot
plot_binary_group_calibration(x, group = NULL)plot_binary_group_calibration(x, group = NULL)
x |
Grouped calibration table or binary expected prediction. |
group |
Grouping-column name when |
A ggplot.
Binary Precision-Recall Plot
plot_binary_precision_recall(x, observed = NULL)plot_binary_precision_recall(x, observed = NULL)
x |
A precision-recall table, binary expected prediction, or numeric probabilities. |
observed |
Optional observed outcomes for numeric probabilities. |
A ggplot.
Binary ROC Plot
plot_binary_roc(x, observed = NULL)plot_binary_roc(x, observed = NULL)
x |
A ROC table, binary expected prediction, or numeric probabilities. |
observed |
Optional observed outcomes for numeric probabilities. |
A ggplot.
Binary Threshold-Metric Plot
plot_binary_threshold_metrics( x, observed = NULL, thresholds = seq(0.1, 0.9, by = 0.05) )plot_binary_threshold_metrics( x, observed = NULL, thresholds = seq(0.1, 0.9, by = 0.05) )
x |
Threshold-metric table, binary expected prediction, or numeric probabilities. |
observed |
Optional observed outcomes for numeric predictions. |
thresholds |
Thresholds to evaluate when |
A ggplot object.
Plot binocular posterior trajectories
plot_binocular_pupil_trajectory(x, probability = x$probability, ...)plot_binocular_pupil_trajectory(x, probability = x$probability, ...)
x |
A binocular trajectory. |
probability |
Central interval probability. |
... |
Additional graphical arguments. |
Plot Design-Support Components with ggplot2
plot_design_support_gg(x)plot_design_support_gg(x)
x |
A |
A ggplot.
Plot Diagnostic Dashboard Availability
plot_diagnostic_dashboard(x)plot_diagnostic_dashboard(x)
x |
A diagnostic dashboard. |
A ggplot.
Duration PIT Plot
plot_duration_pit(x, bins = 10L)plot_duration_pit(x, bins = 10L)
x |
A duration PIT table or duration posterior predictive object. |
bins |
Number of histogram bins. |
A ggplot object.
Duration Predictive Q-Q Plot
plot_duration_qq(x)plot_duration_qq(x)
x |
A duration Q-Q table or duration posterior predictive object. |
A ggplot.
Duration Quantile-Calibration Plot
plot_duration_quantile_calibration(x)plot_duration_quantile_calibration(x)
x |
A duration quantile-calibration table or duration predictive object. |
A ggplot object.
Duration Tail-Check Plot
plot_duration_tail(x)plot_duration_tail(x)
x |
A duration tail-check table. |
A ggplot.
Estimand Interval Plot
plot_estimand_intervals(x, quantities = NULL, probs = c(0.025, 0.5, 0.975))plot_estimand_intervals(x, quantities = NULL, probs = c(0.025, 0.5, 0.975))
x |
A |
quantities |
Optional estimand quantities. |
probs |
Posterior interval probabilities. |
A ggplot object.
Plot Estimand Sensitivity with ggplot2
plot_estimand_sensitivity_gg(x)plot_estimand_sensitivity_gg(x)
x |
An estimand-sensitivity object or its table. |
A ggplot.
Prediction Exceedance-Probability Plot
plot_exceedance_probability(x)plot_exceedance_probability(x)
x |
A table returned by |
A ggplot object.
Plot Group-Deletion Sensitivity
plot_group_deletion_sensitivity(x)plot_group_deletion_sensitivity(x)
x |
A group-deletion object or summary table. |
A ggplot.
Plot Group-Effect Posterior Distributions
plot_group_effect_distribution(x, max_levels = 20L)plot_group_effect_distribution(x, max_levels = 20L)
x |
A table returned by |
max_levels |
Maximum displayed grouping levels. |
A faceted ggplot.
Plot Group-Effect Rank Probabilities
plot_group_effect_rank_probability(x)plot_group_effect_rank_probability(x)
x |
A rank-probability table. |
A ggplot.
Group-Effect Plot
plot_group_effects(x, groups = NULL)plot_group_effects(x, groups = NULL)
x |
A group-effect table or fitted gp3bayes object. |
groups |
Optional grouping factors when |
A faceted ggplot object.
Group Prediction Plot
plot_group_predictions(x, group_column)plot_group_predictions(x, group_column)
x |
A group prediction summary. |
group_column |
Name of the grouping column to use on the axis. |
A ggplot.
Grouped Posterior Predictive Plot
plot_grouped_prediction_check(x)plot_grouped_prediction_check(x)
x |
A |
A ggplot object.
Plot Grouped Pointwise ELPD Contribution
plot_loo_group_elpd(x)plot_loo_group_elpd(x)
x |
A grouped LOO influence table. |
A ggplot.
Plot Grouped LOO Influence
plot_loo_group_influence(x)plot_loo_group_influence(x)
x |
A grouped LOO influence table. |
A ggplot.
LOO Influence Plot
plot_loo_influence(x)plot_loo_influence(x)
x |
A gp3bayes PSIS-LOO object, |
A ggplot object.
Plot Ranked LOO Influence
plot_loo_influence_rank(x)plot_loo_influence_rank(x)
x |
A LOO object or pointwise table. |
A ggplot.
Plot Pareto-k versus Pointwise ELPD
plot_loo_pareto_vs_elpd(x)plot_loo_pareto_vs_elpd(x)
x |
A LOO object or pointwise table. |
A ggplot.
Plot Pointwise LOO ELPD
plot_loo_pointwise_elpd(x)plot_loo_pointwise_elpd(x)
x |
A LOO object or pointwise table. |
A ggplot.
Plot Manifest Differences with ggplot2
plot_manifest_comparison_gg(x)plot_manifest_comparison_gg(x)
x |
A |
A ggplot.
MCMC Review-Flag Plot
plot_mcmc_quality(x)plot_mcmc_quality(x)
x |
A fitted gp3bayes object or |
A ggplot showing parameter-level review flags.
Plot Missingness Fractions with ggplot2
plot_missingness_gg(x)plot_missingness_gg(x)
x |
A |
A ggplot.
LOO Model-Comparison Plot
plot_model_comparison(x)plot_model_comparison(x)
x |
A gp3bayes LOO comparison or comparison table. |
A ggplot object.
Plot Model-Evidence Availability with ggplot2
plot_model_evidence_gg(x)plot_model_evidence_gg(x)
x |
A |
A ggplot.
LOO Model-Weight Plot
plot_model_weights(x)plot_model_weights(x)
x |
A gp3bayes LOO weight object or weight table. |
A ggplot object.
Posterior Area Plot
plot_posterior_areas( x, variables = NULL, regex = NULL, prob = 0.5, prob_outer = 0.95 )plot_posterior_areas( x, variables = NULL, regex = NULL, prob = 0.5, prob_outer = 0.95 )
x |
A gp3bayes fit or posterior draws accepted by
|
variables, regex
|
Posterior variable selectors. |
prob |
Inner interval probability. |
prob_outer |
Outer interval probability. |
A ggplot object.
Posterior Correlation Plot
plot_posterior_correlations( x, variables = NULL, regex = NULL, method = c("pearson", "spearman") )plot_posterior_correlations( x, variables = NULL, regex = NULL, method = c("pearson", "spearman") )
x |
A gp3bayes fit or posterior draws. |
variables, regex
|
Posterior variable selectors. |
method |
Correlation method. |
A ggplot heatmap of posterior-draw correlations.
Posterior Density Plot
plot_posterior_density(x, variables = NULL, regex = NULL)plot_posterior_density(x, variables = NULL, regex = NULL)
x |
A gp3bayes fit or posterior draws. |
variables, regex
|
Posterior variable selectors. |
A ggplot object.
Posterior Interval Plot
plot_posterior_intervals( x, variables = NULL, regex = NULL, prob = 0.8, prob_outer = 0.95 )plot_posterior_intervals( x, variables = NULL, regex = NULL, prob = 0.8, prob_outer = 0.95 )
x |
A gp3bayes fit or posterior draws accepted by
|
variables, regex
|
Posterior variable selectors. |
prob |
Inner interval probability. |
prob_outer |
Outer interval probability. |
A ggplot object.
Posterior Pairs Plot
plot_posterior_pairs(fit, variables = NULL, regex = "^b_", max_variables = 8L)plot_posterior_pairs(fit, variables = NULL, regex = "^b_", max_variables = 8L)
fit |
A fitted |
variables |
Optional variables. |
regex |
Optional variable regular expression. |
max_variables |
Maximum number of variables displayed. |
A bayesplot pairs object.
Plot Power-Scale Sensitivity with ggplot2
plot_powerscale_sensitivity_gg(x)plot_powerscale_sensitivity_gg(x)
x |
A power-scale sensitivity object or its table. |
A ggplot.
Posterior Predictive Statistic Plot
plot_ppc_statistic(x, bins = 30L)plot_ppc_statistic(x, bins = 30L)
x |
A |
bins |
Histogram bins. |
A ggplot.
Plot a Prediction Contrast Profile
plot_prediction_contrast_profile(x)plot_prediction_contrast_profile(x)
x |
A prediction contrast profile. |
A ggplot.
Prediction-Draw Distribution Plot
plot_prediction_draws(x, observations = NULL, max_draws = 500L)plot_prediction_draws(x, observations = NULL, max_draws = 500L)
x |
A |
observations |
Optional prediction-row indices. |
max_draws |
Maximum posterior draws displayed. |
A ggplot.
Plot Prediction-Profile Gradients
plot_prediction_gradient(x)plot_prediction_gradient(x)
x |
A prediction profile or gradient table. |
A ggplot.
Prediction Interval-Width Plot
plot_prediction_interval_width(x)plot_prediction_interval_width(x)
x |
A prediction object or interval-width table. |
A ggplot.
Prediction-Interval Plot
plot_prediction_intervals(x, max_rows = 100L)plot_prediction_intervals(x, max_rows = 100L)
x |
A |
max_rows |
Maximum rows displayed. |
A ggplot object.
Plot a Prediction Profile
plot_prediction_profile(x)plot_prediction_profile(x)
x |
A prediction profile. |
A ggplot.
Prediction Rank-Probability Plot
plot_prediction_rank_probabilities(x)plot_prediction_rank_probabilities(x)
x |
A ranking-probability table. |
A ggplot.
Plot Prediction Score Uncertainty
plot_prediction_score_uncertainty(x)plot_prediction_score_uncertainty(x)
x |
A score-uncertainty object. |
A faceted ggplot.
Prediction-Support Plot
plot_prediction_support(x)plot_prediction_support(x)
x |
A prediction-support audit or its table. |
A ggplot object.
Plot a Prediction Surface
plot_prediction_surface(x)plot_prediction_surface(x)
x |
A prediction surface. |
A ggplot.
Plot Prediction-Surface Uncertainty
plot_prediction_surface_uncertainty(x)plot_prediction_surface_uncertainty(x)
x |
A prediction surface. |
A ggplot.
Plot Predictive Atlas Statistics
plot_predictive_atlas_statistics(x)plot_predictive_atlas_statistics(x)
x |
A predictive distribution atlas. |
A faceted ggplot.
Predictive-Coverage Plot
plot_predictive_coverage(x)plot_predictive_coverage(x)
x |
Predictive coverage table or posterior predictive object. |
A ggplot object.
Plot Posterior-Predictive Quantile Envelope
plot_predictive_quantile_envelope(x)plot_predictive_quantile_envelope(x)
x |
A quantile-envelope table. |
A ggplot.
Predictive-Residual Plot
plot_predictive_residuals(x)plot_predictive_residuals(x)
x |
Residual table returned by |
A ggplot object.
Plot Prior-to-Posterior Contraction
plot_prior_posterior_contraction(x)plot_prior_posterior_contraction(x)
x |
A prior-posterior bridge. |
A ggplot.
Plot Declared Prior and Posterior Densities
plot_prior_posterior_density(x, max_draws = 1000L)plot_prior_posterior_density(x, max_draws = 1000L)
x |
A prior-posterior bridge. |
max_draws |
Maximum draws displayed per distribution. |
A faceted ggplot.
Plot Prior and Posterior Intervals
plot_prior_posterior_intervals(x)plot_prior_posterior_intervals(x)
x |
A prior-posterior bridge. |
A faceted ggplot.
Plot Prior-to-Posterior Location Shift
plot_prior_posterior_shift(x)plot_prior_posterior_shift(x)
x |
A prior-posterior bridge. |
A ggplot.
Plot Prior-Scale Sensitivity
plot_prior_sensitivity(x)plot_prior_sensitivity(x)
x |
A prior-sensitivity object or comparison table. |
A faceted ggplot.
Plot Prior-Sensitivity Scenario Maxima
plot_prior_sensitivity_scenarios(x)plot_prior_sensitivity_scenarios(x)
x |
A prior-sensitivity object or scenario table. |
A ggplot.
Plot residual autocorrelation comparison
plot_pupil_autocorrelation_comparison(x, absolute = TRUE, ...)plot_pupil_autocorrelation_comparison(x, absolute = TRUE, ...)
x |
An autocorrelation comparison object. |
absolute |
Plot median absolute ACF if TRUE. |
... |
Additional graphical arguments. |
Plot a dynamic pupil condition contrast
plot_pupil_dynamic_contrast(x, ...)plot_pupil_dynamic_contrast(x, ...)
x |
A dynamic contrast. |
... |
Additional base graphics arguments. |
Plot declared-window pupil estimands
plot_pupil_estimand(x)plot_pupil_estimand(x)
x |
Pupil estimand object. |
A ggplot object.
# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.
Plot Gaussian-process hyperparameters
plot_pupil_gp_hyperparameters(x, ...)plot_pupil_gp_hyperparameters(x, ...)
x |
A GP-hyperparameter object. |
... |
Additional graphical arguments. |
Plot advanced identifiability/design-support audit
plot_pupil_identifiability_audit(x, ...)plot_pupil_identifiability_audit(x, ...)
x |
An identifiability audit. |
... |
Additional graphical arguments. |
Plot leave-future-out scores
plot_pupil_lfo(x, ...)plot_pupil_lfo(x, ...)
x |
An executed LFO validation or LFO comparison. |
... |
Additional graphical arguments. |
Plot gaze/PFE and luminance measurement-context evidence
plot_pupil_measurement_audit(x)plot_pupil_measurement_audit(x)
x |
A pupil measurement audit. |
A ggplot object.
# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.
Plot measurement-uncertainty audit
plot_pupil_measurement_uncertainty(x, ...)plot_pupil_measurement_uncertainty(x, ...)
x |
A measurement audit. |
... |
Additional graphical arguments. |
Plot missing-response fraction over time
plot_pupil_missingness(x, ...)plot_pupil_missingness(x, ...)
x |
A missingness audit. |
... |
Additional graphical arguments. |
Plot predictive model comparison
plot_pupil_model_comparison(x, ...)plot_pupil_model_comparison(x, ...)
x |
A model-comparison object. |
... |
Additional graphical arguments. |
Plot advanced model computational complexity
plot_pupil_model_complexity(x, ...)plot_pupil_model_complexity(x, ...)
x |
A complexity audit or advanced specification. |
... |
Additional graphical arguments. |
Plot observed pupil trajectories
plot_pupil_observed_trajectory(x, summary = TRUE)plot_pupil_observed_trajectory(x, summary = TRUE)
x |
Prepared pupil object. |
summary |
Whether to plot condition means rather than individual participant-trial traces. |
A ggplot object.
# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.
Plot posterior pupil trajectories or condition differences
plot_pupil_posterior_trajectory(x)plot_pupil_posterior_trajectory(x)
x |
Pupil trajectory or condition-contrast object. |
A ggplot object.
# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.
Uses one consolidated plotting interface for trajectory, residual, feature, autocorrelation, heterogeneity, or measurement-context PPC evidence.
plot_pupil_ppc( x, component = c("trajectory", "residuals", "features", "autocorrelation", "heterogeneity", "measurement_context") )plot_pupil_ppc( x, component = c("trajectory", "residuals", "features", "autocorrelation", "heterogeneity", "measurement_context") )
x |
Pupil PPC object. |
component |
Evidence component to plot. |
A ggplot object.
# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.
Plot posterior predictive calibration
plot_pupil_predictive_calibration(x, ...)plot_pupil_predictive_calibration(x, ...)
x |
A predictive score/calibration object. |
... |
Additional graphical arguments. |
Plot pupil readiness evidence
plot_pupil_readiness(x)plot_pupil_readiness(x)
x |
Pupil readiness audit. |
A ggplot object.
# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.
Plot pupil residual autocorrelation
plot_pupil_residual_acf(x)plot_pupil_residual_acf(x)
x |
Pupil diagnostics object or residual ACF table. |
A ggplot object.
# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.
Plot posterior residual scale over time
plot_pupil_residual_scale(x, ...)plot_pupil_residual_scale(x, ...)
x |
A residual-scale estimand. |
... |
Additional graphical arguments. |
Plot residual spectrum
plot_pupil_residual_spectrum(x, ...)plot_pupil_residual_spectrum(x, ...)
x |
A residual-spectrum object. |
... |
Additional graphical arguments. |
Plot experimental nonlinear response parameters
plot_pupil_response_parameters(x, ...)plot_pupil_response_parameters(x, ...)
x |
A response-parameter object. |
... |
Additional graphical arguments. |
Plot pupil sensitivity scenarios or result comparisons
plot_pupil_sensitivity(x)plot_pupil_sensitivity(x)
x |
Pupil sensitivity suite or comparison. |
A ggplot object.
# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.
Plot empirical temporal-dependence audit
plot_pupil_temporal_dependence(x, ...)plot_pupil_temporal_dependence(x, ...)
x |
A temporal-dependence audit. |
... |
Additional graphical arguments. |
Plot posterior pupil trajectory derivative
plot_pupil_trajectory_derivative(x, probability = x$probability, ...)plot_pupil_trajectory_derivative(x, probability = x$probability, ...)
x |
A trajectory-derivative object. |
probability |
Central posterior interval probability. |
... |
Additional graphical arguments. |
Plot pupil validation evidence
plot_pupil_validation(x)plot_pupil_validation(x)
x |
Pupil validation object. |
A ggplot object.
# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.
Plot Random-Intercept Variance Partition
plot_random_intercept_variance_partition(x)plot_random_intercept_variance_partition(x)
x |
A variance-partition object or table. |
A ggplot.
Plot Random-Slope Sensitivity
plot_random_slope_sensitivity(x)plot_random_slope_sensitivity(x)
x |
A random-slope sensitivity object or estimand-sensitivity table. |
A ggplot.
Rank-Diagnostic Plot
plot_rank_diagnostics(fit, variables = NULL, regex = "^b_")plot_rank_diagnostics(fit, variables = NULL, regex = "^b_")
fit |
A fitted |
variables |
Optional posterior variables. |
regex |
Optional posterior-variable regular expression. |
A ggplot rank-overlay diagnostic.
Plot Recovery Standardized Bias
plot_recovery_bias(x)plot_recovery_bias(x)
x |
A recovery object or recovery parameter table. |
A ggplot.
Plot Recovery Coverage
plot_recovery_coverage(x)plot_recovery_coverage(x)
x |
A recovery object or recovery parameter table. |
A ggplot.
Plot Repetition-Level Recovery Estimates
plot_recovery_estimates(x, variables = NULL)plot_recovery_estimates(x, variables = NULL)
x |
A recovery object or repetition-level estimate table. |
variables |
Optional variables to retain. |
A faceted ggplot.
Plot Recovery Fit Status
plot_recovery_fit_status(x)plot_recovery_fit_status(x)
x |
A recovery object or fit-status table. |
A ggplot.
Plot Recovery RMSE
plot_recovery_rmse(x)plot_recovery_rmse(x)
x |
A recovery object or recovery parameter table. |
A ggplot.
Plot a Reporting Checklist
plot_reporting_checklist(x)plot_reporting_checklist(x)
x |
A reporting checklist, fit, or model card. |
A ggplot.
Sampler-Diagnostic Plot
plot_sampler_diagnostics(fit)plot_sampler_diagnostics(fit)
fit |
A fitted |
A ggplot of sampler metrics relative to review thresholds.
Produces trace, energy, treedepth, or divergence plots for an approved
fitted gp3bayes model.
plot_sampling_diagnostics( fit, type = c("trace", "energy", "treedepth", "divergence"), variables = NULL )plot_sampling_diagnostics( fit, type = c("trace", "energy", "treedepth", "divergence"), variables = NULL )
fit |
A fitted |
type |
One of |
variables |
Optional posterior parameter names used for trace plots. |
Diagnostic plots support interpretation of sampling behaviour. They do not establish convergence or substantive model adequacy by themselves.
A plot object created by bayesplot.
SBC Coverage Plot
plot_sbc_coverage_gg(x, variables = NULL, ...)plot_sbc_coverage_gg(x, variables = NULL, ...)
x |
A |
variables |
Optional variables. |
... |
Arguments passed to SBC. |
A plot object returned by SBC.
SBC ECDF-Difference Plot
plot_sbc_ecdf_gg(x, variables = NULL, ...)plot_sbc_ecdf_gg(x, variables = NULL, ...)
x |
A |
variables |
Optional variables. |
... |
Arguments passed to SBC. |
A plot object returned by SBC.
SBC Rank-Histogram Plot
plot_sbc_rank_gg(x, variables = NULL, ...)plot_sbc_rank_gg(x, variables = NULL, ...)
x |
A |
variables |
Optional variables. |
... |
Arguments passed to SBC. |
A plot object returned by SBC.
SBC Simulated-versus-Estimated Plot
plot_sbc_simulated_vs_estimated_gg(x, variables = NULL, ...)plot_sbc_simulated_vs_estimated_gg(x, variables = NULL, ...)
x |
A |
variables |
Optional variables. |
... |
Arguments passed to SBC. |
A plot object returned by SBC.
Plot Schema Differences with ggplot2
plot_schema_comparison_gg(x)plot_schema_comparison_gg(x)
x |
A |
A ggplot.
Plot a Sensitivity Suite with ggplot2
plot_sensitivity_suite_gg(x)plot_sensitivity_suite_gg(x)
x |
A |
A ggplot.
Prediction-Uncertainty Plot
plot_uncertainty_decomposition(x, max_rows = 100L)plot_uncertainty_decomposition(x, max_rows = 100L)
x |
A |
max_rows |
Maximum observations displayed. |
A ggplot object.
Variance-Component Plot
plot_variance_components(x)plot_variance_components(x)
x |
A variance-component table or fitted gp3bayes object. |
A ggplot object.
Delegates plotting to the LOO-compatible object returned by brms::kfold().
## S3 method for class 'gp3bayes_kfold_cv' plot(x, ...)## S3 method for class 'gp3bayes_kfold_cv' plot(x, ...)
x |
A |
... |
Arguments passed to the underlying plot method. |
x, invisibly.
Plot a Strict Readiness Audit
## S3 method for class 'gp3bayes_strict_readiness_audit' plot(x, type = c("status", "condition", "duration_extremes"), ...)## S3 method for class 'gp3bayes_strict_readiness_audit' plot(x, type = c("status", "condition", "duration_extremes"), ...)
x |
A |
type |
One of |
... |
Additional base-graphics arguments. |
x, invisibly.
Posterior Correlation Table
posterior_correlation_table( x, variables = NULL, regex = NULL, method = c("pearson", "spearman") )posterior_correlation_table( x, variables = NULL, regex = NULL, method = c("pearson", "spearman") )
x |
A gp3bayes fit or posterior draws accepted by
|
variables, regex
|
Posterior variable selectors. |
method |
Correlation method. |
A long data frame of unique posterior-draw correlations.
x <- cbind(a = rnorm(100), b = rnorm(100), c = rnorm(100)) posterior_correlation_table(x)x <- cbind(a = rnorm(100), b = rnorm(100), c = rnorm(100)) posterior_correlation_table(x)
Posterior Interval Table
posterior_interval_table( x, variables = NULL, regex = NULL, probs = c(0.025, 0.5, 0.975) )posterior_interval_table( x, variables = NULL, regex = NULL, probs = c(0.025, 0.5, 0.975) )
x |
A gp3bayes fit, posterior draws object, numeric matrix, or numeric data frame. |
variables |
Optional exact posterior variable names. |
regex |
Optional regular expression for posterior variable names. |
probs |
Three probabilities defining lower, median, and upper summaries. |
A data frame containing posterior location, spread, and intervals.
draws <- cbind(alpha = rnorm(200), beta = rnorm(200, 0.5)) posterior_interval_table(draws)draws <- cbind(alpha = rnorm(200), beta = rnorm(200, 0.5)) posterior_interval_table(draws)
Computes one scalar discrepancy statistic for every posterior predictive draw and compares that distribution with the same statistic in the observed data. The returned probability is descriptive and is not an automatic model verdict.
posterior_predictive_statistic( x, statistic = c("mean", "sd", "median", "q90", "q95", "max", "tail_rate"), threshold = NULL )posterior_predictive_statistic( x, statistic = c("mean", "sd", "median", "q90", "q95", "max", "tail_rate"), threshold = NULL )
x |
A posterior predictive |
statistic |
Built-in statistic: |
threshold |
Required for |
A gp3bayes_ppc_statistic object.
Posterior Predictive Summary Table
posterior_predictive_summary_table(x, probs = c(0.025, 0.5, 0.975))posterior_predictive_summary_table(x, probs = c(0.025, 0.5, 0.975))
x |
A posterior predictive |
probs |
Three summary probabilities. |
Observation-level predictive summaries.
Posterior Direction and ROPE Probability Table
posterior_probability_table(x, variables = NULL, regex = NULL, rope = NULL)posterior_probability_table(x, variables = NULL, regex = NULL, rope = NULL)
x |
A gp3bayes fit or posterior draws accepted by
|
variables, regex
|
Posterior variable selectors. |
rope |
Optional two-element interval defining a region of practical equivalence. It is descriptive only. |
A data frame with posterior direction probabilities and, when requested, the posterior probability inside the supplied interval.
draws <- cbind(alpha = rnorm(500), beta = rnorm(500, 0.4)) posterior_probability_table(draws, rope = c(-0.1, 0.1))draws <- cbind(alpha = rnorm(500), beta = rnorm(500, 0.4)) posterior_probability_table(draws, rope = c(-0.1, 0.1))
Power-Scale Sensitivity Table
powerscale_sensitivity_table(x)powerscale_sensitivity_table(x)
x |
A |
The tabular representation provided by priorsense.
Create a Power-Scaling Sequence
powerscale_sequence_for_fit( fit, variable = NULL, prior_selection = NULL, likelihood_selection = NULL, component = "both" )powerscale_sequence_for_fit( fit, variable = NULL, prior_selection = NULL, likelihood_selection = NULL, component = "both" )
fit |
A gp3bayes fit or |
variable |
Optional posterior variables to inspect. |
prior_selection |
Optional tagged priors to perturb. |
likelihood_selection |
Optional likelihood subset. |
component |
Either prior, likelihood, or both, as supported by priorsense. |
A priorsense powerscaled sequence.
Posterior Predictive Statistic Table
ppc_statistic_table(x)ppc_statistic_table(x)
x |
A |
A one-row data frame.
Predict an advanced pupil trajectory
predict_advanced_pupil_trajectory( fit, newdata = NULL, type = c("expected", "posterior_predictive", "linear"), ndraws = 500L, population_only = TRUE, allow_new_levels = FALSE, max_grid = 5000L )predict_advanced_pupil_trajectory( fit, newdata = NULL, type = c("expected", "posterior_predictive", "linear"), ndraws = 500L, population_only = TRUE, allow_new_levels = FALSE, max_grid = 5000L )
fit |
A fitted advanced pupil model. |
newdata |
Optional prediction data. If omitted, a population-level time-by-condition grid is generated with covariates held at reference values. |
type |
|
ndraws |
Number of posterior draws. |
population_only |
Exclude group-level effects when TRUE. |
allow_new_levels |
Passed to brms prediction methods. |
max_grid |
Maximum generated grid size. |
A gp3bayes_pupil_advanced_trajectory object.
Binary Event-Probability Predictions
predict_binary_probability( fit, newdata = NULL, include_group_effects = FALSE, allow_new_levels = FALSE, ndraws = NULL, probs = c(0.025, 0.5, 0.975) )predict_binary_probability( fit, newdata = NULL, include_group_effects = FALSE, allow_new_levels = FALSE, ndraws = NULL, probs = c(0.025, 0.5, 0.975) )
fit |
A fitted |
newdata |
Optional data frame. |
include_group_effects |
Whether fitted group-level effects are included. |
allow_new_levels |
Whether new grouping levels are permitted by brms. |
ndraws |
Optional number of posterior draws. |
probs |
Three probabilities used to summarise predictions. |
A gp3bayes_prediction of event probabilities.
Duration Predictions
predict_duration( fit, newdata = NULL, type = c("median", "expected", "predictive"), include_group_effects = FALSE, allow_new_levels = FALSE, ndraws = NULL, probs = c(0.025, 0.5, 0.975), seed = 1L )predict_duration( fit, newdata = NULL, type = c("median", "expected", "predictive"), include_group_effects = FALSE, allow_new_levels = FALSE, ndraws = NULL, probs = c(0.025, 0.5, 0.975), seed = 1L )
fit |
A fitted |
newdata |
Optional data frame. |
type |
One of |
include_group_effects |
Whether fitted group-level effects are included. |
allow_new_levels |
Whether new grouping levels are permitted by brms. |
ndraws |
Optional number of posterior draws. |
probs |
Three probabilities used to summarise predictions. |
seed |
Non-negative seed used for posterior predictive simulation. |
A gp3bayes_prediction on the recorded duration scale.
Distinguishes conditional expectations, new-outcome posterior predictions, linear-predictor draws, and the conditional median for lognormal duration models.
predict_model( fit, newdata = NULL, 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 )predict_model( fit, newdata = NULL, 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 )
fit |
A fitted |
newdata |
Optional data frame. |
type |
Prediction quantity: |
include_group_effects |
Whether fitted group-level effects are included. |
allow_new_levels |
Whether new grouping levels are permitted by brms. |
ndraws |
Optional number of posterior draws. |
probs |
Three probabilities used to summarise predictions. |
seed |
Non-negative seed used for posterior predictive simulation. |
A gp3bayes_prediction containing draws, summaries, prediction data,
and interpretation metadata.
Obtains expected, posterior-predictive, or linear-predictor draws from an approved pupil fit with explicit draw and grid-size guards.
predict_pupil_trajectory( fit, newdata = NULL, type = c("expected", "posterior_predictive", "linear"), ndraws = 500L, population_only = TRUE, allow_new_levels = FALSE, max_grid = 5000L, max_cells = 5000000L )predict_pupil_trajectory( fit, newdata = NULL, type = c("expected", "posterior_predictive", "linear"), ndraws = 500L, population_only = TRUE, allow_new_levels = FALSE, max_grid = 5000L, max_cells = 5000000L )
fit |
A |
newdata |
Optional prepared prediction grid. When omitted, a compact
population grid is built from observed event times and conditions.
Participant-conditioned prediction requires explicit |
type |
|
ndraws |
Maximum posterior draws to retain. |
population_only |
If |
allow_new_levels |
Passed conservatively to brms prediction methods. |
max_grid |
Maximum grid rows. |
max_cells |
Maximum draw-by-grid cells. |
A gp3bayes_pupil_prediction.
# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.
Posterior Prediction Contrast
prediction_contrast( x, row1, row2, measure = c("difference", "ratio", "odds_ratio"), probs = c(0.025, 0.5, 0.975) )prediction_contrast( x, row1, row2, measure = c("difference", "ratio", "odds_ratio"), probs = c(0.025, 0.5, 0.975) )
x |
A |
row1, row2
|
Two prediction rows to compare. |
measure |
|
probs |
Posterior interval probabilities. |
A one-row posterior contrast summary.
Prediction Contrast Profile Table
prediction_contrast_profile_table(x)prediction_contrast_profile_table(x)
x |
A prediction contrast profile. |
Contrast summaries.
Convert Prediction Draws to Long Form
prediction_draws_long(x, max_draws = NULL, seed = 1L)prediction_draws_long(x, max_draws = NULL, seed = 1L)
x |
A |
max_draws |
Optional maximum number of posterior draws retained. |
seed |
Non-negative integer used only if draws are subsampled. |
A long data frame with draw, observation, and predicted value.
Posterior Exceedance Probabilities
prediction_exceedance_probability( x, threshold, direction = c("above", "below") )prediction_exceedance_probability( x, threshold, direction = c("above", "below") )
x |
A |
threshold |
Finite response-scale threshold. |
direction |
Whether to evaluate values above or below the threshold. |
Observation-level posterior exceedance probabilities.
Prediction-Profile Gradient Table
prediction_gradient_table(x, probs = c(0.025, 0.5, 0.975))prediction_gradient_table(x, probs = c(0.025, 0.5, 0.975))
x |
A prediction profile. |
probs |
Three interval probabilities. |
Finite-difference posterior predictive gradients.
Prediction Interval Width Table
prediction_interval_width(x)prediction_interval_width(x)
x |
A |
A table of posterior interval width by prediction row.
Pairwise Prediction Contrasts
prediction_pairwise_contrasts( x, rows = NULL, measure = c("difference", "ratio"), max_rows = 20L, probs = c(0.025, 0.5, 0.975) )prediction_pairwise_contrasts( x, rows = NULL, measure = c("difference", "ratio"), max_rows = 20L, probs = c(0.025, 0.5, 0.975) )
x |
A |
rows |
Optional prediction-row indices. At most |
measure |
Difference or ratio. |
max_rows |
Maximum number of prediction rows allowed. |
probs |
Three posterior interval probabilities. |
A data frame containing every unique pairwise contrast.
Prediction Profile Table
prediction_profile_table(x)prediction_profile_table(x)
x |
A prediction profile. |
Profile summaries.
Summarises relative ordering among a small, explicitly supplied set of prediction rows. No row is automatically selected or declared superior.
prediction_rank_probabilities( x, rows = NULL, direction = c("higher", "lower"), max_rows = 20L )prediction_rank_probabilities( x, rows = NULL, direction = c("higher", "lower"), max_rows = 20L )
x |
A |
rows |
Optional prediction rows. |
direction |
Whether larger or smaller values receive rank 1. |
max_rows |
Maximum rows that may be ranked. |
A descriptive ranking-probability table.
Binary fits use Brier and logarithmic scores; duration fits use RMSE and MAE.
prediction_score_uncertainty( fit, newdata = NULL, include_group_effects = FALSE, ndraws = 1000L, probs = c(0.025, 0.5, 0.975) )prediction_score_uncertainty( fit, newdata = NULL, include_group_effects = FALSE, ndraws = 1000L, probs = c(0.025, 0.5, 0.975) )
fit |
A fitted |
newdata |
Optional data containing observed outcomes. |
include_group_effects |
Whether fitted group effects are included. |
ndraws |
Expected-response posterior draws. |
probs |
Three interval probabilities. |
A gp3bayes_prediction_score_uncertainty.
Prediction Score-Uncertainty Table
prediction_score_uncertainty_table(x)prediction_score_uncertainty_table(x)
x |
A prediction-score uncertainty object. |
Metric summaries.
Prediction-Support Table
prediction_support_table(x)prediction_support_table(x)
x |
A |
The underlying support audit table.
Prediction Surface Table
prediction_surface_table(x)prediction_surface_table(x)
x |
A prediction surface. |
Surface summaries.
Prediction Summary Table
prediction_table(x)prediction_table(x)
x |
A |
The observation-level posterior prediction summary.
Separates variability in conditional expected-response draws from total posterior predictive variability. The difference is a descriptive Monte Carlo decomposition and is not a causal variance decomposition.
prediction_uncertainty_decomposition( fit, newdata = NULL, include_group_effects = FALSE, allow_new_levels = FALSE, ndraws = 1000L, seed = 1L )prediction_uncertainty_decomposition( fit, newdata = NULL, include_group_effects = FALSE, allow_new_levels = FALSE, ndraws = 1000L, seed = 1L )
fit |
A fitted |
newdata |
Optional data frame. |
include_group_effects |
Whether fitted group-level effects are included. |
allow_new_levels |
Whether new grouping levels are permitted by brms. |
ndraws |
Optional number of posterior draws. |
seed |
Non-negative seed used for posterior predictive simulation. |
A gp3bayes_prediction_uncertainty object.
Posterior Predictive Coverage Table
predictive_coverage_table(x, levels = c(0.5, 0.8, 0.9, 0.95))predictive_coverage_table(x, levels = c(0.5, 0.8, 0.9, 0.95))
x |
A posterior predictive |
levels |
Central predictive interval levels. |
A table of empirical coverage and mean interval width.
Predictive Distribution Atlas Table
predictive_distribution_atlas_table(x)predictive_distribution_atlas_table(x)
x |
A predictive distribution atlas. |
Draw-level distribution summaries.
Posterior-Predictive Quantile Envelope
predictive_quantile_envelope( x, probabilities = seq(0.05, 0.95, by = 0.05), probs = c(0.025, 0.5, 0.975), ndraws = 500L, include_group_effects = TRUE, seed = 1L )predictive_quantile_envelope( x, probabilities = seq(0.05, 0.95, by = 0.05), probs = c(0.025, 0.5, 0.975), ndraws = 500L, include_group_effects = TRUE, seed = 1L )
x |
A fitted model or predictive atlas. |
probabilities |
Outcome quantile probabilities. |
probs |
Posterior interval probabilities for each replicated quantile. |
ndraws |
Predictive draws when |
include_group_effects |
Whether fitted group effects are included. |
seed |
Predictive seed. |
A quantile-envelope table.
Posterior Predictive Residuals
predictive_residuals(fit, type = NULL, ndraws = 1000L)predictive_residuals(fit, type = NULL, ndraws = 1000L)
fit |
A fitted |
type |
Residual type. Binary models support |
ndraws |
Optional number of expected-response draws. |
A data frame of observed values, posterior expected values, and descriptive residuals.
Convenience wrapper around audit_design_support() for an already-created
specification.
preflight_model_specification(specification, ...)preflight_model_specification(specification, ...)
specification |
A gp3bayes model specification. |
... |
Arguments passed to |
A gp3bayes_design_support_audit.
Prepare binocular pupil data without averaging eyes
prepare_binocular_pupil_timecourse( data, left_col = "pupil_left", right_col = "pupil_right", participant_col = "participant_id", time_col = "time_ms", condition_col = "condition", trial_col = "trial_id", item_col = NULL, covariates = character() )prepare_binocular_pupil_timecourse( data, left_col = "pupil_left", right_col = "pupil_right", participant_col = "participant_id", time_col = "time_ms", condition_col = "condition", trial_col = "trial_id", item_col = NULL, covariates = character() )
data |
A data frame containing left and right pupil responses. |
left_col, right_col
|
Left/right pupil response columns. |
participant_col, time_col, condition_col
|
Structural columns. |
trial_col, item_col
|
Optional structural columns. |
covariates |
Optional additional covariates. |
A gp3bayes_binocular_pupil_prepared object.
Applies explicit binary outcome mapping, explicit two-level condition coding, optional recorded numeric scaling, and a model-readiness gate. No variable is silently scaled or recoded.
prepare_hierarchical_binary_data( data, contract, outcome_mapping = NULL, condition_levels = NULL, condition_coding = c(-0.5, 0.5), scale_predictors = character(), scale_time = FALSE, missing = c("error", "drop") )prepare_hierarchical_binary_data( data, contract, outcome_mapping = NULL, condition_levels = NULL, condition_coding = c(-0.5, 0.5), scale_predictors = character(), scale_time = FALSE, missing = c("error", "drop") )
data |
A data frame containing the columns declared in |
contract |
A binary |
outcome_mapping |
Optional named vector mapping two labelled outcome values to 0 and 1. It is required for non-logical, non-0/1 outcomes. |
condition_levels |
Optional two-value vector listing the condition levels in reference-to-focal order. |
condition_coding |
Two distinct finite numeric values used to encode
the declared condition. The default is |
scale_predictors |
Character vector naming declared numeric predictors to centre and divide by their sample standard deviation. |
scale_time |
Whether to centre and scale the declared linear time variable. |
missing |
Either |
This function performs deterministic preparation only. It does not fit a model, create posterior draws, or establish causal or substantive validity.
A gp3bayes_binary_prepared object containing the analysis data,
contract, readiness audit, transformation registry, fixed-effects formula,
design-matrix columns, and row accounting.
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", predictors = c( "participant_covariate", "trial_covariate" ), interaction = c( "condition", "participant_covariate" ), random_slope = TRUE ) prepared <- prepare_hierarchical_binary_data( simulation$data, contract, condition_levels = c("control", "treatment") ) preparedsimulation <- 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", predictors = c( "participant_covariate", "trial_covariate" ), interaction = c( "condition", "participant_covariate" ), random_slope = TRUE ) prepared <- prepare_hierarchical_binary_data( simulation$data, contract, condition_levels = c("control", "treatment") ) prepared
Validates strictly positive finite uncensored durations, applies explicit unit conversion and recorded scaling, and runs the duration readiness gate.
prepare_hierarchical_duration_data( data, contract, condition_levels = NULL, condition_coding = c(-0.5, 0.5), scale_predictors = character(), scale_time = FALSE, outcome_multiplier = 1, converted_unit = NULL, missing = c("error", "drop") )prepare_hierarchical_duration_data( data, contract, condition_levels = NULL, condition_coding = c(-0.5, 0.5), scale_predictors = character(), scale_time = FALSE, outcome_multiplier = 1, converted_unit = NULL, missing = c("error", "drop") )
data |
A data frame containing columns declared in |
contract |
A duration |
condition_levels |
Optional two-value condition order. |
condition_coding |
Two distinct finite numeric condition codes. |
scale_predictors |
Declared numeric predictors to centre and scale. |
scale_time |
Whether to centre and scale the declared linear time variable. |
outcome_multiplier |
Positive unit-conversion multiplier. |
converted_unit |
Required destination unit when
|
missing |
Either |
Zero, negative, non-finite, censored, truncated, or shifted durations are not supported. Unit conversion is never inferred.
A gp3bayes_duration_prepared object.
Validates ordering, identifiers, event time, pupil values, measurement flags, sampling intervals, and baseline support. Only explicitly requested deterministic transformations are applied and recorded.
prepare_pupil_timecourse( data, contract, baseline_operation = c("none", "subtract", "divide", "proportion_change", "percent_change"), baseline_window = NULL, output_unit = NULL, scale_covariates = character(), max_rows = 2000000L, irregularity_review_cv = 0.1 )prepare_pupil_timecourse( data, contract, baseline_operation = c("none", "subtract", "divide", "proportion_change", "percent_change"), baseline_window = NULL, output_unit = NULL, scale_covariates = character(), max_rows = 2000000L, irregularity_review_cv = 0.1 )
data |
Source data frame. |
contract |
A |
baseline_operation |
One of |
baseline_window |
Required when |
output_unit |
Optional physical output unit. Only metre/millimetre conversions are defined. |
scale_covariates |
Declared numeric covariates to standardize. |
max_rows |
Maximum accepted input rows. |
irregularity_review_cv |
Coefficient-of-variation threshold recorded as a sampling-irregularity review signal. |
A gp3bayes_pupil_prepared object. The source pupil values are
retained in .pupil_source; the modelled values are .pupil_model.
This function does not detect or interpolate blinks, smooth traces, choose a baseline, correct PFE, correct luminance, or automatically exclude samples.
sim <- simulate_pupil_timecourse( n_participants = 3, trials_per_participant = 3, sampling_frequency = 20, seed = 11 ) contract <- create_pupil_contract( "pupil_mm", "participant_id", "trial_id", "event_time", "millimetres", 20, condition_col = "condition", blink_col = "blink", interpolation_col = "interpolated", validity_col = "valid", gaze_x_col = "gaze_x", gaze_y_col = "gaze_y", luminance_col = "luminance", baseline_window = c(-0.5, 0) ) prepared <- prepare_pupil_timecourse( sim$data, contract, baseline_operation = "subtract" ) preparedsim <- simulate_pupil_timecourse( n_participants = 3, trials_per_participant = 3, sampling_frequency = 20, seed = 11 ) contract <- create_pupil_contract( "pupil_mm", "participant_id", "trial_id", "event_time", "millimetres", 20, condition_col = "condition", blink_col = "blink", interpolation_col = "interpolated", validity_col = "valid", gaze_x_col = "gaze_x", gaze_y_col = "gaze_y", luminance_col = "luminance", baseline_window = c(-0.5, 0) ) prepared <- prepare_pupil_timecourse( sim$data, contract, baseline_operation = "subtract" ) prepared
Compares marginal draws from the recorded gp3bayes prior specification with fitted posterior draws on the same parameter scale.
prior_posterior_bridge( fit, variables = NULL, regex = "^(b_|sd_|cor_|sigma$)", ndraws = 4000L, probs = c(0.025, 0.5, 0.975), seed = 1L )prior_posterior_bridge( fit, variables = NULL, regex = "^(b_|sd_|cor_|sigma$)", ndraws = 4000L, probs = c(0.025, 0.5, 0.975), seed = 1L )
fit |
A fitted |
variables |
Optional exact posterior variables. |
regex |
Optional posterior-variable regular expression. |
ndraws |
Number of prior draws and maximum posterior draws used. |
probs |
Three interval probabilities. |
seed |
Non-negative integer seed. |
A gp3bayes_prior_posterior_bridge.
Prior-versus-Posterior Distance Table
prior_posterior_distance_table(x)prior_posterior_distance_table(x)
x |
A |
Marginal empirical distribution-distance summaries.
Long Prior and Posterior Draw Table
prior_posterior_draws_long(x, max_draws = 1000L, seed = 1L)prior_posterior_draws_long(x, max_draws = 1000L, seed = 1L)
x |
A |
max_draws |
Maximum draws per distribution and variable. |
seed |
Non-negative integer seed. |
A long draw table.
Prior-versus-Posterior Summary Table
prior_posterior_summary_table(x)prior_posterior_summary_table(x)
x |
A |
Location, spread, interval, shift, and contraction summaries.
Prior Sensitivity Scenario Table
prior_sensitivity_scenario_table(x)prior_sensitivity_scenario_table(x)
x |
A |
Scenario-level maximum shifts and diagnostic statuses.
Prior Sensitivity Table
prior_sensitivity_table(x)prior_sensitivity_table(x)
x |
A |
Parameter-by-scenario posterior shifts.
Prior-Specification Table
prior_specification_table(x)prior_specification_table(x)
x |
A gp3bayes fit, specification, or prior specification. |
The backend-independent declared prior table.
Publication Registry Table
publication_registry_table(x)publication_registry_table(x)
x |
A publication registry. |
Entry metadata.
Report the gp3bayes 0.5 advanced-pupillometry capability boundary
pupil_advanced_capabilities()pupil_advanced_capabilities()
A data frame listing supported, experimental, and deliberately excluded capabilities.
Report governed compatibility rules for 0.5 advanced models
pupil_advanced_compatibility_table()pupil_advanced_compatibility_table()
A data frame documenting combinations that are supported, reviewed, or deliberately blocked in the 0.5 governed interface.
Resolves the response, time, participant, condition, trial, and item columns that the advanced 0.5 layer will use. Resolution is read-only and does not modify the prepared object.
pupil_advanced_mapping_table(prepared)pupil_advanced_mapping_table(prepared)
prepared |
A 0.4 prepared pupil object or compatible data frame. |
A data frame describing the resolved mapping.
Tabulate an advanced pupil model specification
pupil_advanced_specification_table(x)pupil_advanced_specification_table(x)
x |
An advanced specification. |
A one-row data frame.
Tabulate a temporal-dependence audit
pupil_autocorrelation_table(x, level = c("summary", "series"))pupil_autocorrelation_table(x, level = c("summary", "series"))
x |
A temporal-dependence audit. |
level |
|
Summarise binocular posterior agreement
pupil_binocular_agreement_table(trajectory, tolerance = 0.1)pupil_binocular_agreement_table(trajectory, tolerance = 0.1)
trajectory |
A binocular trajectory object. |
tolerance |
A scientifically declared absolute right-minus-left tolerance. |
A data frame with posterior agreement probabilities.
Extract posterior residual binocular correlation
pupil_binocular_correlation(fit, probability = 0.95)pupil_binocular_correlation(fit, probability = 0.95)
fit |
A binocular fit with residual correlation enabled. |
probability |
Central interval probability. |
A data frame.
Estimate posterior right-minus-left binocular differences
pupil_binocular_difference(x)pupil_binocular_difference(x)
x |
A binocular trajectory object. |
A data frame.
Estimate a posterior condition-difference trajectory
pupil_condition_contrast( prediction, contrast, threshold = 0, probability = 0.95 )pupil_condition_contrast( prediction, contrast, threshold = 0, probability = 0.95 )
prediction |
Pupil prediction with a |
contrast |
Character vector |
threshold |
Scientifically declared threshold on the pupil scale. |
probability |
Credible probability. |
A pupil trajectory/contrast object with pointwise probabilities that
the declared contrast exceeds threshold.
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, "millimetres") pupil_condition_contrast( prediction, contrast = c("treatment", "control"), threshold = 0.1 )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, "millimetres") pupil_condition_contrast( prediction, contrast = c("treatment", "control"), threshold = 0.1 )
Tabulate a pupil distribution declaration or advanced specification
pupil_distribution_table(x)pupil_distribution_table(x)
x |
A distribution declaration, advanced specification, or advanced fit. |
A one-row data frame.
Tabulate a dynamic pupil contrast
pupil_dynamic_contrast_table(x)pupil_dynamic_contrast_table(x)
x |
A dynamic-contrast object. |
A data frame.
Extract Gaussian-process hyperparameters
pupil_gp_hyperparameters(fit, probability = 0.95)pupil_gp_hyperparameters(fit, probability = 0.95)
fit |
A fitted GP pupil model. |
probability |
Central interval probability. |
A gp3bayes_pupil_gp_hyperparameters object.
Tabulate GP hyperparameters
pupil_gp_table(x)pupil_gp_table(x)
x |
A GP-hyperparameter object. |
A data frame.
Tabulate advanced pupil identifiability/design-support audit
pupil_identifiability_table(x)pupil_identifiability_table(x)
x |
An identifiability audit. |
A data frame.
Extract a pupil measurement-context table
pupil_measurement_audit_table(x)pupil_measurement_audit_table(x)
x |
A |
A data frame.
# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.
Summarise measurement uncertainty declared in a model
pupil_measurement_uncertainty_table(x)pupil_measurement_uncertainty_table(x)
x |
A measurement model, advanced specification, or advanced fit. |
A data frame.
Tabulate missingness audit results
pupil_missingness_table(x)pupil_missingness_table(x)
x |
A missingness audit. |
A data frame.
Build an auditable advanced pupil model card
pupil_model_card(x)pupil_model_card(x)
x |
An advanced specification or fit. |
A gp3bayes_pupil_model_card object containing structured metadata
and governance statements suitable for methods supplements.
Tabulate a pupil model card
pupil_model_card_table(x)pupil_model_card_table(x)
x |
A model-card object, specification, or fit. |
Tabulate model comparison
pupil_model_comparison_table(x)pupil_model_comparison_table(x)
x |
A model-comparison object. |
A data frame.
Compute explicit predictive model weights
pupil_model_weights(x, method = c("stacking", "pseudobma"), BB = TRUE)pupil_model_weights(x, method = c("stacking", "pseudobma"), BB = TRUE)
x |
A LOO-based model comparison or a model set. |
method |
|
BB |
Bayesian bootstrap for pseudo-BMA where applicable. |
A data frame of weights. Weights are not used automatically for prediction or model selection.
Extract pupil PPC evidence tables
pupil_ppc_table( x, component = c("trajectory", "distribution", "features", "residuals", "residual_trajectory", "autocorrelation", "heterogeneity", "measurement_context") )pupil_ppc_table( x, component = c("trajectory", "distribution", "features", "residuals", "residual_trajectory", "autocorrelation", "heterogeneity", "measurement_context") )
x |
A pupil PPC object. |
component |
One of |
A data frame.
# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.
Extract pupil readiness tables
pupil_readiness_table( x, component = c("summary", "participant", "condition", "trial") )pupil_readiness_table( x, component = c("summary", "participant", "condition", "trial") )
x |
A |
component |
One of |
A data frame.
# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.
Summarise residual autocorrelation for a pupil fit
pupil_residual_acf(x, max_lag = 10L, ndraws = 200L)pupil_residual_acf(x, max_lag = 10L, ndraws = 200L)
x |
A pupil fit or pupil diagnostics object. |
max_lag |
Maximum lag when |
ndraws |
Draws for fit-based expected residuals. |
A data frame of mean within-series residual autocorrelations.
# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.
Tabulate posterior residual scale
pupil_residual_scale_table(x)pupil_residual_scale_table(x)
x |
A residual-scale estimand. |
A data frame.
Provides a frequency-domain diagnostic for residual periodicity after posterior mean subtraction. It does not infer physiological oscillations.
pupil_residual_spectrum(fit, ndraws = 300L)pupil_residual_spectrum(fit, ndraws = 300L)
fit |
An advanced fit. |
ndraws |
Posterior expected-mean draws. |
A gp3bayes_pupil_residual_spectrum object.
Tabulate nonlinear response parameters
pupil_response_parameter_table(x)pupil_response_parameter_table(x)
x |
A response-parameter object. |
Extract pupil sensitivity scenarios or comparison results
pupil_sensitivity_table(x)pupil_sensitivity_table(x)
x |
A pupil sensitivity suite or sensitivity comparison. |
A data frame.
# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.
Convert a pupil specification to a publication-ready table
pupil_specification_table(x)pupil_specification_table(x)
x |
A pupil model specification. |
A data frame.
# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.
Tabulate posterior pupil trajectory derivatives
pupil_trajectory_derivative_table(x, probability = x$probability)pupil_trajectory_derivative_table(x, probability = x$probability)
x |
A trajectory-derivative object. |
probability |
Optional interval probability overriding the stored value. |
A data frame.
Convert a pupil trajectory to a table
pupil_trajectory_table(x)pupil_trajectory_table(x)
x |
A pupil trajectory object. |
A data frame.
# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.
Extract a pupil validation table
pupil_validation_table(x)pupil_validation_table(x)
x |
A pupil validation object. |
A data frame.
# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.
For binary logit models the residual latent variance is pi^2 / 3. For
lognormal duration models residual log-scale variance is sigma^2.
Random-slope variance is deliberately excluded.
random_intercept_variance_partition(fit, probs = c(0.025, 0.5, 0.975))random_intercept_variance_partition(fit, probs = c(0.025, 0.5, 0.975))
fit |
A fitted |
probs |
Three interval probabilities. |
A gp3bayes_random_intercept_variance_partition.
Random-Intercept Variance-Partition Table
random_intercept_variance_partition_table(x)random_intercept_variance_partition_table(x)
x |
A variance-partition object. |
Component-level variance and fraction summaries.
Random-Slope Sensitivity Table
random_slope_sensitivity_table(x)random_slope_sensitivity_table(x)
x |
A |
The retained estimand-sensitivity comparison.
Read a Frozen Analysis Manifest
read_analysis_manifest(file)read_analysis_manifest(file)
file |
Explicit |
A validated gp3bayes_analysis_manifest.
Read a Frozen gp3bayes Object Schema
read_gp3bayes_schema(file)read_gp3bayes_schema(file)
file |
Explicit |
A gp3bayes_object_schema.
Recovery Estimate Table
recovery_estimate_table(x)recovery_estimate_table(x)
x |
A |
Repetition-level truth, posterior summaries, and coverage records.
Recovery Fit-Status Table
recovery_fit_status_table(x)recovery_fit_status_table(x)
x |
A |
Repetition-level completion and diagnostic-status records.
Recovery Parameter Summary Table
recovery_parameter_table(x)recovery_parameter_table(x)
x |
A |
Parameter-level recovery summaries.
Register a Publication Figure
register_publication_figure( registry, name, figure, caption = NULL, source = NULL )register_publication_figure( registry, name, figure, caption = NULL, source = NULL )
registry |
A publication registry. |
name |
Unique entry name. |
figure |
A ggplot, bayesplot grid, or gtable. |
caption |
Optional caption. |
source |
Optional source label. |
An updated registry.
Register a Publication Table
register_publication_table( registry, name, table, caption = NULL, source = NULL )register_publication_table( registry, name, table, caption = NULL, source = NULL )
registry |
A publication registry. |
name |
Unique entry name. |
table |
A data frame. |
caption |
Optional caption. |
source |
Optional source label. |
An updated registry.
Flags observations that are extreme on the log-duration scale using both a robust MAD rule and an outer-IQR rule. The function never deletes values and never changes the model family automatically.
review_duration_extremes(data, contract, mad_cutoff = 4, iqr_multiplier = 3)review_duration_extremes(data, contract, mad_cutoff = 4, iqr_multiplier = 3)
data |
A data frame. |
contract |
An approved duration contract. |
mad_cutoff |
Robust absolute z-score cutoff on log durations. |
iqr_multiplier |
Multiplier for the outer-IQR rule on log durations. |
A gp3bayes_duration_extreme_review object.
Repeatedly simulates from the approved hierarchical Bernoulli-logit generator, fits the restricted model, and compares posterior intervals with known generating values.
run_binary_recovery( repetitions = 20L, n_participants = 30L, trials_per_participant = 16L, n_items = 12L, include_items = TRUE, random_slope = TRUE, seed = 1001L, chains = 4L, iter = 1500L, warmup = 750L, cores = min(chains, .gp3b_default_cores(chains)), adapt_delta = 0.95, max_treedepth = 12L, refresh = 0L, interval_probability = 0.95, minimum_repetitions = 20L, maximum_standardized_bias = 0.25, minimum_coverage = 0.8, minimum_diagnostic_pass_fraction = 0.8, continue_on_error = TRUE )run_binary_recovery( repetitions = 20L, n_participants = 30L, trials_per_participant = 16L, n_items = 12L, include_items = TRUE, random_slope = TRUE, seed = 1001L, chains = 4L, iter = 1500L, warmup = 750L, cores = min(chains, .gp3b_default_cores(chains)), adapt_delta = 0.95, max_treedepth = 12L, refresh = 0L, interval_probability = 0.95, minimum_repetitions = 20L, maximum_standardized_bias = 0.25, minimum_coverage = 0.8, minimum_diagnostic_pass_fraction = 0.8, continue_on_error = TRUE )
repetitions |
Number of simulation-fit repetitions. |
n_participants, trials_per_participant, n_items
|
Synthetic design sizes. |
include_items |
Whether crossed item effects are included. |
random_slope |
Whether a participant condition slope is generated and fitted. |
seed |
First simulation seed. |
chains, iter, warmup, cores, adapt_delta, max_treedepth, refresh
|
Restricted sampling controls. |
interval_probability |
Central posterior interval probability. |
minimum_repetitions |
Repetitions required before an overall pass is possible. |
maximum_standardized_bias |
Maximum absolute bias divided by the empirical standard deviation of estimates for a pass. |
minimum_coverage |
Minimum empirical interval coverage for a pass. |
minimum_diagnostic_pass_fraction |
Minimum fraction of fits with a diagnostic pass. |
continue_on_error |
Whether failed repetitions are recorded instead of stopping. |
A small recovery run is a smoke test, not validation. Even when all declared thresholds pass, the object records no automatic validation claim.
A gp3bayes_binary_recovery object.
Repeatedly simulates and fits the approved hierarchical lognormal duration model and compares posterior intervals with known generating values.
run_duration_recovery( repetitions = 20L, n_participants = 30L, trials_per_participant = 16L, n_items = 12L, include_items = TRUE, random_slope = TRUE, baseline_median = 500, outcome_unit = "milliseconds", seed = 2001L, chains = 4L, iter = 1500L, warmup = 750L, cores = min(chains, .gp3b_default_cores(chains)), adapt_delta = 0.95, max_treedepth = 12L, refresh = 0L, interval_probability = 0.95, minimum_repetitions = 20L, maximum_standardized_bias = 0.25, minimum_coverage = 0.8, minimum_diagnostic_pass_fraction = 0.8, continue_on_error = TRUE )run_duration_recovery( repetitions = 20L, n_participants = 30L, trials_per_participant = 16L, n_items = 12L, include_items = TRUE, random_slope = TRUE, baseline_median = 500, outcome_unit = "milliseconds", seed = 2001L, chains = 4L, iter = 1500L, warmup = 750L, cores = min(chains, .gp3b_default_cores(chains)), adapt_delta = 0.95, max_treedepth = 12L, refresh = 0L, interval_probability = 0.95, minimum_repetitions = 20L, maximum_standardized_bias = 0.25, minimum_coverage = 0.8, minimum_diagnostic_pass_fraction = 0.8, continue_on_error = TRUE )
repetitions |
Number of simulation-fit repetitions. |
n_participants, trials_per_participant, n_items
|
Synthetic design sizes. |
include_items |
Whether crossed item effects are included. |
random_slope |
Whether a participant condition slope is generated and fitted. |
baseline_median |
Baseline synthetic duration median. |
outcome_unit |
Synthetic duration unit. |
seed |
First simulation seed. |
chains, iter, warmup, cores, adapt_delta, max_treedepth, refresh
|
Restricted sampling controls. |
interval_probability |
Central posterior interval probability. |
minimum_repetitions |
Repetitions required before an overall pass is possible. |
maximum_standardized_bias |
Maximum absolute bias divided by the empirical standard deviation of estimates for a pass. |
minimum_coverage |
Minimum empirical interval coverage for a pass. |
minimum_diagnostic_pass_fraction |
Minimum fraction of fits with a diagnostic pass. |
continue_on_error |
Whether failed repetitions are recorded instead of stopping. |
A small run is a smoke test. No result creates an automatic validation claim.
A gp3bayes_duration_recovery.
This is an intentionally explicit refitting workflow. It can be expensive. The result reports how the primary estimand changes when declared units are omitted, without automatically labelling any unit invalid.
run_group_deletion_sensitivity( plan, backend = c("rstan", "cmdstanr"), chains = 4L, iter = 2000L, warmup = 1000L, cores = 1L, seed = 1L, adapt_delta = 0.95, max_treedepth = 12L, refresh = 0L, ndraws = NULL, retain_fits = FALSE )run_group_deletion_sensitivity( plan, backend = c("rstan", "cmdstanr"), chains = 4L, iter = 2000L, warmup = 1000L, cores = 1L, seed = 1L, adapt_delta = 0.95, max_treedepth = 12L, refresh = 0L, ndraws = NULL, retain_fits = FALSE )
plan |
A group-deletion sensitivity plan. |
backend |
|
chains, iter, warmup, cores, seed, adapt_delta, max_treedepth, refresh
|
Restricted sampling controls. |
ndraws |
Optional number of draws used for each estimand. |
retain_fits |
Whether fitted objects are retained. |
A gp3bayes_group_deletion_sensitivity.
Run Random-Intercept versus Random-Slope Sensitivity
run_random_slope_sensitivity( plan, backend = c("rstan", "cmdstanr"), chains = 4L, iter = 2000L, warmup = 1000L, cores = 1L, seed = 1L, adapt_delta = 0.95, max_treedepth = 12L, refresh = 0L, ndraws = NULL, retain_fits = FALSE )run_random_slope_sensitivity( plan, backend = c("rstan", "cmdstanr"), chains = 4L, iter = 2000L, warmup = 1000L, cores = 1L, seed = 1L, adapt_delta = 0.95, max_treedepth = 12L, refresh = 0L, ndraws = NULL, retain_fits = FALSE )
plan |
A random-slope sensitivity plan. |
backend |
|
chains, iter, warmup, cores, seed, adapt_delta, max_treedepth, refresh
|
Restricted sampling controls. |
ndraws |
Optional number of draws used for each estimand. |
retain_fits |
Whether fitted objects are retained. |
A gp3bayes_random_slope_sensitivity.
Run a Simulation-Based Calibration Plan
run_sbc_plan( plan, cores_per_fit = 1L, keep_fits = FALSE, thin_ranks = NULL, cache_mode = "none", cache_location = NULL )run_sbc_plan( plan, cores_per_fit = 1L, keep_fits = FALSE, thin_ranks = NULL, cache_mode = "none", cache_location = NULL )
plan |
A |
cores_per_fit |
Cores used by each fit. |
keep_fits |
Whether to retain fitted objects. |
thin_ranks |
Optional rank thinning. |
cache_mode |
SBC cache mode. |
cache_location |
Optional cache location. |
A gp3bayes_sbc_result.
Orchestrates approved sensitivity components. Refitting components only run
when explicitly requested in plan. Failures are retained as inspectable
component results unless stop_on_error = TRUE.
run_sensitivity_suite( fit, plan = create_sensitivity_suite_plan(), reference_estimand = NULL, stop_on_error = FALSE )run_sensitivity_suite( fit, plan = create_sensitivity_suite_plan(), reference_estimand = NULL, stop_on_error = FALSE )
fit |
An approved gp3bayes fit. |
plan |
A |
reference_estimand |
Optional precomputed primary estimand. When
alternatives are supplied and this is omitted it is computed with
|
stop_on_error |
Whether the first component error should stop the suite. |
A gp3bayes_sensitivity_suite.
Summarise NUTS Sampler Diagnostics
sampler_diagnostic_table(fit)sampler_diagnostic_table(fit)
fit |
A fitted |
A data frame containing sampler-level summaries and review flags.
File output is explicit: no current-directory default is provided.
save_figure_set( x, directory, width = 7, height = 5, dpi = 300, device = "png", overwrite = FALSE )save_figure_set( x, directory, width = 7, height = 5, dpi = 300, device = "png", overwrite = FALSE )
x |
A |
directory |
Existing or creatable output directory. |
width, height
|
Figure dimensions in inches. |
dpi |
Raster resolution. |
device |
File extension/device, such as |
overwrite |
Whether existing files may be replaced. |
Invisibly, the written file paths.
Save Publication Registry Figures
save_publication_registry_figures( x, directory, width = 7, height = 5, dpi = 300, device = "png", overwrite = FALSE )save_publication_registry_figures( x, directory, width = 7, height = 5, dpi = 300, device = "png", overwrite = FALSE )
x |
A publication registry. |
directory |
Explicit output directory. |
width, height
|
Figure dimensions in inches. |
dpi |
Raster resolution. |
device |
Graphics device/extension. |
overwrite |
Whether existing files may be replaced. |
Invisibly, written file paths.
SBC Overview Table
sbc_overview_table(x)sbc_overview_table(x)
x |
A |
A conservative one-row metadata summary.
SBC Statistics Table
sbc_stats_table(x)sbc_stats_table(x)
x |
A |
The statistics table retained by the SBC result.
Schema-Comparison Table
schema_comparison_table(x)schema_comparison_table(x)
x |
A |
Structural schema comparisons.
Metrics are descriptive out-of-sample or held-out scores only when the caller supplies predictions generated without using the scored observations.
score_pupil_predictions(observed, draws, probability = 0.9)score_pupil_predictions(observed, draws, probability = 0.9)
observed |
Numeric observed values. |
draws |
Matrix of posterior predictive draws (draws x observations). |
probability |
Central interval used for empirical coverage and width. |
A gp3bayes_pupil_predictive_score object.
Sensitivity-Suite Table
sensitivity_suite_table(x)sensitivity_suite_table(x)
x |
A |
The component-level sensitivity table.
Generates deterministic hierarchical traces with optional Student-t contamination, heteroskedasticity, ARMA dependence, measurement error, and missingness. The simulator is intended for examples, recovery studies, and failure-path validation; it does not claim physiological realism.
simulate_advanced_pupil_timecourse( n_participants = 24L, trials_per_participant = 6L, time_points = 41L, time_range = c(-500, 2500), conditions = c("control", "treatment"), family = c("gaussian", "student"), residual_scale = 0.08, heteroskedastic_strength = 0.35, ar = 0.45, ma = numeric(), participant_sd = 0.12, amplitude_condition = 0.22, latency_condition = 120, outlier_fraction = 0.01, missing_fraction = 0.03, measurement_error_sd = 0.015, student_df = 5, seed = 2026 )simulate_advanced_pupil_timecourse( n_participants = 24L, trials_per_participant = 6L, time_points = 41L, time_range = c(-500, 2500), conditions = c("control", "treatment"), family = c("gaussian", "student"), residual_scale = 0.08, heteroskedastic_strength = 0.35, ar = 0.45, ma = numeric(), participant_sd = 0.12, amplitude_condition = 0.22, latency_condition = 120, outlier_fraction = 0.01, missing_fraction = 0.03, measurement_error_sd = 0.015, student_df = 5, seed = 2026 )
n_participants |
Number of participants. |
trials_per_participant |
Trials per participant. |
time_points |
Number of samples per trial. |
time_range |
Numeric length-two time range in milliseconds. |
conditions |
Character condition labels. |
family |
|
residual_scale |
Baseline residual SD. |
heteroskedastic_strength |
Multiplicative time-varying noise strength. |
ar |
Numeric AR coefficients, length at most 3. |
ma |
Numeric MA coefficients, length at most 2. |
participant_sd |
Participant random-intercept SD. |
amplitude_condition |
Difference in response amplitude for condition 2. |
latency_condition |
Difference in peak latency for condition 2. |
outlier_fraction |
Fraction of observations receiving extra contamination. |
missing_fraction |
Fraction of pupil observations set missing. |
measurement_error_sd |
Known response-measurement SD; zero disables. |
student_df |
Degrees of freedom when |
seed |
Random seed. |
A gp3bayes_pupil_advanced_simulation object with data and stored truth.
Simulate a Dedicated Binary Pathology Scenario
simulate_binary_pathology( scenario = c("null_contrast", "weak_information", "severe_imbalance", "near_separation", "omitted_random_slope", "sparse_item_structure", "all_zero_participants", "rank_deficiency", "missing_outcomes"), seed = 1L )simulate_binary_pathology( scenario = c("null_contrast", "weak_information", "severe_imbalance", "near_separation", "omitted_random_slope", "sparse_item_structure", "all_zero_participants", "rank_deficiency", "missing_outcomes"), seed = 1L )
scenario |
Pathological or stress-test scenario. |
seed |
Non-negative integer seed. |
A gp3bayes_pathological_simulation.
Simulate joint binocular pupil traces
simulate_binocular_pupil_timecourse( ..., residual_correlation = 0.65, eye_bias = 0.015, eye_specific_sd = 0.035 )simulate_binocular_pupil_timecourse( ..., residual_correlation = 0.65, eye_bias = 0.015, eye_specific_sd = 0.035 )
... |
Arguments passed to |
residual_correlation |
Approximate left/right innovation correlation. |
eye_bias |
Mean right-minus-left difference. |
eye_specific_sd |
Eye-specific noise SD. |
A gp3bayes_binocular_pupil_simulation object.
Simulate Marginal Draws from Declared gp3bayes Priors
simulate_declared_prior_draws( x, variables = NULL, regex = NULL, ndraws = 4000L, seed = 1L )simulate_declared_prior_draws( x, variables = NULL, regex = NULL, ndraws = 4000L, seed = 1L )
x |
A gp3bayes fit, specification, or prior specification. |
variables |
Posterior-style variable names. When |
regex |
Optional regular expression applied after inference. |
ndraws |
Number of marginal prior draws. |
seed |
Non-negative integer seed. |
A numeric draw matrix.
Simulate a Dedicated Duration Pathology Scenario
simulate_duration_pathology( scenario = c("null_ratio", "high_group_heterogeneity", "weak_information", "severe_imbalance", "heavy_tailed_contamination", "mixture", "censoring", "incorrect_unit", "zero_duration", "negative_duration"), seed = 1L )simulate_duration_pathology( scenario = c("null_ratio", "high_group_heterogeneity", "weak_information", "severe_imbalance", "heavy_tailed_contamination", "mixture", "censoring", "incorrect_unit", "zero_duration", "negative_duration"), seed = 1L )
scenario |
Pathological or stress-test duration scenario. |
seed |
Non-negative integer seed. |
A gp3bayes_pathological_simulation.
Generates deterministic synthetic repeated-measures data from the approved Bernoulli-logit contract. The simulator records all generating parameters, participant effects, optional crossed item effects, and the random-number seed. It performs no model fitting.
simulate_hierarchical_binary_data( n_participants = 40, trials_per_participant = 20, n_items = 20, intercept = stats::qlogis(0.35), condition_effect = 0.8, participant_covariate_effect = 0.3, trial_covariate_effect = 0.15, interaction_effect = 0.25, participant_sd = 0.7, item_sd = 0.35, random_slope_sd = 0.3, random_slope_cor = 0, condition_probability = 0.5, balanced_condition = TRUE, include_items = TRUE, seed = 1 )simulate_hierarchical_binary_data( n_participants = 40, trials_per_participant = 20, n_items = 20, intercept = stats::qlogis(0.35), condition_effect = 0.8, participant_covariate_effect = 0.3, trial_covariate_effect = 0.15, interaction_effect = 0.25, participant_sd = 0.7, item_sd = 0.35, random_slope_sd = 0.3, random_slope_cor = 0, condition_probability = 0.5, balanced_condition = TRUE, include_items = TRUE, seed = 1 )
n_participants |
Number of participants. |
trials_per_participant |
Number of observations per participant. |
n_items |
Number of crossed items when |
intercept |
Population intercept on the log-odds scale. |
condition_effect |
Population condition contrast on the log-odds scale. |
participant_covariate_effect |
Participant-covariate coefficient. |
trial_covariate_effect |
Trial-covariate coefficient. |
interaction_effect |
Condition-by-participant-covariate coefficient. |
participant_sd |
Participant random-intercept standard deviation. |
item_sd |
Crossed item random-intercept standard deviation. |
random_slope_sd |
Participant condition-slope standard deviation. |
random_slope_cor |
Correlation between participant intercepts and condition slopes. It must lie strictly between -1 and 1. |
condition_probability |
Treatment probability when
|
balanced_condition |
Whether each participant receives an approximately balanced condition sequence. |
include_items |
Whether to generate a crossed item identifier. |
seed |
Non-negative integer random-number seed. |
The condition is generated using -0.5 and 0.5 internally and returned
as a factor with levels control and treatment. The data-generating model
includes one participant random intercept, one optional correlated
participant condition slope, and one optional crossed item intercept.
A gp3bayes_binary_simulation containing synthetic data, stored
truth, generated random effects, and design metadata.
simulation <- simulate_hierarchical_binary_data( n_participants = 12, trials_per_participant = 8, n_items = 6, seed = 2026 ) simulation head(simulation$data)simulation <- simulate_hierarchical_binary_data( n_participants = 12, trials_per_participant = 8, n_items = 6, seed = 2026 ) simulation head(simulation$data)
Generates deterministic strictly positive uncensored durations from the approved hierarchical lognormal contract.
simulate_hierarchical_duration_data( n_participants = 40L, trials_per_participant = 20L, n_items = 20L, baseline_median = 500, condition_effect = log(1.15), participant_covariate_effect = log(1.08), trial_covariate_effect = log(1.04), interaction_effect = log(1.05), participant_sd = 0.35, item_sd = 0.2, random_slope_sd = 0.15, random_slope_cor = 0, residual_sd = 0.4, condition_probability = 0.5, balanced_condition = TRUE, include_items = TRUE, outcome_unit = "milliseconds", seed = 1L )simulate_hierarchical_duration_data( n_participants = 40L, trials_per_participant = 20L, n_items = 20L, baseline_median = 500, condition_effect = log(1.15), participant_covariate_effect = log(1.08), trial_covariate_effect = log(1.04), interaction_effect = log(1.05), participant_sd = 0.35, item_sd = 0.2, random_slope_sd = 0.15, random_slope_cor = 0, residual_sd = 0.4, condition_probability = 0.5, balanced_condition = TRUE, include_items = TRUE, outcome_unit = "milliseconds", seed = 1L )
n_participants |
Number of participants. |
trials_per_participant |
Observations per participant. |
n_items |
Number of crossed items when |
baseline_median |
Baseline duration median in |
condition_effect |
Population condition contrast on the log-duration scale. |
participant_covariate_effect |
Participant-covariate coefficient on the log-duration scale. |
trial_covariate_effect |
Trial-covariate coefficient on the log-duration scale. |
interaction_effect |
Condition-by-participant-covariate coefficient on the log-duration scale. |
participant_sd |
Participant random-intercept standard deviation on the log scale. |
item_sd |
Crossed item random-intercept standard deviation. |
random_slope_sd |
Participant condition-slope standard deviation. |
random_slope_cor |
Correlation between participant intercepts and condition slopes. |
residual_sd |
Lognormal residual standard deviation. |
condition_probability |
Focal-condition probability for an unbalanced design. |
balanced_condition |
Whether each participant receives an approximately balanced condition sequence. |
include_items |
Whether crossed items are generated. |
outcome_unit |
Recorded duration unit. |
seed |
Non-negative integer random-number seed. |
The generated outcome is strictly positive, finite, and uncensored. The function does not generate zero, censored, truncated, shifted, or survival outcomes.
A gp3bayes_duration_simulation containing synthetic data, stored
truth, random effects, and design metadata.
Simulate data from the experimental nonlinear response-shape family
simulate_pupil_response_shape( n_participants = 20L, trials_per_participant = 6L, time_points = 41L, conditions = c("control", "treatment"), baseline = 3.2, amplitude = 0.7, onset = 250, rise = 180, duration = 1200, decay = 260, condition_amplitude_ratio = 1.2, condition_onset_shift = 80, residual_sd = 0.08, seed = 2026 )simulate_pupil_response_shape( n_participants = 20L, trials_per_participant = 6L, time_points = 41L, conditions = c("control", "treatment"), baseline = 3.2, amplitude = 0.7, onset = 250, rise = 180, duration = 1200, decay = 260, condition_amplitude_ratio = 1.2, condition_onset_shift = 80, residual_sd = 0.08, seed = 2026 )
n_participants, trials_per_participant, time_points
|
Simulation sizes. |
conditions |
Condition labels. |
baseline, amplitude, onset, rise, duration, decay
|
Shape parameters. |
condition_amplitude_ratio |
Multiplicative amplitude ratio for condition 2. |
condition_onset_shift |
Onset shift for condition 2. |
residual_sd |
Residual SD. |
seed |
Seed. |
Generates event-aligned synthetic pupil data with participant/item heterogeneity, a smooth non-universal response waveform, AR(1) residual dependence, optional blink/data-loss segments, gaze drift, and luminance nuisance variation.
simulate_pupil_timecourse( n_participants = 20L, trials_per_participant = 12L, n_items = 12L, sampling_frequency = 60, time_window = c(-0.5, 2.5), baseline_window = c(-0.5, 0), conditions = c("control", "treatment"), baseline_pupil = 4, response_amplitude = 0.45, condition_difference = 0.18, peak_latency = 0.9, participant_sd = 0.25, item_sd = 0.08, residual_sd = 0.08, ar1 = 0.55, blink_trial_probability = 0.15, blink_duration = 0.12, include_gaze = TRUE, include_luminance = TRUE, gaze_drift_sd = 0.002, luminance_amplitude = 0.12, seed = 2026, max_rows = 500000L )simulate_pupil_timecourse( n_participants = 20L, trials_per_participant = 12L, n_items = 12L, sampling_frequency = 60, time_window = c(-0.5, 2.5), baseline_window = c(-0.5, 0), conditions = c("control", "treatment"), baseline_pupil = 4, response_amplitude = 0.45, condition_difference = 0.18, peak_latency = 0.9, participant_sd = 0.25, item_sd = 0.08, residual_sd = 0.08, ar1 = 0.55, blink_trial_probability = 0.15, blink_duration = 0.12, include_gaze = TRUE, include_luminance = TRUE, gaze_drift_sd = 0.002, luminance_amplitude = 0.12, seed = 2026, max_rows = 500000L )
n_participants |
Number of participants. |
trials_per_participant |
Number of trials per participant. |
n_items |
Number of crossed items; use |
sampling_frequency |
Sampling frequency in Hz. |
time_window |
Two-element event-relative time window in seconds. |
baseline_window |
Two-element pre-event baseline window. |
conditions |
Character vector of condition labels. |
baseline_pupil |
Baseline pupil level in millimetres. |
response_amplitude |
Peak amplitude of the common simulated response. |
condition_difference |
Additional peak amplitude in the second condition. For more than two conditions it is multiplied by the zero-based condition index. |
peak_latency |
Time of the simulated waveform peak in seconds. |
participant_sd, item_sd
|
Standard deviations for simulated hierarchy. |
residual_sd |
Innovation standard deviation. |
ar1 |
AR(1) residual coefficient with absolute value below one. |
blink_trial_probability |
Probability that a trial contains one synthetic blink/data-loss interval. |
blink_duration |
Blink interval duration in seconds. |
include_gaze, include_luminance
|
Whether to add nuisance signals. |
gaze_drift_sd |
Standard deviation of gaze drift increments. |
luminance_amplitude |
Amplitude of the synthetic luminance nuisance. |
seed |
Reproducibility seed. |
max_rows |
Maximum allowed output rows. |
A gp3bayes_pupil_simulation containing data and separate truth.
The waveform is a convenient synthetic data-generating shape, not a claim about a universal biological pupil response.
sim <- simulate_pupil_timecourse( n_participants = 4, trials_per_participant = 4, sampling_frequency = 20, seed = 2026 ) head(sim$data)sim <- simulate_pupil_timecourse( n_participants = 4, trials_per_participant = 4, sampling_frequency = 20, seed = 2026 ) head(sim$data)
Builds the 0.5 advanced model contract without compiling or fitting Stan. The function is additive to the frozen 0.4 API: it consumes the same prepared pupil data but returns a distinct advanced specification.
specify_advanced_pupil_timecourse_model( prepared, temporal_structure = c("smooth", "linear", "gaussian_process"), family = c("gaussian", "student"), residual_scale = c("constant", "condition", "time", "condition_time"), distribution = NULL, smooth_basis_dimension = 10L, gp_spec = create_pupil_gp_spec(), condition_trajectory = NULL, autocorrelation = c("none", "ar1", "ar2", "arma11"), participant_trajectory = c("none", "factor_smooth"), item_effects = NULL, covariates = character(), measurement_model = NULL, missingness_model = NULL, prior_scales = NULL, predictive_target = c("new_trial_known_participant", "new_participant", "future_segment", "new_sample_known_trial"), allow_high_complexity = FALSE )specify_advanced_pupil_timecourse_model( prepared, temporal_structure = c("smooth", "linear", "gaussian_process"), family = c("gaussian", "student"), residual_scale = c("constant", "condition", "time", "condition_time"), distribution = NULL, smooth_basis_dimension = 10L, gp_spec = create_pupil_gp_spec(), condition_trajectory = NULL, autocorrelation = c("none", "ar1", "ar2", "arma11"), participant_trajectory = c("none", "factor_smooth"), item_effects = NULL, covariates = character(), measurement_model = NULL, missingness_model = NULL, prior_scales = NULL, predictive_target = c("new_trial_known_participant", "new_participant", "future_segment", "new_sample_known_trial"), allow_high_complexity = FALSE )
prepared |
A prepared 0.4 pupil object or compatible data frame. |
temporal_structure |
|
family |
|
residual_scale |
Residual-scale model: constant, condition, time, or condition-by-time. |
distribution |
Optional object from |
smooth_basis_dimension |
Basis dimension for smooth mean trajectories. |
gp_spec |
A GP configuration from |
condition_trajectory |
Whether condition-specific trajectories are included. Defaults to TRUE when a condition column exists. |
autocorrelation |
One of |
participant_trajectory |
|
item_effects |
Include a random item intercept when an item column exists. |
covariates |
Additional declared covariates. |
measurement_model |
Optional known-uncertainty declaration. |
missingness_model |
Optional MAR-oriented missingness declaration. |
prior_scales |
Optional named numeric prior-scale overrides. |
predictive_target |
Declared prediction target inherited from the 0.4 validation vocabulary. |
allow_high_complexity |
Permit specifications flagged by the complexity audit. This is an explicit opt-in, not automatic model approval. |
A gp3bayes_pupil_advanced_specification object.
Combines prepared binary data, a successful readiness audit, the restricted hierarchical formula, and validated family-specific priors. The returned object is not executable and performs no model fitting.
specify_binary_model( prepared, baseline = 0.5, intercept_scale = 1.5, coefficient_scale = 0.75, group_sd_scale = 1, correlation_eta = 2, student_df = 3 )specify_binary_model( prepared, baseline = 0.5, intercept_scale = 1.5, coefficient_scale = 0.75, group_sd_scale = 1, correlation_eta = 2, student_df = 3 )
prepared |
A |
baseline |
Plausible baseline event probability. |
intercept_scale |
Optional scale for the normal intercept prior. |
coefficient_scale |
Optional common scale for normal population-level coefficient priors, including the approved interaction. |
group_sd_scale |
Scale for half-Student-t group standard deviations. |
correlation_eta |
LKJ shape used when a random slope is requested. |
student_df |
Degrees of freedom for half-Student-t scale priors. |
The specification retains the prepared data because backend-independent prior predictive simulation must reproduce the declared design. It contains no backend object, posterior draws, or fitted model.
A gp3bayes_binary_model_specification that also inherits from
gp3bayes_model_specification.
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 ) specificationsimulation <- 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 ) specification
Retains the approved binary model contract while recording a common main-effect prior scale and a narrower coefficient-specific interaction prior scale.
specify_binary_model_with_interaction_prior( prepared, baseline, intercept_scale = 1.5, main_effect_scale = 0.75, interaction_scale = 0.5, group_sd_scale = 1, correlation_eta = 2, student_df = 3 )specify_binary_model_with_interaction_prior( prepared, baseline, intercept_scale = 1.5, main_effect_scale = 0.75, interaction_scale = 0.5, group_sd_scale = 1, correlation_eta = 2, student_df = 3 )
prepared |
A |
baseline |
Plausible baseline event probability. |
intercept_scale |
Intercept-prior scale. |
main_effect_scale |
Common population main-effect prior scale. |
interaction_scale |
Interaction prior scale. |
group_sd_scale |
Group-level standard-deviation prior scale. |
correlation_eta |
LKJ shape. |
student_df |
Student-t degrees of freedom. |
A binary model specification with advanced prior metadata.
Specify a joint binocular pupil model
specify_binocular_pupil_model( prepared, temporal_structure = c("smooth", "linear", "gaussian_process"), family = c("gaussian", "student"), smooth_basis_dimension = 10L, gp_spec = create_pupil_gp_spec(), residual_correlation = TRUE, item_effects = NULL, prior_scales = NULL, allow_high_complexity = FALSE )specify_binocular_pupil_model( prepared, temporal_structure = c("smooth", "linear", "gaussian_process"), family = c("gaussian", "student"), smooth_basis_dimension = 10L, gp_spec = create_pupil_gp_spec(), residual_correlation = TRUE, item_effects = NULL, prior_scales = NULL, allow_high_complexity = FALSE )
prepared |
A binocular prepared object. |
temporal_structure |
Mean trajectory type. |
family |
Gaussian or Student-t for both eyes. |
smooth_basis_dimension |
Requested smooth basis dimension; when omitted, an unsupported default is conservatively reduced to observed temporal support, while explicitly unsupported values are rejected. |
gp_spec |
GP configuration when requested. |
residual_correlation |
Whether to estimate left/right residual correlation. |
item_effects |
Include item random intercepts when available. |
prior_scales |
Optional prior-scale overrides. |
allow_high_complexity |
Explicit computational opt-in for exact GP on large time grids. |
A gp3bayes_binocular_pupil_specification object.
Combines prepared positive-duration data with the approved hierarchical lognormal formula and explicit prior specification.
specify_duration_model( prepared, baseline, intercept_scale = 1, coefficient_scale = 0.5, group_sd_scale = 1, residual_scale = 1, correlation_eta = 2, student_df = 3 )specify_duration_model( prepared, baseline, intercept_scale = 1, coefficient_scale = 0.5, group_sd_scale = 1, residual_scale = 1, correlation_eta = 2, student_df = 3 )
prepared |
A |
baseline |
Plausible baseline median in the prepared outcome unit. |
intercept_scale |
Positive normal-intercept prior scale. |
coefficient_scale |
Positive population-coefficient prior scale. |
group_sd_scale |
Positive group standard-deviation prior scale. |
residual_scale |
Positive lognormal residual-scale prior scale. |
correlation_eta |
LKJ shape for an approved random slope. |
student_df |
Degrees of freedom for half-Student-t scale priors. |
A gp3bayes_duration_model_specification.
Uses the candidate duration defaults of 0.35 for population main effects and 0.25 for the approved two-way interaction.
specify_duration_model_with_interaction_prior( prepared, baseline, intercept_scale = 1, main_effect_scale = 0.35, interaction_scale = 0.25, group_sd_scale = 0.5, residual_scale = 0.5, correlation_eta = 2, student_df = 3 )specify_duration_model_with_interaction_prior( prepared, baseline, intercept_scale = 1, main_effect_scale = 0.35, interaction_scale = 0.25, group_sd_scale = 0.5, residual_scale = 0.5, correlation_eta = 2, student_df = 3 )
prepared |
A |
baseline |
Plausible baseline median in the recorded outcome unit. |
intercept_scale |
Intercept-prior scale. |
main_effect_scale |
Common population main-effect prior scale. |
interaction_scale |
Interaction prior scale. |
group_sd_scale |
Group-level standard-deviation prior scale. |
residual_scale |
Lognormal residual-scale prior scale. |
correlation_eta |
LKJ shape. |
student_df |
Student-t degrees of freedom. |
A duration model specification with advanced prior metadata.
Declare an advanced pupil observation distribution
specify_pupil_distribution( family = c("gaussian", "student"), residual_scale = c("constant", "condition", "time", "condition_time") )specify_pupil_distribution( family = c("gaussian", "student"), residual_scale = c("constant", "condition", "time", "condition_time") )
family |
Gaussian or Student-t. |
residual_scale |
Constant, condition-, time-, or condition-by-time scale. |
A gp3bayes_pupil_distribution_spec object.
Uses a smooth asymmetric gated response: baseline + exp(log_amplitude) * logistic((time-onset)/exp(log_rise)) * logistic((onset+exp(log_duration)-time)/exp(log_decay)).
specify_pupil_response_shape_model( prepared, family = c("gaussian", "student"), condition_effects = c("amplitude", "onset", "duration"), participant_effects = c("baseline", "amplitude"), covariates = character(), prior_scales = NULL )specify_pupil_response_shape_model( prepared, family = c("gaussian", "student"), condition_effects = c("amplitude", "onset", "duration"), participant_effects = c("baseline", "amplitude"), covariates = character(), prior_scales = NULL )
prepared |
A prepared pupil object or compatible data frame. |
family |
Gaussian or Student-t. |
condition_effects |
Character subset of |
participant_effects |
Character subset of |
covariates |
Additional covariates for baseline only. |
prior_scales |
Optional named positive numeric prior-scale overrides. |
Condition effects can enter log-amplitude, onset, and log-duration. This is a deliberately single, inspectable response family rather than an arbitrary nonlinear-formula interface.
A gp3bayes_pupil_response_shape_specification object.
Constructs an inspectable, closed-set Gaussian model specification. Users cannot supply a raw formula or arbitrary family.
specify_pupil_timecourse_model( prepared, temporal_structure = c("smooth", "linear"), smooth_basis_dimension = 10L, condition_trajectory = NULL, autocorrelation = c("ar1", "none"), participant_trajectory = c("none", "factor_smooth"), item_effects = NULL, covariates = character(), prior_scales = NULL )specify_pupil_timecourse_model( prepared, temporal_structure = c("smooth", "linear"), smooth_basis_dimension = 10L, condition_trajectory = NULL, autocorrelation = c("ar1", "none"), participant_trajectory = c("none", "factor_smooth"), item_effects = NULL, covariates = character(), prior_scales = NULL )
prepared |
A |
temporal_structure |
|
smooth_basis_dimension |
Basis dimension for approved smooth terms. |
condition_trajectory |
|
autocorrelation |
|
participant_trajectory |
|
item_effects |
|
covariates |
Character vector of already-declared numeric nuisance covariates in the prepared data. |
prior_scales |
Optional named positive scale values. Required for pixels and arbitrary units. |
A gp3bayes_pupil_model_specification.
Defaults are unit-aware weak regularizers for physical millimetres/metres and declared transformed scales. Pixel and arbitrary-unit outcomes require user-declared prior scales because tracker-specific units are not interchangeable.
No unrestricted formula, likelihood family, smooth, autocorrelation order, or backend argument is accepted.
sim <- simulate_pupil_timecourse( n_participants = 3, trials_per_participant = 3, sampling_frequency = 20, seed = 2 ) contract <- create_pupil_contract( "pupil_mm", "participant_id", "trial_id", "event_time", "millimetres", 20, condition_col = "condition" ) prepared <- prepare_pupil_timecourse(sim$data, contract) specify_pupil_timecourse_model(prepared, autocorrelation = "none")sim <- simulate_pupil_timecourse( n_participants = 3, trials_per_participant = 3, sampling_frequency = 20, seed = 2 ) contract <- create_pupil_contract( "pupil_mm", "participant_id", "trial_id", "event_time", "millimetres", 20, condition_col = "condition" ) prepared <- prepare_pupil_timecourse(sim$data, contract) specify_pupil_timecourse_model(prepared, autocorrelation = "none")
Identifies participants or items whose observed binary outcomes are all zero or all one. Such groups are retained and reported; they are not deleted.
summarise_binary_group_variation( data, contract, group = c("participant", "item") )summarise_binary_group_variation( data, contract, group = c("participant", "item") )
data |
A data frame. |
contract |
An approved binary model contract. |
group |
Either |
A gp3bayes_binary_group_variation object.
Reports posterior location, uncertainty intervals, R-hat, effective sample sizes, probability of a positive coefficient, and odds-ratio transforms for population-level coefficients.
summarise_binary_posterior(fit, probability = 0.95, variables = NULL)summarise_binary_posterior(fit, probability = 0.95, variables = NULL)
fit |
A |
probability |
Central posterior interval probability. |
variables |
Optional supported posterior variable names. |
Probability-positive values and intervals are descriptive posterior summaries. They are not frequentist significance tests and do not establish causal or substantive validity.
A gp3bayes_binary_posterior_summary.
Computes the observed proportion of each focal-condition level and applies explicit review and failure thresholds. The thresholds are workflow thresholds, not universal statistical laws.
summarise_condition_balance( data, contract, warning_fraction = 0.1, failure_fraction = 0.02 )summarise_condition_balance( data, contract, warning_fraction = 0.1, failure_fraction = 0.02 )
data |
A data frame. |
contract |
An approved model contract. |
warning_fraction |
Minimum condition fraction below which review is requested. |
failure_fraction |
Minimum condition fraction below which the strict readiness gate fails. |
A gp3bayes_condition_balance object.
Reports posterior location, uncertainty, diagnostics, and multiplicative duration-ratio transforms for population-level coefficients.
summarise_duration_posterior(fit, probability = 0.95, variables = NULL)summarise_duration_posterior(fit, probability = 0.95, variables = NULL)
fit |
A |
probability |
Central posterior interval probability. |
variables |
Optional supported posterior variable names. |
Exponentiating a population-level coefficient gives its conditional multiplicative effect on the median duration under the approved lognormal model. This is not automatically a causal effect.
A gp3bayes_duration_posterior_summary.
Summarise Posterior Estimand Draws
summarise_estimand_draws(x, quantities = NULL, probs = c(0.025, 0.5, 0.975))summarise_estimand_draws(x, quantities = NULL, probs = c(0.025, 0.5, 0.975))
x |
A |
quantities |
Optional estimand-draw columns to summarise. |
probs |
Three probabilities defining lower, middle, and upper summaries. |
A data frame.
Summarise MCMC Quality Evidence
summarise_mcmc_quality(fit, ...)summarise_mcmc_quality(fit, ...)
fit |
A fitted |
... |
Threshold arguments passed to |
A gp3bayes_mcmc_quality object containing parameter and sampler
diagnostic evidence. It is a review object, not an adequacy certificate.
Family-neutral wrapper around summarise_binary_posterior() and
summarise_duration_posterior().
summarise_model_posterior(fit, ...)summarise_model_posterior(fit, ...)
fit |
A |
... |
Family-specific diagnostic arguments. |
A family-specific gp3bayes posterior summary.
Returns posterior location, uncertainty, R-hat, and ESS evidence for model parameters without converting them into psychological constructs.
summarise_pupil_posterior(fit, probability = 0.95)summarise_pupil_posterior(fit, probability = 0.95)
fit |
A fitted pupil model. |
probability |
Credible interval probability. |
A gp3bayes_pupil_posterior_summary.
# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.
Summarise an SBC Result
summarise_sbc_result(x)summarise_sbc_result(x)
x |
A |
A conservative summary list.
Summarise a Sensitivity Suite
summarise_sensitivity_suite(x)summarise_sensitivity_suite(x)
x |
A |
A component-level data frame.
gp3bayes Publication Theme
theme_gp3bayes(base_size = 11, base_family = "")theme_gp3bayes(base_size = 11, base_family = "")
base_size |
Base font size. |
base_family |
Base font family. |
A ggplot2 theme.
if (requireNamespace("ggplot2", quietly = TRUE)) theme_gp3bayes()if (requireNamespace("ggplot2", quietly = TRUE)) theme_gp3bayes()
Translate an advanced pupil model to brms without fitting
translate_advanced_pupil_model_to_brms(specification)translate_advanced_pupil_model_to_brms(specification)
specification |
An advanced pupil specification. |
A gp3bayes_pupil_advanced_brms_specification object containing the
brms formula, family, priors, and translated data.
Converts an approved backend-independent binary specification into a
restricted brms representation. The formula, Bernoulli-logit family, and
priors are derived entirely from the existing gp3bayes specification.
translate_binary_model_to_brms(specification)translate_binary_model_to_brms(specification)
specification |
A |
This function performs translation and prior validation only. It does not compile Stan code, run MCMC, create posterior draws, or assess convergence. Users cannot supply an alternative formula, family, backend, algorithm, or arbitrary backend arguments.
A gp3bayes_binary_backend_specification containing the restricted
formula, family, translated priors, validated prior table, and backend
metadata.
if (requireNamespace("brms", quietly = TRUE)) { simulation <- simulate_hierarchical_binary_data( n_participants = 12, trials_per_participant = 8, n_items = 6, 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 ) translate_binary_model_to_brms(specification) }if (requireNamespace("brms", quietly = TRUE)) { simulation <- simulate_hierarchical_binary_data( n_participants = 12, trials_per_participant = 8, n_items = 6, 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 ) translate_binary_model_to_brms(specification) }
Translate an Advanced Binary Specification to brms
translate_binary_model_with_interaction_prior(specification)translate_binary_model_with_interaction_prior(specification)
specification |
An advanced binary specification. |
A validated restricted brms translation.
Translate a binocular specification to a brms multivariate formula
translate_binocular_pupil_model_to_brms(specification)translate_binocular_pupil_model_to_brms(specification)
specification |
A binocular specification. |
A gp3bayes_binocular_brms_specification object.
Converts an approved backend-independent duration specification into a fixed
hierarchical lognormal brms representation.
translate_duration_model_to_brms(specification)translate_duration_model_to_brms(specification)
specification |
A |
Translation validates the formula and priors but does not compile Stan code or fit a model. Users cannot supply an alternative family, formula, backend, algorithm, Stan extension, or arbitrary backend arguments.
A gp3bayes_duration_backend_specification.
Translate an Advanced Duration Specification to brms
translate_duration_model_with_interaction_prior(specification)translate_duration_model_with_interaction_prior(specification)
specification |
An advanced duration specification. |
A validated restricted brms translation.
Creates a fixed Gaussian brms representation without compiling or fitting.
translate_pupil_model_to_brms(specification)translate_pupil_model_to_brms(specification)
specification |
A pupil model specification. |
A gp3bayes_pupil_brms_translation.
# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.
Translate the experimental response-shape model to brms
translate_pupil_response_shape_to_brms(specification)translate_pupil_response_shape_to_brms(specification)
specification |
A response-shape specification. |
A backend-independent brms translation object.
Validate an Analysis Manifest
validate_analysis_manifest(manifest, strict = FALSE)validate_analysis_manifest(manifest, strict = FALSE)
manifest |
A |
strict |
Whether failures should raise an error. |
A gp3bayes_manifest_validation.
Checks whether the packages and external runtime required by one approved
gp3bayes backend are available. With compile_test = TRUE, an optional
minimal compiler smoke test is performed. The smoke test does not fit a
statistical model and writes no persistent files.
validate_backend_environment( backend = c("rstan", "cmdstanr"), compile_test = FALSE, strict = FALSE )validate_backend_environment( backend = c("rstan", "cmdstanr"), compile_test = FALSE, strict = FALSE )
backend |
Either |
compile_test |
Whether to run an optional compiler smoke test. |
strict |
Whether an unavailable backend should raise an error. |
A gp3bayes_backend_environment object.
validate_backend_environment("rstan") validate_backend_environment("cmdstanr")validate_backend_environment("rstan") validate_backend_environment("cmdstanr")
Performs lightweight structural validation for gp3bayes contracts, prepared data, specifications, fits, summaries, diagnostics, manifests, design audits, sensitivity suites, evidence collections, and backend reliability objects. The function checks object structure only; it does not establish statistical adequacy or substantive validity.
validate_gp3bayes_object(x, recursive = TRUE, strict = FALSE)validate_gp3bayes_object(x, recursive = TRUE, strict = FALSE)
x |
A gp3bayes object. |
recursive |
Whether nested contract/specification/prepared objects should also be checked when present. |
strict |
Whether a failed structural check should raise an error. |
A gp3bayes_object_validation object.
Validate an Object Against a Frozen gp3bayes Schema
validate_gp3bayes_schema(x, schema, strict = FALSE, compare_lengths = FALSE)validate_gp3bayes_schema(x, schema, strict = FALSE, compare_lengths = FALSE)
x |
A gp3bayes object. |
schema |
A |
strict |
Whether structural drift should raise an error. |
compare_lengths |
Whether analysis-specific object lengths should be required to match the frozen schema. |
A gp3bayes_schema_validation object.
Validates the completeness and internal consistency of a
gp3bayes_prior_specification.
validate_prior_specification(priors, contract = NULL)validate_prior_specification(priors, contract = NULL)
priors |
A |
contract |
Optional |
priors, invisibly.
Validate a Publication Registry
validate_publication_registry(x)validate_publication_registry(x)
x |
A publication registry. |
A validation object.
Execute or materialize leave-future-out validation
validate_pupil_leave_future_out( fit, plan, execute = FALSE, cores = 1L, seed = 2026 )validate_pupil_leave_future_out( fit, plan, execute = FALSE, cores = 1L, seed = 2026 )
fit |
An advanced fitted model. |
plan |
An LFO plan. |
execute |
If FALSE, returns the plan without refitting. TRUE performs sequential model refits and future-block log scoring. |
cores |
Maximum cores passed to brms update; restricted to 2. |
seed |
Base seed for refits. |
A gp3bayes_pupil_lfo_validation object.
Executes exact target-specific K-fold through brms::kfold() for K-fold
targets, or a finite leave-future-segment refit for the future target.
Execution is opt-in because it can be computationally expensive.
validate_pupil_model( fit, plan, execute = FALSE, ndraws = 200L, max_cells = 3000000L )validate_pupil_model( fit, plan, execute = FALSE, ndraws = 200L, max_cells = 3000000L )
fit |
A fitted pupil model. |
plan |
A pupil validation plan. |
execute |
Whether to execute refitting. |
ndraws |
Draws retained for finite future-segment prediction scoring. |
max_cells |
Memory guard for future-segment predictions. |
A gp3bayes_pupil_validation.
# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.# See vignette("bayesian-dynamic-pupillometry", package = "gp3bayes") for a complete workflow.
Round-trips the prepared data through the recorded inverse and forward transformation and compares transformed columns and fixed-effect matrices.
validate_transformation_replay(prepared, tolerance = 1e-10)validate_transformation_replay(prepared, tolerance = 1e-10)
prepared |
A binary or duration prepared object. |
tolerance |
Numeric comparison tolerance. |
A gp3bayes_transformation_replay_audit.
Variance-Component Posterior Table
variance_component_table(fit, probs = c(0.025, 0.5, 0.975))variance_component_table(fit, probs = c(0.025, 0.5, 0.975))
fit |
A fitted |
probs |
Three posterior interval probabilities. |
A posterior summary table for group SDs, correlations, and residual scale where applicable.
Write an Analysis-Bundle Markdown Report
write_analysis_bundle_report(x, file)write_analysis_bundle_report(x, file)
x |
A |
file |
Explicit output file path. |
Invisibly, the normalized output path.
Write a Diagnostic Dashboard Report
write_diagnostic_dashboard_report(x, file, overwrite = FALSE)write_diagnostic_dashboard_report(x, file, overwrite = FALSE)
x |
A diagnostic dashboard. |
file |
Explicit Markdown output path. |
overwrite |
Whether an existing file may be replaced. |
Invisibly, normalized output path.
Write a Model Card
write_model_card(x, file, overwrite = FALSE)write_model_card(x, file, overwrite = FALSE)
x |
A |
file |
Explicit Markdown output path. |
overwrite |
Whether an existing file may be replaced. |
Invisibly, the normalized written path.
Write a Publication Registry
write_publication_registry(x, file, overwrite = FALSE)write_publication_registry(x, file, overwrite = FALSE)
x |
A publication registry. |
file |
Explicit Markdown output path. |
overwrite |
Whether an existing file may be replaced. |
Invisibly, the normalized output path.
Writes a conservative Markdown provenance report to an explicit path.
write_reproducibility_report(manifest, file, overwrite = FALSE)write_reproducibility_report(manifest, file, overwrite = FALSE)
manifest |
An analysis manifest. |
file |
Explicit Markdown output path. |
overwrite |
Whether an existing file may be replaced. |
The normalized output path, invisibly.