Setup Guide

This guide is for participants. Complete it before the workshop if possible.

Use this page as a pre-workshop readiness checklist. The goal is not merely to install packages, but to confirm that R, Quarto, CmdStan, and the workshop project can all work together before Bayesian model fitting begins.

Required Software Copy-and-Paste Mode Install R Packages Common Problems Fallback Plan

Required Software

Install in this order:

  1. R, version 4.3 or later.
  2. RTools (Windows only) — must match your R version: RTools43 for R 4.3.x, RTools44 for R 4.4.x. Without RTools, Stan model compilation will fail. Download: https://cran.r-project.org/bin/windows/Rtools/
  3. RStudio Desktop or Positron, recommended if you want a notebook editor.
  4. Quarto, required only if you want to render the .qmd notebooks locally.
  5. CmdStan, installed from R through cmdstanr (covered below).

After installing R, RTools, and Quarto on Windows, close and reopen PowerShell so the new programs appear on your PATH.

Choose a Workshop Folder (Windows)

On Windows, clone or unzip the workshop materials to a short path outside OneDrive, for example C:\workshops\BayesianAnalysis or %USERPROFILE%\BayesianAnalysis. Paths inside OneDrive\Documents\... can break Stan compilation because of path-length limits and OneDrive file-sync locks.

Copy-and-Paste Mode for R GUI

If you are using the rendered HTML notebooks and copying code into R GUI, you do not need RStudio to run the R code. RStudio or Positron is more convenient, but R GUI can run the snippets as long as the setup is correct.

Before copying notebook code, open R GUI and set the working folder to the workshop folder. On Windows, use File > Change dir… and choose the BayesianAnalysis folder. You can also run a command like this, changing the path to match your computer:

setwd("C:/workshops/BayesianAnalysis")

Check that R can see the workshop files:

file.exists("data/education_intervention.csv")
file.exists("setup/test_installation.R")

Both should return TRUE.

When copying code from the HTML notebooks:

  • copy only the R code inside the grey code block;
  • do not copy the Quarto markers such as ```{r} or ```;
  • run the chunks in order, because later chunks often depend on objects created earlier;
  • if a model-fitting chunk is slow, use the rendered output on the page and continue with the interpretation exercise.

You can paste directly into the R Console. If you want somewhere to hold several lines before running them, use File > New script inside R GUI. Notepad can store text, but it cannot run R code.

Install R Packages

Open R and run:

install.packages(
  c(
    "tidyverse",
    "brms",
    "tidybayes",
    "bayesplot",
    "posterior",
    "loo",
    "broom",
    "broom.mixed",
    "lme4",
    "here",
    "skimr",
    "patchwork",
    "psych"
  ),
  repos = c(CRAN = "https://cloud.r-project.org")
)

cmdstanr is not on CRAN. Install it from the Stan r-universe repository:

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

Install CmdStan itself (the underlying Stan toolchain):

cmdstanr::install_cmdstan()

On Windows, this step requires RTools to already be installed.

Check the installation:

source("setup/test_installation.R")

Common Installation Problems

CmdStan is missing

Run:

cmdstanr::install_cmdstan()

Then restart R.

C++ toolchain is missing

Bayesian models fitted with Stan need a working C++ toolchain.

On Windows, install RTools for your R version.

On macOS, install Xcode command line tools:

xcode-select --install

On Linux, install build tools through your package manager.

brms installs but models do not run

Check whether CmdStan is available:

cmdstanr::cmdstan_version()

If that fails, reinstall CmdStan:

cmdstanr::install_cmdstan()

Fallback Plan

If model fitting is slow or installation fails during the workshop:

  • follow the notebook explanations and code;
  • use the printed or rendered expected outputs;
  • work through interpretation exercises;
  • fit models later after setup is resolved.

The facilitator should keep pre-rendered outputs available for live teaching.