Merge pull request #951 from stan-dev/document-global-options

Document global options and add `cmdstanr_output_dir`

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:

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

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

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) {

R/options.R

@@ -0,0 +1,46 @@
+#' 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][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.
+#'
+#' * `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. 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
+#' 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 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
+#' use case and is documented with the methods that make use of `mc.cores`.
+#'
+#'
+NULL

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."
       )
     }
   }

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