From 262c32036c805dde340fcedc44806a10b5351070 Mon Sep 17 00:00:00 2001 From: jgabry Date: Wed, 17 Apr 2024 11:47:09 -0600 Subject: [PATCH 1/5] document global options closes #944 --- DESCRIPTION | 2 +- R/generics.R | 7 ++--- R/options.R | 39 +++++++++++++++++++++++++ R/zzz.R | 13 +++++++-- man/cmdstan_coercion.Rd | 6 ++-- man/cmdstanr_global_options.Rd | 33 +++++++++++++++++++++ man/model-method-check_syntax.Rd | 2 +- man/model-method-compile.Rd | 2 +- man/model-method-diagnose.Rd | 2 +- man/model-method-expose_functions.Rd | 2 +- man/model-method-format.Rd | 2 +- man/model-method-generate-quantities.Rd | 2 +- man/model-method-laplace.Rd | 2 +- man/model-method-optimize.Rd | 2 +- man/model-method-pathfinder.Rd | 2 +- man/model-method-variables.Rd | 2 +- man/model-method-variational.Rd | 2 +- 17 files changed, 100 insertions(+), 22 deletions(-) create mode 100644 R/options.R create mode 100644 man/cmdstanr_global_options.Rd diff --git a/DESCRIPTION b/DESCRIPTION index 3d55cb48..7ce3e65e 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -29,7 +29,7 @@ URL: https://mc-stan.org/cmdstanr/, https://discourse.mc-stan.org BugReports: https://github.com/stan-dev/cmdstanr/issues Encoding: UTF-8 LazyData: true -RoxygenNote: 7.3.0 +RoxygenNote: 7.3.1 Roxygen: list(markdown = TRUE, r6 = FALSE) SystemRequirements: CmdStan (https://mc-stan.org/users/interfaces/cmdstan) Depends: diff --git a/R/generics.R b/R/generics.R index 663cb859..656cf9a1 100644 --- a/R/generics.R +++ b/R/generics.R @@ -1,9 +1,8 @@ - #' Coercion methods for CmdStan objects #' -#' These methods are used to coerce objects into `cmdstanr` objects. -#' Primarily intended for other packages to use when interfacing -#' with `cmdstanr`. +#' These are generic functions intended to primarily be used by developers of +#' packages that interface with on CmdStanR. Developers can define methods on +#' top of these generics to coerce objects into CmdStanR's fitted model objects. #' #' @param object to be coerced #' @param ... additional arguments diff --git a/R/options.R b/R/options.R new file mode 100644 index 00000000..b5e39663 --- /dev/null +++ b/R/options.R @@ -0,0 +1,39 @@ +#' CmdStanR global options +#' +#' These options can be set via [options()] for an entire \R session. +#' +#' @name cmdstanr_global_options +#' +#' @details +#' +#' * `cmdstanr_draws_format`: Which format provided by the \pkg{posterior} +#' package should be used when returning the posterior or approximate posterior +#' draws? The default depends on the model fitting method. See +#' [draws][fit-method-draws] for more details. +#' +#' * `cmdstanr_force_recompile`: Should the default be to recompile models +#' even if there were no Stan code changes since last compiled? See +#' [compile][fit-method-compile] for more details. The default is `FALSE`. +#' +#' * `cmdstanr_max_rows`: The maximum number of rows of output to print when +#' using the [`$print()`][fit-method-summary] method. The default is 10. +#' +#' * `cmdstanr_no_ver_check`: Should the check for a more recent version of +#' CmdStan be disabled? The default is `FALSE`. +#' +#' * `cmdstanr_verbose`: Should more information be printed +#' when compiling or running models, including showing how CmdStan was called +#' internally? The default is `FALSE`. +#' +#' * `cmdstanr_warn_inits`: Should a warning be thrown if initial values are +#' only provided for a subset of parameters? The default is `TRUE`. +#' +#' * `cmdstanr_write_stan_file_dir`: The directory where [write_stan_file()] +#' should write Stan files. The default is [tempdir()]. +#' +#' * `mc.cores`: The number of cores to use for various parallelization tasks +#' (e.g. running MCMC chains, installing CmdStan). The default depends on the +#' use case and is documented with the methods that make use of `mc.cores`. +#' +#' +NULL diff --git a/R/zzz.R b/R/zzz.R index 0a255258..860eb894 100644 --- a/R/zzz.R +++ b/R/zzz.R @@ -10,9 +10,16 @@ startup_messages <- function() { } skip_version_check <- isTRUE(getOption( - "CMDSTANR_NO_VER_CHECK", - default = identical(tolower(Sys.getenv("CMDSTANR_NO_VER_CHECK")), "true") + "cmdstanr_no_ver_check", + default = identical(tolower(Sys.getenv("cmdstanr_no_ver_check")), "true") )) + if (!skip_version_check) { + # check if they used the old all caps version + skip_version_check <- isTRUE(getOption( + "CMDSTANR_NO_VER_CHECK", + default = identical(tolower(Sys.getenv("CMDSTANR_NO_VER_CHECK")), "true") + )) + } if (!skip_version_check) { latest_version <- try(suppressWarnings(latest_released_version(retries = 0)), silent = TRUE) current_version <- try(cmdstan_version(), silent = TRUE) @@ -21,7 +28,7 @@ startup_messages <- function() { && latest_version > current_version) { packageStartupMessage( "\nA newer version of CmdStan is available. See ?install_cmdstan() to install it.", - "\nTo disable this check set option or environment variable CMDSTANR_NO_VER_CHECK=TRUE." + "\nTo disable this check set option or environment variable cmdstanr_no_ver_check=TRUE." ) } } diff --git a/man/cmdstan_coercion.Rd b/man/cmdstan_coercion.Rd index d2d2b483..33a36d3a 100644 --- a/man/cmdstan_coercion.Rd +++ b/man/cmdstan_coercion.Rd @@ -31,7 +31,7 @@ as.CmdStanDiagnose(object, ...) \item{...}{additional arguments} } \description{ -These methods are used to coerce objects into \code{cmdstanr} objects. -Primarily intended for other packages to use when interfacing -with \code{cmdstanr}. +These are generic functions intended to primarily be used by developers of +packages that interface with on CmdStanR. Developers can define methods on +top of these generics to coerce objects into CmdStanR's fitted model objects. } diff --git a/man/cmdstanr_global_options.Rd b/man/cmdstanr_global_options.Rd new file mode 100644 index 00000000..dda64c88 --- /dev/null +++ b/man/cmdstanr_global_options.Rd @@ -0,0 +1,33 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/options.R +\name{cmdstanr_global_options} +\alias{cmdstanr_global_options} +\title{CmdStanR global options} +\description{ +These options can be set via \code{\link[=options]{options()}} for an entire \R session. +} +\details{ +\itemize{ +\item \code{cmdstanr_draws_format}: Which format provided by the \pkg{posterior} +package should be used when returning the posterior or approximate posterior +draws? The default depends on the model fitting method. See +\link[=fit-method-draws]{draws} for more details. +\item \code{cmdstanr_force_recompile}: Should the default be to recompile models +even if there were no Stan code changes since last compiled? See +\link[=fit-method-compile]{compile} for more details. The default is \code{FALSE}. +\item \code{cmdstanr_max_rows}: The maximum number of rows of output to print when +using the \code{\link[=fit-method-summary]{$print()}} method. The default is 10. +\item \code{cmdstanr_no_ver_check}: Should the check for a more recent version of +CmdStan be disabled? The default is \code{FALSE}. +\item \code{cmdstanr_verbose}: Should more information be printed +when compiling or running models, including showing how CmdStan was called +internally? The default is \code{FALSE}. +\item \code{cmdstanr_warn_inits}: Should a warning be thrown if initial values are +only provided for a subset of parameters? The default is \code{TRUE}. +\item \code{cmdstanr_write_stan_file_dir}: The directory where \code{\link[=write_stan_file]{write_stan_file()}} +should write Stan files. The default is \code{\link[=tempdir]{tempdir()}}. +\item \code{mc.cores}: The number of cores to use for various parallelization tasks +(e.g. running MCMC chains, installing CmdStan). The default depends on the +use case and is documented with the methods that make use of \code{mc.cores}. +} +} diff --git a/man/model-method-check_syntax.Rd b/man/model-method-check_syntax.Rd index a646a5e1..68366fb5 100644 --- a/man/model-method-check_syntax.Rd +++ b/man/model-method-check_syntax.Rd @@ -86,8 +86,8 @@ Other CmdStanModel methods: \code{\link{model-method-laplace}}, \code{\link{model-method-optimize}}, \code{\link{model-method-pathfinder}}, -\code{\link{model-method-sample_mpi}}, \code{\link{model-method-sample}}, +\code{\link{model-method-sample_mpi}}, \code{\link{model-method-variables}}, \code{\link{model-method-variational}} } diff --git a/man/model-method-compile.Rd b/man/model-method-compile.Rd index d295eedc..7bfa47d7 100644 --- a/man/model-method-compile.Rd +++ b/man/model-method-compile.Rd @@ -157,8 +157,8 @@ Other CmdStanModel methods: \code{\link{model-method-laplace}}, \code{\link{model-method-optimize}}, \code{\link{model-method-pathfinder}}, -\code{\link{model-method-sample_mpi}}, \code{\link{model-method-sample}}, +\code{\link{model-method-sample_mpi}}, \code{\link{model-method-variables}}, \code{\link{model-method-variational}} } diff --git a/man/model-method-diagnose.Rd b/man/model-method-diagnose.Rd index 9a0acd31..99043501 100644 --- a/man/model-method-diagnose.Rd +++ b/man/model-method-diagnose.Rd @@ -129,8 +129,8 @@ Other CmdStanModel methods: \code{\link{model-method-laplace}}, \code{\link{model-method-optimize}}, \code{\link{model-method-pathfinder}}, -\code{\link{model-method-sample_mpi}}, \code{\link{model-method-sample}}, +\code{\link{model-method-sample_mpi}}, \code{\link{model-method-variables}}, \code{\link{model-method-variational}} } diff --git a/man/model-method-expose_functions.Rd b/man/model-method-expose_functions.Rd index a62f7bb8..b7d42231 100644 --- a/man/model-method-expose_functions.Rd +++ b/man/model-method-expose_functions.Rd @@ -77,8 +77,8 @@ Other CmdStanModel methods: \code{\link{model-method-laplace}}, \code{\link{model-method-optimize}}, \code{\link{model-method-pathfinder}}, -\code{\link{model-method-sample_mpi}}, \code{\link{model-method-sample}}, +\code{\link{model-method-sample_mpi}}, \code{\link{model-method-variables}}, \code{\link{model-method-variational}} } diff --git a/man/model-method-format.Rd b/man/model-method-format.Rd index 2aa34f18..d24010a4 100644 --- a/man/model-method-format.Rd +++ b/man/model-method-format.Rd @@ -106,8 +106,8 @@ Other CmdStanModel methods: \code{\link{model-method-laplace}}, \code{\link{model-method-optimize}}, \code{\link{model-method-pathfinder}}, -\code{\link{model-method-sample_mpi}}, \code{\link{model-method-sample}}, +\code{\link{model-method-sample_mpi}}, \code{\link{model-method-variables}}, \code{\link{model-method-variational}} } diff --git a/man/model-method-generate-quantities.Rd b/man/model-method-generate-quantities.Rd index bf25602e..23acba19 100644 --- a/man/model-method-generate-quantities.Rd +++ b/man/model-method-generate-quantities.Rd @@ -178,8 +178,8 @@ Other CmdStanModel methods: \code{\link{model-method-laplace}}, \code{\link{model-method-optimize}}, \code{\link{model-method-pathfinder}}, -\code{\link{model-method-sample_mpi}}, \code{\link{model-method-sample}}, +\code{\link{model-method-sample_mpi}}, \code{\link{model-method-variables}}, \code{\link{model-method-variational}} } diff --git a/man/model-method-laplace.Rd b/man/model-method-laplace.Rd index b033fbe3..253d67f5 100644 --- a/man/model-method-laplace.Rd +++ b/man/model-method-laplace.Rd @@ -214,8 +214,8 @@ Other CmdStanModel methods: \code{\link{model-method-generate-quantities}}, \code{\link{model-method-optimize}}, \code{\link{model-method-pathfinder}}, -\code{\link{model-method-sample_mpi}}, \code{\link{model-method-sample}}, +\code{\link{model-method-sample_mpi}}, \code{\link{model-method-variables}}, \code{\link{model-method-variational}} } diff --git a/man/model-method-optimize.Rd b/man/model-method-optimize.Rd index dcf77444..b9b53454 100644 --- a/man/model-method-optimize.Rd +++ b/man/model-method-optimize.Rd @@ -332,8 +332,8 @@ Other CmdStanModel methods: \code{\link{model-method-generate-quantities}}, \code{\link{model-method-laplace}}, \code{\link{model-method-pathfinder}}, -\code{\link{model-method-sample_mpi}}, \code{\link{model-method-sample}}, +\code{\link{model-method-sample_mpi}}, \code{\link{model-method-variables}}, \code{\link{model-method-variational}} } diff --git a/man/model-method-pathfinder.Rd b/man/model-method-pathfinder.Rd index 85fc9236..41504358 100644 --- a/man/model-method-pathfinder.Rd +++ b/man/model-method-pathfinder.Rd @@ -357,8 +357,8 @@ Other CmdStanModel methods: \code{\link{model-method-generate-quantities}}, \code{\link{model-method-laplace}}, \code{\link{model-method-optimize}}, -\code{\link{model-method-sample_mpi}}, \code{\link{model-method-sample}}, +\code{\link{model-method-sample_mpi}}, \code{\link{model-method-variables}}, \code{\link{model-method-variational}} } diff --git a/man/model-method-variables.Rd b/man/model-method-variables.Rd index dc80ed9a..87e9d73e 100644 --- a/man/model-method-variables.Rd +++ b/man/model-method-variables.Rd @@ -46,8 +46,8 @@ Other CmdStanModel methods: \code{\link{model-method-laplace}}, \code{\link{model-method-optimize}}, \code{\link{model-method-pathfinder}}, -\code{\link{model-method-sample_mpi}}, \code{\link{model-method-sample}}, +\code{\link{model-method-sample_mpi}}, \code{\link{model-method-variational}} } \concept{CmdStanModel methods} diff --git a/man/model-method-variational.Rd b/man/model-method-variational.Rd index 3678f11e..1b2d9a74 100644 --- a/man/model-method-variational.Rd +++ b/man/model-method-variational.Rd @@ -333,8 +333,8 @@ Other CmdStanModel methods: \code{\link{model-method-laplace}}, \code{\link{model-method-optimize}}, \code{\link{model-method-pathfinder}}, -\code{\link{model-method-sample_mpi}}, \code{\link{model-method-sample}}, +\code{\link{model-method-sample_mpi}}, \code{\link{model-method-variables}} } \concept{CmdStanModel methods} From 4da28a7261d36dc44aa3c84d3ea18fdd722e59e4 Mon Sep 17 00:00:00 2001 From: jgabry Date: Wed, 17 Apr 2024 11:53:54 -0600 Subject: [PATCH 2/5] add option cmdstanr_output_dir closes #945 --- R/model.R | 16 ++++++++-------- R/options.R | 5 ++++- man-roxygen/model-common-args.R | 3 ++- man/cmdstanr_global_options.Rd | 4 +++- man/model-method-diagnose.Rd | 5 +++-- man/model-method-generate-quantities.Rd | 5 +++-- man/model-method-laplace.Rd | 5 +++-- man/model-method-optimize.Rd | 5 +++-- man/model-method-pathfinder.Rd | 5 +++-- man/model-method-sample.Rd | 5 +++-- man/model-method-sample_mpi.Rd | 5 +++-- man/model-method-variational.Rd | 5 +++-- 12 files changed, 41 insertions(+), 27 deletions(-) diff --git a/R/model.R b/R/model.R index 289558f0..0b4ba47e 100644 --- a/R/model.R +++ b/R/model.R @@ -1123,7 +1123,7 @@ sample <- function(data = NULL, refresh = NULL, init = NULL, save_latent_dynamics = FALSE, - output_dir = NULL, + output_dir = getOption("cmdstanr_output_dir"), output_basename = NULL, sig_figs = NULL, chains = 4, @@ -1334,7 +1334,7 @@ sample_mpi <- function(data = NULL, refresh = NULL, init = NULL, save_latent_dynamics = FALSE, - output_dir = NULL, + output_dir = getOption("cmdstanr_output_dir"), output_basename = NULL, chains = 1, chain_ids = seq_len(chains), @@ -1484,7 +1484,7 @@ optimize <- function(data = NULL, refresh = NULL, init = NULL, save_latent_dynamics = FALSE, - output_dir = NULL, + output_dir = getOption("cmdstanr_output_dir"), output_basename = NULL, sig_figs = NULL, threads = NULL, @@ -1622,7 +1622,7 @@ laplace <- function(data = NULL, refresh = NULL, init = NULL, save_latent_dynamics = FALSE, - output_dir = NULL, + output_dir = getOption("cmdstanr_output_dir"), output_basename = NULL, sig_figs = NULL, threads = NULL, @@ -1769,7 +1769,7 @@ variational <- function(data = NULL, refresh = NULL, init = NULL, save_latent_dynamics = FALSE, - output_dir = NULL, + output_dir = getOption("cmdstanr_output_dir"), output_basename = NULL, sig_figs = NULL, threads = NULL, @@ -1908,7 +1908,7 @@ pathfinder <- function(data = NULL, refresh = NULL, init = NULL, save_latent_dynamics = FALSE, - output_dir = NULL, + output_dir = getOption("cmdstanr_output_dir"), output_basename = NULL, sig_figs = NULL, opencl_ids = NULL, @@ -2060,7 +2060,7 @@ CmdStanModel$set("public", name = "pathfinder", value = pathfinder) generate_quantities <- function(fitted_params, data = NULL, seed = NULL, - output_dir = NULL, + output_dir = getOption("cmdstanr_output_dir"), output_basename = NULL, sig_figs = NULL, parallel_chains = getOption("mc.cores", 1), @@ -2125,7 +2125,7 @@ CmdStanModel$set("public", name = "generate_quantities", value = generate_quanti diagnose <- function(data = NULL, seed = NULL, init = NULL, - output_dir = NULL, + output_dir = getOption("cmdstanr_output_dir"), output_basename = NULL, epsilon = NULL, error = NULL) { diff --git a/R/options.R b/R/options.R index b5e39663..575ff27f 100644 --- a/R/options.R +++ b/R/options.R @@ -21,6 +21,9 @@ #' * `cmdstanr_no_ver_check`: Should the check for a more recent version of #' CmdStan be disabled? The default is `FALSE`. #' +#' * `cmdstanr_output_dir`: The directory where CmdStan should write its output +#' CSV files when fitting models. The default is a temporary directory. +#' #' * `cmdstanr_verbose`: Should more information be printed #' when compiling or running models, including showing how CmdStan was called #' internally? The default is `FALSE`. @@ -29,7 +32,7 @@ #' only provided for a subset of parameters? The default is `TRUE`. #' #' * `cmdstanr_write_stan_file_dir`: The directory where [write_stan_file()] -#' should write Stan files. The default is [tempdir()]. +#' should write Stan files. The default is a temporary directory. #' #' * `mc.cores`: The number of cores to use for various parallelization tasks #' (e.g. running MCMC chains, installing CmdStan). The default depends on the diff --git a/man-roxygen/model-common-args.R b/man-roxygen/model-common-args.R index ca609ebe..f65eb21c 100644 --- a/man-roxygen/model-common-args.R +++ b/man-roxygen/model-common-args.R @@ -60,7 +60,8 @@ #' methods there will be a single file. For interactive use this can typically #' be left at `NULL` (temporary directory) since CmdStanR makes the CmdStan #' output (posterior draws and diagnostics) available in \R via methods of the -#' fitted model objects. The behavior of `output_dir` is as follows: +#' fitted model objects. This can be set for an entire \R session using +#' `options(cmdstanr_output_dir)`. The behavior of `output_dir` is as follows: #' * If `NULL` (the default), then the CSV files are written to a temporary #' directory and only saved permanently if the user calls one of the `$save_*` #' methods of the fitted model object (e.g., diff --git a/man/cmdstanr_global_options.Rd b/man/cmdstanr_global_options.Rd index dda64c88..d6435165 100644 --- a/man/cmdstanr_global_options.Rd +++ b/man/cmdstanr_global_options.Rd @@ -19,13 +19,15 @@ even if there were no Stan code changes since last compiled? See using the \code{\link[=fit-method-summary]{$print()}} method. The default is 10. \item \code{cmdstanr_no_ver_check}: Should the check for a more recent version of CmdStan be disabled? The default is \code{FALSE}. +\item \code{cmdstanr_output_dir}: The directory where CmdStan should write its output +CSV files when fitting models. The default is a temporary directory. \item \code{cmdstanr_verbose}: Should more information be printed when compiling or running models, including showing how CmdStan was called internally? The default is \code{FALSE}. \item \code{cmdstanr_warn_inits}: Should a warning be thrown if initial values are only provided for a subset of parameters? The default is \code{TRUE}. \item \code{cmdstanr_write_stan_file_dir}: The directory where \code{\link[=write_stan_file]{write_stan_file()}} -should write Stan files. The default is \code{\link[=tempdir]{tempdir()}}. +should write Stan files. The default is a temporary directory. \item \code{mc.cores}: The number of cores to use for various parallelization tasks (e.g. running MCMC chains, installing CmdStan). The default depends on the use case and is documented with the methods that make use of \code{mc.cores}. diff --git a/man/model-method-diagnose.Rd b/man/model-method-diagnose.Rd index 99043501..631ce6f6 100644 --- a/man/model-method-diagnose.Rd +++ b/man/model-method-diagnose.Rd @@ -9,7 +9,7 @@ diagnose( data = NULL, seed = NULL, init = NULL, - output_dir = NULL, + output_dir = getOption("cmdstanr_output_dir"), output_basename = NULL, epsilon = NULL, error = NULL @@ -68,7 +68,8 @@ its output CSV files. For MCMC there will be one file per chain; for other methods there will be a single file. For interactive use this can typically be left at \code{NULL} (temporary directory) since CmdStanR makes the CmdStan output (posterior draws and diagnostics) available in \R via methods of the -fitted model objects. The behavior of \code{output_dir} is as follows: +fitted model objects. This can be set for an entire \R session using +\code{options(cmdstanr_output_dir)}. The behavior of \code{output_dir} is as follows: \itemize{ \item If \code{NULL} (the default), then the CSV files are written to a temporary directory and only saved permanently if the user calls one of the \verb{$save_*} diff --git a/man/model-method-generate-quantities.Rd b/man/model-method-generate-quantities.Rd index 23acba19..21ce47a2 100644 --- a/man/model-method-generate-quantities.Rd +++ b/man/model-method-generate-quantities.Rd @@ -9,7 +9,7 @@ generate_quantities( fitted_params, data = NULL, seed = NULL, - output_dir = NULL, + output_dir = getOption("cmdstanr_output_dir"), output_basename = NULL, sig_figs = NULL, parallel_chains = getOption("mc.cores", 1), @@ -62,7 +62,8 @@ its output CSV files. For MCMC there will be one file per chain; for other methods there will be a single file. For interactive use this can typically be left at \code{NULL} (temporary directory) since CmdStanR makes the CmdStan output (posterior draws and diagnostics) available in \R via methods of the -fitted model objects. The behavior of \code{output_dir} is as follows: +fitted model objects. This can be set for an entire \R session using +\code{options(cmdstanr_output_dir)}. The behavior of \code{output_dir} is as follows: \itemize{ \item If \code{NULL} (the default), then the CSV files are written to a temporary directory and only saved permanently if the user calls one of the \verb{$save_*} diff --git a/man/model-method-laplace.Rd b/man/model-method-laplace.Rd index 253d67f5..2ebb00b3 100644 --- a/man/model-method-laplace.Rd +++ b/man/model-method-laplace.Rd @@ -11,7 +11,7 @@ laplace( refresh = NULL, init = NULL, save_latent_dynamics = FALSE, - output_dir = NULL, + output_dir = getOption("cmdstanr_output_dir"), output_basename = NULL, sig_figs = NULL, threads = NULL, @@ -83,7 +83,8 @@ its output CSV files. For MCMC there will be one file per chain; for other methods there will be a single file. For interactive use this can typically be left at \code{NULL} (temporary directory) since CmdStanR makes the CmdStan output (posterior draws and diagnostics) available in \R via methods of the -fitted model objects. The behavior of \code{output_dir} is as follows: +fitted model objects. This can be set for an entire \R session using +\code{options(cmdstanr_output_dir)}. The behavior of \code{output_dir} is as follows: \itemize{ \item If \code{NULL} (the default), then the CSV files are written to a temporary directory and only saved permanently if the user calls one of the \verb{$save_*} diff --git a/man/model-method-optimize.Rd b/man/model-method-optimize.Rd index b9b53454..dbed1150 100644 --- a/man/model-method-optimize.Rd +++ b/man/model-method-optimize.Rd @@ -11,7 +11,7 @@ optimize( refresh = NULL, init = NULL, save_latent_dynamics = FALSE, - output_dir = NULL, + output_dir = getOption("cmdstanr_output_dir"), output_basename = NULL, sig_figs = NULL, threads = NULL, @@ -97,7 +97,8 @@ its output CSV files. For MCMC there will be one file per chain; for other methods there will be a single file. For interactive use this can typically be left at \code{NULL} (temporary directory) since CmdStanR makes the CmdStan output (posterior draws and diagnostics) available in \R via methods of the -fitted model objects. The behavior of \code{output_dir} is as follows: +fitted model objects. This can be set for an entire \R session using +\code{options(cmdstanr_output_dir)}. The behavior of \code{output_dir} is as follows: \itemize{ \item If \code{NULL} (the default), then the CSV files are written to a temporary directory and only saved permanently if the user calls one of the \verb{$save_*} diff --git a/man/model-method-pathfinder.Rd b/man/model-method-pathfinder.Rd index 41504358..d16ad170 100644 --- a/man/model-method-pathfinder.Rd +++ b/man/model-method-pathfinder.Rd @@ -11,7 +11,7 @@ pathfinder( refresh = NULL, init = NULL, save_latent_dynamics = FALSE, - output_dir = NULL, + output_dir = getOption("cmdstanr_output_dir"), output_basename = NULL, sig_figs = NULL, opencl_ids = NULL, @@ -102,7 +102,8 @@ its output CSV files. For MCMC there will be one file per chain; for other methods there will be a single file. For interactive use this can typically be left at \code{NULL} (temporary directory) since CmdStanR makes the CmdStan output (posterior draws and diagnostics) available in \R via methods of the -fitted model objects. The behavior of \code{output_dir} is as follows: +fitted model objects. This can be set for an entire \R session using +\code{options(cmdstanr_output_dir)}. The behavior of \code{output_dir} is as follows: \itemize{ \item If \code{NULL} (the default), then the CSV files are written to a temporary directory and only saved permanently if the user calls one of the \verb{$save_*} diff --git a/man/model-method-sample.Rd b/man/model-method-sample.Rd index 526c9c88..51b4ce45 100644 --- a/man/model-method-sample.Rd +++ b/man/model-method-sample.Rd @@ -11,7 +11,7 @@ sample( refresh = NULL, init = NULL, save_latent_dynamics = FALSE, - output_dir = NULL, + output_dir = getOption("cmdstanr_output_dir"), output_basename = NULL, sig_figs = NULL, chains = 4, @@ -115,7 +115,8 @@ its output CSV files. For MCMC there will be one file per chain; for other methods there will be a single file. For interactive use this can typically be left at \code{NULL} (temporary directory) since CmdStanR makes the CmdStan output (posterior draws and diagnostics) available in \R via methods of the -fitted model objects. The behavior of \code{output_dir} is as follows: +fitted model objects. This can be set for an entire \R session using +\code{options(cmdstanr_output_dir)}. The behavior of \code{output_dir} is as follows: \itemize{ \item If \code{NULL} (the default), then the CSV files are written to a temporary directory and only saved permanently if the user calls one of the \verb{$save_*} diff --git a/man/model-method-sample_mpi.Rd b/man/model-method-sample_mpi.Rd index ca7203da..078461bb 100644 --- a/man/model-method-sample_mpi.Rd +++ b/man/model-method-sample_mpi.Rd @@ -13,7 +13,7 @@ sample_mpi( refresh = NULL, init = NULL, save_latent_dynamics = FALSE, - output_dir = NULL, + output_dir = getOption("cmdstanr_output_dir"), output_basename = NULL, chains = 1, chain_ids = seq_len(chains), @@ -114,7 +114,8 @@ its output CSV files. For MCMC there will be one file per chain; for other methods there will be a single file. For interactive use this can typically be left at \code{NULL} (temporary directory) since CmdStanR makes the CmdStan output (posterior draws and diagnostics) available in \R via methods of the -fitted model objects. The behavior of \code{output_dir} is as follows: +fitted model objects. This can be set for an entire \R session using +\code{options(cmdstanr_output_dir)}. The behavior of \code{output_dir} is as follows: \itemize{ \item If \code{NULL} (the default), then the CSV files are written to a temporary directory and only saved permanently if the user calls one of the \verb{$save_*} diff --git a/man/model-method-variational.Rd b/man/model-method-variational.Rd index 1b2d9a74..87decfd9 100644 --- a/man/model-method-variational.Rd +++ b/man/model-method-variational.Rd @@ -11,7 +11,7 @@ variational( refresh = NULL, init = NULL, save_latent_dynamics = FALSE, - output_dir = NULL, + output_dir = getOption("cmdstanr_output_dir"), output_basename = NULL, sig_figs = NULL, threads = NULL, @@ -98,7 +98,8 @@ its output CSV files. For MCMC there will be one file per chain; for other methods there will be a single file. For interactive use this can typically be left at \code{NULL} (temporary directory) since CmdStanR makes the CmdStan output (posterior draws and diagnostics) available in \R via methods of the -fitted model objects. The behavior of \code{output_dir} is as follows: +fitted model objects. This can be set for an entire \R session using +\code{options(cmdstanr_output_dir)}. The behavior of \code{output_dir} is as follows: \itemize{ \item If \code{NULL} (the default), then the CSV files are written to a temporary directory and only saved permanently if the user calls one of the \verb{$save_*} From 280d786c854727d7af50e08515246b77e4d54f86 Mon Sep 17 00:00:00 2001 From: jgabry Date: Wed, 17 Apr 2024 12:02:31 -0600 Subject: [PATCH 3/5] link to global options from help(cmdstanr) --- R/cmdstanr-package.R | 3 +++ man/cmdstanr-package.Rd | 3 +++ 2 files changed, 6 insertions(+) diff --git a/R/cmdstanr-package.R b/R/cmdstanr-package.R index 305241bf..ce6bc525 100644 --- a/R/cmdstanr-package.R +++ b/R/cmdstanr-package.R @@ -26,6 +26,9 @@ #' [_Getting started with CmdStanR_](https://mc-stan.org/cmdstanr/articles/cmdstanr.html) #' demonstrates the basic functionality of the package. #' +#' For a list of global [options][base::options()] see +#' [cmdstanr_global_options]. +#' #' @template seealso-docs #' @inherit cmdstan_model examples #' @import R6 diff --git a/man/cmdstanr-package.Rd b/man/cmdstanr-package.Rd index c98b0b3a..87bedc0d 100644 --- a/man/cmdstanr-package.Rd +++ b/man/cmdstanr-package.Rd @@ -65,6 +65,9 @@ you already have CmdStan installed see \code{\link[=cmdstan_model]{cmdstan_model otherwise see \code{\link[=install_cmdstan]{install_cmdstan()}} to install CmdStan. The vignette \href{https://mc-stan.org/cmdstanr/articles/cmdstanr.html}{\emph{Getting started with CmdStanR}} demonstrates the basic functionality of the package. + +For a list of global \link[base:options]{options} see +\link{cmdstanr_global_options}. } \examples{ From 4dff908b0b9fd5ce202a0258adc4d366f15060b9 Mon Sep 17 00:00:00 2001 From: jgabry Date: Wed, 17 Apr 2024 14:23:48 -0600 Subject: [PATCH 4/5] fix bad doc link --- R/options.R | 2 +- man/cmdstanr_global_options.Rd | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/R/options.R b/R/options.R index 575ff27f..42a7f536 100644 --- a/R/options.R +++ b/R/options.R @@ -13,7 +13,7 @@ #' #' * `cmdstanr_force_recompile`: Should the default be to recompile models #' even if there were no Stan code changes since last compiled? See -#' [compile][fit-method-compile] for more details. The default is `FALSE`. +#' [compile][model-method-compile] for more details. The default is `FALSE`. #' #' * `cmdstanr_max_rows`: The maximum number of rows of output to print when #' using the [`$print()`][fit-method-summary] method. The default is 10. diff --git a/man/cmdstanr_global_options.Rd b/man/cmdstanr_global_options.Rd index d6435165..42ba3ac2 100644 --- a/man/cmdstanr_global_options.Rd +++ b/man/cmdstanr_global_options.Rd @@ -14,7 +14,7 @@ draws? The default depends on the model fitting method. See \link[=fit-method-draws]{draws} for more details. \item \code{cmdstanr_force_recompile}: Should the default be to recompile models even if there were no Stan code changes since last compiled? See -\link[=fit-method-compile]{compile} for more details. The default is \code{FALSE}. +\link[=model-method-compile]{compile} for more details. The default is \code{FALSE}. \item \code{cmdstanr_max_rows}: The maximum number of rows of output to print when using the \code{\link[=fit-method-summary]{$print()}} method. The default is 10. \item \code{cmdstanr_no_ver_check}: Should the check for a more recent version of From a89b46ca8667e57cd97e926edf40ae72035ee097 Mon Sep 17 00:00:00 2001 From: jgabry Date: Thu, 18 Apr 2024 09:08:22 -0600 Subject: [PATCH 5/5] clarify difference between temp dir and user specified dir --- R/options.R | 8 ++++++-- man/cmdstanr_global_options.Rd | 8 ++++++-- 2 files changed, 12 insertions(+), 4 deletions(-) diff --git a/R/options.R b/R/options.R index 42a7f536..7948908a 100644 --- a/R/options.R +++ b/R/options.R @@ -22,7 +22,9 @@ #' CmdStan be disabled? The default is `FALSE`. #' #' * `cmdstanr_output_dir`: The directory where CmdStan should write its output -#' CSV files when fitting models. The default is a temporary directory. +#' CSV files when fitting models. The default is a temporary directory. Files in +#' a temporary directory are removed as part of \R garbage collection, while +#' files in an explicitly defined directory are not automatically deleted. #' #' * `cmdstanr_verbose`: Should more information be printed #' when compiling or running models, including showing how CmdStan was called @@ -32,7 +34,9 @@ #' only provided for a subset of parameters? The default is `TRUE`. #' #' * `cmdstanr_write_stan_file_dir`: The directory where [write_stan_file()] -#' should write Stan files. The default is a temporary directory. +#' should write Stan files. The default is a temporary directory. Files in +#' a temporary directory are removed as part of \R garbage collection, while +#' files in an explicitly defined directory are not automatically deleted. #' #' * `mc.cores`: The number of cores to use for various parallelization tasks #' (e.g. running MCMC chains, installing CmdStan). The default depends on the diff --git a/man/cmdstanr_global_options.Rd b/man/cmdstanr_global_options.Rd index 42ba3ac2..a011b81a 100644 --- a/man/cmdstanr_global_options.Rd +++ b/man/cmdstanr_global_options.Rd @@ -20,14 +20,18 @@ using the \code{\link[=fit-method-summary]{$print()}} method. The default is 10. \item \code{cmdstanr_no_ver_check}: Should the check for a more recent version of CmdStan be disabled? The default is \code{FALSE}. \item \code{cmdstanr_output_dir}: The directory where CmdStan should write its output -CSV files when fitting models. The default is a temporary directory. +CSV files when fitting models. The default is a temporary directory. Files in +a temporary directory are removed as part of \R garbage collection, while +files in an explicitly defined directory are not automatically deleted. \item \code{cmdstanr_verbose}: Should more information be printed when compiling or running models, including showing how CmdStan was called internally? The default is \code{FALSE}. \item \code{cmdstanr_warn_inits}: Should a warning be thrown if initial values are only provided for a subset of parameters? The default is \code{TRUE}. \item \code{cmdstanr_write_stan_file_dir}: The directory where \code{\link[=write_stan_file]{write_stan_file()}} -should write Stan files. The default is a temporary directory. +should write Stan files. The default is a temporary directory. Files in +a temporary directory are removed as part of \R garbage collection, while +files in an explicitly defined directory are not automatically deleted. \item \code{mc.cores}: The number of cores to use for various parallelization tasks (e.g. running MCMC chains, installing CmdStan). The default depends on the use case and is documented with the methods that make use of \code{mc.cores}.