Skip to content

Commit 2980ca7

Browse files
jgabryjgabry
authored
Merge pull request #951 from stan-dev/document-global-options
Document global options and add `cmdstanr_output_dir`
2 parents 30c945c + a965644 commit 2980ca7

23 files changed

Lines changed: 153 additions & 47 deletions

‎DESCRIPTION‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ URL: https://mc-stan.org/cmdstanr/, https://discourse.mc-stan.org
2929
BugReports: https://github.com/stan-dev/cmdstanr/issues
3030
Encoding: UTF-8
3131
LazyData: true
32-
RoxygenNote: 7.3.0
32+
RoxygenNote: 7.3.1
3333
Roxygen: list(markdown = TRUE, r6 = FALSE)
3434
SystemRequirements: CmdStan (https://mc-stan.org/users/interfaces/cmdstan)
3535
Depends:

‎R/cmdstanr-package.R‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,9 @@
2626
#' [_Getting started with CmdStanR_](https://mc-stan.org/cmdstanr/articles/cmdstanr.html)
2727
#' demonstrates the basic functionality of the package.
2828
#'
29+
#' For a list of global [options][base::options()] see
30+
#' [cmdstanr_global_options].
31+
#'
2932
#' @template seealso-docs
3033
#' @inherit cmdstan_model examples
3134
#' @import R6

‎R/generics.R‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,8 @@
1-
21
#' Coercion methods for CmdStan objects
32
#'
4-
#' These methods are used to coerce objects into `cmdstanr` objects.
5-
#' Primarily intended for other packages to use when interfacing
6-
#' with `cmdstanr`.
3+
#' These are generic functions intended to primarily be used by developers of
4+
#' packages that interface with on CmdStanR. Developers can define methods on
5+
#' top of these generics to coerce objects into CmdStanR's fitted model objects.
76
#'
87
#' @param object to be coerced
98
#' @param ... additional arguments

‎R/model.R‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1123,7 +1123,7 @@ sample <- function(data = NULL,
11231123
refresh = NULL,
11241124
init = NULL,
11251125
save_latent_dynamics = FALSE,
1126-
output_dir = NULL,
1126+
output_dir = getOption("cmdstanr_output_dir"),
11271127
output_basename = NULL,
11281128
sig_figs = NULL,
11291129
chains = 4,
@@ -1334,7 +1334,7 @@ sample_mpi <- function(data = NULL,
13341334
refresh = NULL,
13351335
init = NULL,
13361336
save_latent_dynamics = FALSE,
1337-
output_dir = NULL,
1337+
output_dir = getOption("cmdstanr_output_dir"),
13381338
output_basename = NULL,
13391339
chains = 1,
13401340
chain_ids = seq_len(chains),
@@ -1484,7 +1484,7 @@ optimize <- function(data = NULL,
14841484
refresh = NULL,
14851485
init = NULL,
14861486
save_latent_dynamics = FALSE,
1487-
output_dir = NULL,
1487+
output_dir = getOption("cmdstanr_output_dir"),
14881488
output_basename = NULL,
14891489
sig_figs = NULL,
14901490
threads = NULL,
@@ -1622,7 +1622,7 @@ laplace <- function(data = NULL,
16221622
refresh = NULL,
16231623
init = NULL,
16241624
save_latent_dynamics = FALSE,
1625-
output_dir = NULL,
1625+
output_dir = getOption("cmdstanr_output_dir"),
16261626
output_basename = NULL,
16271627
sig_figs = NULL,
16281628
threads = NULL,
@@ -1769,7 +1769,7 @@ variational <- function(data = NULL,
17691769
refresh = NULL,
17701770
init = NULL,
17711771
save_latent_dynamics = FALSE,
1772-
output_dir = NULL,
1772+
output_dir = getOption("cmdstanr_output_dir"),
17731773
output_basename = NULL,
17741774
sig_figs = NULL,
17751775
threads = NULL,
@@ -1908,7 +1908,7 @@ pathfinder <- function(data = NULL,
19081908
refresh = NULL,
19091909
init = NULL,
19101910
save_latent_dynamics = FALSE,
1911-
output_dir = NULL,
1911+
output_dir = getOption("cmdstanr_output_dir"),
19121912
output_basename = NULL,
19131913
sig_figs = NULL,
19141914
opencl_ids = NULL,
@@ -2060,7 +2060,7 @@ CmdStanModel$set("public", name = "pathfinder", value = pathfinder)
20602060
generate_quantities <- function(fitted_params,
20612061
data = NULL,
20622062
seed = NULL,
2063-
output_dir = NULL,
2063+
output_dir = getOption("cmdstanr_output_dir"),
20642064
output_basename = NULL,
20652065
sig_figs = NULL,
20662066
parallel_chains = getOption("mc.cores", 1),
@@ -2125,7 +2125,7 @@ CmdStanModel$set("public", name = "generate_quantities", value = generate_quanti
21252125
diagnose <- function(data = NULL,
21262126
seed = NULL,
21272127
init = NULL,
2128-
output_dir = NULL,
2128+
output_dir = getOption("cmdstanr_output_dir"),
21292129
output_basename = NULL,
21302130
epsilon = NULL,
21312131
error = NULL) {

‎R/options.R‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
#' CmdStanR global options
2+
#'
3+
#' These options can be set via [options()] for an entire \R session.
4+
#'
5+
#' @name cmdstanr_global_options
6+
#'
7+
#' @details
8+
#'
9+
#' * `cmdstanr_draws_format`: Which format provided by the \pkg{posterior}
10+
#' package should be used when returning the posterior or approximate posterior
11+
#' draws? The default depends on the model fitting method. See
12+
#' [draws][fit-method-draws] for more details.
13+
#'
14+
#' * `cmdstanr_force_recompile`: Should the default be to recompile models
15+
#' even if there were no Stan code changes since last compiled? See
16+
#' [compile][model-method-compile] for more details. The default is `FALSE`.
17+
#'
18+
#' * `cmdstanr_max_rows`: The maximum number of rows of output to print when
19+
#' using the [`$print()`][fit-method-summary] method. The default is 10.
20+
#'
21+
#' * `cmdstanr_no_ver_check`: Should the check for a more recent version of
22+
#' CmdStan be disabled? The default is `FALSE`.
23+
#'
24+
#' * `cmdstanr_output_dir`: The directory where CmdStan should write its output
25+
#' CSV files when fitting models. The default is a temporary directory. Files in
26+
#' a temporary directory are removed as part of \R garbage collection, while
27+
#' files in an explicitly defined directory are not automatically deleted.
28+
#'
29+
#' * `cmdstanr_verbose`: Should more information be printed
30+
#' when compiling or running models, including showing how CmdStan was called
31+
#' internally? The default is `FALSE`.
32+
#'
33+
#' * `cmdstanr_warn_inits`: Should a warning be thrown if initial values are
34+
#' only provided for a subset of parameters? The default is `TRUE`.
35+
#'
36+
#' * `cmdstanr_write_stan_file_dir`: The directory where [write_stan_file()]
37+
#' should write Stan files. The default is a temporary directory. Files in
38+
#' a temporary directory are removed as part of \R garbage collection, while
39+
#' files in an explicitly defined directory are not automatically deleted.
40+
#'
41+
#' * `mc.cores`: The number of cores to use for various parallelization tasks
42+
#' (e.g. running MCMC chains, installing CmdStan). The default depends on the
43+
#' use case and is documented with the methods that make use of `mc.cores`.
44+
#'
45+
#'
46+
NULL

‎R/zzz.R‎

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,16 @@ startup_messages <- function() {
1010
}
1111

1212
skip_version_check <- isTRUE(getOption(
13-
"CMDSTANR_NO_VER_CHECK",
14-
default = identical(tolower(Sys.getenv("CMDSTANR_NO_VER_CHECK")), "true")
13+
"cmdstanr_no_ver_check",
14+
default = identical(tolower(Sys.getenv("cmdstanr_no_ver_check")), "true")
1515
))
16+
if (!skip_version_check) {
17+
# check if they used the old all caps version
18+
skip_version_check <- isTRUE(getOption(
19+
"CMDSTANR_NO_VER_CHECK",
20+
default = identical(tolower(Sys.getenv("CMDSTANR_NO_VER_CHECK")), "true")
21+
))
22+
}
1623
if (!skip_version_check) {
1724
latest_version <- try(suppressWarnings(latest_released_version(retries = 0)), silent = TRUE)
1825
current_version <- try(cmdstan_version(), silent = TRUE)
@@ -21,7 +28,7 @@ startup_messages <- function() {
2128
&& latest_version > current_version) {
2229
packageStartupMessage(
2330
"\nA newer version of CmdStan is available. See ?install_cmdstan() to install it.",
24-
"\nTo disable this check set option or environment variable CMDSTANR_NO_VER_CHECK=TRUE."
31+
"\nTo disable this check set option or environment variable cmdstanr_no_ver_check=TRUE."
2532
)
2633
}
2734
}

‎man-roxygen/model-common-args.R‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,8 @@
6060
#' methods there will be a single file. For interactive use this can typically
6161
#' be left at `NULL` (temporary directory) since CmdStanR makes the CmdStan
6262
#' output (posterior draws and diagnostics) available in \R via methods of the
63-
#' fitted model objects. The behavior of `output_dir` is as follows:
63+
#' fitted model objects. This can be set for an entire \R session using
64+
#' `options(cmdstanr_output_dir)`. The behavior of `output_dir` is as follows:
6465
#' * If `NULL` (the default), then the CSV files are written to a temporary
6566
#' directory and only saved permanently if the user calls one of the `$save_*`
6667
#' methods of the fitted model object (e.g.,

‎man/cmdstan_coercion.Rd‎

Lines changed: 3 additions & 3 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎man/cmdstanr-package.Rd‎

Lines changed: 3 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎man/cmdstanr_global_options.Rd‎

Lines changed: 39 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)