Read CmdStan CSV files into R

read_cmdstan_csv() reads CmdStan's output CSV files into R and returns the contents as a list (see the Value section for details). It is also possible to create CmdStanR's fitted model objects directly from CmdStan CSV files using the as_cmdstan_fit() function.

Usage

read_cmdstan_csv(
  files,
  variables = NULL,
  sampler_diagnostics = NULL,
  format = getOption("cmdstanr_draws_format", NULL)
)

as_cmdstan_fit(
  files,
  variables = NULL,
  check_diagnostics = TRUE,
  format = getOption("cmdstanr_draws_format")
)

Arguments

files

(character vector) The paths to the CmdStan CSV files. These can be files generated by running CmdStanR or running CmdStan directly. Compressed files ending in .csv.gz or .csv.bz2 can also be read. They are decompressed with gzip or bzip2 (on Windows the copies that come with Rtools) into a temporary file, so the temporary directory needs room for the uncompressed size of all the files. Some Linux distributions keep /tmp in memory, where that room runs out sooner than on disk. Set the TMPDIR environment variable before starting R to use a different directory.

variables

(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.

sampler_diagnostics

(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.

format

(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.

check_diagnostics

(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.

Value

as_cmdstan_fit() returns a fitted model object (CmdStanMCMC, CmdStanVB, etc.). A fitted model object created this way has some limitations compared to fitted model objects created directly by a model fitting method. See the Reconstructed fitted model objects section below for details.

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. A note about variable names and sizes reported in metadata: stan_variables lists the Stan variables and stan_variable_sizes the shape each one's columns fill. A complex variable gets a trailing dimension of 2 for its real and imaginary parts, and a tuple the dimensions of its outer array only. Column names use [i,j] for indices, [real] and [imag] for the parts of a complex number, and : for tuple elements (tup:2[1,1] is element [1,1] of the matrix in a tuple's second element, arr_tup[1]:2 the second element of the first tuple in an array of tuples). The posterior package treats everything before the last [ as the variable name, so it groups the columns of a complex variable but not those of a tuple.

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

For MCMC 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 the laplace, pathfinder and variational methods, 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:

time: Run time information for the individual processes, with one row in the chains data frame per CSV file. The returned object is the same as for the $time() method except the total run time can't be inferred directly from the CSV files (they may have been generated in parallel) and is therefore NA. For CmdStan versions before 2.39 the individual process times are reported as zero.
generated_quantities: A draws_array of the generated quantities.

Reconstructed fitted model objects

as_cmdstan_fit() reconstructs a fitted model object from CmdStan CSV files. The CSV files do not contain all of the information available to the model fitting methods, the Stan source, the console output, or the paths to most input and auxiliary files, so the reconstructed object has a reduced set of methods.

Only the following methods are available for every reconstructed object: $draws(), $lp(), $materialize(), $metadata(), $output_files(), $print(), $save_object(), and $summary(). Additional methods are available according to the inference method:

For MCMC, $diagnostic_summary(), $inv_metric(), $loo(), $num_chains(), $sampler_diagnostics(), and $time() are available. However, the total time reported by $time() will be NA because the CSV files do not record whether the chains ran in parallel.
For optimization, $mle() is available.
For variational inference, Laplace approximation, and Pathfinder, $lp_approx() is available.

All other fitted-model methods are unavailable because they require information not contained in the CSV files. Calling an unavailable method produces an informative error.

Examples

# \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] "/tmp/RtmpwHIm89/logistic-202610151532-01-854067.csv"
#> [2] "/tmp/RtmpwHIm89/logistic-202610151532-02-854067.csv"
#> [3] "/tmp/RtmpwHIm89/logistic-202610151532-03-854067.csv"
#> [4] "/tmp/RtmpwHIm89/logistic-202610151532-04-854067.csv"

# Creating fitting model objects with as_cmdstan_fit()

# 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.67  -0.66 0.25 0.25 -1.09 -0.28 1.00     4411     2967
#>   beta[2] -0.28  -0.28 0.23 0.23 -0.65  0.09 1.00     4075     2301
#>   beta[3]  0.69   0.69 0.26 0.27  0.27  1.13 1.00     4237     3104
str(fit2$draws())
#>  'draws_array' num [1:1000, 1:4, 1:105] -69.6 -65.3 -64 -65 -65 ...
#>  - 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]" ...


# 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 40
#>   ..$ stan_version_patch  : num 0
#>   ..$ start_datetime      : chr "2026-10-15 15:32:51 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          : int 4
#>   ..$ id                  : num [1:4] 1 2 3 4
#>   ..$ init                : num [1:4] 2 2 2 2
#>   ..$ seed                : num 6.3e+08
#>   ..$ refresh             : num 100
#>   ..$ sig_figs            : num 8
#>   ..$ profile_file        : chr "/tmp/RtmpwHIm89/logistic-profile-202610151532-01-3a641c.csv"
#>   ..$ save_cmdstan_config : int 0
#>   ..$ stanc_version       : chr "stanc3 v2.40.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.664 0.712 0.796 0.736
#>   ..$ 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.04 0.039 0.039 0.039
#>   .. ..$ sampling: num [1:4] 0.041 0.04 0.04 0.04
#>   .. ..$ total   : num [1:4] 0.081 0.079 0.079 0.079
#>   ..$ 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.04 0.039 0.039 0.039
#>   .. ..$ sampling: num [1:4] 0.041 0.04 0.04 0.04
#>   .. ..$ total   : num [1:4] 0.081 0.079 0.079 0.079
#>  $ inv_metric                     :List of 4
#>   ..$ 1: num [1:4] 0.0466 0.0632 0.0488 0.0752
#>   ..$ 2: num [1:4] 0.0481 0.0551 0.0536 0.0744
#>   ..$ 3: num [1:4] 0.0418 0.059 0.0427 0.0592
#>   ..$ 4: num [1:4] 0.0557 0.061 0.0534 0.0682
#>  $ step_size                      :List of 4
#>   ..$ 1: num 0.664
#>   ..$ 2: num 0.712
#>   ..$ 3: num 0.796
#>   ..$ 4: num 0.736
#>  $ warmup_draws                   : 'draws_array' num [1:1000, 1:4, 1:105] -65.9 -65.9 -65.9 -66.5 -65.8 ...
#>   ..- 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] -69.6 -65.3 -64 -65 -65 ...
#>   ..- 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] 7.45e-01 0.00 2.74e-161 9.88e-01 9.15e-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.977 0.942 0.854 0.808 0.594 ...
#>   ..- 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]")
)
# }

Usage

Arguments

Value

Reconstructed fitted model objects

See also

Examples