Merge pull request #140 from venpopov/feature/issue-132-renaming-get_…

…model_prior

Transition to get_prior, make_stancode and make_standata

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: bmm
 Title: Easy and Accesible Bayesian Measurement Models using 'brms'
-Version: 0.4.0.9000
+Version: 0.4.1.9000
 Authors@R: c(
     person("Vencislav", "Popov", , "[email protected]", role = c("aut", "cre", "cph")),
     person("Gidon", "Frischkorn", , "[email protected]", role = c("aut", "cph")),

NAMESPACE

@@ -3,6 +3,9 @@
 S3method("+",bmmformula)
 S3method("[",bmmformula)
 S3method(bmf2bf,bmmmodel)
+S3method(brms::get_prior,bmmformula)
+S3method(brms::make_stancode,bmmformula)
+S3method(brms::make_standata,bmmformula)
 S3method(check_data,IMMspatial)
 S3method(check_data,bmmmodel)
 S3method(check_data,default)
@@ -58,9 +61,9 @@ export(fit_info)
 export(fit_model)
 export(get_model_prior)
 export(get_stancode)
-export(get_stancode_parblock)
 export(get_standata)
 export(k2sd)
+export(make_stancode_parblock)
 export(mixture2p)
 export(mixture3p)
 export(pIMM)

NEWS.md

@@ -1,5 +1,8 @@
 # bmm 0.4.0+
 
+### New features
+* deprecate get_model_prior(), get_stancode() and get_standata(). These functions will be removed in future versions of the package. If you are using *brms* version 2.20.14 or later, you can now use the *brms* functions `get_prior`, `make_stancode` and `make_standata` directly with *bmm* models.
+
 # bmm 0.4.0
 
 ### New features

R/helpers-data.R

@@ -230,20 +230,14 @@ rad2deg <- function(rad){
 #'   with `bmm`. Given the `model`, the `data` and the `formula` for the model,
 #'   this function will return the combined stan data generated by `bmm` and
 #'   `brms`
-#' @param formula An object of class `brmsformula`. A symbolic description of
-#'   the model to be fitted.
-#' @param data An object of class data.frame, containing data of all variables
-#'   used in the model. The names of the variables must match the variable names
-#'   passed to the `bmmmodel` object for required argurments.
-#' @param model A description of the model to be fitted. This is a call to a
-#'   `bmmmodel` such as `mixture3p()` function. Every model function has a
-#'   number of required arguments which need to be specified within the function
-#'   call. Call [supported_models()] to see the list of supported models and
-#'   their required arguments
-#' @param prior One or more `brmsprior` objects created by [brms::set_prior()]
-#'   or related functions and combined using the c method or the + operator. See
-#'   also [get_model_prior()] for more help. Not necessary for the default model
-#'   fitting, but you can provide prior constraints to model parameters
+#'
+#'   If you are using *brms* version 2.20.14 or later, you can use
+#'   [make_standata()] directly with the `bmmformula` object. If you are using
+#'   an older version of *brms*, you have to use [get_standata()] to obtain the
+#'   default priors. The usage of [get_standata()] is deprecated and will be
+#'   removed in future versions of *bmm*.
+#'
+#' @inheritParams fit_model
 #' @param ... Further arguments passed to [brms::make_standata()]. See the
 #'   description of [brms::make_standata()] for more details
 #'
@@ -266,15 +260,32 @@ rad2deg <- function(rad){
 #' ff <- bmf(c ~ 1,
 #'           kappa ~ 1)
 #'
-#' # fit the model
-#' get_standata(formula = ff,
-#'              data = dat,
-#'              model = sdmSimple(resp_err = "y")
-#' )
+#'
+#' if (utils::packageVersion('brms') >= "2.20.14") {
+#'   # generate the stan data (if using brms version 2.20.14 or later)
+#'   make_standata(formula = ff,
+#'                 data = dat,
+#'                 model = sdmSimple(resp_err = "y"))
+#' } else {
+#'   # generate the stan data (if using an older version of brms)
+#'   get_standata(formula = ff,
+#'                data = dat,
+#'                model = sdmSimple(resp_err = "y"))
+#' }
 #' }
 #'
 get_standata <- function(formula, data, model, prior=NULL, ...) {
+  if (utils::packageVersion('brms') >= "2.20.14") {
+    message("get_standata is deprecated. Please use make_standata() instead.")
+    return(brms::make_standata(formula = formula, data = data,
+                               model = model, prior = prior, ...))
+  }
+  make_standata.bmmformula(formula = formula, data = data,
+                           model = model, prior = prior, ...)
+}
 
+#' @rdname get_standata
+make_standata.bmmformula <- function(formula, data, model, prior = NULL, ...) {
   # check model, formula and data, and transform data if necessary
   model <- check_model(model, data)
   data <- check_data(model, data, formula)

R/helpers-model.R

@@ -605,36 +605,27 @@ use_model_template <- function(model_name,
 
 
 #' @title Generate Stan code for bmm models
-#' @description A wrapper around `brms::make_stancode()` for models specified with
-#'   `bmm`. Given the `model`, the `data` and the `formula` for the model, this
-#'   function will return the combined stan code generated by `bmm` and `brms`
-#' @param formula An object of class `bmmformula`. A symbolic description of
-#'   the model to be fitted.
-#' @param data An object of class data.frame, containing data of all variables
-#'   used in the model. The names of the variables must match the variable names
-#'   passed to the `bmmmodel` object for required argurments.
-#' @param model A description of the model to be fitted. This is a call to a
-#'   `bmmmodel` such as `mixture3p()` function. Every model function has a
-#'   number of required arguments which need to be specified within the function
-#'   call. Call [supported_models()] to see the list of supported models and
-#'   their required arguments
-#' @param prior One or more `brmsprior` objects created by [brms::set_prior()]
-#'   or related functions and combined using the c method or the + operator. See
-#'   also [get_model_prior()] for more help. Not necessary for the default model
-#'   fitting, but you can provide prior constraints to model parameters
+#' @description A wrapper around `brms::make_stancode()` for models specified
+#'   with `bmm`. Given the `model`, the `data` and the `formula` for the model,
+#'   this function will return the combined stan code generated by `bmm` and
+#'   `brms`
+#'
+#'   If you are using *brms* version 2.20.14 or later, you should use
+#'   [make_stancode()] directly with the `bmmformula` object. If you are using
+#'   an older version of *brms*, you have to use [get_stancode()] to obtain the
+#'   default priors. The usage of [get_stancode()] is deprecated and will be
+#'   removed in future versions of *bmm*.
+#'
+#' @inheritParams fit_model
 #' @param ... Further arguments passed to [brms::make_stancode()]. See the
 #'   description of [brms::make_stancode()] for more details
 #'
 #' @returns A character string containing the fully commented Stan code to fit a
 #'   bmm model.
 #'
-#'
 #' @seealso [supported_models()], [brms::make_stancode()]
-#'
 #' @export
-#'
 #' @keywords extract_info
-#'
 #' @examples
 #' \dontrun{
 #' # generate artificial data from the Signal Discrimination Model
@@ -644,15 +635,29 @@ use_model_template <- function(model_name,
 #' ff <- bmmformula(c ~ 1,
 #'                  kappa ~ 1)
 #'
-#' # fit the model
+#' # generate the Stan code (if you are using brms version 2.20.14 or later)
+#' make_stancode(formula = ff,
+#'               data = dat,
+#'               model = sdmSimple(resp_err = "y"))
+#'
+#' # generate the Stan code (if you are using an older version of brms)
 #' get_stancode(formula = ff,
 #'              data = dat,
-#'              model = sdmSimple(resp_err = "y")
-#' )
+#'              model = sdmSimple(resp_err = "y"))
 #' }
 #'
 get_stancode <- function(formula, data, model, prior=NULL, ...) {
+  if (utils::packageVersion('brms') >= "2.20.14") {
+    message("get_stancode is deprecated. Please use make_stancode() instead.")
+    return(brms::make_stancode(formula = formula, data = data,
+                               model = model, prior = prior, ...))
+  }
+  make_stancode.bmmformula(formula = formula, data = data,
+                           model = model, prior = prior, ...)
+}
 
+#' @rdname get_stancode
+make_stancode.bmmformula <- function(formula, data, model, prior=NULL, ...) {
   # check model, formula and data, and transform data if necessary
   model <- check_model(model,data)
   data <- check_data(model, data, formula)
@@ -677,20 +682,7 @@ get_stancode <- function(formula, data, model, prior=NULL, ...) {
 #'   `bmm`. Given the `model`, the `data` and the `formula` for the model, this
 #'   function will return just the parameters block. Useful for figuring out
 #'   which paramters you can set initial values on
-#' @param formula An object of class `bmmformula`. A symbolic description of
-#'   the model to be fitted.
-#' @param data An object of class data.frame, containing data of all variables
-#'   used in the model. The names of the variables must match the variable names
-#'   passed to the `bmmmodel` object for required argurments.
-#' @param model A description of the model to be fitted. This is a call to a
-#'   `bmmmodel` such as `mixture3p()` function. Every model function has a
-#'   number of required arguments which need to be specified within the function
-#'   call. Call [supported_models()] to see the list of supported models and
-#'   their required arguments
-#' @param prior One or more `brmsprior` objects created by [brms::set_prior()]
-#'   or related functions and combined using the c method or the + operator. See
-#'   also [get_model_prior()] for more help. Not necessary for the default model
-#'   fitting, but you can provide prior constraints to model parameters
+#' @inheritParams fit_model
 #' @param ... Further arguments passed to [brms::make_stancode()]. See the
 #'   description of [brms::make_stancode()] for more details
 #'
@@ -703,7 +695,7 @@ get_stancode <- function(formula, data, model, prior=NULL, ...) {
 #' @seealso [supported_models()], [get_stancode()]
 #'
 #' @export
-get_stancode_parblock <- function(formula, data, model, prior=NULL, ...) {
+make_stancode_parblock <- function(formula, data, model, prior=NULL, ...) {
   stancode <- get_stancode(formula, data, model, prior, ...)
   .extract_parblock(stancode)
 }

R/helpers-prior.R

@@ -1,45 +1,34 @@
-# internal function to combine two priors (e.g. the default prior with the user given prior)
-# parts present in prior2 will overwrite the corresponding parts in prior1
-combine_prior <- function(prior1, prior2) {
-  if (!is.null(prior2)) {
-    combined_prior <- dplyr::anti_join(prior1, prior2, by=c('class', 'dpar','nlpar','coef','group','resp'))
-    prior <- combined_prior + prior2
-  } else {
-    prior <- prior1
-  }
-  return(prior)
-}
-
-
-#' @title Get Default priors for Measurement Models specified in BRMS
-#' @description Obtain the default priors for a Bayesian multilevel measurement model,
-#'   as well as information for which parameters priors can be specified.
-#'   Given the `model`, the `data` and the `formula` for the model, this function will return
-#'   the default priors that would be used to estimate the model. Additionally, it will
-#'   return all model parameters that have no prior specified (flat priors). This can help to
-#'   get an idea about which priors need to be specified and also know which priors were
-#'   used if no user-specified priors were passed to the [fit_model()] function.
-#' @param formula An object of class `bmmformula`. A symbolic description of
-#'   the model to be fitted.
-#' @param data An object of class data.frame, containing data of all variables
-#'   used in the model. The names of the variables must match the variable names
-#'   passed to the `bmmmodel` object for required argurments.
-#' @param model A description of the model to be fitted. This is a call to a
-#'   `bmmmodel` such as `mixture3p()` function. Every model function has a
-#'   number of required arguments which need to be specified within the function
-#'   call. Call [supported_models()] to see the list of supported models and
-#'   their required arguments
+#' @title Get Default priors for Measurement Models specified in BMM
+#' @description Obtain the default priors for a Bayesian multilevel measurement
+#'   model, as well as information for which parameters priors can be specified.
+#'   Given the `model`, the `data` and the `formula` for the model, this
+#'   function will return the default priors that would be used to estimate the
+#'   model. Additionally, it will return all model parameters that have no prior
+#'   specified (flat priors). This can help to get an idea about which priors
+#'   need to be specified and also know which priors were used if no
+#'   user-specified priors were passed to the [fit_model()] function.
+#'
+#'   If you are using *brms* version 2.20.14 or later, you should use
+#'   [get_prior][brms::get_prior()] directly with the `bmmformula` object. If you are using an
+#'   older version of *brms*, you have to use [get_model_prior()] to obtain the
+#'   default priors. The usage of [get_model_prior()] is deprecated and will be
+#'   removed in future versions of *bmm*.
+#'
+#'
+#' @inheritParams fit_model
 #' @param ... Further arguments passed to [brms::get_prior()]. See the
 #'   description of [brms::get_prior()] for more details
 #'
 #' @details `r a= supported_models(); a`
 #'
 #'   Type `help(package=bmm)` for a full list of available help topics.
 #'
-#' @returns A data.frame with columns specifying the `prior`, the `class`, the `coef` and `group`
-#'    for each of the priors specified. Separate rows contain the information on the
-#'    parameters (or parameter classes) for which priors can be specified.
+#' @returns A data.frame with columns specifying the `prior`, the `class`, the
+#'   `coef` and `group` for each of the priors specified. Separate rows contain
+#'   the information on the parameters (or parameter classes) for which priors
+#'   can be specified.
 #'
+#' @name get_model_prior
 #'
 #' @seealso [supported_models()], [brms::get_prior()]
 #'
@@ -57,14 +46,32 @@ combine_prior <- function(prior1, prior2) {
 #'           c ~ 1,
 #'           kappa ~ 1)
 #'
-#' # fit the model
-#' get_model_prior(formula = ff,
-#'                 data = dat,
-#'                 model = sdmSimple()
-#' )
-#' }
 #'
+#' if (utils::packageVersion('brms') >= "2.20.14") {
+#'   # extract the default bmm prior (if using brms version 2.20.14 or later)
+#'   get_prior(formula = ff,
+#'             data = dat,
+#'             model = sdmSimple())
+#' } else {
+#'    # (if using an older version of brms)
+#'    get_model_prior(formula = ff,
+#'                    data = dat,
+#'                    model = sdmSimple())
+#' }
+#' }
+#' @export
 get_model_prior <- function(formula, data, model, ...) {
+  if (utils::packageVersion('brms') >= "2.20.14") {
+    message("get_model_prior is deprecated. Please use get_prior() instead.")
+    return(brms::get_prior(formula = formula, data = data, model = model, ...))
+  }
+  get_prior.bmmformula(formula = formula, data = data, model = model, ...)
+}
+
+
+
+#' @rdname get_model_prior
+get_prior.bmmformula <- function(formula, data, model, ...) {
   model <- check_model(model, data)
   data <- check_data(model, data, formula)
   formula <- check_formula(model, data, formula)
@@ -77,7 +84,6 @@ get_model_prior <- function(formula, data, model, ...) {
   combine_prior(brms_priors, prior_args$prior)
 }
 
-
 #' @title construct constant priors to fix fixed model parameters
 #' @param model a `bmmmodel` object
 #' @param additional_pars a list of name=value pairs to fix additional
@@ -233,3 +239,16 @@ set_default_prior <- function(bmmformula, data, prior_list) {
   }
   prior
 }
+
+
+# internal function to combine two priors (e.g. the default prior with the user given prior)
+# parts present in prior2 will overwrite the corresponding parts in prior1
+combine_prior <- function(prior1, prior2) {
+  if (!is.null(prior2)) {
+    combined_prior <- dplyr::anti_join(prior1, prior2, by=c('class', 'dpar','nlpar','coef','group','resp'))
+    prior <- combined_prior + prior2
+  } else {
+    prior <- prior1
+  }
+  return(prior)
+}

R/zzz.R

@@ -1,5 +1,11 @@
 .onLoad <- function(libname, pkgname) {
   suppressMessages(bmm_options(reset_options = TRUE))
+
+  if (utils::packageVersion('brms') >= "2.20.14") {
+    #' @exportS3Method brms::get_prior bmmformula
+    #' @exportS3Method brms::make_standata bmmformula
+    #' @exportS3Method brms::make_stancode bmmformula
+  }
 }
 
 .onAttach <- function(libname, pkgname) {