From dc98fee90623926a5792c158d5f936ef1b26c7c3 Mon Sep 17 00:00:00 2001 From: Paul Buerkner Date: Tue, 14 Jul 2020 18:15:04 +0200 Subject: [PATCH] fix issue #956 --- DESCRIPTION | 2 +- R/log_lik.R | 3 ++ R/posterior_epred.R | 6 ++-- R/posterior_predict.R | 39 +++++++++++------------- man-roxygen/details-allow_new_levels.R | 8 +++++ man-roxygen/details-newdata-na.R | 4 +++ man/log_lik.brmsfit.Rd | 14 +++++++++ man/posterior_epred.brmsfit.Rd | 8 +++++ man/posterior_predict.brmsfit.Rd | 42 +++++++++++++++----------- 9 files changed, 83 insertions(+), 43 deletions(-) create mode 100644 man-roxygen/details-allow_new_levels.R create mode 100644 man-roxygen/details-newdata-na.R diff --git a/DESCRIPTION b/DESCRIPTION index aaca02945..4bca60b0e 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -78,4 +78,4 @@ Additional_repositories: VignetteBuilder: knitr, R.rsp -RoxygenNote: 7.1.0 +RoxygenNote: 7.1.1 diff --git a/R/log_lik.R b/R/log_lik.R index 9ac45ae24..d0d74708f 100644 --- a/R/log_lik.R +++ b/R/log_lik.R @@ -26,6 +26,9 @@ #' If \code{pointwise = TRUE}, the output is a function #' with a \code{draws} attribute containing all relevant #' data and posterior samples. +#' +#' @template details-newdata-na +#' @template details-allow_new_levels #' #' @aliases log_lik #' @method log_lik brmsfit diff --git a/R/posterior_epred.R b/R/posterior_epred.R index 0cffa0721..d332ef9be 100644 --- a/R/posterior_epred.R +++ b/R/posterior_epred.R @@ -25,10 +25,8 @@ #' categories. In multivariate models, an additional dimension is added to the #' output which indexes along the different response variables. #' -#' @details \code{NA} values within factors in \code{newdata}, -#' are interpreted as if all dummy variables of this factor are -#' zero. This allows, for instance, to make predictions of the grand mean -#' when using sum coding. +#' @template details-newdata-na +#' @template details-allow_new_levels #' #' @examples #' \dontrun{ diff --git a/R/posterior_predict.R b/R/posterior_predict.R index acdc25903..6cb41099e 100644 --- a/R/posterior_predict.R +++ b/R/posterior_predict.R @@ -29,27 +29,24 @@ #' @param ... Further arguments passed to \code{\link{prepare_predictions}} #' that control several aspects of data validation and prediction. #' -#' @return An \code{array} of predicted response values. If \code{summary = -#' FALSE}, the output is as an S x N matrix, where S is the number of -#' posterior samples and N is the number of observations. In multivariate -#' models, an additional dimension is added to the output which indexes along -#' the different response variables. -#' -#' @details \code{NA} values within factors in \code{newdata}, -#' are interpreted as if all dummy variables of this factor are -#' zero. This allows, for instance, to make predictions of the grand mean -#' when using sum coding. -#' -#' For truncated discrete models only: In the absence of any general algorithm -#' to sample from truncated discrete distributions, rejection sampling is -#' applied in this special case. This means that values are sampled until a -#' value lies within the defined truncation boundaries. In practice, this -#' procedure may be rather slow (especially in \R). Thus, we try to do -#' approximate rejection sampling by sampling each value \code{ntrys} times -#' and then select a valid value. If all values are invalid, the closest -#' boundary is used, instead. If there are more than a few of these -#' pathological cases, a warning will occur suggesting to increase argument -#' \code{ntrys}. +#' @return An \code{array} of predicted response values. In univariate models, +#' the output is as an S x N matrix, where S is the number of posterior +#' samples and N is the number of observations. In multivariate models, an +#' additional dimension is added to the output which indexes along the +#' different response variables. +#' +#' @template details-newdata-na +#' @template details-allow_new_levels +#' @details For truncated discrete models only: In the absence of any general +#' algorithm to sample from truncated discrete distributions, rejection +#' sampling is applied in this special case. This means that values are +#' sampled until a value lies within the defined truncation boundaries. In +#' practice, this procedure may be rather slow (especially in \R). Thus, we +#' try to do approximate rejection sampling by sampling each value +#' \code{ntrys} times and then select a valid value. If all values are +#' invalid, the closest boundary is used, instead. If there are more than a +#' few of these pathological cases, a warning will occur suggesting to +#' increase argument \code{ntrys}. #' #' @examples #' \dontrun{ diff --git a/man-roxygen/details-allow_new_levels.R b/man-roxygen/details-allow_new_levels.R new file mode 100644 index 000000000..3366c2c8b --- /dev/null +++ b/man-roxygen/details-allow_new_levels.R @@ -0,0 +1,8 @@ +#' @details +#' In multilevel models, it is possible to +#' allow new levels of grouping factors to be used in the predictions. +#' This can be controlled via argument \code{allow_new_levels}. +#' New levels can be sampled in multiple ways, which can be controlled +#' via argument \code{sample_new_levels}. Both of these arguments are +#' documented in \code{\link{prepare_predictions}} along with several +#' other useful arguments to control specific aspects of the predictions. diff --git a/man-roxygen/details-newdata-na.R b/man-roxygen/details-newdata-na.R new file mode 100644 index 000000000..24063b239 --- /dev/null +++ b/man-roxygen/details-newdata-na.R @@ -0,0 +1,4 @@ +#' @details \code{NA} values within factors in \code{newdata}, +#' are interpreted as if all dummy variables of this factor are +#' zero. This allows, for instance, to make predictions of the grand mean +#' when using sum coding. diff --git a/man/log_lik.brmsfit.Rd b/man/log_lik.brmsfit.Rd index b0758661b..38a9a52bc 100644 --- a/man/log_lik.brmsfit.Rd +++ b/man/log_lik.brmsfit.Rd @@ -74,3 +74,17 @@ Usually, an S x N matrix containing the pointwise log-likelihood \description{ Compute the Pointwise Log-Likelihood } +\details{ +\code{NA} values within factors in \code{newdata}, + are interpreted as if all dummy variables of this factor are + zero. This allows, for instance, to make predictions of the grand mean + when using sum coding. + +In multilevel models, it is possible to +allow new levels of grouping factors to be used in the predictions. +This can be controlled via argument \code{allow_new_levels}. +New levels can be sampled in multiple ways, which can be controlled +via argument \code{sample_new_levels}. Both of these arguments are +documented in \code{\link{prepare_predictions}} along with several +other useful arguments to control specific aspects of the predictions. +} diff --git a/man/posterior_epred.brmsfit.Rd b/man/posterior_epred.brmsfit.Rd index faa2b7928..07c646c69 100644 --- a/man/posterior_epred.brmsfit.Rd +++ b/man/posterior_epred.brmsfit.Rd @@ -83,6 +83,14 @@ similar. are interpreted as if all dummy variables of this factor are zero. This allows, for instance, to make predictions of the grand mean when using sum coding. + +In multilevel models, it is possible to +allow new levels of grouping factors to be used in the predictions. +This can be controlled via argument \code{allow_new_levels}. +New levels can be sampled in multiple ways, which can be controlled +via argument \code{sample_new_levels}. Both of these arguments are +documented in \code{\link{prepare_predictions}} along with several +other useful arguments to control specific aspects of the predictions. } \examples{ \dontrun{ diff --git a/man/posterior_predict.brmsfit.Rd b/man/posterior_predict.brmsfit.Rd index d30f70cb8..9abd61780 100644 --- a/man/posterior_predict.brmsfit.Rd +++ b/man/posterior_predict.brmsfit.Rd @@ -68,11 +68,11 @@ for truncated discrete models only that control several aspects of data validation and prediction.} } \value{ -An \code{array} of predicted response values. If \code{summary = - FALSE}, the output is as an S x N matrix, where S is the number of - posterior samples and N is the number of observations. In multivariate - models, an additional dimension is added to the output which indexes along - the different response variables. +An \code{array} of predicted response values. In univariate models, + the output is as an S x N matrix, where S is the number of posterior + samples and N is the number of observations. In multivariate models, an + additional dimension is added to the output which indexes along the + different response variables. } \description{ Compute posterior samples of the posterior predictive distribution. Can be @@ -87,18 +87,26 @@ both methods averaged across samples should be very similar. \code{NA} values within factors in \code{newdata}, are interpreted as if all dummy variables of this factor are zero. This allows, for instance, to make predictions of the grand mean - when using sum coding. - - For truncated discrete models only: In the absence of any general algorithm - to sample from truncated discrete distributions, rejection sampling is - applied in this special case. This means that values are sampled until a - value lies within the defined truncation boundaries. In practice, this - procedure may be rather slow (especially in \R). Thus, we try to do - approximate rejection sampling by sampling each value \code{ntrys} times - and then select a valid value. If all values are invalid, the closest - boundary is used, instead. If there are more than a few of these - pathological cases, a warning will occur suggesting to increase argument - \code{ntrys}. + when using sum coding. + +In multilevel models, it is possible to +allow new levels of grouping factors to be used in the predictions. +This can be controlled via argument \code{allow_new_levels}. +New levels can be sampled in multiple ways, which can be controlled +via argument \code{sample_new_levels}. Both of these arguments are +documented in \code{\link{prepare_predictions}} along with several +other useful arguments to control specific aspects of the predictions. + +For truncated discrete models only: In the absence of any general + algorithm to sample from truncated discrete distributions, rejection + sampling is applied in this special case. This means that values are + sampled until a value lies within the defined truncation boundaries. In + practice, this procedure may be rather slow (especially in \R). Thus, we + try to do approximate rejection sampling by sampling each value + \code{ntrys} times and then select a valid value. If all values are + invalid, the closest boundary is used, instead. If there are more than a + few of these pathological cases, a warning will occur suggesting to + increase argument \code{ntrys}. } \examples{ \dontrun{