Install and Update the R Package

Use the standalone installer for colleagues who call dsambayesplus from R or RStudio. Downloading the whole repository is unnecessary for this workflow. Updates are explicit: run the installer before loading the package, when you intend to change versions. Do not put it in .Rprofile or a model-fitting script.

The installer needs internet access and personal read access to the private tandpds/dsambayesplus repository. It installs source packages. R >= 4.1 and a working C++ toolchain for Stan are still required; see the Windows guide or Linux/macOS guide for toolchain setup.

One-time setup

Each colleague completes this setup with their own GitHub account and token. The repository administrator grants that account read access; the colleague creates and stores their own credential. Share the installer and these instructions. Do not create a shared team token or distribute the maintainer’s personal token. Individual credentials allow access to be revoked separately.

  1. In RStudio, install the helper dependencies into your writable personal or project library:

    install.packages(c("gh", "remotes"))

  2. Create your own GitHub personal access token. Where supported by your organisation, use a fine-grained token restricted to this repository with Contents: read-only permission. Complete any required organisation approval or single sign-on authorisation. Follow your organisation’s access policy if your membership does not support fine-grained tokens.

  3. With Git installed and its credential manager configured, store the token through the interactive prompt:

    gitcreds::gitcreds_set()

    gitcreds is installed as a dependency of gh. Use the operating system’s credential manager where available. Without Git, GITHUB_PAT in your private user-level .Renviron is an alternative; restart R after editing it. An existing GITHUB_PAT or GITHUB_TOKEN can override stored credentials, so remove or replace an expired environment token if authentication still fails. Never distribute a shared token or put a token in the installer, project files, console history or Git. A token does not grant access your account lacks. See GitHub’s token guidance.

  4. Open the installer source on GitHub while signed in and save its raw contents as install_dsambayesplus.R in your working directory. Download this one file, not the repository ZIP. Review the file before sourcing it. Sourcing defines the helper; it does not install anything until you call the function.

Install or refresh

Start a fresh R session (Session > Restart R in RStudio), then run:

source("install_dsambayesplus.R")
install_dsambayesplus()
library(dsambayesplus)

The helper selects the numerically highest published vX.Y.Z software release. It excludes draft releases, prereleases and handbook releases. A Git tag alone is insufficient: it must have a published GitHub release. This policy does not use GitHub’s “latest” label or install development main. Publishing a release is the maintainer’s approval step; the helper does not validate the release’s statistical methods or software quality.

The helper resolves the tag to a commit and installs that exact commit with remotes. It skips installation if the selected version, commit and repository already match the package in the target library. A previous ZIP/local install without that provenance is reinstalled once. An explicit call can replace a development version with the selected release, including an older version. Required dependencies are installed as needed; upgrade = "never" avoids upgrading other dependencies merely because newer versions exist. This does not provide a complete dependency lock.

The output records the selected tag, commit, library and installed version. The default target is .libPaths()[1L]. To use another existing writable library, prepend it to .libPaths() before installing and loading the package. Check what R loads with find.package("dsambayesplus").

To check without installing, or deliberately select a published version:

install_dsambayesplus(check_only = TRUE)
install_dsambayesplus(ref = "v1.0.1") # Only if this software release is published.

Check-only mode may run with the package loaded. Installation requires a fresh session. Missing credentials, unavailable GitHub access or no eligible release stop the helper before installation; there is no fallback to main. An install failure stops execution rather than proceeding to load the package. Resolve the error before starting an analysis.

Keep the saved helper for future release checks. Download it again when the installer itself changes. The helper refreshes the installed package; it does not refresh its own saved source file.

Keep existing analyses reproducible

Use a project library and renv.lock for an ongoing analysis. Install a chosen release in that project, check the analysis, then record the environment with renv::snapshot(). Colleagues use renv::restore() to recover the recorded package versions. Review and snapshot an update deliberately; do not call the latest-release installer every time an existing model runs. See the renv workflow.

The lockfile records package versions and remote provenance. It does not preserve your R executable, compiler, data, credentials or model results.

When a repository checkout is needed

The installed package includes the R API, including run_from_yaml() for your own configuration files. Repository files such as runme.R, scripts/, bundled configs and example data require a separate checkout. Package updates do not update those files.

For that workflow, use Git to clone the private repository. To select a release in an existing checkout, first preserve local work and inspect git status:

git status --short
git fetch --tags origin
git switch --detach v1.0.1

Replace v1.0.1 with the published software release you intend to use. If there are local changes, resolve them before switching; do not discard them to make the command succeed. In a fresh R session using the checkout’s package library, install the selected checkout with remotes::install_local(".", dependencies = NA, upgrade = "never"). This keeps the package and repository runner on the same source version. Follow the platform setup guide for library selection. Git commands also work in an RStudio Terminal with Git installed. A downloaded ZIP is a fixed snapshot and cannot be refreshed with Git.