Install and Setup (Windows / RStudio)

Audience

Windows users running dsambayesplus through RStudio (or VS Code) on a work-issued machine without full administrator rights. If you use Linux or macOS, or you are comfortable with a Unix shell, use Install and Setup instead; this page only covers the parts that differ on Windows.

This page assumes no prior bash experience. Every command below runs from the RStudio Console or an RStudio Terminal tab.

For R API use, confirm the toolchain in step 1, then follow Install and update the R package. That route uses a short standalone helper and your personal credentials; it does not need the full repository. Steps 2 onward below are for repository runners, bundled examples and development.

Before you start

  • R >= 4.1 and RStudio Desktop. Both installers offer a per-user “Just Me” install mode that does not require administrator rights. If the installer still requests admin rights on your machine, or blocks silently, ask your IT team to install R and RStudio; both are standard enterprise packages.
  • For repository runners only: install Git for Windows and clone the private repository using an authenticated Git client, or RStudio’s **File > New Project

    Version Control > Git** with https://github.com/tandpds/dsambayesplus.git. Open the checkout as your RStudio project. A ZIP is a fixed snapshot; it cannot fetch later changes. See checkout updates.

1. Confirm R and the C++ toolchain

In the RStudio Console:

R.version.string

Confirm the version is 4.1 or later.

Stan compilation needs a C++ toolchain. On Windows, select Rtools for your installed R version using the compatibility table on its download page.

  1. Download and run the Rtools installer for your R version.
  2. Restart RStudio.
  3. Verify the toolchain is detected:
if (!requireNamespace("pkgbuild", quietly = TRUE)) install.packages("pkgbuild")
pkgbuild::has_build_tools(debug = TRUE)

Expected: TRUE. If this returns FALSE and you cannot complete the Rtools install yourself (some configurations need admin rights to register the toolchain on PATH), ask your IT team to install Rtools for your R version.

2. Set up the environment (no bash required)

The Linux/macOS setup uses a bash helper (scripts/r-library-path.sh) to select a repo-local package library and Stan cache directory. RStudio on Windows does not need bash for this: the same result is achieved with R code, run automatically at the start of every session.

Add a file named .Rprofile in the repository root (if one does not already exist) containing:

# Repo-local, R-version-specific package library and Stan cache.
# Mirrors scripts/r-library-path.sh for Windows/RStudio sessions.
repo_root <- normalizePath(getwd(), winslash = "/", mustWork = TRUE)
r_version <- as.character(getRversion())

Sys.setenv(R_LIBS_USER = file.path(repo_root, paste0(".Rlib-host-r", r_version)))
Sys.setenv(XDG_CACHE_HOME = file.path(repo_root, ".cache"))

dir.create(Sys.getenv("R_LIBS_USER"), recursive = TRUE, showWarnings = FALSE)
.libPaths(c(Sys.getenv("R_LIBS_USER"), .libPaths()))
dir.create(Sys.getenv("XDG_CACHE_HOME"), recursive = TRUE, showWarnings = FALSE)

Then restart R so RStudio picks it up: Session > Restart R.

The .libPaths() call makes the new library active in the current session; setting R_LIBS_USER inside .Rprofile alone is insufficient. If the project uses renv, use its library activation instead of this snippet. Do not add installation or update calls to .Rprofile.

This keeps the package library and Stan cache inside the repository folder, avoiding permission issues on a locked-down system library, exactly like the Linux/macOS setup. Do not commit .Rprofile if it contains anything machine-specific beyond the snippet above; the repository’s .gitignore already excludes .Rlib-* and .cache.

Where to place the repository: put it under a local, writable folder such as C:\Users\<you>\Documents\dsambayesplus, not a network drive or a folder your IT policy marks read-only. A network drive with a deep path is a common source of “permission denied” and Windows path-length errors.

3. Install dsambayesplus from the local checkout

With the project open in RStudio (so the working directory is the repository root) and R restarted after step 2:

if (!requireNamespace("remotes", quietly = TRUE)) install.packages("remotes")
remotes::install_local(".", dependencies = NA, upgrade = "never")

4. Updates and personal GitHub credentials

Follow Install and update the R package for the package-only helper, credential setup and project version management. For this checkout workflow, follow that page’s Git update instructions, then restart R and reinstall the selected local checkout using step 3. Refreshing the installed package alone does not refresh runme.R or bundled configs.

5. Verify the installation

library(dsambayesplus)
cat("Version:", as.character(utils::packageVersion("dsambayesplus")), "\n")

6. Run the CLI runner from RStudio

Open Tools > Terminal > New Terminal. This opens a terminal already positioned at the repository root, whether RStudio is configured to use Git Bash, PowerShell, or Command Prompt on your machine (Tools > Global Options > Terminal shows and changes which one). The Rscript command below is identical in all three:

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

Expected: validation completes without errors. Then run the full example:

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

Expected: a timestamped run directory appears under results/ in the RStudio Files pane.

7. Inspect results

Browse results/<run_dir>/ in the RStudio Files pane, or load the fitted model directly in the Console:

model <- readRDS("results/<run_dir>/20_model_fit/model.rds")

Continue with Quickstart (YAML Runner) for the full walkthrough of the staged output.

Troubleshooting

pkgbuild::has_build_tools() returns FALSE

Rtools is missing, is the wrong version for your installed R, or was not registered on PATH. Reinstall Rtools matching R.version.string, restart RStudio, and check again. If that still fails, ask your IT team; some machine configurations restrict PATH changes to admin accounts.

Package or GitHub install fails with a network error

Check credentials and repository access first. A proxy or firewall may also block the CRAN mirror, GitHub API or archive downloads. Ask IT to check the failing URL in the error. A local checkout avoids downloading package source from GitHub, but missing dependencies still require network access.

“Permission denied” writing to the library or cache folder

The repository is on a network drive or a folder your IT policy marks read-only. Move (or re-clone) it to a local folder such as C:\Users\<you>\Documents\dsambayesplus and repeat step 2.

.Rprofile changes do not seem to take effect

.Rprofile only runs when R starts. Use Session > Restart R, not just re-running the file’s contents, and confirm you are working in the project whose root contains the .Rprofile file.

Errors mentioning very long file paths

Windows has a default path-length limit. Keep the repository close to a drive root (for example C:\dev\dsambayesplus) rather than several folders deep under Documents or a synced cloud-storage folder.