Install and Setup

Audience

Engineers and analysts setting up dsambayesplus for local development or modelling runs. This page is written for a Unix shell (Linux or macOS). If you are on Windows using RStudio, especially on a work-issued machine without full administrator rights, use Install and Setup (Windows / RStudio) instead.

For package API use, follow Install and update the R package. The checkout instructions below apply when you need repository runners, bundled examples or development tools. Installing the package does not require a checkout.

Prerequisites

  • R >= 4.1: check with R --version.
  • A C++ toolchain for Stan compilation. This is the most common source of setup issues:
    • macOS: install Xcode Command Line Tools (xcode-select --install).
    • Windows: install Rtools matching your R version. Ensure make is on your PATH.
    • Linux (Ubuntu/Debian): sudo apt install build-essential.
    • See the RStan Getting Started Guide for detailed platform instructions.
  • A local Git checkout of this repository for the instructions below. See checkout updates to keep its runner and installed package on the same release.

Open a terminal in the repository root and run:

# 1. Select an ABI-safe host library and create it with the cache
source scripts/r-library-path.sh
dsambayesplus_set_r_library host
mkdir -p "$R_LIBS_USER" .cache

# 2. Set the cache path (add both settings to .bashrc/.zshrc for persistence)
export XDG_CACHE_HOME="$PWD/.cache"

# 3. Install dsambayesplus from the local checkout
R -q -e 'if (!requireNamespace("remotes", quietly = TRUE)) install.packages("remotes")'
R -q -e 'remotes::install_local(".", dependencies = NA, upgrade = "never")'

This keeps all package libraries and Stan compilation caches inside the repo, avoiding permission issues with system library paths.

Do not share a compiled package library between R runtimes or containers. dsambayesplus_set_r_library host selects .Rlib-host-r<active-R-version>/; use dsambayesplus_set_r_library container inside a container instead. The path is deliberately derived from the active runtime, not hard-coded in the repository.

Verify the installation

1. Confirm dsambayesplus loads

R -q -e 'library(dsambayesplus); cat("Version:", as.character(utils::packageVersion("dsambayesplus")), "\n")'

Expected: prints the installed package version.

2. Confirm the runner works

Rscript scripts/dsambayesplus.R validate --config config/blm_timeseries.yaml

Expected: validation completes without errors.

3. (Optional) Run the test suite

R -q -e 'testthat::test_dir("tests/testthat")'

Expected: all tests pass.

Package installation without a checkout

Use the standalone release installer. It reads stored personal credentials and checks published software releases. Run it explicitly in a fresh R session before loading the package. It does not update a separate repository checkout or install development main.

Using renv (optional)

The repository includes a renv.lock file recording dependency versions. To use it:

R -q -e 'install.packages("renv"); renv::restore()'

This restores the recorded package versions, subject to source availability and platform requirements. It does not preserve R, the compiler or input data. For your own analysis, maintain a project lockfile and update it deliberately after checking an upgrade; see project version management.

Runner setup and first execution

1. Validate the example config

Rscript scripts/dsambayesplus.R validate --config config/blm_timeseries.yaml

2. Execute a full run

Rscript scripts/dsambayesplus.R run --config config/blm_timeseries.yaml

Expected: a timestamped run directory is created under results/ with model outputs and diagnostics.

Repository helper: runme.R

In a cloned checkout, runme.R is a command-line convenience wrapper around the YAML runner. Run it from a terminal; do not source it in an interactive R session.

Rscript runme.R --mode=validate --config=config/blm_timeseries.yaml

For interactive use, call dsambayesplus::run_from_yaml() directly.

Troubleshooting

Stan compilation fails

Symptom: errors during Compiling model... referencing C++ or compiler issues.

Actions:

  1. Confirm your C++ toolchain is working: R -q -e 'pkgbuild::has_build_tools(debug = TRUE)'.
  2. On Windows, ensure Rtools is installed and make is on your PATH.
  3. Clear the Stan cache and retry: rm -rf .cache/dsambayesplus.
  4. Follow the RStan Getting Started Guide for your platform.

Package installation fails

Symptom: install.packages(".", repos = NULL, type = "source") errors.

Actions:

  1. Confirm you are in the repository root directory.
  2. Confirm the selected R_LIBS_USER directory exists and is writable.
  3. Check for missing system dependencies in the error output.

Stale Stan cache

Symptom: unexpected model behaviour after updating the package.

Actions:

  1. Clear the cache: rm -rf .cache/dsambayesplus.
  2. Re-run with model.force_recompile: true in your config if you need to invalidate a stale compiled model.

Permission issues

Symptom: write failures for library, cache, or run outputs.

Actions:

  1. Ensure R_LIBS_USER, .cache, and results/ are writable.
  2. Keep R_LIBS_USER and XDG_CACHE_HOME set in your shell session.
  3. Run all commands from the repository root.