Package 'cmdstanr'

Description

Stan Development Team

CmdStanR: the R interface to CmdStan.

Details

CmdStanR (cmdstanr package) is an interface to Stan (mc-stan.org) for R users. It provides the necessary objects and functions to compile a Stan program and run Stan's algorithms from R via CmdStan, the shell interface to Stan (mc-stan.org/users/interfaces/cmdstan).

Different ways of interfacing with Stan’s C++

The RStan interface (rstan package) is an in-memory interface to Stan and relies on R packages like Rcpp and inline to call C++ code from R. On the other hand, the CmdStanR interface does not directly call any C++ code from R, instead relying on the CmdStan interface behind the scenes for compilation, running algorithms, and writing results to output files.

Advantages of RStan

• Allows other developers to distribute R packages with pre-compiled Stan programs (like rstanarm) on CRAN. (Note: As of 2023, this can mostly be achieved with CmdStanR as well. See Developing using CmdStanR.)

• Avoids use of R6 classes, which may result in more familiar syntax for many R users.

• CRAN binaries available for Mac and Windows.

Advantages of CmdStanR

• Compatible with latest versions of Stan. Keeping up with Stan releases is complicated for RStan, often requiring non-trivial changes to the rstan package and new CRAN releases of both rstan and StanHeaders. With CmdStanR the latest improvements in Stan will be available from R immediately after updating CmdStan using cmdstanr::install_cmdstan().

• Running Stan via external processes results in fewer unexpected crashes, especially in RStudio.

• Less memory overhead.

• More permissive license. RStan uses the GPL-3 license while the license for CmdStanR is BSD-3, which is a bit more permissive and is the same license used for CmdStan and the Stan C++ source code.

Getting started

CmdStanR requires a working version of CmdStan. If you already have CmdStan installed see cmdstan_model() to get started, otherwise see install_cmdstan() to install CmdStan. The vignette Getting started with CmdStanR demonstrates the basic functionality of the package.

For a list of global options see cmdstanr_global_options.

Author(s)

Maintainer: Andrew Johnson [email protected] (ORCID)

Authors:

• Jonah Gabry [email protected]

• Rok Češnovar [email protected]

• Steve Bronder

Other contributors:

• Ben Bales [contributor]

• Mitzi Morris [contributor]

• Mikhail Popov [contributor]

• Mike Lawrence [contributor]

• William Michael Landau [email protected] (ORCID) [contributor]

• Jacob Socolar [contributor]

• Martin Modrák [contributor]

• Ven Popov [contributor]

See Also

The CmdStanR website (mc-stan.org/cmdstanr) for online documentation and tutorials.

The Stan and CmdStan documentation:

• Stan documentation: mc-stan.org/users/documentation

• CmdStan User’s Guide: mc-stan.org/docs/cmdstan-guide

Useful links:

• https://mc-stan.org/cmdstanr/

• https://discourse.mc-stan.org

• Report bugs at https://github.com/stan-dev/cmdstanr/issues

Examples

## Not run: 
library(cmdstanr)
library(posterior)
library(bayesplot)
color_scheme_set("brightblue")

# Set path to CmdStan
# (Note: if you installed CmdStan via install_cmdstan() with default settings
# then setting the path is unnecessary but the default below should still work.
# Otherwise use the `path` argument to specify the location of your
# CmdStan installation.)
set_cmdstan_path(path = NULL)

# Create a CmdStanModel object from a Stan program,
# here using the example model that comes with CmdStan
file <- file.path(cmdstan_path(), "examples/bernoulli/bernoulli.stan")
mod <- cmdstan_model(file)
mod$print()
# Print with line numbers. This can be set globally using the
# `cmdstanr_print_line_numbers` option.
mod$print(line_numbers = TRUE)

# Data as a named list (like RStan)
stan_data <- list(N = 10, y = c(0,1,0,0,0,0,0,0,0,1))

# Run MCMC using the 'sample' method
fit_mcmc <- mod$sample(
  data = stan_data,
  seed = 123,
  chains = 2,
  parallel_chains = 2
)

# Use 'posterior' package for summaries
fit_mcmc$summary()

# Check sampling diagnostics
fit_mcmc$diagnostic_summary()

# Get posterior draws
draws <- fit_mcmc$draws()
print(draws)

# Convert to data frame using posterior::as_draws_df
as_draws_df(draws)

# Plot posterior using bayesplot (ggplot2)
mcmc_hist(fit_mcmc$draws("theta"))

# For models fit using MCMC, if you like working with RStan's stanfit objects
# then you can create one with rstan::read_stan_csv()
# stanfit <- rstan::read_stan_csv(fit_mcmc$output_files())


# Run 'optimize' method to get a point estimate (default is Stan's LBFGS algorithm)
# and also demonstrate specifying data as a path to a file instead of a list
my_data_file <- file.path(cmdstan_path(), "examples/bernoulli/bernoulli.data.json")
fit_optim <- mod$optimize(data = my_data_file, seed = 123)
fit_optim$summary()

# Run 'optimize' again with 'jacobian=TRUE' and then draw from Laplace approximation
# to the posterior
fit_optim <- mod$optimize(data = my_data_file, jacobian = TRUE)
fit_laplace <- mod$laplace(data = my_data_file, mode = fit_optim, draws = 2000)
fit_laplace$summary()

# Run 'variational' method to use ADVI to approximate posterior
fit_vb <- mod$variational(data = stan_data, seed = 123)
fit_vb$summary()
mcmc_hist(fit_vb$draws("theta"))

# Run 'pathfinder' method, a new alternative to the variational method
fit_pf <- mod$pathfinder(data = stan_data, seed = 123)
fit_pf$summary()
mcmc_hist(fit_pf$draws("theta"))

# Run 'pathfinder' again with more paths, fewer draws per path,
# better covariance approximation, and fewer LBFGSs iterations
fit_pf <- mod$pathfinder(data = stan_data, num_paths=10, single_path_draws=40,
                         history_size=50, max_lbfgs_iters=100)

# Specifying initial values as a function
fit_mcmc_w_init_fun <- mod$sample(
  data = stan_data,
  seed = 123,
  chains = 2,
  refresh = 0,
  init = function() list(theta = runif(1))
)
fit_mcmc_w_init_fun_2 <- mod$sample(
  data = stan_data,
  seed = 123,
  chains = 2,
  refresh = 0,
  init = function(chain_id) {
    # silly but demonstrates optional use of chain_id
    list(theta = 1 / (chain_id + 1))
  }
)
fit_mcmc_w_init_fun_2$init()

# Specifying initial values as a list of lists
fit_mcmc_w_init_list <- mod$sample(
  data = stan_data,
  seed = 123,
  chains = 2,
  refresh = 0,
  init = list(
    list(theta = 0.75), # chain 1
    list(theta = 0.25)  # chain 2
  )
)
fit_optim_w_init_list <- mod$optimize(
  data = stan_data,
  seed = 123,
  init = list(
    list(theta = 0.75)
  )
)
fit_optim_w_init_list$init()

## End(Not run)

Description

Create a draws object supported by the posterior package. These methods are just wrappers around CmdStanR's $draws() method provided for convenience.

Usage

## S3 method for class 'CmdStanMCMC'
as_draws(x, ...)

## S3 method for class 'CmdStanMLE'
as_draws(x, ...)

## S3 method for class 'CmdStanLaplace'
as_draws(x, ...)

## S3 method for class 'CmdStanVB'
as_draws(x, ...)

## S3 method for class 'CmdStanGQ'
as_draws(x, ...)

## S3 method for class 'CmdStanPathfinder'
as_draws(x, ...)

Arguments

Details

To subset iterations, chains, or draws, use the posterior::subset_draws() method after creating the draws object.

Examples

## Not run: 
fit <- cmdstanr_example()
as_draws(fit)

# posterior's as_draws_*() methods will also work
posterior::as_draws_rvars(fit)
posterior::as_draws_list(fit)

## End(Not run)

Description

This function converts a CmdStanMCMC object to an mcmc.list object compatible with the coda package. This is primarily intended for users of Stan coming from BUGS/JAGS who are used to coda for plotting and diagnostics. In general we recommend the more recent MCMC diagnostics in posterior and the ggplot2-based plotting functions in bayesplot, but for users who prefer coda this function provides compatibility.

Usage

as_mcmc.list(x)

Arguments

Value

An mcmc.list object compatible with the coda package.

Examples

## Not run: 
fit <- cmdstanr_example()
x <- as_mcmc.list(fit)

## End(Not run)

Description

These are generic functions intended to primarily be used by developers of packages that interface with on CmdStanR. Developers can define methods on top of these generics to coerce objects into CmdStanR's fitted model objects.

Usage

as.CmdStanMCMC(object, ...)

as.CmdStanMLE(object, ...)

as.CmdStanLaplace(object, ...)

as.CmdStanVB(object, ...)

as.CmdStanPathfinder(object, ...)

as.CmdStanGQ(object, ...)

as.CmdStanDiagnose(object, ...)

Arguments

Description

Create a new CmdStanModel object from a file containing a Stan program or from an existing Stan executable. The CmdStanModel object stores the path to a Stan program and compiled executable (once created), and provides methods for fitting the model using Stan's algorithms.

See the compile and ... arguments for control over whether and how compilation happens.

Usage

cmdstan_model(stan_file = NULL, exe_file = NULL, compile = TRUE, ...)

Arguments

Value

A CmdStanModel object.

See Also

install_cmdstan(), $compile(), $check_syntax()

The CmdStanR website (mc-stan.org/cmdstanr) for online documentation and tutorials.

The Stan and CmdStan documentation:

• Stan documentation: mc-stan.org/users/documentation

• CmdStan User’s Guide: mc-stan.org/docs/cmdstan-guide

Examples

## Not run: 
library(cmdstanr)
library(posterior)
library(bayesplot)
color_scheme_set("brightblue")

# Set path to CmdStan
# (Note: if you installed CmdStan via install_cmdstan() with default settings
# then setting the path is unnecessary but the default below should still work.
# Otherwise use the `path` argument to specify the location of your
# CmdStan installation.)
set_cmdstan_path(path = NULL)

# Create a CmdStanModel object from a Stan program,
# here using the example model that comes with CmdStan
file <- file.path(cmdstan_path(), "examples/bernoulli/bernoulli.stan")
mod <- cmdstan_model(file)
mod$print()
# Print with line numbers. This can be set globally using the
# `cmdstanr_print_line_numbers` option.
mod$print(line_numbers = TRUE)

# Data as a named list (like RStan)
stan_data <- list(N = 10, y = c(0,1,0,0,0,0,0,0,0,1))

# Run MCMC using the 'sample' method
fit_mcmc <- mod$sample(
  data = stan_data,
  seed = 123,
  chains = 2,
  parallel_chains = 2
)

# Use 'posterior' package for summaries
fit_mcmc$summary()

# Check sampling diagnostics
fit_mcmc$diagnostic_summary()

# Get posterior draws
draws <- fit_mcmc$draws()
print(draws)

# Convert to data frame using posterior::as_draws_df
as_draws_df(draws)

# Plot posterior using bayesplot (ggplot2)
mcmc_hist(fit_mcmc$draws("theta"))

# For models fit using MCMC, if you like working with RStan's stanfit objects
# then you can create one with rstan::read_stan_csv()
# stanfit <- rstan::read_stan_csv(fit_mcmc$output_files())


# Run 'optimize' method to get a point estimate (default is Stan's LBFGS algorithm)
# and also demonstrate specifying data as a path to a file instead of a list
my_data_file <- file.path(cmdstan_path(), "examples/bernoulli/bernoulli.data.json")
fit_optim <- mod$optimize(data = my_data_file, seed = 123)
fit_optim$summary()

# Run 'optimize' again with 'jacobian=TRUE' and then draw from Laplace approximation
# to the posterior
fit_optim <- mod$optimize(data = my_data_file, jacobian = TRUE)
fit_laplace <- mod$laplace(data = my_data_file, mode = fit_optim, draws = 2000)
fit_laplace$summary()

# Run 'variational' method to use ADVI to approximate posterior
fit_vb <- mod$variational(data = stan_data, seed = 123)
fit_vb$summary()
mcmc_hist(fit_vb$draws("theta"))

# Run 'pathfinder' method, a new alternative to the variational method
fit_pf <- mod$pathfinder(data = stan_data, seed = 123)
fit_pf$summary()
mcmc_hist(fit_pf$draws("theta"))

# Run 'pathfinder' again with more paths, fewer draws per path,
# better covariance approximation, and fewer LBFGSs iterations
fit_pf <- mod$pathfinder(data = stan_data, num_paths=10, single_path_draws=40,
                         history_size=50, max_lbfgs_iters=100)

# Specifying initial values as a function
fit_mcmc_w_init_fun <- mod$sample(
  data = stan_data,
  seed = 123,
  chains = 2,
  refresh = 0,
  init = function() list(theta = runif(1))
)
fit_mcmc_w_init_fun_2 <- mod$sample(
  data = stan_data,
  seed = 123,
  chains = 2,
  refresh = 0,
  init = function(chain_id) {
    # silly but demonstrates optional use of chain_id
    list(theta = 1 / (chain_id + 1))
  }
)
fit_mcmc_w_init_fun_2$init()

# Specifying initial values as a list of lists
fit_mcmc_w_init_list <- mod$sample(
  data = stan_data,
  seed = 123,
  chains = 2,
  refresh = 0,
  init = list(
    list(theta = 0.75), # chain 1
    list(theta = 0.25)  # chain 2
  )
)
fit_optim_w_init_list <- mod$optimize(
  data = stan_data,
  seed = 123,
  init = list(
    list(theta = 0.75)
  )
)
fit_optim_w_init_list$init()

## End(Not run)

Description

A CmdStanDiagnose object is the object returned by the $diagnose() method of a CmdStanModel object.

Methods

CmdStanDiagnose objects have the following associated methods:

See Also

The CmdStanR website (mc-stan.org/cmdstanr) for online documentation and tutorials.

The Stan and CmdStan documentation:

• Stan documentation: mc-stan.org/users/documentation

• CmdStan User’s Guide: mc-stan.org/docs/cmdstan-guide

Other fitted model objects: CmdStanGQ, CmdStanLaplace, CmdStanMCMC, CmdStanMLE, CmdStanPathfinder, CmdStanVB

Examples

## Not run: 
test <- cmdstanr_example("logistic", method = "diagnose")

# retrieve the gradients
test$gradients()

## End(Not run)

Description

A CmdStanGQ object is the fitted model object returned by the $generate_quantities() method of a CmdStanModel object.

Methods

CmdStanGQ objects have the following associated methods, all of which have their own (linked) documentation pages.

Extract contents of generated quantities object

Summarize inferences

Save fitted model object and temporary files

Report run times, console output, return codes

See Also

The CmdStanR website (mc-stan.org/cmdstanr) for online documentation and tutorials.

The Stan and CmdStan documentation:

• Stan documentation: mc-stan.org/users/documentation

• CmdStan User’s Guide: mc-stan.org/docs/cmdstan-guide

Other fitted model objects: CmdStanDiagnose, CmdStanLaplace, CmdStanMCMC, CmdStanMLE, CmdStanPathfinder, CmdStanVB

Examples

## Not run: 
# first fit a model using MCMC
mcmc_program <- write_stan_file(
  "data {
    int<lower=0> N;
    array[N] int<lower=0,upper=1> y;
  }
  parameters {
    real<lower=0,upper=1> theta;
  }
  model {
    y ~ bernoulli(theta);
  }"
)
mod_mcmc <- cmdstan_model(mcmc_program)

data <- list(N = 10, y = c(1,1,0,0,0,1,0,1,0,0))
fit_mcmc <- mod_mcmc$sample(data = data, seed = 123, refresh = 0)

# stan program for standalone generated quantities
# (could keep model block, but not necessary so removing it)
gq_program <- write_stan_file(
  "data {
    int<lower=0> N;
    array[N] int<lower=0,upper=1> y;
  }
  parameters {
    real<lower=0,upper=1> theta;
  }
  generated quantities {
    array[N] int y_rep = bernoulli_rng(rep_vector(theta, N));
  }"
)

mod_gq <- cmdstan_model(gq_program)
fit_gq <- mod_gq$generate_quantities(fit_mcmc, data = data, seed = 123)
str(fit_gq$draws())

library(posterior)
as_draws_df(fit_gq$draws())

## End(Not run)

Description

A CmdStanLaplace object is the fitted model object returned by the $laplace() method of a CmdStanModel object.

Methods

CmdStanLaplace objects have the following associated methods, all of which have their own (linked) documentation pages.

Extract contents of fitted model object

Summarize inferences

Save fitted model object and temporary files

Report run times, console output, return codes

See Also

The CmdStanR website (mc-stan.org/cmdstanr) for online documentation and tutorials.

The Stan and CmdStan documentation:

• Stan documentation: mc-stan.org/users/documentation

• CmdStan User’s Guide: mc-stan.org/docs/cmdstan-guide

Other fitted model objects: CmdStanDiagnose, CmdStanGQ, CmdStanMCMC, CmdStanMLE, CmdStanPathfinder, CmdStanVB

Description

A CmdStanMCMC object is the fitted model object returned by the $sample() method of a CmdStanModel object. Like CmdStanModel objects, CmdStanMCMC objects are R6 objects.

Methods

CmdStanMCMC objects have the following associated methods, all of which have their own (linked) documentation pages.

Extract contents of fitted model object

Summarize inferences and diagnostics

Save fitted model object and temporary files

Report run times, console output, return codes

Expose Stan functions and additional methods to R

See Also

The CmdStanR website (mc-stan.org/cmdstanr) for online documentation and tutorials.

The Stan and CmdStan documentation:

• Stan documentation: mc-stan.org/users/documentation

• CmdStan User’s Guide: mc-stan.org/docs/cmdstan-guide

Other fitted model objects: CmdStanDiagnose, CmdStanGQ, CmdStanLaplace, CmdStanMLE, CmdStanPathfinder, CmdStanVB

Description

A CmdStanMLE object is the fitted model object returned by the $optimize() method of a CmdStanModel object.

Methods

CmdStanMLE objects have the following associated methods, all of which have their own (linked) documentation pages.

Extract contents of fitted model object

Summarize inferences

Save fitted model object and temporary files

Report run times, console output, return codes

Expose Stan functions and additional methods to R

See Also

The CmdStanR website (mc-stan.org/cmdstanr) for online documentation and tutorials.

The Stan and CmdStan documentation:

• Stan documentation: mc-stan.org/users/documentation

• CmdStan User’s Guide: mc-stan.org/docs/cmdstan-guide

Other fitted model objects: CmdStanDiagnose, CmdStanGQ, CmdStanLaplace, CmdStanMCMC, CmdStanPathfinder, CmdStanVB

Description

A CmdStanModel object is an R6 object created by the cmdstan_model() function. The object stores the path to a Stan program and compiled executable (once created), and provides methods for fitting the model using Stan's algorithms.

Methods

CmdStanModel objects have the following associated methods, many of which have their own (linked) documentation pages:

Stan code

Compilation

Diagnostics

Model fitting

See Also

The CmdStanR website (mc-stan.org/cmdstanr) for online documentation and tutorials.

The Stan and CmdStan documentation:

• Stan documentation: mc-stan.org/users/documentation

• CmdStan User’s Guide: mc-stan.org/docs/cmdstan-guide

Examples

## Not run: 
library(cmdstanr)
library(posterior)
library(bayesplot)
color_scheme_set("brightblue")

# Set path to CmdStan
# (Note: if you installed CmdStan via install_cmdstan() with default settings
# then setting the path is unnecessary but the default below should still work.
# Otherwise use the `path` argument to specify the location of your
# CmdStan installation.)
set_cmdstan_path(path = NULL)

# Create a CmdStanModel object from a Stan program,
# here using the example model that comes with CmdStan
file <- file.path(cmdstan_path(), "examples/bernoulli/bernoulli.stan")
mod <- cmdstan_model(file)
mod$print()
# Print with line numbers. This can be set globally using the
# `cmdstanr_print_line_numbers` option.
mod$print(line_numbers = TRUE)

# Data as a named list (like RStan)
stan_data <- list(N = 10, y = c(0,1,0,0,0,0,0,0,0,1))

# Run MCMC using the 'sample' method
fit_mcmc <- mod$sample(
  data = stan_data,
  seed = 123,
  chains = 2,
  parallel_chains = 2
)

# Use 'posterior' package for summaries
fit_mcmc$summary()

# Check sampling diagnostics
fit_mcmc$diagnostic_summary()

# Get posterior draws
draws <- fit_mcmc$draws()
print(draws)

# Convert to data frame using posterior::as_draws_df
as_draws_df(draws)

# Plot posterior using bayesplot (ggplot2)
mcmc_hist(fit_mcmc$draws("theta"))

# For models fit using MCMC, if you like working with RStan's stanfit objects
# then you can create one with rstan::read_stan_csv()
# stanfit <- rstan::read_stan_csv(fit_mcmc$output_files())


# Run 'optimize' method to get a point estimate (default is Stan's LBFGS algorithm)
# and also demonstrate specifying data as a path to a file instead of a list
my_data_file <- file.path(cmdstan_path(), "examples/bernoulli/bernoulli.data.json")
fit_optim <- mod$optimize(data = my_data_file, seed = 123)
fit_optim$summary()

# Run 'optimize' again with 'jacobian=TRUE' and then draw from Laplace approximation
# to the posterior
fit_optim <- mod$optimize(data = my_data_file, jacobian = TRUE)
fit_laplace <- mod$laplace(data = my_data_file, mode = fit_optim, draws = 2000)
fit_laplace$summary()

# Run 'variational' method to use ADVI to approximate posterior
fit_vb <- mod$variational(data = stan_data, seed = 123)
fit_vb$summary()
mcmc_hist(fit_vb$draws("theta"))

# Run 'pathfinder' method, a new alternative to the variational method
fit_pf <- mod$pathfinder(data = stan_data, seed = 123)
fit_pf$summary()
mcmc_hist(fit_pf$draws("theta"))

# Run 'pathfinder' again with more paths, fewer draws per path,
# better covariance approximation, and fewer LBFGSs iterations
fit_pf <- mod$pathfinder(data = stan_data, num_paths=10, single_path_draws=40,
                         history_size=50, max_lbfgs_iters=100)

# Specifying initial values as a function
fit_mcmc_w_init_fun <- mod$sample(
  data = stan_data,
  seed = 123,
  chains = 2,
  refresh = 0,
  init = function() list(theta = runif(1))
)
fit_mcmc_w_init_fun_2 <- mod$sample(
  data = stan_data,
  seed = 123,
  chains = 2,
  refresh = 0,
  init = function(chain_id) {
    # silly but demonstrates optional use of chain_id
    list(theta = 1 / (chain_id + 1))
  }
)
fit_mcmc_w_init_fun_2$init()

# Specifying initial values as a list of lists
fit_mcmc_w_init_list <- mod$sample(
  data = stan_data,
  seed = 123,
  chains = 2,
  refresh = 0,
  init = list(
    list(theta = 0.75), # chain 1
    list(theta = 0.25)  # chain 2
  )
)
fit_optim_w_init_list <- mod$optimize(
  data = stan_data,
  seed = 123,
  init = list(
    list(theta = 0.75)
  )
)
fit_optim_w_init_list$init()

## End(Not run)

Description

A CmdStanPathfinder object is the fitted model object returned by the $pathfinder() method of a CmdStanModel object.

Methods

CmdStanPathfinder objects have the following associated methods, all of which have their own (linked) documentation pages.

Extract contents of fitted model object

Summarize inferences

Save fitted model object and temporary files

Report run times, console output, return codes

See Also

The CmdStanR website (mc-stan.org/cmdstanr) for online documentation and tutorials.

The Stan and CmdStan documentation:

• Stan documentation: mc-stan.org/users/documentation

• CmdStan User’s Guide: mc-stan.org/docs/cmdstan-guide

Other fitted model objects: CmdStanDiagnose, CmdStanGQ, CmdStanLaplace, CmdStanMCMC, CmdStanMLE, CmdStanVB

Description

Fit models for use in examples

Usage

cmdstanr_example(
  example = c("logistic", "schools", "schools_ncp"),
  method = c("sample", "optimize", "laplace", "variational", "pathfinder", "diagnose"),
  ...,
  quiet = TRUE,
  force_recompile = getOption("cmdstanr_force_recompile", default = FALSE)
)

print_example_program(example = c("logistic", "schools", "schools_ncp"))

Arguments

Value

The fitted model object returned by the selected method.

Examples

## Not run: 
print_example_program("logistic")
fit_logistic_mcmc <- cmdstanr_example("logistic", chains = 2)
fit_logistic_mcmc$summary()

fit_logistic_optim <- cmdstanr_example("logistic", method = "optimize")
fit_logistic_optim$summary()

fit_logistic_vb <- cmdstanr_example("logistic", method = "variational")
fit_logistic_vb$summary()

print_example_program("schools")
fit_schools_mcmc <- cmdstanr_example("schools")
fit_schools_mcmc$summary()

print_example_program("schools_ncp")
fit_schools_ncp_mcmc <- cmdstanr_example("schools_ncp")
fit_schools_ncp_mcmc$summary()

# optimization fails for hierarchical model
cmdstanr_example("schools", "optimize", quiet = FALSE)

## End(Not run)

Description

These options can be set via options() for an entire R session.

Details

• cmdstanr_draws_format: Which format provided by the posterior package should be used when returning the posterior or approximate posterior draws? The default depends on the model fitting method. See draws for more details.

• cmdstanr_force_recompile: Should the default be to recompile models even if there were no Stan code changes since last compiled? See compile for more details. The default is FALSE.

• cmdstanr_max_rows: The maximum number of rows of output to print when using the $print() method. The default is 10.

• cmdstanr_no_ver_check: Should the check for a more recent version of CmdStan be disabled? The default is FALSE.

• cmdstanr_output_dir: The directory where CmdStan should write its output CSV files when fitting models. The default is a temporary directory. Files in a temporary directory are removed as part of R garbage collection, while files in an explicitly defined directory are not automatically deleted.

• cmdstanr_verbose: Should more information be printed when compiling or running models, including showing how CmdStan was called internally? The default is FALSE.

• cmdstanr_warn_inits: Should a warning be thrown if initial values are only provided for a subset of parameters? The default is TRUE.

• cmdstanr_write_stan_file_dir: The directory where write_stan_file() should write Stan files. The default is a temporary directory. Files in a temporary directory are removed as part of R garbage collection, while files in an explicitly defined directory are not automatically deleted.

• mc.cores: The number of cores to use for various parallelization tasks (e.g. running MCMC chains, installing CmdStan). The default depends on the use case and is documented with the methods that make use of mc.cores.

Description

A CmdStanVB object is the fitted model object returned by the $variational() method of a CmdStanModel object.

Methods

CmdStanVB objects have the following associated methods, all of which have their own (linked) documentation pages.

Extract contents of fitted model object

Summarize inferences

Save fitted model object and temporary files

Report run times, console output, return codes

Expose Stan functions and additional methods to R

See Also

The CmdStanR website (mc-stan.org/cmdstanr) for online documentation and tutorials.

The Stan and CmdStan documentation:

• Stan documentation: mc-stan.org/users/documentation

• CmdStan User’s Guide: mc-stan.org/docs/cmdstan-guide

Other fitted model objects: CmdStanDiagnose, CmdStanGQ, CmdStanLaplace, CmdStanMCMC, CmdStanMLE, CmdStanPathfinder

Description

Write posterior draws objects to CSV files suitable for running standalone generated quantities with CmdStan.

Usage

draws_to_csv(
  draws,
  sampler_diagnostics = NULL,
  dir = tempdir(),
  basename = "fittedParams"
)

Arguments

Details

draws_to_csv() generates a CSV suitable for running standalone generated quantities with CmdStan. The CSV file contains a single comment ⁠#num_samples⁠, which equals the number of iterations in the supplied draws object.

The comment is followed by the column names. The first column is the lp__ value, followed by sampler diagnostics and finnaly other variables of the draws object. #' If the draws object does not contain the lp__ or sampler diagnostics variables, columns with zeros are created in order to conform with the requirements of the standalone generated quantities method of CmdStan.

The column names line is finally followed by the values of the draws in the same order as the column names.

Value

Paths to CSV files (one per chain).

Examples

## Not run: 
draws <- posterior::example_draws()

draws_csv_files <- draws_to_csv(draws)
print(draws_csv_files)

# draws_csv_files <- draws_to_csv(draws,
#                                 sampler_diagnostic = sampler_diagnostics,
#                                 dir = "~/my_folder",
#                                 basename = "my-samples")

## End(Not run)

Description

This provides a knitr engine for Stan, suitable for usage when attempting to render Stan chunks and compile the model code within to an executable with CmdStan. Use register_knitr_engine() to make this the default engine for stan chunks. See the vignette R Markdown CmdStan Engine for an example.

Usage

eng_cmdstan(options)

Arguments

Examples

## Not run: 
knitr::knit_engines$set(stan = cmdstanr::eng_cmdstan)

## End(Not run)

Description

Run CmdStan's stansummary and diagnose utilities. These are documented in the CmdStan Guide:

• https://mc-stan.org/docs/cmdstan-guide/stansummary.html

• https://mc-stan.org/docs/cmdstan-guide/diagnose.html

Although these methods can be used for models fit using the $variational() method, much of the output is currently only relevant for models fit using the $sample() method.

See the $summary() for computing similar summaries in R rather than calling CmdStan's utilites.

Usage

cmdstan_summary(flags = NULL)

cmdstan_diagnose()

Arguments

See Also

CmdStanMCMC, fit-method-summary

Examples

## Not run: 
fit <- cmdstanr_example("logistic")
fit$cmdstan_diagnose()
fit$cmdstan_summary()

## End(Not run)

Description

Return Stan code

Usage

code()

Value

A character vector with one element per line of code.

See Also

CmdStanMCMC, CmdStanMLE, CmdStanVB, CmdStanGQ

Examples

## Not run: 
fit <- cmdstanr_example()
fit$code() # character vector
cat(fit$code(), sep = "\n") # pretty print

## End(Not run)

Description

The ⁠$constrain_variables()⁠ method transforms input parameters to the constrained scale.

Usage

constrain_variables(
  unconstrained_variables,
  transformed_parameters = TRUE,
  generated_quantities = TRUE
)

Arguments

See Also

log_prob(), grad_log_prob(), constrain_variables(), unconstrain_variables(), unconstrain_draws(), variable_skeleton(), hessian()

Examples

## Not run: 
fit_mcmc <- cmdstanr_example("logistic", method = "sample", force_recompile = TRUE)
fit_mcmc$constrain_variables(unconstrained_variables = c(0.5, 1.2, 1.1, 2.2))

## End(Not run)

Description

Warnings and summaries of sampler diagnostics. To instead get the underlying values of the sampler diagnostics for each iteration and chain use the $sampler_diagnostics() method.

Currently parameter-specific diagnostics like R-hat and effective sample size are not handled by this method. Those diagnostics are provided via the $summary() method (using posterior::summarize_draws()).

Usage

diagnostic_summary(
  diagnostics = c("divergences", "treedepth", "ebfmi"),
  quiet = FALSE
)

Arguments

Value

A list with as many named elements as diagnostics selected. The possible elements and their values are:

• "num_divergent": A vector of the number of divergences per chain.

• "num_max_treedepth": A vector of the number of times max_treedepth was hit per chain.

• "ebfmi": A vector of E-BFMI values per chain.

See Also

CmdStanMCMC and the $sampler_diagnostics() method

Examples

## Not run: 
fit <- cmdstanr_example("schools")
fit$diagnostic_summary()
fit$diagnostic_summary(quiet = TRUE)

## End(Not run)

Description

Extract posterior draws after MCMC or approximate posterior draws after variational approximation using formats provided by the posterior package.

The variables include the parameters, transformed parameters, and generated quantities from the Stan program as well as lp__, the total log probability (target) accumulated in the model block.

Usage

draws(
  variables = NULL,
  inc_warmup = FALSE,
  format = getOption("cmdstanr_draws_format")
)

Arguments

Value

Depends on the value of format. The defaults are:

• For MCMC, a 3-D draws_array object (iteration x chain x variable).

• For standalone generated quantities, a 3-D draws_array object (iteration x chain x variable).

• For variational inference, a 2-D draws_matrix object (draw x variable) because there are no chains. An additional variable lp_approx__ is also included, which is the log density of the variational approximation to the posterior evaluated at each of the draws.

• For optimization, a 1-row draws_matrix with one column per variable. These are not actually draws, just point estimates stored in the draws_matrix format. See $mle() to extract them as a numeric vector.

See Also

CmdStanMCMC, CmdStanMLE, CmdStanVB, CmdStanGQ

Examples

## Not run: 
# logistic regression with intercept alpha and coefficients beta
fit <- cmdstanr_example("logistic", method = "sample")

# returned as 3-D array (see ?posterior::draws_array)
draws <- fit$draws()
dim(draws)
str(draws)

# can easily convert to other formats (data frame, matrix, list)
# using the posterior package
head(posterior::as_draws_matrix(draws))

# or can specify 'format' argument to avoid manual conversion
# matrix format combines all chains
draws <- fit$draws(format = "matrix")
head(draws)

# can select specific parameters
fit$draws("alpha")
fit$draws("beta")  # selects entire vector beta
fit$draws(c("alpha", "beta[2]"))

# can be passed directly to bayesplot plotting functions
bayesplot::color_scheme_set("brightblue")
bayesplot::mcmc_dens(fit$draws(c("alpha", "beta")))
bayesplot::mcmc_scatter(fit$draws(c("beta[1]", "beta[2]")), alpha = 0.3)


# example using variational inference
fit <- cmdstanr_example("logistic", method = "variational")
head(fit$draws("beta")) # a matrix by default
head(fit$draws("beta", format = "df"))

## End(Not run)

Description

The ⁠$grad_log_prob()⁠ method provides access to the Stan model's log_prob function and its derivative.

Usage

grad_log_prob(
  unconstrained_variables,
  jacobian = TRUE,
  jacobian_adjustment = NULL
)

Arguments

See Also

log_prob(), grad_log_prob(), constrain_variables(), unconstrain_variables(), unconstrain_draws(), variable_skeleton(), hessian()

Examples

## Not run: 
fit_mcmc <- cmdstanr_example("logistic", method = "sample", force_recompile = TRUE)
fit_mcmc$grad_log_prob(unconstrained_variables = c(0.5, 1.2, 1.1, 2.2))

## End(Not run)

Description

Return the data frame containing the gradients for all parameters.

Usage

gradients()

Value

A list of lists. See Examples.

See Also

CmdStanDiagnose

Examples

## Not run: 
test <- cmdstanr_example("logistic", method = "diagnose")

# retrieve the gradients
test$gradients()

## End(Not run)

Description

The ⁠$hessian()⁠ method provides access to the Stan model's log_prob, its derivative, and its hessian.

Usage

hessian(unconstrained_variables, jacobian = TRUE, jacobian_adjustment = NULL)

Arguments

See Also

log_prob(), grad_log_prob(), constrain_variables(), unconstrain_variables(), unconstrain_draws(), variable_skeleton(), hessian()

Examples

## Not run: 
fit_mcmc <- cmdstanr_example("logistic", method = "sample", force_recompile = TRUE)
# fit_mcmc$init_model_methods(hessian = TRUE)
# fit_mcmc$hessian(unconstrained_variables = c(0.5, 1.2, 1.1, 2.2))

## End(Not run)

Description

Return user-specified initial values. If the user provided initial values files or R objects (list of lists or function) via the init argument when fitting the model then these are returned (always in the list of lists format). Currently it is not possible to extract initial values generated automatically by CmdStan, although CmdStan may support this in the future.

Usage

init()

Value

A list of lists. See Examples.

See Also

CmdStanMCMC, CmdStanMLE, CmdStanVB

Examples

## Not run: 
init_fun <- function() list(alpha = rnorm(1), beta = rnorm(3))
fit <- cmdstanr_example("logistic", init = init_fun, chains = 2)
str(fit$init())

# partial inits (only specifying for a subset of parameters)
init_list <- list(
  list(mu = 10, tau = 2),
  list(mu = -10, tau = 1)
)
fit <- cmdstanr_example("schools_ncp", init = init_list, chains = 2, adapt_delta = 0.9)

# only user-specified inits returned
str(fit$init())

## End(Not run)

Description

The ⁠$init_model_methods()⁠ method compiles and initializes the log_prob, grad_log_prob, constrain_variables, unconstrain_variables and unconstrain_draws functions. These are then available as methods of the fitted model object. This requires the additional Rcpp package, which are not required for fitting models using CmdStanR.

Note: there may be many compiler warnings emitted during compilation but these can be ignored so long as they are warnings and not errors.

Usage

init_model_methods(seed = 1, verbose = FALSE, hessian = FALSE)

Arguments

See Also

log_prob(), grad_log_prob(), constrain_variables(), unconstrain_variables(), unconstrain_draws(), variable_skeleton(), hessian()

Examples

## Not run: 
fit_mcmc <- cmdstanr_example("logistic", method = "sample", force_recompile = TRUE)

## End(Not run)

Description

Extract the inverse metric (mass matrix) for each MCMC chain.

Usage

inv_metric(matrix = TRUE)

Arguments

Value

A list of length equal to the number of MCMC chains. See the matrix argument for details.

See Also

CmdStanMCMC

Examples

## Not run: 
fit <- cmdstanr_example("logistic")
fit$inv_metric()
fit$inv_metric(matrix=FALSE)

fit <- cmdstanr_example("logistic", metric = "dense_e")
fit$inv_metric()

## End(Not run)

Description

The ⁠$log_prob()⁠ method provides access to the Stan model's log_prob function.

Usage

log_prob(unconstrained_variables, jacobian = TRUE, jacobian_adjustment = NULL)

Arguments

See Also

log_prob(), grad_log_prob(), constrain_variables(), unconstrain_variables(), unconstrain_draws(), variable_skeleton(), hessian()

Examples

## Not run: 
fit_mcmc <- cmdstanr_example("logistic", method = "sample", force_recompile = TRUE)
fit_mcmc$log_prob(unconstrained_variables = c(0.5, 1.2, 1.1, 2.2))

## End(Not run)

Description

The ⁠$loo()⁠ method computes approximate LOO-CV using the loo package. In order to use this method you must compute and save the pointwise log-likelihood in your Stan program. See loo::loo.array() and the loo package vignettes for details.

Usage

loo(variables = "log_lik", r_eff = TRUE, moment_match = FALSE, ...)

Arguments

Value

The object returned by loo::loo.array() or loo::loo_moment_match.default().

See Also

The loo package website with documentation and vignettes.

Examples

## Not run: 
# the "logistic" example model has "log_lik" in generated quantities
fit <- cmdstanr_example("logistic")
loo_result <- fit$loo(cores = 2)
print(loo_result)

## End(Not run)

Description

The ⁠$lp()⁠ method extracts lp__, the total log probability (target) accumulated in the model block of the Stan program. For variational inference the log density of the variational approximation to the posterior is available via the ⁠$lp_approx()⁠ method. For Laplace approximation the unnormalized density of the approximation to the posterior is available via the ⁠$lp_approx()⁠ method.

See the Log Probability Increment vs. Sampling Statement section of the Stan Reference Manual for details on when normalizing constants are dropped from log probability calculations.

Usage

lp()

lp_approx()

lp_approx()

Value

A numeric vector with length equal to the number of (post-warmup) draws or length equal to 1 for optimization.

Details

lp__ is the unnormalized log density on Stan's unconstrained space. This will in general be different than the unnormalized model log density evaluated at a posterior draw (which is on the constrained space). lp__ is intended to diagnose sampling efficiency and evaluate approximations.

For variational inference lp_approx__ is the log density of the variational approximation to lp__ (also on the unconstrained space). It is exposed in the variational method for performing the checks described in Yao et al. (2018) and implemented in the loo package.

For Laplace approximation lp_approx__ is the unnormalized density of the Laplace approximation. It can be used to perform the same checks as in the case of the variational method described in Yao et al. (2018).

References

Yao, Y., Vehtari, A., Simpson, D., and Gelman, A. (2018). Yes, but did it work?: Evaluating variational inference. Proceedings of the 35th International Conference on Machine Learning, PMLR 80:5581–5590.

See Also

CmdStanMCMC, CmdStanMLE, CmdStanLaplace, CmdStanVB

Examples

## Not run: 
fit_mcmc <- cmdstanr_example("logistic")
head(fit_mcmc$lp())

fit_mle <- cmdstanr_example("logistic", method = "optimize")
fit_mle$lp()

fit_vb <- cmdstanr_example("logistic", method = "variational")
plot(fit_vb$lp(), fit_vb$lp_approx())

## End(Not run)

Description

The ⁠$metadata()⁠ method returns a list of information gathered from the CSV output files, including the CmdStan configuration used when fitting the model. See Examples and read_cmdstan_csv().

Usage

metadata()

See Also

CmdStanMCMC, CmdStanMLE, CmdStanVB, CmdStanGQ

Examples

## Not run: 
fit_mcmc <- cmdstanr_example("logistic", method = "sample")
str(fit_mcmc$metadata())

fit_mle <- cmdstanr_example("logistic", method = "optimize")
str(fit_mle$metadata())

fit_vb <- cmdstanr_example("logistic", method = "variational")
str(fit_vb$metadata())

## End(Not run)

Description

The ⁠$mle()⁠ method is only available for CmdStanMLE objects. It returns the penalized maximum likelihood estimate (posterior mode) as a numeric vector with one element per variable. The returned vector does not include lp__, the total log probability (target) accumulated in the model block of the Stan program, which is available via the $lp() method and also included in the $draws() method.

Usage

mle(variables = NULL)

Arguments

Value

A numeric vector. See Examples.

See Also

CmdStanMLE

Examples

## Not run: 
fit <- cmdstanr_example("logistic", method = "optimize")
fit$mle("alpha")
fit$mle("beta")
fit$mle("beta[2]")

## End(Not run)

Description

The ⁠$num_chains()⁠ method returns the number of MCMC chains.

Usage

num_chains()

Value

An integer.

See Also

CmdStanMCMC

Examples

## Not run: 
fit_mcmc <- cmdstanr_example(chains = 2)
fit_mcmc$num_chains()

## End(Not run)

Description

For MCMC, the ⁠$output()⁠ method returns the stdout and stderr of all chains as a list of character vectors if id=NULL. If the id argument is specified it instead pretty prints the console output for a single chain.

For optimization and variational inference ⁠$output()⁠ just pretty prints the console output.

Usage

output(id = NULL)

Arguments

See Also

CmdStanMCMC, CmdStanMLE, CmdStanVB, CmdStanGQ

Examples

## Not run: 
fit_mcmc <- cmdstanr_example("logistic", method = "sample")
fit_mcmc$output(1)
out <- fit_mcmc$output()
str(out)

fit_mle <- cmdstanr_example("logistic", method = "optimize")
fit_mle$output()

fit_vb <- cmdstanr_example("logistic", method = "variational")
fit_vb$output()

## End(Not run)

Description

The ⁠$profiles()⁠ method returns a list of data frames with profiling data if any profiling data was written to the profile CSV files. See save_profile_files() to control where the files are saved.

Support for profiling Stan programs is available with CmdStan >= 2.26 and requires adding profiling statements to the Stan program.

Usage

profiles()

Value

A list of data frames with profiling data if the profiling CSV files were created.

See Also

CmdStanMCMC, CmdStanMLE, CmdStanVB, CmdStanGQ

Examples

## Not run: 
# first fit a model using MCMC
mcmc_program <- write_stan_file(
  'data {
    int<lower=0> N;
    array[N] int<lower=0,upper=1> y;
  }
  parameters {
    real<lower=0,upper=1> theta;
  }
  model {
    profile("likelihood") {
      y ~ bernoulli(theta);
    }
  }
  generated quantities {
    array[N] int y_rep;
    profile("gq") {
      y_rep = bernoulli_rng(rep_vector(theta, N));
    }
  }
'
)
mod_mcmc <- cmdstan_model(mcmc_program)

data <- list(N = 10, y = c(1,1,0,0,0,1,0,1,0,0))
fit <- mod_mcmc$sample(data = data, seed = 123, refresh = 0)

fit$profiles()

## End(Not run)

Description

The ⁠$return_codes()⁠ method returns a vector of return codes from the CmdStan run(s). A return code of 0 indicates a successful run.

Usage

return_codes()

Value

An integer vector of return codes with length equal to the number of CmdStan runs (number of chains for MCMC and one otherwise).

See Also

CmdStanMCMC, CmdStanMLE, CmdStanVB, CmdStanGQ

Examples

## Not run: 
# example with return codes all zero
fit_mcmc <- cmdstanr_example("schools", method = "sample")
fit_mcmc$return_codes() # should be all zero

# example of non-zero return code (optimization fails for hierarchical model)
fit_opt <- cmdstanr_example("schools", method = "optimize")
fit_opt$return_codes() # should be non-zero

## End(Not run)

Description

Extract the values of sampler diagnostics for each iteration and chain of MCMC. To instead get summaries of these diagnostics and associated warning messages use the $diagnostic_summary() method.

Usage

sampler_diagnostics(
  inc_warmup = FALSE,
  format = getOption("cmdstanr_draws_format", "draws_array")
)

Arguments

Value

Depends on format, but the default is a 3-D draws_array object (iteration x chain x variable). The variables for Stan's default MCMC algorithm are "accept_stat__", "stepsize__", "treedepth__", "n_leapfrog__", "divergent__", "energy__".

See Also

CmdStanMCMC

Examples

## Not run: 
fit <- cmdstanr_example("logistic")
sampler_diagnostics <- fit$sampler_diagnostics()
str(sampler_diagnostics)

library(posterior)
as_draws_df(sampler_diagnostics)

# or specify format to get a data frame instead of calling as_draws_df
fit$sampler_diagnostics(format = "df")

## End(Not run)

Description

This method is a wrapper around base::saveRDS() that ensures that all posterior draws and diagnostics are saved when saving a fitted model object. Because the contents of the CmdStan output CSV files are only read into R lazily (i.e., as needed), the ⁠$save_object()⁠ method is the safest way to guarantee that everything has been read in before saving.

Usage

save_object(file, ...)

Arguments

See Also

CmdStanMCMC, CmdStanMLE, CmdStanVB, CmdStanGQ

Examples

## Not run: 
fit <- cmdstanr_example("logistic")

temp_rds_file <- tempfile(fileext = ".RDS")
fit$save_object(file = temp_rds_file)
rm(fit)

fit <- readRDS(temp_rds_file)
fit$summary()

## End(Not run)

Description

All fitted model objects have methods for saving (moving to a specified location) the files created by CmdStanR to hold CmdStan output csv files and input data files. These methods move the files from their current location (possibly the temporary directory) to a user-specified location. The paths stored in the fitted model object will also be updated to point to the new file locations.

The versions without the save_ prefix (e.g., ⁠$output_files()⁠) return the current file paths without moving any files.

Usage

save_output_files(dir = ".", basename = NULL, timestamp = TRUE, random = TRUE)

save_latent_dynamics_files(
  dir = ".",
  basename = NULL,
  timestamp = TRUE,
  random = TRUE
)

save_profile_files(dir = ".", basename = NULL, timestamp = TRUE, random = TRUE)

save_data_file(dir = ".", basename = NULL, timestamp = TRUE, random = TRUE)

save_config_files(dir = ".", basename = NULL, timestamp = TRUE, random = TRUE)

save_metric_files(dir = ".", basename = NULL, timestamp = TRUE, random = TRUE)

output_files(include_failed = FALSE)

profile_files(include_failed = FALSE)

latent_dynamics_files(include_failed = FALSE)

data_file()

config_files(include_failed = FALSE)

metric_files(include_failed = FALSE)

Arguments

Value

The ⁠$save_*⁠ methods print a message with the new file paths and (invisibly) return a character vector of the new paths (or NA for any that couldn't be copied). They also have the side effect of setting the internal paths in the fitted model object to the new paths.

The methods without the save_ prefix return character vectors of file paths without moving any files.

Details

For ⁠$save_output_files()⁠ the files moved to dir will have names of the form basename-timestamp-id-random, where

• basename is the user's provided basename argument;

• timestamp is of the form format(Sys.time(), "%Y%m%d%H%M");

• id is the MCMC chain id (or 1 for non MCMC);

• random contains six random alphanumeric characters;

For ⁠$save_latent_dynamics_files()⁠ everything is the same as for ⁠$save_output_files()⁠ except "-diagnostic-" is included in the new file name after basename.

For ⁠$save_profile_files()⁠ everything is the same as for ⁠$save_output_files()⁠ except "-profile-" is included in the new file name after basename.

For ⁠$save_metric_files()⁠ everything is the same as for ⁠$save_output_files()⁠ except "-metric-" is included in the new file name after basename.

For ⁠$save_config_files()⁠ everything is the same as for ⁠$save_output_files()⁠ except "-config-" is included in the new file name after basename.

For ⁠$save_data_file()⁠ no id is included in the file name because even with multiple MCMC chains the data file is the same.

See Also

CmdStanMCMC, CmdStanMLE, CmdStanVB, CmdStanGQ

Examples

## Not run: 
fit <- cmdstanr_example()
fit$output_files()
fit$data_file()

# just using tempdir for the example
my_dir <- tempdir()
fit$save_output_files(dir = my_dir, basename = "banana")
fit$save_output_files(dir = my_dir, basename = "tomato", timestamp = FALSE)
fit$save_output_files(dir = my_dir, basename = "lettuce", timestamp = FALSE, random = FALSE)

## End(Not run)

Description

The ⁠$summary()⁠ method runs summarise_draws() from the posterior package and returns the output. For MCMC, only post-warmup draws are included in the summary.

There is also a ⁠$print()⁠ method that prints the same summary stats but removes the extra formatting used for printing tibbles and returns the fitted model object itself. The ⁠$print()⁠ method may also be faster than ⁠$summary()⁠ because it is designed to only compute the summary statistics for the variables that will actually fit in the printed output whereas ⁠$summary()⁠ will compute them for all of the specified variables in order to be able to return them to the user. See Examples.

Usage

summary(variables = NULL, ...)

Arguments

Value

The ⁠$summary()⁠ method returns the tibble data frame created by posterior::summarise_draws().

The ⁠$print()⁠ method returns the fitted model object itself (invisibly), which is the standard behavior for print methods in R.

See Also

CmdStanMCMC, CmdStanMLE, CmdStanLaplace, CmdStanVB, CmdStanGQ

Examples

## Not run: 
fit <- cmdstanr_example("logistic")
fit$summary()
fit$print()
fit$print(max_rows = 2) # same as print(fit, max_rows = 2)

# include only certain variables
fit$summary("beta")
fit$print(c("alpha", "beta[2]"))

# include all variables but only certain summaries
fit$summary(NULL, c("mean", "sd"))

# can use functions created from formulas
# for example, calculate Pr(beta > 0)
fit$summary("beta", prob_gt_0 = ~ mean(. > 0))

# can combine user-specified functions with
# the default summary functions
fit$summary(variables = c("alpha", "beta"),
  posterior::default_summary_measures()[1:4],
  quantiles = ~ quantile2(., probs = c(0.025, 0.975)),
  posterior::default_convergence_measures()
  )

# the functions need to calculate the appropriate
# value for a matrix input
fit$summary(variables = "alpha", dim)

# the usual [stats::var()] is therefore not directly suitable as it
# will produce a covariance matrix unless the data is converted to a vector
fit$print(c("alpha", "beta"), var2 = ~var(as.vector(.x)))


## End(Not run)

Description

Report the run time in seconds. For MCMC additional information is provided about the run times of individual chains and the warmup and sampling phases. For Laplace approximation the time only include the time for drawing the approximate sample and does not include the time taken to run the ⁠$optimize()⁠ method.

Usage

time()

Value

A list with elements

• total: (scalar) The total run time. For MCMC this may be different than the sum of the chain run times if parallelization was used.

• chains: (data frame) For MCMC only, timing info for the individual chains. The data frame has columns "chain_id", "warmup", "sampling", and "total".

See Also

CmdStanMCMC, CmdStanMLE, CmdStanVB, CmdStanGQ

Examples

## Not run: 
fit_mcmc <- cmdstanr_example("logistic", method = "sample")
fit_mcmc$time()

fit_vb <- cmdstanr_example("logistic", method = "variational")
fit_vb$time()

fit_mle <- cmdstanr_example("logistic", method = "optimize", jacobian = TRUE)
fit_mle$time()

# use fit_mle to draw samples from laplace approximation
fit_laplace <- cmdstanr_example("logistic", method = "laplace", mode = fit_mle)
fit_laplace$time() # just time for drawing sample not for running optimize
fit_laplace$time()$total + fit_mle$time()$total # total time

## End(Not run)

Description

The ⁠$unconstrain_draws()⁠ method transforms all parameter draws to the unconstrained scale. The method returns a list for each chain, containing the parameter values from each iteration on the unconstrained scale. If called with no arguments, then the draws within the fit object are unconstrained. Alternatively, either an existing draws object or a character vector of paths to CSV files can be passed.

Usage

unconstrain_draws(
  files = NULL,
  draws = NULL,
  format = getOption("cmdstanr_draws_format", "draws_array"),
  inc_warmup = FALSE
)

Arguments

See Also

log_prob(), grad_log_prob(), constrain_variables(), unconstrain_variables(), unconstrain_draws(), variable_skeleton(), hessian()

Examples

## Not run: 
fit_mcmc <- cmdstanr_example("logistic", method = "sample", force_recompile = TRUE)

# Unconstrain all internal draws
unconstrained_internal_draws <- fit_mcmc$unconstrain_draws()

# Unconstrain external CmdStan CSV files
unconstrained_csv <- fit_mcmc$unconstrain_draws(files = fit_mcmc$output_files())

# Unconstrain existing draws object
unconstrained_draws <- fit_mcmc$unconstrain_draws(draws = fit_mcmc$draws())

## End(Not run)

Description

The ⁠$unconstrain_variables()⁠ method transforms input parameters to the unconstrained scale.

Usage

unconstrain_variables(variables)

Arguments

See Also

log_prob(), grad_log_prob(), constrain_variables(), unconstrain_variables(), unconstrain_draws(), variable_skeleton(), hessian()

Examples

## Not run: 
fit_mcmc <- cmdstanr_example("logistic", method = "sample", force_recompile = TRUE)
fit_mcmc$unconstrain_variables(list(alpha = 0.5, beta = c(0.7, 1.1, 0.2)))

## End(Not run)

Description

The ⁠$variable_skeleton()⁠ method returns the variable skeleton needed by utils::relist() to re-structure a vector of constrained parameter values to a named list.

Usage

variable_skeleton(transformed_parameters = TRUE, generated_quantities = TRUE)

Arguments

See Also

log_prob(), grad_log_prob(), constrain_variables(), unconstrain_variables(), unconstrain_draws(), variable_skeleton(), hessian()

Examples

## Not run: 
fit_mcmc <- cmdstanr_example("logistic", method = "sample", force_recompile = TRUE)
fit_mcmc$variable_skeleton()

## End(Not run)

Description

The install_cmdstan() function attempts to download and install the latest release of CmdStan. Installing a previous release or a new release candidate is also possible by specifying the version or release_url argument. See the first few sections of the CmdStan installation guide for details on the C++ toolchain required for installing CmdStan.

The rebuild_cmdstan() function cleans and rebuilds the CmdStan installation. Use this function in case of any issues when compiling models.

The cmdstan_make_local() function is used to read/write makefile flags and variables from/to the make/local file of a CmdStan installation. Writing to the make/local file can be used to permanently add makefile flags/variables to an installation. For example adding specific compiler switches, changing the C++ compiler, etc. A change to the make/local file should typically be followed by calling rebuild_cmdstan().

The check_cmdstan_toolchain() function attempts to check for the required C++ toolchain. It is called internally by install_cmdstan() but can also be called directly by the user.

Usage

install_cmdstan(
  dir = NULL,
  cores = getOption("mc.cores", 2),
  quiet = FALSE,
  overwrite = FALSE,
  timeout = 1200,
  version = NULL,
  release_url = NULL,
  release_file = NULL,
  cpp_options = list(),
  check_toolchain = TRUE,
  wsl = FALSE
)

rebuild_cmdstan(
  dir = cmdstan_path(),
  cores = getOption("mc.cores", 2),
  quiet = FALSE,
  timeout = 600
)

cmdstan_make_local(dir = cmdstan_path(), cpp_options = NULL, append = TRUE)

check_cmdstan_toolchain(fix = FALSE, quiet = FALSE)

Arguments

Value

For cmdstan_make_local(), if cpp_options=NULL then the existing contents of make/local are returned without writing anything, otherwise the updated contents are returned.

Examples

## Not run: 
check_cmdstan_toolchain()

# install_cmdstan(cores = 4)

cpp_options <- list(
  "CXX" = "clang++",
  "CXXFLAGS+= -march=native",
  PRECOMPILED_HEADERS = TRUE
)
# cmdstan_make_local(cpp_options = cpp_options)
# rebuild_cmdstan()

## End(Not run)

Description

The ⁠$check_syntax()⁠ method of a CmdStanModel object checks the Stan program for syntax errors and returns TRUE (invisibly) if parsing succeeds. If invalid syntax in found an error is thrown.

Usage

check_syntax(
  pedantic = FALSE,
  include_paths = NULL,
  stanc_options = list(),
  quiet = FALSE
)

Arguments

Value

The ⁠$check_syntax()⁠ method returns TRUE (invisibly) if the model is valid.

See Also

The CmdStanR website (mc-stan.org/cmdstanr) for online documentation and tutorials.

The Stan and CmdStan documentation:

• Stan documentation: mc-stan.org/users/documentation

• CmdStan User’s Guide: mc-stan.org/docs/cmdstan-guide

Other CmdStanModel methods: model-method-compile, model-method-diagnose, model-method-expose_functions, model-method-format, model-method-generate-quantities, model-method-laplace, model-method-optimize, model-method-pathfinder, model-method-sample, model-method-sample_mpi, model-method-variables, model-method-variational

Examples

## Not run: 
file <- write_stan_file("
data {
  int N;
  array[N] int y;
}
parameters {
  // should have <lower=0> but omitting to demonstrate pedantic mode
  real lambda;
}
model {
  y ~ poisson(lambda);
}
")
mod <- cmdstan_model(file, compile = FALSE)

# the program is syntactically correct, however...
mod$check_syntax()

# pedantic mode will warn that lambda should be constrained to be positive
# and that lambda has no prior distribution
mod$check_syntax(pedantic = TRUE)

## End(Not run)

Description

The ⁠$compile()⁠ method of a CmdStanModel object checks the syntax of the Stan program, translates the program to C++, and creates a compiled executable. To just check the syntax of a Stan program without compiling it use the $check_syntax() method instead.

In most cases the user does not need to explicitly call the ⁠$compile()⁠ method as compilation will occur when calling cmdstan_model(). However it is possible to set compile=FALSE in the call to cmdstan_model() and subsequently call the ⁠$compile()⁠ method directly.

After compilation, the paths to the executable and the .hpp file containing the generated C++ code are available via the ⁠$exe_file()⁠ and ⁠$hpp_file()⁠ methods. The default is to create the executable in the same directory as the Stan program and to write the generated C++ code in a temporary directory. To save the C++ code to a non-temporary location use ⁠$save_hpp_file(dir)⁠.

Usage

compile(
  quiet = TRUE,
  dir = NULL,
  pedantic = FALSE,
  include_paths = NULL,
  user_header = NULL,
  cpp_options = list(),
  stanc_options = list(),
  force_recompile = getOption("cmdstanr_force_recompile", default = FALSE),
  compile_model_methods = FALSE,
  compile_standalone = FALSE,
  dry_run = FALSE,
  compile_hessian_method = FALSE,
  threads = FALSE
)

Arguments

Value

The ⁠$compile()⁠ method is called for its side effect of creating the executable and adding its path to the CmdStanModel object, but it also returns the CmdStanModel object invisibly.

After compilation, the ⁠$exe_file()⁠, ⁠$hpp_file()⁠, and ⁠$save_hpp_file()⁠ methods can be used and return file paths.

See Also

The $check_syntax() method to check Stan syntax or enable pedantic model without compiling.

The CmdStanR website (mc-stan.org/cmdstanr) for online documentation and tutorials.

The Stan and CmdStan documentation:

• Stan documentation: mc-stan.org/users/documentation

• CmdStan User’s Guide: mc-stan.org/docs/cmdstan-guide

Other CmdStanModel methods: model-method-check_syntax, model-method-diagnose, model-method-expose_functions, model-method-format, model-method-generate-quantities, model-method-laplace, model-method-optimize, model-method-pathfinder, model-method-sample, model-method-sample_mpi, model-method-variables, model-method-variational

Examples

## Not run: 
file <- file.path(cmdstan_path(), "examples/bernoulli/bernoulli.stan")

# by default compilation happens when cmdstan_model() is called.
# to delay compilation until calling the $compile() method set compile=FALSE
mod <- cmdstan_model(file, compile = FALSE)
mod$compile()
mod$exe_file()

# turn on threading support (for using functions that support within-chain parallelization)
mod$compile(force_recompile = TRUE, cpp_options = list(stan_threads = TRUE))
mod$exe_file()

# turn on pedantic mode (new in Stan v2.24)
file_pedantic <- write_stan_file("
parameters {
  real sigma;  // pedantic mode will warn about missing <lower=0>
}
model {
  sigma ~ exponential(1);
}
")
mod <- cmdstan_model(file_pedantic, pedantic = TRUE)


## End(Not run)

Description

The ⁠$diagnose()⁠ method of a CmdStanModel object runs Stan's basic diagnostic feature that will calculate the gradients of the initial state and compare them with gradients calculated by finite differences. Discrepancies between the two indicate that there is a problem with the model or initial states or else there is a bug in Stan.

Usage

diagnose(
  data = NULL,
  seed = NULL,
  init = NULL,
  output_dir = getOption("cmdstanr_output_dir"),
  output_basename = NULL,
  epsilon = NULL,
  error = NULL
)

Arguments

Value

A CmdStanDiagnose object.

See Also

The CmdStanR website (mc-stan.org/cmdstanr) for online documentation and tutorials.

The Stan and CmdStan documentation:

• Stan documentation: mc-stan.org/users/documentation

• CmdStan User’s Guide: mc-stan.org/docs/cmdstan-guide

Other CmdStanModel methods: model-method-check_syntax, model-method-compile, model-method-expose_functions, model-method-format, model-method-generate-quantities, model-method-laplace, model-method-optimize, model-method-pathfinder, model-method-sample, model-method-sample_mpi, model-method-variables, model-method-variational

Examples

## Not run: 
test <- cmdstanr_example("logistic", method = "diagnose")

# retrieve the gradients
test$gradients()

## End(Not run)

Description

The ⁠$expose_functions()⁠ method of a CmdStanModel object will compile the functions in the Stan program's functions block and expose them for use in R. This can also be specified via the compile_standalone argument to the $compile() method.

This method is also available for fitted model objects (CmdStanMCMC, CmdStanVB, etc.). See Examples.

Note: there may be many compiler warnings emitted during compilation but these can be ignored so long as they are warnings and not errors.

Usage

expose_functions(global = FALSE, verbose = FALSE)

Arguments

See Also

The CmdStanR website (mc-stan.org/cmdstanr) for online documentation and tutorials.

The Stan and CmdStan documentation:

• Stan documentation: mc-stan.org/users/documentation

• CmdStan User’s Guide: mc-stan.org/docs/cmdstan-guide

Other CmdStanModel methods: model-method-check_syntax, model-method-compile, model-method-diagnose, model-method-format, model-method-generate-quantities, model-method-laplace, model-method-optimize, model-method-pathfinder, model-method-sample, model-method-sample_mpi, model-method-variables, model-method-variational

Examples

## Not run: 
stan_file <- write_stan_file(
 "
 functions {
   real a_plus_b(real a, real b) {
     return a + b;
   }
 }
 parameters {
   real x;
 }
 model {
   x ~ std_normal();
 }
 "
)
mod <- cmdstan_model(stan_file)
mod$expose_functions()
mod$functions$a_plus_b(1, 2)

fit <- mod$sample(refresh = 0)
fit$expose_functions() # already compiled because of above but this would compile them otherwise
fit$functions$a_plus_b(1, 2)

## End(Not run)

Description

The ⁠$format()⁠ method of a CmdStanModel object runs stanc's auto-formatter on the model code. Either saves the formatted model directly back to the file or prints it for inspection.

Usage

format(
  overwrite_file = FALSE,
  canonicalize = FALSE,
  backup = TRUE,
  max_line_length = NULL,
  quiet = FALSE
)

Arguments

Value

The ⁠$format()⁠ method returns TRUE (invisibly) if the model is valid.

See Also

The CmdStanR website (mc-stan.org/cmdstanr) for online documentation and tutorials.

The Stan and CmdStan documentation:

• Stan documentation: mc-stan.org/users/documentation

• CmdStan User’s Guide: mc-stan.org/docs/cmdstan-guide

Other CmdStanModel methods: model-method-check_syntax, model-method-compile, model-method-diagnose, model-method-expose_functions, model-method-generate-quantities, model-method-laplace, model-method-optimize, model-method-pathfinder, model-method-sample, model-method-sample_mpi, model-method-variables, model-method-variational

Examples

## Not run: 

# Example of fixing old syntax
# real x[2] --> array[2] real x;
file <- write_stan_file("
parameters {
  real x[2];
}
model {
  x ~ std_normal();
}
")

# set compile=FALSE then call format to fix old syntax
mod <- cmdstan_model(file, compile = FALSE)
mod$format(canonicalize = list("deprecations"))

# overwrite the original file instead of just printing it
mod$format(canonicalize = list("deprecations"), overwrite_file = TRUE)
mod$compile()


# Example of removing unnecessary whitespace
file <- write_stan_file("
data {
  int N;
  array[N] int y;
}
parameters {
  real                     lambda;
}
model {
  target +=
 poisson_lpmf(y | lambda);
}
")
mod <- cmdstan_model(file, compile = FALSE)
mod$format(canonicalize = TRUE)

## End(Not run)

Description

The ⁠$generate_quantities()⁠ method of a CmdStanModel object runs Stan's standalone generated quantities to obtain generated quantities based on previously fitted parameters.

Usage

generate_quantities(
  fitted_params,
  data = NULL,
  seed = NULL,
  output_dir = getOption("cmdstanr_output_dir"),
  output_basename = NULL,
  sig_figs = NULL,
  parallel_chains = getOption("mc.cores", 1),
  threads_per_chain = NULL,
  opencl_ids = NULL
)

Arguments

Value

A CmdStanGQ object.

See Also

The CmdStanR website (mc-stan.org/cmdstanr) for online documentation and tutorials.

The Stan and CmdStan documentation:

• Stan documentation: mc-stan.org/users/documentation

• CmdStan User’s Guide: mc-stan.org/docs/cmdstan-guide

Other CmdStanModel methods: model-method-check_syntax, model-method-compile, model-method-diagnose, model-method-expose_functions, model-method-format, model-method-laplace, model-method-optimize, model-method-pathfinder, model-method-sample, model-method-sample_mpi, model-method-variables, model-method-variational

Examples

## Not run: 
# first fit a model using MCMC
mcmc_program <- write_stan_file(
  "data {
    int<lower=0> N;
    array[N] int<lower=0,upper=1> y;
  }
  parameters {
    real<lower=0,upper=1> theta;
  }
  model {
    y ~ bernoulli(theta);
  }"
)
mod_mcmc <- cmdstan_model(mcmc_program)

data <- list(N = 10, y = c(1,1,0,0,0,1,0,1,0,0))
fit_mcmc <- mod_mcmc$sample(data = data, seed = 123, refresh = 0)

# stan program for standalone generated quantities
# (could keep model block, but not necessary so removing it)
gq_program <- write_stan_file(
  "data {
    int<lower=0> N;
    array[N] int<lower=0,upper=1> y;
  }
  parameters {
    real<lower=0,upper=1> theta;
  }
  generated quantities {
    array[N] int y_rep = bernoulli_rng(rep_vector(theta, N));
  }"
)

mod_gq <- cmdstan_model(gq_program)
fit_gq <- mod_gq$generate_quantities(fit_mcmc, data = data, seed = 123)
str(fit_gq$draws())

library(posterior)
as_draws_df(fit_gq$draws())

## End(Not run)

Description

The ⁠$laplace()⁠ method of a CmdStanModel object produces a sample from a normal approximation centered at the mode of a distribution in the unconstrained space. If the mode is a maximum a posteriori (MAP) estimate, the samples provide an estimate of the mean and standard deviation of the posterior distribution. If the mode is a maximum likelihood estimate (MLE), the sample provides an estimate of the standard error of the likelihood. Whether the mode is the MAP or MLE depends on the value of the jacobian argument when running optimization. See the CmdStan User’s Guide for more details.

Any argument left as NULL will default to the default value used by the installed version of CmdStan.

Usage

laplace(
  data = NULL,
  seed = NULL,
  refresh = NULL,
  init = NULL,
  save_latent_dynamics = FALSE,
  output_dir = getOption("cmdstanr_output_dir"),
  output_basename = NULL,
  sig_figs = NULL,
  threads = NULL,
  opencl_ids = NULL,
  mode = NULL,
  opt_args = NULL,
  jacobian = TRUE,
  draws = NULL,
  show_messages = TRUE,
  show_exceptions = TRUE,
  save_cmdstan_config = NULL
)

Arguments

Value

A CmdStanLaplace object.

See Also

The CmdStanR website (mc-stan.org/cmdstanr) for online documentation and tutorials.