From 4b3e79213b7a05e5639f31e2c68dfc3623eed5a1 Mon Sep 17 00:00:00 2001 From: "Mattan S. Ben-Shachar" Date: Thu, 5 Sep 2024 13:27:58 +0300 Subject: [PATCH] si, bf, describe_posterior [skip] --- R/bayesfactor_parameters.R | 54 ++++++++++++++++++++++------------- R/bayesfactor_restricted.R | 21 ++++++++++++-- R/describe_posterior.R | 53 +++++++++++++++++++++++++++++++++- R/si.R | 39 ++++++++++++++++++++----- man/bayesfactor_parameters.Rd | 40 ++++++++++++++------------ man/bayesfactor_restricted.Rd | 50 +++++++++++++++++++------------- man/describe_posterior.Rd | 21 ++++++++++++++ man/si.Rd | 43 ++++++++++++++-------------- 8 files changed, 231 insertions(+), 90 deletions(-) diff --git a/R/bayesfactor_parameters.R b/R/bayesfactor_parameters.R index f11f9c665..1bfe0b010 100644 --- a/R/bayesfactor_parameters.R +++ b/R/bayesfactor_parameters.R @@ -85,26 +85,22 @@ #' (Note that by default, `brms::brm()` uses flat priors for fixed-effects; #' See example below.) #' \cr\cr -#' It is important to provide the correct `prior` for meaningful results. +#' It is important to provide the correct `prior` for meaningful results, +#' to match the `posterior`-type input: #' -#' - When `posterior` is a numerical vector, `prior` should also be a numerical vector. -#' - When `posterior` is a `data.frame`, `prior` should also be a `data.frame`, with matching column order. -#' - When `posterior` is a `stanreg`, `brmsfit` or other supported Bayesian model: -#' - `prior` can be set to `NULL`, in which case prior samples are drawn internally. -#' - `prior` can also be a model equivalent to `posterior` but with samples from -#' the priors *only*. See [unupdate()]. -#' - **Note:** When `posterior` is a `brmsfit_multiple` model, `prior` **must** be provided. -#' - When `posterior` is an output from a `{marginaleffects}` function, `prior` should also be an an output -#' from a `{marginaleffects}` function equivalent to `posterior` but created -#' with a model of priors samples *only*. -#' - When `posterior` is an `emmGrid` / `emm_list` object: -#' - `prior` should also be an `emmGrid` / `emm_list` object equivalent to `posterior` but -#' created with a model of priors samples *only*. See [unupdate()]. -#' - `prior` can also be the original (posterior) *model*. If so, the function will try to -#' update the `emmGrid` / `emm_list` to use the [unupdate()]d prior-model. -#' (*This cannot be done for `brmsfit` models.*) -#' - **Note**: When the `emmGrid` has undergone any transformations (`"log"`, `"response"`, etc.), -#' or `regrid`ing, then `prior` must be an `emmGrid` object, as stated above. +#' - **A numeric vector** - `prior` should also be a _numeric vector_, representing the prior-estimate. +#' - **A data frame** - `prior` should also be a _data frame_, representing the prior-estimates, in matching column order. +#' - If `rvar_col` is specified, `prior` should be _the name of an `rvar` column_ that represents the prior-estimates. +#' - **Supported Bayesian model (`stanreg`, `brmsfit`, etc.)** +#' - `prior` should be _a model an equivalent model with MCMC samples from the priors *only*_. See [unupdate()]. +#' - If `prior` is set to `NULL`, [unupdate()] is called internally (not supported for `brmsfit_multiple` model). +#' - **Output from a `{marginaleffects}` function** - `prior` should also be _an equivalent output_ from a `{marginaleffects}` function based on a prior-model +#' (See [unupdate()]). +#' - **Output from an `{emmeans}` function** +#' - `prior` should also be _an equivalent output_ from an `{emmeans}` function based on a prior-model (See [unupdate()]). +#' - `prior` can also be _the original (posterior) model_, in which case the function +#' will try to "unupdate" the estimates (not supported if the estimates have undergone +#' any transformations -- `"log"`, `"response"`, etc. -- or any `regrid`ing). #' #' @section Interpreting Bayes Factors: #' A Bayes factor greater than 1 can be interpreted as evidence against the @@ -406,13 +402,31 @@ bayesfactor_parameters.comparisons <- bayesfactor_parameters.emmGrid #' @rdname bayesfactor_parameters +#' @inheritParams p_direction #' @export bayesfactor_parameters.data.frame <- function(posterior, prior = NULL, direction = "two-sided", null = 0, + rvar_col = NULL, verbose = TRUE, ...) { + if (length(x_rvar <- .possibly_extract_rvar_col(posterior, rvar_col)) > 0L) { + cl <- match.call() + cl[[1]] <- bayestestR::bayesfactor_parameters + cl$posterior <- x_rvar + cl$rvar_col <- NULL + if (length(prior_rvar <- .possibly_extract_rvar_col(posterior, prior)) > 0L) { + cl$prior <- prior_rvar + } + out <- eval.parent(cl) + + obj_name <- insight::safe_deparse_symbol(substitute(posterior)) + attr(out, "object_name") <- sprintf('%s[["%s"]]', obj_name, rvar_col) + + return(.append_datagrid(out, posterior)) + } + # find direction direction <- .get_direction(direction) @@ -473,7 +487,7 @@ bayesfactor_parameters.draws <- function(posterior, ...) { bayesfactor_parameters( .posterior_draws_to_df(posterior), - prior = prior, + prior = if (!is.null(prior)) .posterior_draws_to_df(prior), direction = direction, null = null, verbose = verbose, diff --git a/R/bayesfactor_restricted.R b/R/bayesfactor_restricted.R index c5ddf4f46..6dbb1644b 100644 --- a/R/bayesfactor_restricted.R +++ b/R/bayesfactor_restricted.R @@ -195,7 +195,21 @@ bayesfactor_restricted.predictions <- bayesfactor_restricted.emmGrid bayesfactor_restricted.comparisons <- bayesfactor_restricted.emmGrid #' @export -bayesfactor_restricted.data.frame <- function(posterior, hypothesis, prior = NULL, ...) { +#' @rdname bayesfactor_restricted +#' @inheritParams p_direction +bayesfactor_restricted.data.frame <- function(posterior, hypothesis, prior = NULL, rvar_col = NULL, ...) { + if (length(x_rvar <- .possibly_extract_rvar_col(posterior, rvar_col)) > 0L) { + cl <- match.call() + cl[[1]] <- bayestestR::bayesfactor_restricted + cl$posterior <- x_rvar + cl$rvar_col <- NULL + if (length(prior_rvar <- .possibly_extract_rvar_col(posterior, prior)) > 0L) { + cl$prior <- prior_rvar + } + return(eval.parent(cl)) + } + + p_hypothesis <- parse(text = hypothesis) if (is.null(prior)) { @@ -251,7 +265,10 @@ bayesfactor_restricted.data.frame <- function(posterior, hypothesis, prior = NUL #' @export bayesfactor_restricted.draws <- function(posterior, hypothesis, prior = NULL, ...) { - bayesfactor_restricted(.posterior_draws_to_df(posterior), hypothesis = hypothesis, prior = prior, ...) + bayesfactor_restricted(.posterior_draws_to_df(posterior), + hypothesis = hypothesis, + prior = if (!is.null(prior)) .posterior_draws_to_df(prior), + ...) } #' @export diff --git a/R/describe_posterior.R b/R/describe_posterior.R index 56b3c8432..a551702b4 100644 --- a/R/describe_posterior.R +++ b/R/describe_posterior.R @@ -568,7 +568,58 @@ describe_posterior.double <- describe_posterior.numeric #' @export -describe_posterior.data.frame <- describe_posterior.numeric +#' @rdname describe_posterior +#' @inheritParams p_direction +describe_posterior.data.frame <- function(posterior, + centrality = "median", + dispersion = FALSE, + ci = 0.95, + ci_method = "eti", + test = c("p_direction", "rope"), + rope_range = "default", + rope_ci = 0.95, + keep_iterations = FALSE, + bf_prior = NULL, + BF = 1, + rvar_col = NULL, + verbose = TRUE, + ...) { + if (length(x_rvar <- .possibly_extract_rvar_col(posterior, rvar_col)) > 0L) { + cl <- match.call() + cl[[1]] <- bayestestR::describe_posterior + cl$posterior <- x_rvar + cl$rvar_col <- NULL + if (length(prior_rvar <- .possibly_extract_rvar_col(posterior, bf_prior)) > 0L) { + cl$bf_prior <- prior_rvar + } + out <- eval.parent(cl) + + obj_name <- insight::safe_deparse_symbol(substitute(posterior)) + attr(out, "object_name") <- sprintf('%s[["%s"]]', obj_name, rvar_col) + + return(.append_datagrid(out, posterior)) + } + + + out <- .describe_posterior( + posterior, + centrality = centrality, + dispersion = dispersion, + ci = ci, + ci_method = ci_method, + test = test, + rope_range = rope_range, + rope_ci = rope_ci, + keep_iterations = keep_iterations, + bf_prior = bf_prior, + BF = BF, + verbose = verbose, + ... + ) + + class(out) <- unique(c("describe_posterior", "see_describe_posterior", class(out))) + out +} #' @export diff --git a/R/si.R b/R/si.R index 497a60f74..65fa6fb47 100644 --- a/R/si.R +++ b/R/si.R @@ -221,8 +221,31 @@ si.get_predicted <- function(posterior, prior = NULL, BF = 1, use_iterations = F #' @rdname si +#' @inheritParams p_direction #' @export -si.data.frame <- function(posterior, prior = NULL, BF = 1, verbose = TRUE, ...) { +si.data.frame <- function(posterior, prior = NULL, BF = 1, rvar_col = NULL, verbose = TRUE, ...) { + if (length(x_rvar <- .possibly_extract_rvar_col(posterior, rvar_col)) > 0L) { + cl <- match.call() + cl[[1]] <- bayestestR::si + cl$posterior <- x_rvar + cl$rvar_col <- NULL + if (length(prior_rvar <- .possibly_extract_rvar_col(posterior, prior)) > 0L) { + cl$prior <- prior_rvar + } + out <- eval.parent(cl) + + obj_name <- insight::safe_deparse_symbol(substitute(posterior)) + attr(out, "object_name") <- sprintf('%s[["%s"]]', obj_name, rvar_col) + + # This doesn't use .append_datagrid because we get a non-grid output + dgrid <- posterior[,vapply(posterior, function(col) !inherits(col, "rvar"), FUN.VALUE = logical(1)), drop = FALSE] + dgrid$Parameter <- unique(out$Parameter) + out_grid <- datawizard::data_join(dgrid, out, by = "Parameter") + class(out_grid) <- class(out) + return(out) + } + + if (is.null(prior)) { prior <- posterior insight::format_warning( @@ -255,7 +278,9 @@ si.data.frame <- function(posterior, prior = NULL, BF = 1, verbose = TRUE, ...) #' @export si.draws <- function(posterior, prior = NULL, BF = 1, verbose = TRUE, ...) { - si(.posterior_draws_to_df(posterior), prior = prior, BF = BF, verbose = verbose, ...) + si(.posterior_draws_to_df(posterior), + prior = if (!is.null(prior)) .posterior_draws_to_df(prior), + BF = BF, verbose = verbose, ...) } #' @export @@ -276,7 +301,7 @@ si.rvar <- si.draws ) } - out <- data.frame( + data.frame( Parameter = colnames(posterior), CI = BF, CI_low = sis[, 1], @@ -310,12 +335,12 @@ si.rvar <- si.draws f_prior <- .logspline(prior, ...) f_posterior <- .logspline(posterior, ...) - d_prior <- logspline::dlogspline(x_axis, f_prior) - d_posterior <- logspline::dlogspline(x_axis, f_posterior) + d_prior <- logspline::dlogspline(x_axis, f_prior, log = TRUE) + d_posterior <- logspline::dlogspline(x_axis, f_posterior, log = TRUE) - relative_d <- d_posterior / d_prior + relative_d <- d_posterior - d_prior - crit <- relative_d >= BF + crit <- relative_d >= log(BF) cp <- rle(stats::na.omit(crit)) if (length(cp$lengths) > 3 && verbose) { diff --git a/man/bayesfactor_parameters.Rd b/man/bayesfactor_parameters.Rd index a29ee8d37..2af2c0143 100644 --- a/man/bayesfactor_parameters.Rd +++ b/man/bayesfactor_parameters.Rd @@ -117,6 +117,7 @@ bf_rope( prior = NULL, direction = "two-sided", null = 0, + rvar_col = NULL, verbose = TRUE, ... ) @@ -152,6 +153,9 @@ that should be returned. Meta-parameters (like \code{lp__} or \code{prior_}) are filtered by default, so only parameters that typically appear in the \code{summary()} are returned. Use \code{parameters} to select specific parameters for the output.} + +\item{rvar_col}{A single character - the name of an \code{rvar} column in the data +frame to be processed. See example in \code{\link[=p_direction]{p_direction()}}.} } \value{ A data frame containing the (log) Bayes factor representing evidence @@ -228,29 +232,27 @@ prior. (Note that by default, \code{brms::brm()} uses flat priors for fixed-effects; See example below.) \cr\cr -It is important to provide the correct \code{prior} for meaningful results. +It is important to provide the correct \code{prior} for meaningful results, +to match the \code{posterior}-type input: +\itemize{ +\item \strong{A numeric vector} - \code{prior} should also be a \emph{numeric vector}, representing the prior-estimate. +\item \strong{A data frame} - \code{prior} should also be a \emph{data frame}, representing the prior-estimates, in matching column order. \itemize{ -\item When \code{posterior} is a numerical vector, \code{prior} should also be a numerical vector. -\item When \code{posterior} is a \code{data.frame}, \code{prior} should also be a \code{data.frame}, with matching column order. -\item When \code{posterior} is a \code{stanreg}, \code{brmsfit} or other supported Bayesian model: +\item If \code{rvar_col} is specified, \code{prior} should be \emph{the name of an \code{rvar} column} that represents the prior-estimates. +} +\item \strong{Supported Bayesian model (\code{stanreg}, \code{brmsfit}, etc.)} \itemize{ -\item \code{prior} can be set to \code{NULL}, in which case prior samples are drawn internally. -\item \code{prior} can also be a model equivalent to \code{posterior} but with samples from -the priors \emph{only}. See \code{\link[=unupdate]{unupdate()}}. -\item \strong{Note:} When \code{posterior} is a \code{brmsfit_multiple} model, \code{prior} \strong{must} be provided. +\item \code{prior} should be \emph{a model an equivalent model with MCMC samples from the priors \emph{only}}. See \code{\link[=unupdate]{unupdate()}}. +\item If \code{prior} is set to \code{NULL}, \code{\link[=unupdate]{unupdate()}} is called internally (not supported for \code{brmsfit_multiple} model). } -\item When \code{posterior} is an output from a \code{{marginaleffects}} function, \code{prior} should also be an an output -from a \code{{marginaleffects}} function equivalent to \code{posterior} but created -with a model of priors samples \emph{only}. -\item When \code{posterior} is an \code{emmGrid} / \code{emm_list} object: +\item \strong{Output from a \code{{marginaleffects}} function} - \code{prior} should also be \emph{an equivalent output} from a \code{{marginaleffects}} function based on a prior-model +(See \code{\link[=unupdate]{unupdate()}}). +\item \strong{Output from an \code{{emmeans}} function} \itemize{ -\item \code{prior} should also be an \code{emmGrid} / \code{emm_list} object equivalent to \code{posterior} but -created with a model of priors samples \emph{only}. See \code{\link[=unupdate]{unupdate()}}. -\item \code{prior} can also be the original (posterior) \emph{model}. If so, the function will try to -update the \code{emmGrid} / \code{emm_list} to use the \code{\link[=unupdate]{unupdate()}}d prior-model. -(\emph{This cannot be done for \code{brmsfit} models.}) -\item \strong{Note}: When the \code{emmGrid} has undergone any transformations (\code{"log"}, \code{"response"}, etc.), -or \code{regrid}ing, then \code{prior} must be an \code{emmGrid} object, as stated above. +\item \code{prior} should also be \emph{an equivalent output} from an \code{{emmeans}} function based on a prior-model (See \code{\link[=unupdate]{unupdate()}}). +\item \code{prior} can also be \emph{the original (posterior) model}, in which case the function +will try to "unupdate" the estimates (not supported if the estimates have undergone +any transformations -- \code{"log"}, \code{"response"}, etc. -- or any \code{regrid}ing). } } } diff --git a/man/bayesfactor_restricted.Rd b/man/bayesfactor_restricted.Rd index 6ed081598..f01623e53 100644 --- a/man/bayesfactor_restricted.Rd +++ b/man/bayesfactor_restricted.Rd @@ -7,6 +7,7 @@ \alias{bayesfactor_restricted.brmsfit} \alias{bayesfactor_restricted.blavaan} \alias{bayesfactor_restricted.emmGrid} +\alias{bayesfactor_restricted.data.frame} \alias{as.logical.bayesfactor_restricted} \title{Bayes Factors (BF) for Order Restricted Models} \usage{ @@ -56,6 +57,14 @@ bf_restricted(posterior, hypothesis, prior = NULL, verbose = TRUE, ...) ... ) +\method{bayesfactor_restricted}{data.frame}( + posterior, + hypothesis, + prior = NULL, + rvar_col = NULL, + ... +) + \method{as.logical}{bayesfactor_restricted}(x, which = c("posterior", "prior"), ...) } \arguments{ @@ -77,6 +86,9 @@ returned? Only applies to mixed models. May be abbreviated.} conditional model or the zero-inflated part of the model be returned? May be abbreviated. Only applies to \pkg{brms}-models.} +\item{rvar_col}{A single character - the name of an \code{rvar} column in the data +frame to be processed. See example in \code{\link[=p_direction]{p_direction()}}.} + \item{x}{An object of class \code{bayesfactor_restricted}} \item{which}{Should the logical matrix be of the posterior or prior distribution(s)?} @@ -119,29 +131,27 @@ prior. (Note that by default, \code{brms::brm()} uses flat priors for fixed-effects; See example below.) \cr\cr -It is important to provide the correct \code{prior} for meaningful results. +It is important to provide the correct \code{prior} for meaningful results, +to match the \code{posterior}-type input: \itemize{ -\item When \code{posterior} is a numerical vector, \code{prior} should also be a numerical vector. -\item When \code{posterior} is a \code{data.frame}, \code{prior} should also be a \code{data.frame}, with matching column order. -\item When \code{posterior} is a \code{stanreg}, \code{brmsfit} or other supported Bayesian model: +\item \strong{A numeric vector} - \code{prior} should also be a \emph{numeric vector}, representing the prior-estimate. +\item \strong{A data frame} - \code{prior} should also be a \emph{data frame}, representing the prior-estimates, in matching column order. \itemize{ -\item \code{prior} can be set to \code{NULL}, in which case prior samples are drawn internally. -\item \code{prior} can also be a model equivalent to \code{posterior} but with samples from -the priors \emph{only}. See \code{\link[=unupdate]{unupdate()}}. -\item \strong{Note:} When \code{posterior} is a \code{brmsfit_multiple} model, \code{prior} \strong{must} be provided. -} -\item When \code{posterior} is an output from a \code{{marginaleffects}} function, \code{prior} should also be an an output -from a \code{{marginaleffects}} function equivalent to \code{posterior} but created -with a model of priors samples \emph{only}. -\item When \code{posterior} is an \code{emmGrid} / \code{emm_list} object: +\item If \code{rvar_col} is specified, \code{prior} should be \emph{the name of an \code{rvar} column} that represents the prior-estimates. +} +\item \strong{Supported Bayesian model (\code{stanreg}, \code{brmsfit}, etc.)} +\itemize{ +\item \code{prior} should be \emph{a model an equivalent model with MCMC samples from the priors \emph{only}}. See \code{\link[=unupdate]{unupdate()}}. +\item If \code{prior} is set to \code{NULL}, \code{\link[=unupdate]{unupdate()}} is called internally (not supported for \code{brmsfit_multiple} model). +} +\item \strong{Output from a \code{{marginaleffects}} function} - \code{prior} should also be \emph{an equivalent output} from a \code{{marginaleffects}} function based on a prior-model +(See \code{\link[=unupdate]{unupdate()}}). +\item \strong{Output from an \code{{emmeans}} function} \itemize{ -\item \code{prior} should also be an \code{emmGrid} / \code{emm_list} object equivalent to \code{posterior} but -created with a model of priors samples \emph{only}. See \code{\link[=unupdate]{unupdate()}}. -\item \code{prior} can also be the original (posterior) \emph{model}. If so, the function will try to -update the \code{emmGrid} / \code{emm_list} to use the \code{\link[=unupdate]{unupdate()}}d prior-model. -(\emph{This cannot be done for \code{brmsfit} models.}) -\item \strong{Note}: When the \code{emmGrid} has undergone any transformations (\code{"log"}, \code{"response"}, etc.), -or \code{regrid}ing, then \code{prior} must be an \code{emmGrid} object, as stated above. +\item \code{prior} should also be \emph{an equivalent output} from an \code{{emmeans}} function based on a prior-model (See \code{\link[=unupdate]{unupdate()}}). +\item \code{prior} can also be \emph{the original (posterior) model}, in which case the function +will try to "unupdate" the estimates (not supported if the estimates have undergone +any transformations -- \code{"log"}, \code{"response"}, etc. -- or any \code{regrid}ing). } } } diff --git a/man/describe_posterior.Rd b/man/describe_posterior.Rd index 1cfa19d72..bc3e0fcfe 100644 --- a/man/describe_posterior.Rd +++ b/man/describe_posterior.Rd @@ -3,6 +3,7 @@ \name{describe_posterior} \alias{describe_posterior} \alias{describe_posterior.numeric} +\alias{describe_posterior.data.frame} \alias{describe_posterior.stanreg} \alias{describe_posterior.brmsfit} \title{Describe Posterior Distributions} @@ -25,6 +26,23 @@ describe_posterior(posterior, ...) ... ) +\method{describe_posterior}{data.frame}( + posterior, + centrality = "median", + dispersion = FALSE, + ci = 0.95, + ci_method = "eti", + test = c("p_direction", "rope"), + rope_range = "default", + rope_ci = 0.95, + keep_iterations = FALSE, + bf_prior = NULL, + BF = 1, + rvar_col = NULL, + verbose = TRUE, + ... +) + \method{describe_posterior}{stanreg}( posterior, centrality = "median", @@ -123,6 +141,9 @@ case of models) ignored.} \item{verbose}{Toggle off warnings.} +\item{rvar_col}{A single character - the name of an \code{rvar} column in the data +frame to be processed. See example in \code{\link[=p_direction]{p_direction()}}.} + \item{diagnostic}{Diagnostic metrics to compute. Character (vector) or list with one or more of these options: \code{"ESS"}, \code{"Rhat"}, \code{"MCSE"} or \code{"all"}.} diff --git a/man/si.Rd b/man/si.Rd index 45e87e7c3..a99c3cc97 100644 --- a/man/si.Rd +++ b/man/si.Rd @@ -62,7 +62,7 @@ si(posterior, ...) ... ) -\method{si}{data.frame}(posterior, prior = NULL, BF = 1, verbose = TRUE, ...) +\method{si}{data.frame}(posterior, prior = NULL, BF = 1, rvar_col = NULL, verbose = TRUE, ...) } \arguments{ \item{posterior}{A numerical vector, \code{stanreg} / \code{brmsfit} object, @@ -95,6 +95,9 @@ for the output.} (returned by \code{\link[insight:get_predicted]{insight::get_predicted()}}), the function is applied to the iterations instead of the predictions. This only applies to models that return iterations for predicted values (e.g., \code{brmsfit} models).} + +\item{rvar_col}{A single character - the name of an \code{rvar} column in the data +frame to be processed. See example in \code{\link[=p_direction]{p_direction()}}.} } \value{ A data frame containing the lower and upper bounds of the SI. @@ -150,29 +153,27 @@ prior. (Note that by default, \code{brms::brm()} uses flat priors for fixed-effects; See example below.) \cr\cr -It is important to provide the correct \code{prior} for meaningful results. +It is important to provide the correct \code{prior} for meaningful results, +to match the \code{posterior}-type input: +\itemize{ +\item \strong{A numeric vector} - \code{prior} should also be a \emph{numeric vector}, representing the prior-estimate. +\item \strong{A data frame} - \code{prior} should also be a \emph{data frame}, representing the prior-estimates, in matching column order. \itemize{ -\item When \code{posterior} is a numerical vector, \code{prior} should also be a numerical vector. -\item When \code{posterior} is a \code{data.frame}, \code{prior} should also be a \code{data.frame}, with matching column order. -\item When \code{posterior} is a \code{stanreg}, \code{brmsfit} or other supported Bayesian model: +\item If \code{rvar_col} is specified, \code{prior} should be \emph{the name of an \code{rvar} column} that represents the prior-estimates. +} +\item \strong{Supported Bayesian model (\code{stanreg}, \code{brmsfit}, etc.)} \itemize{ -\item \code{prior} can be set to \code{NULL}, in which case prior samples are drawn internally. -\item \code{prior} can also be a model equivalent to \code{posterior} but with samples from -the priors \emph{only}. See \code{\link[=unupdate]{unupdate()}}. -\item \strong{Note:} When \code{posterior} is a \code{brmsfit_multiple} model, \code{prior} \strong{must} be provided. -} -\item When \code{posterior} is an output from a \code{{marginaleffects}} function, \code{prior} should also be an an output -from a \code{{marginaleffects}} function equivalent to \code{posterior} but created -with a model of priors samples \emph{only}. -\item When \code{posterior} is an \code{emmGrid} / \code{emm_list} object: +\item \code{prior} should be \emph{a model an equivalent model with MCMC samples from the priors \emph{only}}. See \code{\link[=unupdate]{unupdate()}}. +\item If \code{prior} is set to \code{NULL}, \code{\link[=unupdate]{unupdate()}} is called internally (not supported for \code{brmsfit_multiple} model). +} +\item \strong{Output from a \code{{marginaleffects}} function} - \code{prior} should also be \emph{an equivalent output} from a \code{{marginaleffects}} function based on a prior-model +(See \code{\link[=unupdate]{unupdate()}}). +\item \strong{Output from an \code{{emmeans}} function} \itemize{ -\item \code{prior} should also be an \code{emmGrid} / \code{emm_list} object equivalent to \code{posterior} but -created with a model of priors samples \emph{only}. See \code{\link[=unupdate]{unupdate()}}. -\item \code{prior} can also be the original (posterior) \emph{model}. If so, the function will try to -update the \code{emmGrid} / \code{emm_list} to use the \code{\link[=unupdate]{unupdate()}}d prior-model. -(\emph{This cannot be done for \code{brmsfit} models.}) -\item \strong{Note}: When the \code{emmGrid} has undergone any transformations (\code{"log"}, \code{"response"}, etc.), -or \code{regrid}ing, then \code{prior} must be an \code{emmGrid} object, as stated above. +\item \code{prior} should also be \emph{an equivalent output} from an \code{{emmeans}} function based on a prior-model (See \code{\link[=unupdate]{unupdate()}}). +\item \code{prior} can also be \emph{the original (posterior) model}, in which case the function +will try to "unupdate" the estimates (not supported if the estimates have undergone +any transformations -- \code{"log"}, \code{"response"}, etc. -- or any \code{regrid}ing). } } }