---
title: "Optional Bayesian Backend Installation"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Optional Bayesian Backend Installation}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

## 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.

```{r core-installation, eval=FALSE}
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:

```{r rstan-packages, eval=FALSE}
install.packages(
  c(
    "brms",
    "rstan",
    "posterior",
    "bayesplot"
  )
)
```

For the `cmdstanr` route, install the common packages first:

```{r cmdstanr-common-packages, eval=FALSE}
install.packages(
  c(
    "brms",
    "posterior",
    "bayesplot"
  )
)
```

Then install CmdStanR from the Stan R-universe repository:

```{r cmdstanr-installation, eval=FALSE}
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:

```{r windows-build-tools, eval=FALSE}
pkgbuild::has_build_tools(
  debug = TRUE
)
```

The result should be `TRUE`.

For `cmdstanr`, additionally run:

```{r cmdstanr-preflight, eval=FALSE}
cmdstanr::check_cmdstan_toolchain()
check_cmdstan_backend(strict = TRUE)
```

## Backend preflight

```{r backend-capabilities, eval=FALSE}
bayesian_backend_capabilities()
```

For `rstan`:

```{r rstan-preflight, eval=FALSE}
stopifnot(
  requireNamespace("brms", quietly = TRUE),
  requireNamespace("rstan", quietly = TRUE),
  requireNamespace("posterior", quietly = TRUE)
)
```

For `cmdstanr`:

```{r cmdstanr-namespace-preflight, eval=FALSE}
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.

```{r compilation-smoke, eval=FALSE}
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.

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