change examples, update docs

NEWS.md

@@ -10,9 +10,11 @@ if potentially results-changing arguments are provided to the criterion method.
 ### Other Changes
 
 * Change `make_stancode` and `make_standata` to be aliases of `stancode` and 
-`standata`, respectively. This enable other packages to define new `stancode`
-and `standata` methods to generate Stan code and data for their own objects 
-building on brms. Thanks to Ven Popov for helping with this. (#1604)
+`standata`, respectively. Change `get_prior` to be an alias of a new generic 
+method `default_prior`. This enable other packages to define new `stancode`, 
+`standata` and `default_prior` methods to generate Stan code and data, and extract
+the default priors, for their own objects building on brms. Thanks to Ven Popov 
+for helping with this. (#1604)
 * No longer automatically canonicalize the Stan code if cmdstanr is used
 as backend. (#1544)
 * Improve parameter class names in the `summary` output.

R/brm.R

@@ -418,8 +418,8 @@
 #'
 #'
 #' # fit a model manually via rstan
-#' scode <- make_stancode(count ~ Trt, data = epilepsy)
-#' sdata <- make_standata(count ~ Trt, data = epilepsy)
+#' scode <- stancode(count ~ Trt, data = epilepsy)
+#' sdata <- standata(count ~ Trt, data = epilepsy)
 #' stanfit <- rstan::stan(model_code = scode, data = sdata)
 #' # feed the Stan model back into brms
 #' fit8 <- brm(count ~ Trt, data = epilepsy, empty = TRUE)

R/make_standata.R

@@ -53,7 +53,6 @@ make_standata <- function(formula, ...) {
 #'
 #' @return A named list of objects containing the required data
 #'   to fit a \pkg{brms} model with \pkg{Stan}.
-#'   The \code{get_prior} function is an alias of \code{default_prior}.
 #'
 #' @examples
 #' sdata1 <- standata(rating ~ treat + period + carry + (1|subject),

R/priors.R

@@ -319,8 +319,8 @@
 #' identical(prior1, prior3)
 #'
 #' # check which parameters can have priors
-#' get_prior(rating ~ treat + period + carry + (1|subject),
-#'           data = inhaler, family = cumulative())
+#' default_prior(rating ~ treat + period + carry + (1|subject),
+#'              data = inhaler, family = cumulative())
 #'
 #' # define some priors
 #' bprior <- c(prior_string("normal(0,10)", class = "b"),
@@ -329,25 +329,25 @@
 #'                    group = ~subject, coef = ~Intercept))
 #'
 #' # verify that the priors indeed found their way into Stan's model code
-#' make_stancode(rating ~ treat + period + carry + (1|subject),
-#'               data = inhaler, family = cumulative(),
-#'               prior = bprior)
+#' stancode(rating ~ treat + period + carry + (1|subject),
+#'          data = inhaler, family = cumulative(),
+#'          prior = bprior)
 #'
 #' # use the horseshoe prior to model sparsity in regression coefficients
-#' make_stancode(count ~ zAge + zBase * Trt,
-#'               data = epilepsy, family = poisson(),
-#'               prior = set_prior("horseshoe(3)"))
+#' stancode(count ~ zAge + zBase * Trt,
+#'          data = epilepsy, family = poisson(),
+#'          prior = set_prior("horseshoe(3)"))
 #'
 #' # fix certain priors to constants
 #' bprior <- prior(constant(1), class = "b") +
 #'   prior(constant(2), class = "b", coef = "zBase") +
 #'   prior(constant(0.5), class = "sd")
-#' make_stancode(count ~ zAge + zBase + (1 | patient),
+#' stancode(count ~ zAge + zBase + (1 | patient),
 #'               data = epilepsy, prior = bprior)
 #'
 #' # pass priors to Stan without checking
 #' prior <- prior_string("target += normal_lpdf(b[1] | 0, 1)", check = FALSE)
-#' make_stancode(count ~ Trt, data = epilepsy, prior = prior)
+#' stancode(count ~ Trt, data = epilepsy, prior = prior)
 #'
 #' # define priors in a vectorized manner
 #' # useful in particular for categorical or multivariate models
@@ -474,6 +474,7 @@ default_prior <- function(object, ...) {
 #' @rdname default_prior
 #' @export
 get_prior <- function(formula, ...) {
+  # became an alias of default_prior in 2.20.14.
   default_prior(formula, ...)
 }
 
@@ -536,7 +537,7 @@ default_prior.default <- function(object, data, family = gaussian(), autocor = N
   .default_prior(bterms, data, ...)
 }
 
-# internal work function of 'get_prior'
+# internal work function of 'default_prior'
 # @param internal return priors for internal use?
 # @return a brmsprior object
 .default_prior <- function(bterms, data, internal = FALSE, ...) {
@@ -916,7 +917,7 @@ def_lscale_prior <- function(bterms, data, plb = 0.01, pub = 0.01) {
 # @param ranef: a list returned by tidy_ranef
 # @param def_scale_prior a character string defining
 #   the default prior for SD parameters
-# @param internal: see 'get_prior'
+# @param internal: see 'default_prior'
 prior_re <- function(ranef, def_scale_prior, internal = FALSE, ...) {
   prior <- empty_prior()
   if (!nrow(ranef)) {
@@ -1189,7 +1190,7 @@ def_scale_prior.brmsterms <- function(x, data, center = TRUE, df = 3,
 #' Validate priors supplied by the user. Return a complete
 #' set of priors for the given model, including default priors.
 #'
-#' @inheritParams get_prior.default
+#' @inheritParams default_prior.default
 #' @inheritParams brm
 #'
 #' @return An object of class \code{brmsprior}.
@@ -1256,7 +1257,7 @@ validate_prior <- function(prior, formula, data, family = gaussian(),
         "The following priors do not correspond ",
         "to any model parameter: \n",
         collapse(.print_prior(prior[invalid, ]), "\n"),
-        "Function 'get_prior' might be helpful to you."
+        "Function 'default_prior' might be helpful to you."
       )
     }
     prior <- prior[!invalid, ]
@@ -1319,7 +1320,7 @@ validate_prior <- function(prior, formula, data, family = gaussian(),
         "' will not be used in the model as all related coefficients have ",
         "individual priors already. If you did not set those ",
         "priors yourself, then maybe brms has assigned default priors. ",
-        "See ?set_prior and ?get_prior for more details."
+        "See ?set_prior and ?default_prior for more details."
       )
     }
   }
@@ -2311,17 +2312,17 @@ has_special_prior <- function(prior, px = NULL, class = NULL) {
 #' @returns A named list with elements \code{const} and \code{broadcast}.
 #'
 #' @examples
-#' make_stancode(count ~ Base + Age, data = epilepsy,
-#'               prior = prior(constant(1), class = "b"))
+#' stancode(count ~ Base + Age, data = epilepsy,
+#'          prior = prior(constant(1), class = "b"))
 #'
 #' # will fail parsing because brms will try to broadcast a vector into a vector
-#' make_stancode(count ~ Base + Age, data = epilepsy,
-#'               prior = prior(constant(alpha), class = "b"),
-#'               stanvars = stanvar(c(1, 0), name = "alpha"))
+#' stancode(count ~ Base + Age, data = epilepsy,
+#'          prior = prior(constant(alpha), class = "b"),
+#'          stanvars = stanvar(c(1, 0), name = "alpha"))
 #'
-#' make_stancode(count ~ Base + Age, data = epilepsy,
-#'               prior = prior(constant(alpha, broadcast = FALSE), class = "b"),
-#'               stanvars = stanvar(c(1, 0), name = "alpha"))
+#' stancode(count ~ Base + Age, data = epilepsy,
+#'          prior = prior(constant(alpha, broadcast = FALSE), class = "b"),
+#'          stanvars = stanvar(c(1, 0), name = "alpha"))
 #'
 #' @seealso \code{\link{set_prior}}
 #'

R/projpred.R

@@ -251,7 +251,7 @@ get_refmodel.brmsfit <- function(object, newdata = NULL, resp = NULL,
     if (!is.null(orhs)) warn_wrhs_orhs("orhs")
   }
 
-  # extract the response variable manually instead of from make_standata
+  # extract the response variable manually instead of from standata
   # so that it passes input checks of validate_newdata later on (#1314)
   formula <- formula(object)
   if (!is.null(resp)) {

R/rename_pars.R

@@ -14,8 +14,8 @@
 #' @examples
 #' \dontrun{
 #' # fit a model manually via rstan
-#' scode <- make_stancode(count ~ Trt, data = epilepsy)
-#' sdata <- make_standata(count ~ Trt, data = epilepsy)
+#' scode <- stancode(count ~ Trt, data = epilepsy)
+#' sdata <- standata(count ~ Trt, data = epilepsy)
 #' stanfit <- rstan::stan(model_code = scode, data = sdata)
 #'
 #' # feed the Stan model back into brms

R/stanvars.R

@@ -44,30 +44,30 @@
 #' @examples
 #' bprior <- prior(normal(mean_intercept, 10), class = "Intercept")
 #' stanvars <- stanvar(5, name = "mean_intercept")
-#' make_stancode(count ~ Trt, epilepsy, prior = bprior,
-#'               stanvars = stanvars)
+#' stancode(count ~ Trt, epilepsy, prior = bprior,
+#'          stanvars = stanvars)
 #'
 #' # define a multi-normal prior with known covariance matrix
 #' bprior <- prior(multi_normal(M, V), class = "b")
 #' stanvars <- stanvar(rep(0, 2), "M", scode = "  vector[K] M;") +
 #'   stanvar(diag(2), "V", scode = "  matrix[K, K] V;")
-#' make_stancode(count ~ Trt + zBase, epilepsy,
-#'               prior = bprior, stanvars = stanvars)
+#' stancode(count ~ Trt + zBase, epilepsy,
+#'          prior = bprior, stanvars = stanvars)
 #'
 #' # define a hierachical prior on the regression coefficients
 #' bprior <- set_prior("normal(0, tau)", class = "b") +
 #'   set_prior("target += normal_lpdf(tau | 0, 10)", check = FALSE)
 #' stanvars <- stanvar(scode = "real<lower=0> tau;",
 #'                     block = "parameters")
-#' make_stancode(count ~ Trt + zBase, epilepsy,
-#'               prior = bprior, stanvars = stanvars)
+#' stancode(count ~ Trt + zBase, epilepsy,
+#'          prior = bprior, stanvars = stanvars)
 #'
 #' # ensure that 'tau' is passed to the likelihood of a threaded model
 #' # not necessary for this example but may be necessary in other cases
 #' stanvars <- stanvar(scode = "real<lower=0> tau;",
 #'                     block = "parameters", pll_args = "real tau")
-#' make_stancode(count ~ Trt + zBase, epilepsy,
-#'               stanvars = stanvars, threads = threading(2))
+#' stancode(count ~ Trt + zBase, epilepsy,
+#'          stanvars = stanvars, threads = threading(2))
 #'
 #' @export
 stanvar <- function(x = NULL, name = NULL, scode = NULL,

doc/brms_overview.ltx

@@ -119,7 +119,7 @@ devtools::install_github("paul-buerkner/brms")
 Additionally, a \proglang{C++} compiler is required. This is because \pkg{brms} internally creates \pkg{Stan} code, which is translated to \proglang{C++} and compiled afterwards. The program \pkg{Rtools} \citep{Rtools2015} comes with a \proglang{C++} compiler for Windows\footnote{During the installation process, there is an option to change the system \code{PATH}. Please make sure to check this options, because otherwise \pkg{Rtools} will not be available within \proglang{R}.}.
 On OS X, one should use \pkg{Xcode} \citep{Xcode2015} from the App Store. To check whether the compiler can be called within \proglang{R}, run \code{system("g++ -v")} when using \pkg{Rtools} or \code{system("clang++ -v")} when using \pkg{Xcode}. If no warning occurs and a few lines of difficult to read system code are printed out, the compiler should work correctly. For more detailed instructions on how to get the compilers running, see the prerequisites section on \url{https://github.com/stan-dev/rstan/wiki/RStan-Getting-Started}.
 
-Models are fitted in \pkg{brms} using the following procedure, which is also summarized in Figure~\ref{flowchart}. First, the user specifies the model using the \code{brm} function in a way typical for most model fitting \proglang{R} functions, that is by defining \code{formula}, \code{data}, and \code{family}, as well as some other optional arguments. Second, this information is processed and the \code{make_stancode} and \code{make_standata} functions are called. The former generates the model code in \pkg{Stan} language and the latter prepares the data for use in \pkg{Stan}. These two are the mandatory parts of every \pkg{Stan} model and without \pkg{brms}, users would have to specify them themselves. Third, \pkg{Stan} code and data as well as additional arguments (such as the number of iterations and chains) are passed to functions of the \pkg{rstan} package (the \proglang{R} interface of \pkg{Stan}; \citeauthor{stan2017}, \citeyear{stan2017}). Fourth, the model is fitted by \pkg{Stan} after translating and compiling it in \proglang{C++}. Fifth, after the model has been fitted and returned by \pkg{rstan}, the fitted model object is post-processed in \pkg{brms} among others by renaming the model parameters to be understood by the user. Sixth, the results can be investigated in \proglang{R} using various methods such as \code{summary}, \code{plot}, or \code{predict} (for a complete list of methods type \code{methods(class = "brmsfit")}).
+Models are fitted in \pkg{brms} using the following procedure, which is also summarized in Figure~\ref{flowchart}. First, the user specifies the model using the \code{brm} function in a way typical for most model fitting \proglang{R} functions, that is by defining \code{formula}, \code{data}, and \code{family}, as well as some other optional arguments. Second, this information is processed and the \code{stancode} and \code{standata} functions are called. The former generates the model code in \pkg{Stan} language and the latter prepares the data for use in \pkg{Stan}. These two are the mandatory parts of every \pkg{Stan} model and without \pkg{brms}, users would have to specify them themselves. Third, \pkg{Stan} code and data as well as additional arguments (such as the number of iterations and chains) are passed to functions of the \pkg{rstan} package (the \proglang{R} interface of \pkg{Stan}; \citeauthor{stan2017}, \citeyear{stan2017}). Fourth, the model is fitted by \pkg{Stan} after translating and compiling it in \proglang{C++}. Fifth, after the model has been fitted and returned by \pkg{rstan}, the fitted model object is post-processed in \pkg{brms} among others by renaming the model parameters to be understood by the user. Sixth, the results can be investigated in \proglang{R} using various methods such as \code{summary}, \code{plot}, or \code{predict} (for a complete list of methods type \code{methods(class = "brmsfit")}).
 
 \begin{figure}[ht]
   \centering