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(). See
the Value section for details on the structure of the returned list.
It is also possible to create CmdStanR's fitted model objects directly from
CmdStan CSV files using the as_cmdstan_fit() function.
(character vector) The paths to the CmdStan CSV files. These can be files generated by running CmdStanR or running CmdStan directly.
(character vector) Optionally, the names of 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.
(character vector) 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.
(string) The format for storing the draws or point estimates. The default depends on the method used to fit the model. See draws for details, in particular the note about speed and memory for models with many parameters.
(logical) For models fit using MCMC, should
diagnostic checks be performed after reading in the files? The default is
TRUE but set to FALSE to avoid checking for problems with divergences
and treedepth.
as_cmdstan_fit() returns a CmdStanMCMC, CmdStanMLE, CmdStanLaplace or
CmdStanVB object. Some methods typically defined for those objects will not
work (e.g. save_data_file()) but the important methods like $summary(),
$draws(), $sampler_diagnostics() and others will work fine.
read_cmdstan_csv() returns 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:
time: Run time information for the individual chains. The returned object
is the same as for the $time() method except the total run
time can't be inferred from the CSV files (the chains may have been run in
parallel) and is therefore NA.
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 (or different format if format is
specified) of warmup draws.
post_warmup_draws: A draws_array (or
different format if format is specified) of post-warmup draws.
warmup_sampler_diagnostics: If save_warmup was TRUE when fitting the
model then a draws_array (or different format if
format is specified) of warmup draws of the sampler diagnostic variables.
post_warmup_sampler_diagnostics: A
draws_array (or different format if format is
specified) 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 laplace and variational inference the returned list also includes the following components:
draws: A draws_matrix (or different format
if format is specified) 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.
# \dontrun{
# Generate some CSV files to use for demonstration
fit1 <- cmdstanr_example("logistic", method = "sample", save_warmup = TRUE)
csv_files <- fit1$output_files()
print(csv_files)
#> [1] "/var/folders/s0/zfzm55px2nd2v__zlw5xfj2h0000gn/T/RtmpiACQ3q/logistic-202407021545-1-30065a.csv"
#> [2] "/var/folders/s0/zfzm55px2nd2v__zlw5xfj2h0000gn/T/RtmpiACQ3q/logistic-202407021545-2-30065a.csv"
#> [3] "/var/folders/s0/zfzm55px2nd2v__zlw5xfj2h0000gn/T/RtmpiACQ3q/logistic-202407021545-3-30065a.csv"
#> [4] "/var/folders/s0/zfzm55px2nd2v__zlw5xfj2h0000gn/T/RtmpiACQ3q/logistic-202407021545-4-30065a.csv"
# Creating fitting model objects
# Create a CmdStanMCMC object from the CSV files
fit2 <- as_cmdstan_fit(csv_files)
fit2$print("beta")
#> variable mean median sd mad q5 q95 rhat ess_bulk ess_tail
#> beta[1] -0.68 -0.67 0.25 0.25 -1.10 -0.27 1.00 3980 2575
#> beta[2] -0.26 -0.26 0.22 0.22 -0.64 0.09 1.00 4323 3108
#> beta[3] 0.68 0.67 0.27 0.26 0.26 1.13 1.00 4167 3210
# Using read_cmdstan_csv
#
# Read in everything
x <- read_cmdstan_csv(csv_files)
str(x)
#> List of 8
#> $ metadata :List of 42
#> ..$ stan_version_major : num 2
#> ..$ stan_version_minor : num 35
#> ..$ stan_version_patch : num 0
#> ..$ start_datetime : chr "2024-07-02 21:45:26 UTC"
#> ..$ method : chr "sample"
#> ..$ save_warmup : int 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
#> ..$ save_metric : int 0
#> ..$ algorithm : chr "hmc"
#> ..$ engine : chr "nuts"
#> ..$ metric : chr "diag_e"
#> ..$ stepsize_jitter : num 0
#> ..$ num_chains : num 1
#> ..$ id : num [1:4] 1 2 3 4
#> ..$ init : num [1:4] 2 2 2 2
#> ..$ seed : num 2.06e+09
#> ..$ refresh : num 100
#> ..$ sig_figs : num -1
#> ..$ profile_file : chr "/var/folders/s0/zfzm55px2nd2v__zlw5xfj2h0000gn/T/RtmpiACQ3q/logistic-profile-202407021545-1-8f8eaa.csv"
#> ..$ save_cmdstan_config : int 0
#> ..$ stanc_version : chr "stanc3 v2.35.0"
#> ..$ sampler_diagnostics : chr [1:6] "accept_stat__" "stepsize__" "treedepth__" "n_leapfrog__" ...
#> ..$ variables : chr [1:105] "lp__" "alpha" "beta[1]" "beta[2]" ...
#> ..$ step_size_adaptation: num [1:4] 0.753 0.696 0.766 0.757
#> ..$ model_name : chr "logistic_model"
#> ..$ adapt_engaged : int 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
#> ..$ threads_per_chain : num 1
#> ..$ time :'data.frame': 4 obs. of 4 variables:
#> .. ..$ chain_id: num [1:4] 1 2 3 4
#> .. ..$ warmup : num [1:4] 0.119 0.121 0.128 0.12
#> .. ..$ sampling: num [1:4] 0.129 0.131 0.122 0.118
#> .. ..$ total : num [1:4] 0.248 0.252 0.25 0.238
#> ..$ stan_variable_sizes :List of 4
#> .. ..$ lp__ : num 1
#> .. ..$ alpha : num 1
#> .. ..$ beta : num 3
#> .. ..$ log_lik: num 100
#> ..$ stan_variables : chr [1:4] "lp__" "alpha" "beta" "log_lik"
#> ..$ model_params : chr [1:105] "lp__" "alpha" "beta[1]" "beta[2]" ...
#> $ time :List of 2
#> ..$ total : int NA
#> ..$ chains:'data.frame': 4 obs. of 4 variables:
#> .. ..$ chain_id: num [1:4] 1 2 3 4
#> .. ..$ warmup : num [1:4] 0.119 0.121 0.128 0.12
#> .. ..$ sampling: num [1:4] 0.129 0.131 0.122 0.118
#> .. ..$ total : num [1:4] 0.248 0.252 0.25 0.238
#> $ inv_metric :List of 4
#> ..$ 1: num [1:4] 0.0537 0.06 0.0539 0.075
#> ..$ 2: num [1:4] 0.0427 0.0583 0.0515 0.083
#> ..$ 3: num [1:4] 0.0455 0.062 0.0441 0.0752
#> ..$ 4: num [1:4] 0.0443 0.0707 0.0544 0.0781
#> $ step_size :List of 4
#> ..$ 1: num 0.753
#> ..$ 2: num 0.696
#> ..$ 3: num 0.766
#> ..$ 4: num 0.757
#> $ warmup_draws : 'draws_array' num [1:1000, 1:4, 1:105] -77.2 -77.2 -77.2 -65.2 -65.2 ...
#> ..- attr(*, "dimnames")=List of 3
#> .. ..$ iteration: chr [1:1000] "1" "2" "3" "4" ...
#> .. ..$ chain : chr [1:4] "1" "2" "3" "4"
#> .. ..$ variable : chr [1:105] "lp__" "alpha" "beta[1]" "beta[2]" ...
#> $ post_warmup_draws : 'draws_array' num [1:1000, 1:4, 1:105] -67.2 -64.2 -64.3 -65.2 -66.3 ...
#> ..- attr(*, "dimnames")=List of 3
#> .. ..$ iteration: chr [1:1000] "1" "2" "3" "4" ...
#> .. ..$ chain : chr [1:4] "1" "2" "3" "4"
#> .. ..$ variable : chr [1:105] "lp__" "alpha" "beta[1]" "beta[2]" ...
#> $ warmup_sampler_diagnostics : 'draws_array' num [1:1000, 1:4, 1:6] 0.749 0 0 0.978 0.989 ...
#> ..- 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.865 1 0.991 0.942 0.714 ...
#> ..- 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(csv_files, sampler_diagnostics = "")
# Don't read in any of the parameters or generated quantities
x <- read_cmdstan_csv(csv_files, variables = "")
# Read in only specific parameters and sampler diagnostics
x <- read_cmdstan_csv(
csv_files,
variables = c("alpha", "beta[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 the vector "beta" but only one element of the vector "log_lik"
x <- read_cmdstan_csv(
csv_files,
variables = c("beta", "log_lik[3]")
)
# }