Skip to contents

Save output and data files

Source: R/fit.R
fit-method-save_output_files.Rd

Fitted model objects returned directly by a CmdStanModel method have methods for saving (moving to a specified location) files created by CmdStanR, including 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.

Objects created by as_cmdstan_fit() support $output_files() but not the other methods documented on this page because the original CmdStan run is unavailable. See Reconstructed fitted model objects in the as_cmdstan_fit() documentation for details.

Usage

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

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

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

dir

(string) Path to directory where the files should be saved.

basename

(string) Base filename to use. If NULL (the default), the model name is used. See Details.

timestamp

(logical) Should a timestamp be added to the file name(s)? Defaults to TRUE. See Details.

random

(logical) Should a six-character random hexadecimal suffix be added to the file name(s)? Defaults to TRUE. See Details.

compress

(string) Compression for the saved CSV files: "none", "gzip", or "bzip2". If NULL (the default), the files keep their current compression. Only applies to $save_output_files() and $save_latent_dynamics_files().

include_failed

(logical) Should CmdStan runs that failed also be included? The default is FALSE.

Value

The $save_* methods print a message with the new file paths and (invisibly) return a character vector of the new paths. If any file cannot be copied then the method errors and no original files are removed. The methods 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.csv (.csv.gz or .csv.bz2 if compressed), where

  • basename is the user's provided basename argument or, if NULL, the model name;

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

  • id is the MCMC chain id, zero-padded to at least two digits (or 01 for non-MCMC);

  • random contains six random hexadecimal characters.

$save_latent_dynamics_files() uses the pattern basename-diagnostic-timestamp-id-random.csv (.csv.gz or .csv.bz2 if compressed). The $latent_dynamics_files() and $save_latent_dynamics_files() methods apply only to CmdStanMCMC and CmdStanVB objects created with save_latent_dynamics = TRUE.

$save_profile_files() uses the pattern basename-profile-timestamp-id-random.csv.

$save_metric_files() uses the pattern basename-metric-timestamp-id-random.json. Make sure to set save_metric = TRUE when fitting the model.

$save_config_files() uses the pattern basename-config-timestamp-id-random.json. Make sure to set save_cmdstan_config = TRUE when fitting the model.

$save_data_file() uses the pattern basename-timestamp-random.ext, where .ext is the original data file extension. No id is included because even with multiple MCMC chains the data file is the same.

Examples

# \dontrun{
fit <- cmdstanr_example()
fit$output_files()
#> [1] "/tmp/RtmpwHIm89/logistic-202610151529-01-98a3e1.csv"
#> [2] "/tmp/RtmpwHIm89/logistic-202610151529-02-98a3e1.csv"
#> [3] "/tmp/RtmpwHIm89/logistic-202610151529-03-98a3e1.csv"
#> [4] "/tmp/RtmpwHIm89/logistic-202610151529-04-98a3e1.csv"
fit$data_file()
#> [1] "/home/runner/work/_temp/Library/cmdstanr/logistic.data.json"

# just using tempdir for the example
my_dir <- tempdir()
fit$save_output_files(dir = my_dir, basename = "banana")
#> Moved 4 files and set internal paths to new locations:
#> - /tmp/RtmpwHIm89/banana-202610151529-01-90a793.csv
#> - /tmp/RtmpwHIm89/banana-202610151529-02-90a793.csv
#> - /tmp/RtmpwHIm89/banana-202610151529-03-90a793.csv
#> - /tmp/RtmpwHIm89/banana-202610151529-04-90a793.csv
fit$save_output_files(dir = my_dir, basename = "tomato", timestamp = FALSE)
#> Moved 4 files and set internal paths to new locations:
#> - /tmp/RtmpwHIm89/tomato-01-21145c.csv
#> - /tmp/RtmpwHIm89/tomato-02-21145c.csv
#> - /tmp/RtmpwHIm89/tomato-03-21145c.csv
#> - /tmp/RtmpwHIm89/tomato-04-21145c.csv
fit$save_output_files(dir = my_dir, basename = "lettuce", timestamp = FALSE, random = FALSE)
#> Moved 4 files and set internal paths to new locations:
#> - /tmp/RtmpwHIm89/lettuce-01.csv
#> - /tmp/RtmpwHIm89/lettuce-02.csv
#> - /tmp/RtmpwHIm89/lettuce-03.csv
#> - /tmp/RtmpwHIm89/lettuce-04.csv
# }