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 TinyStan is not available on CRAN, you can install the R package from the source code using the remotes package:

remotes::install_github("https://github.com/WardBrian/tinystan", subdir="clients/R")

To install a specific version of TinyStan you can use the argument ref, for example, ref="v0.1.0".

The first time you compile a model, the TinyStan source code for your current version will be downloaded and placed in :file:~/.tinystan/. If you prefer to use a source distribution of TinyStan, 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 TinyStan’s pre-requisites and downloaded a copy of the TinyStan source code.

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

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

from the TinyStan folder.

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

API Reference#

Model interface#

Class tinystan_model#

tinystan_model(lib, stanc_args = NULL, make_args = NULL, warn = TRUE)

Load a Stan model, compiling if necessary.

Examples#

data_file <- system.file('bernoulli.data.json', package = 'tinystan')
mod <- tinystan_model(system.file('bernoulli.stan', package = 'tinystan'))
fit = sampler(model = mod, data = data_file)
fit

Generic function sampler#

#### S3 method for class 'tinystan_model'
sampler(
  model,
  data = "",
  num_chains = 4,
  inits = NULL,
  seed = NULL,
  id = 1,
  init_radius = 2,
  num_warmup = 1000,
  num_samples = 1000,
  metric = HMCMetric$DIAGONAL,
  init_inv_metric = NULL,
  save_metric = FALSE,
  adapt = TRUE,
  delta = 0.8,
  gamma = 0.05,
  kappa = 0.75,
  t0 = 10,
  init_buffer = 75,
  term_buffer = 50,
  window = 25,
  save_warmup = FALSE,
  stepsize = 1,
  stepsize_jitter = 0,
  max_depth = 10,
  refresh = 0,
  num_threads = -1
)

Run Stan’s NUTS sampler

Examples#

data_file <- system.file('bernoulli.data.json', package = 'tinystan')
mod <- tinystan_model(system.file('bernoulli.stan', package = 'tinystan'))
fit = sampler(model = mod, data = data_file)
fit

Enumeration HMCMetric#

Format#

An object of class list of length 3.

HMCMetric

Choices of metric for HMC. Can select from $UNIT, $DENSE, and $DIAGONAL.

Generic function pathfinder#

#### S3 method for class 'tinystan_model'
pathfinder(
  model,
  data = "",
  num_paths = 4,
  inits = NULL,
  seed = NULL,
  id = 1,
  init_radius = 2,
  num_draws = 1000,
  max_history_size = 5,
  init_alpha = 0.001,
  tol_obj = 1e-12,
  tol_rel_obj = 10000,
  tol_grad = 1e-08,
  tol_rel_grad = 1e+07,
  tol_param = 1e-08,
  num_iterations = 1000,
  num_elbo_draws = 25,
  num_multi_draws = 1000,
  calculate_lp = TRUE,
  psis_resample = TRUE,
  refresh = 0,
  num_threads = -1
)

Run Stan’s pathfinder algorithm

Generic function optimizer#

#### S3 method for class 'tinystan_model'
optimizer(
  model,
  data = "",
  init = NULL,
  seed = NULL,
  id = 1,
  init_radius = 2,
  algorithm = OptimizationAlgorithm$LBFGS,
  jacobian = FALSE,
  num_iterations = 2000,
  max_history_size = 5,
  init_alpha = 0.001,
  tol_obj = 1e-12,
  tol_rel_obj = 10000,
  tol_grad = 1e-08,
  tol_rel_grad = 1e+07,
  tol_param = 1e-08,
  refresh = 0,
  num_threads = -1
)

Run Stan’s Optimization algorithms

Enumeration OptimizationAlgorithm#

Format#

An object of class list of length 3.

OptimizationAlgorithm

Choices of optimization algorithm. Can select from $NEWTON, $BFGS, and $LBFGS.

Generic function laplace_sampler#

#### S3 method for class 'tinystan_model'
laplace_sampler(
  model,
  mode,
  data = "",
  num_draws = 1000,
  jacobian = TRUE,
  calculate_lp = TRUE,
  save_hessian = FALSE,
  seed = NULL,
  refresh = 0,
  num_threads = -1
)

Run Stan’s Laplace approximation algorithm

Compilation utilities#

Function set_tinystan_path()#

set_tinystan_path(path)

Set the path to TinyStan.

Details#

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

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.

Compiles a Stan model.

Details#

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

See Also#

set_tinystan_path()