read_cmdstan_csv() is used internally by CmdStanR to read CmdStan's output CSV files into R. It can also be used by CmdStan users as a more flexible and efficient alternative to rstan::read_stan_csv().

read_cmdstan_csv(files, variables = NULL, sampler_diagnostics = NULL)

Arguments

files

A character vector of paths to the CSV files to read.

variables

Optionally, a character vector naming the variables (parameters, transformed parameters, and generated quantities) to read in.

  • If NULL (the default) then all variables are included.

  • If an empty string (variables="") then none are included.

  • For non-scalar variables all elements or specific elements can be selected:

    • variables = "theta" selects all elements of theta;

    • variables = c("theta[1]", "theta[3]") selects only the 1st and 3rd elements.

sampler_diagnostics

Works the same way as variables but for sampler diagnostic variables (e.g., "treedepth__", "accept_stat__", etc.). Ignored if the model was not fit using MCMC.

Value

A named list with the following components:

  • metadata: A list of the meta information from the run that produced the CSV file(s). See Examples below.

The other components in the returned list depend on the method that produced the CSV file(s).

For sampling the returned list also includes the following components:

  • inv_metric: A list (one element per chain) of inverse mass matrices or their diagonals, depending on the type of metric used.

  • step_size: A list (one element per chain) of the step sizes used.

  • warmup_draws: If save_warmup was TRUE when fitting the model then a draws_array of warmup draws.

  • post_warmup_draws: A draws_array of post-warmup draws.

  • warmup_sampler_diagnostics: If save_warmup was TRUE when fitting the model then a draws_array of warmup draws of the sampler diagnostic variables.

  • post_warmup_sampler_diagnostics: A draws_array of post-warmup draws of the sampler diagnostic variables.

For optimization the returned list also includes the following components:

  • point_estimates: Point estimates for the model parameters.

For variational inference the returned list also includes the following components:

  • draws: A draws_matrix of draws from the approximate posterior distribution.

For standalone generated quantities the returned list also includes the following components:

  • generated_quantities: A draws_array of the generated quantities.

Examples

# \dontrun{ stan_program <- write_stan_file( "parameters { real alpha_scalar; vector[2] theta_vector; matrix[2,2] tau_matrix; } model { alpha_scalar ~ std_normal(); theta_vector ~ std_normal(); to_vector(tau_matrix) ~ std_normal(); }" ) # only using capture.output to avoid too much printed output in example out <- utils::capture.output( mod <- cmdstan_model(stan_program), fit <- mod$sample(save_warmup=TRUE) )
#> Compiling Stan program...
# Read in everything x <- read_cmdstan_csv(fit$output_files()) str(x)
#> List of 7 #> $ metadata :List of 33 #> ..$ stan_version_major : num 2 #> ..$ stan_version_minor : num 25 #> ..$ stan_version_patch : num 0 #> ..$ method : chr "sample" #> ..$ save_warmup : num 1 #> ..$ thin : num 1 #> ..$ gamma : num 0.05 #> ..$ kappa : num 0.75 #> ..$ t0 : num 10 #> ..$ init_buffer : num 75 #> ..$ term_buffer : num 50 #> ..$ window : num 25 #> ..$ algorithm : chr "hmc" #> ..$ engine : chr "nuts" #> ..$ metric : chr "diag_e" #> ..$ stepsize_jitter : num 0 #> ..$ id : num [1:4] 1 2 3 4 #> ..$ init : num [1:4] 2 2 2 2 #> ..$ seed : num [1:4] 2.28e+08 9.36e+08 5.51e+07 7.81e+08 #> ..$ refresh : num 100 #> ..$ sig_figs : num -1 #> ..$ sampler_diagnostics : chr [1:6] "accept_stat__" "stepsize__" "treedepth__" "n_leapfrog__" ... #> ..$ model_params : chr [1:8] "lp__" "alpha_scalar" "theta_vector[1]" "theta_vector[2]" ... #> ..$ step_size_adaptation: num [1:4] 0.738 0.663 0.784 0.726 #> ..$ model_name : chr "file2ed23068f793_model" #> ..$ adapt_engaged : num 1 #> ..$ adapt_delta : num 0.8 #> ..$ max_treedepth : num 10 #> ..$ step_size : num [1:4] 1 1 1 1 #> ..$ iter_warmup : num 1000 #> ..$ iter_sampling : num 1000 #> ..$ stan_variable_dims :List of 4 #> .. ..$ lp__ : num 1 #> .. ..$ alpha_scalar: num 1 #> .. ..$ theta_vector: num 2 #> .. ..$ tau_matrix : num [1:2] 2 2 #> ..$ stan_variables : chr [1:4] "lp__" "alpha_scalar" "theta_vector" "tau_matrix" #> $ inv_metric :List of 4 #> ..$ 1: num [1:7] 0.924 1.057 0.981 0.958 1.153 ... #> ..$ 2: num [1:7] 1.128 0.872 1.114 0.84 0.93 ... #> ..$ 3: num [1:7] 0.823 1.038 1.009 0.976 1.071 ... #> ..$ 4: num [1:7] 1.004 0.989 0.964 0.852 0.951 ... #> $ step_size :List of 4 #> ..$ 1: num 0.738 #> ..$ 2: num 0.663 #> ..$ 3: num 0.784 #> ..$ 4: num 0.726 #> $ warmup_draws : 'draws_array' num [1:1000, 1:4, 1:8] -2.37 -2.37 -2.37 -4.28 -2.85 ... #> ..- attr(*, "dimnames")=List of 3 #> .. ..$ iteration: chr [1:1000] "1" "2" "3" "4" ... #> .. ..$ chain : chr [1:4] "1" "2" "3" "4" #> .. ..$ variable : chr [1:8] "lp__" "alpha_scalar" "theta_vector[1]" "theta_vector[2]" ... #> $ post_warmup_draws : 'draws_array' num [1:1000, 1:4, 1:8] -2.25 -1.48 -2.59 -2.24 -3.21 ... #> ..- attr(*, "dimnames")=List of 3 #> .. ..$ iteration: chr [1:1000] "1" "2" "3" "4" ... #> .. ..$ chain : chr [1:4] "1" "2" "3" "4" #> .. ..$ variable : chr [1:8] "lp__" "alpha_scalar" "theta_vector[1]" "theta_vector[2]" ... #> $ warmup_sampler_diagnostics : 'draws_array' num [1:1000, 1:4, 1:6] 9.99e-01 0.00 2.07e-10 9.81e-01 9.97e-01 ... #> ..- attr(*, "dimnames")=List of 3 #> .. ..$ iteration: chr [1:1000] "1" "2" "3" "4" ... #> .. ..$ chain : chr [1:4] "1" "2" "3" "4" #> .. ..$ variable : chr [1:6] "accept_stat__" "stepsize__" "treedepth__" "n_leapfrog__" ... #> $ post_warmup_sampler_diagnostics: 'draws_array' num [1:1000, 1:4, 1:6] 0.88 0.988 0.915 0.852 0.832 ... #> ..- attr(*, "dimnames")=List of 3 #> .. ..$ iteration: chr [1:1000] "1" "2" "3" "4" ... #> .. ..$ chain : chr [1:4] "1" "2" "3" "4" #> .. ..$ variable : chr [1:6] "accept_stat__" "stepsize__" "treedepth__" "n_leapfrog__" ...
# Don't read in any of the sampler diagnostic variables x <- read_cmdstan_csv(fit$output_files(), sampler_diagnostics = "") # Don't read in any of the parameters or generated quantities x <- read_cmdstan_csv(fit$output_files(), variables = "") # Read in only specific parameters and sampler diagnostics x <- read_cmdstan_csv( fit$output_files(), variables = c("alpha_scalar", "theta_vector[2]"), sampler_diagnostics = c("n_leapfrog__", "accept_stat__") ) # For non-scalar parameters all elements can be selected or only some elements, # e.g. all of "theta_vector" but only one element of "tau_matrix" x <- read_cmdstan_csv( fit$output_files(), variables = c("theta_vector", "tau_matrix[2,1]") ) # }