Save output and data files — fit-method-save_output_files • cmdstanr
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.

# Save output and data files

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

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.

    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)

    output_files(include_failed = FALSE)

    profile_files(include_failed = FALSE)

    latent_dynamics_files(include_failed = FALSE)

    data_file()

## Arguments

dir

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

basename

  (string) Base filename to use. See Details.

timestamp

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

random

  (logical) Should random alphanumeric characters be added to the end of the file name(s)? Defaults to `TRUE`. See Details.

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

    # \dontrun{
    fit <- cmdstanr_example()
    fit$output_files()
    #> [1] "/var/folders/s0/zfzm55px2nd2v__zlw5xfj2h0000gn/T/RtmpFBtN6X/logistic-202307251436-1-3f09a2.csv"
    #> [2] "/var/folders/s0/zfzm55px2nd2v__zlw5xfj2h0000gn/T/RtmpFBtN6X/logistic-202307251436-2-3f09a2.csv"
    #> [3] "/var/folders/s0/zfzm55px2nd2v__zlw5xfj2h0000gn/T/RtmpFBtN6X/logistic-202307251436-3-3f09a2.csv"
    #> [4] "/var/folders/s0/zfzm55px2nd2v__zlw5xfj2h0000gn/T/RtmpFBtN6X/logistic-202307251436-4-3f09a2.csv"
    fit$data_file()
    #> [1] "/private/var/folders/s0/zfzm55px2nd2v__zlw5xfj2h0000gn/T/RtmpKFjP9Y/temp_libpath15d4242e55c52/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:
    #> - /var/folders/s0/zfzm55px2nd2v__zlw5xfj2h0000gn/T/RtmpFBtN6X/banana-202307251436-1-1e5555.csv
    #> - /var/folders/s0/zfzm55px2nd2v__zlw5xfj2h0000gn/T/RtmpFBtN6X/banana-202307251436-2-1e5555.csv
    #> - /var/folders/s0/zfzm55px2nd2v__zlw5xfj2h0000gn/T/RtmpFBtN6X/banana-202307251436-3-1e5555.csv
    #> - /var/folders/s0/zfzm55px2nd2v__zlw5xfj2h0000gn/T/RtmpFBtN6X/banana-202307251436-4-1e5555.csv
    fit$save_output_files(dir = my_dir, basename = "tomato", timestamp = FALSE)
    #> Moved 4 files and set internal paths to new locations:
    #> - /var/folders/s0/zfzm55px2nd2v__zlw5xfj2h0000gn/T/RtmpFBtN6X/tomato-1-092670.csv
    #> - /var/folders/s0/zfzm55px2nd2v__zlw5xfj2h0000gn/T/RtmpFBtN6X/tomato-2-092670.csv
    #> - /var/folders/s0/zfzm55px2nd2v__zlw5xfj2h0000gn/T/RtmpFBtN6X/tomato-3-092670.csv
    #> - /var/folders/s0/zfzm55px2nd2v__zlw5xfj2h0000gn/T/RtmpFBtN6X/tomato-4-092670.csv
    fit$save_output_files(dir = my_dir, basename = "lettuce", timestamp = FALSE, random = FALSE)
    #> Moved 4 files and set internal paths to new locations:
    #> - /var/folders/s0/zfzm55px2nd2v__zlw5xfj2h0000gn/T/RtmpFBtN6X/lettuce-1.csv
    #> - /var/folders/s0/zfzm55px2nd2v__zlw5xfj2h0000gn/T/RtmpFBtN6X/lettuce-2.csv
    #> - /var/folders/s0/zfzm55px2nd2v__zlw5xfj2h0000gn/T/RtmpFBtN6X/lettuce-3.csv
    #> - /var/folders/s0/zfzm55px2nd2v__zlw5xfj2h0000gn/T/RtmpFBtN6X/lettuce-4.csv
    # }