R Interface#

Installation#

Note

Mac users have reported issues when using a copy of R installed from conda-forge. If you encounter an issue, you may need to use R from the official R project website or a system package manager like brew.

From inside R#

While BridgeStan is not available on CRAN, it is mirrored by the R-Multiverse project and can be installed as follows:

install.packages(
  "bridgestan",
  repos = c("https://community.r-multiverse.org", getOption("repos"))
)

Alternatively, you can install the R package from the source code on Github using the remotes package:

remotes::install_github("https://github.com/roualdes/bridgestan", subdir="R")

To install a specific version of BridgeStan you can use the argument ref, for example, ref="v2.8.0".

The first time you compile a model, the BridgeStan source code for your current version will be downloaded and placed in :file:~/.bridgestan/. If you prefer to use a source distribution of BridgeStan, consult the following section.

Note that the system pre-requisites from the Getting Started guide are still required and will not be automatically installed by this method.

From Source#

This assumes you have followed the Getting Started guide to install BridgeStan’s pre-requisites and downloaded a copy of the BridgeStan source code.

To install the R package from the source code, run:

install.packages(file.path(getwd(),"R"), repos=NULL, type="source")

from the BridgeStan folder.

To use the BridgeStan source you’ve manually downloaded instead of one the package will download for you, you must use set_bridgestan_path() or the $BRIDGESTAN environment variable.

Note that the R package depends on R 3+ and R6, and will install R6 if it is not already installed.

Example Program#

An example program is provided alongside the R interface code in example.R:

Show example.R 
# Before running this, make sure you are in the directory bridgestan/R

library(bridgestan)

model <- StanModel$new(
  "../test_models/bernoulli/bernoulli.stan",
  "../test_models/bernoulli/bernoulli.data.json",
  1234
)

print(paste0("This model's name is ", model$name(), "."))
print(paste0("This model has ", model$param_num(), " parameters."))


x <- runif(model$param_unc_num())
q <- log(x / (1 - x))

res <- model$log_density_gradient(q, jacobian = FALSE)

print(paste0(
  "log_density and gradient of Bernoulli model: ",
  res$val,
  ", ",
  res$gradient
))

API Reference#

StanModel#

Description#

R6 Class representing a compiled BridgeStan model.

This model exposes log density, gradient, and Hessian information as well as constraining and unconstraining transforms.

Methods#

#

Compilation utilities#

Function compile_model()#

compile_model(stan_file, stanc_args = NULL, make_args = NULL)

Arguments#

  • stan_file: A path to a Stan model file.

  • make_args: A vector of additional arguments to pass to Make. For example, c('STAN_THREADS=True') will enable threading for the compiled model. If the same flags are defined in make/local, the versions passed here will take precedent.

  • stanc_arg: A vector of arguments to pass to stanc3. For example, c('--O1') will enable compiler optimization level 1.

Returns#

Path to the compiled model.

Description#

Compiles a Stan model.

Details#

Run BridgeStan’s Makefile on a .stan file, creating the .so used by the StanModel class. This function checks that the path to BridgeStan is valid and will error if not. This can be set with set_bridgestan_path.

See Also#

set_bridgestan_path()

Function set_bridgestan_path()#

set_bridgestan_path(path)

Description#

Set the path to BridgeStan.

Details#

This should point to the top-level folder of the repository.