Optional Bayesian Backend Installation

Core installation

The package is independently useful without a Bayesian backend. Model contracts, readiness audits, deterministic simulation, preparation, specification, and prior predictive checks do not require brms, rstan, posterior, bayesplot, or a compiler.

install.packages(
  "gp3bayes",
  repos = NULL,
  type = "source"
)

Optional fitting and validation dependencies

Full-MCMC fitting uses brms with either rstan or cmdstanr. Posterior diagnostics and visualisation use posterior and bayesplot.

For the rstan route:

install.packages(
  c(
    "brms",
    "rstan",
    "posterior",
    "bayesplot"
  )
)

For the cmdstanr route, install the common packages first:

install.packages(
  c(
    "brms",
    "posterior",
    "bayesplot"
  )
)

Then install CmdStanR from the Stan R-universe repository:

install.packages(
  "cmdstanr",
  repos = c(
    "https://stan-dev.r-universe.dev",
    getOption("repos")
  )
)

cmdstanr::check_cmdstan_toolchain()
cmdstanr::install_cmdstan()

The supported fitting interface remains restricted to brms and full MCMC. gp3bayes allows rstan or cmdstanr as implementation backends but does not expose variational inference, Pathfinder, Laplace approximation, arbitrary Stan programs, arbitrary model families, or arbitrary backend arguments.

Windows toolchain check

On Windows, source compilation requires the Rtools version compatible with the installed R version. After installing Rtools, start a clean R session and run:

pkgbuild::has_build_tools(
  debug = TRUE
)

The result should be TRUE.

For cmdstanr, additionally run:

cmdstanr::check_cmdstan_toolchain()
check_cmdstan_backend(strict = TRUE)

Backend preflight

bayesian_backend_capabilities()

For rstan:

stopifnot(
  requireNamespace("brms", quietly = TRUE),
  requireNamespace("rstan", quietly = TRUE),
  requireNamespace("posterior", quietly = TRUE)
)

For cmdstanr:

stopifnot(
  requireNamespace("brms", quietly = TRUE),
  requireNamespace("cmdstanr", quietly = TRUE),
  requireNamespace("posterior", quietly = TRUE)
)

check_cmdstan_backend(strict = TRUE)

Minimal compilation smoke test

Compilation should be tested with a deliberately small synthetic model before a large analysis. Short chains may produce low effective-sample-size warnings; those warnings must not be interpreted as adequate posterior inference.

simulation <- simulate_hierarchical_binary_data(
  n_participants = 8,
  trials_per_participant = 6,
  n_items = 4,
  random_slope_sd = 0,
  seed = 7001
)

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
)

smoke_fit <- fit_binary_model_backend(
  specification,
  backend = "rstan",
  chains = 2,
  iter = 300,
  warmup = 150,
  cores = 2,
  seed = 7002,
  refresh = 0
)

A successful smoke fit confirms compilation and sampling execution only. Production analyses require adequate iterations, sampling diagnostics, posterior predictive checks, sensitivity assessment, and transparent reporting.

Clean-process package checks

After a Stan fit on Windows, run package checks and pkgdown builds in separate clean R processes. This avoids accidental inheritance of model-compilation flags from the interactive session.

Rscript --vanilla -e "devtools::check()"
Rscript --vanilla -e "pkgdown::check_pkgdown(); pkgdown::build_site(preview = FALSE)"