% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/wrappers.R
\name{pooled_heterogeneity.brma}
\alias{pooled_heterogeneity.brma}
\title{Pooled Heterogeneity for brma Objects}
\usage{
\method{pooled_heterogeneity}{brma}(object, probs = c(0.025, 0.975), conditional = FALSE, ...)
}
\arguments{
\item{object}{a fitted brma object}

\item{probs}{quantiles of the posterior distribution to be displayed.
Defaults to \code{c(.025, .975)} for 95\% credible intervals.}

\item{conditional}{whether to return the pooled heterogeneity conditional on
the heterogeneity component for RoBMA product-space objects. Defaults to
\code{FALSE}.}

\item{...}{additional arguments passed to \code{\link{predict.brma}}; wrapper
arguments such as \code{newdata}, \code{type}, and \code{quiet} are fixed.}
}
\value{
A \code{brma_samples} object containing posterior samples. When printed,
displays a summary table. Use \code{summary()} to obtain the summary table directly.
The samples can be converted to \pkg{posterior} draws formats using \code{as_draws()}.
}
\description{
Computes the pooled (aggregated) heterogeneity estimate (tau)
from a fitted brma object by averaging across the scale model matrix.
}
\details{
This function is a convenience wrapper around \code{predict.brma(...,
type = "terms.scale", newdata = TRUE)}.

For location-scale models (with scale regression), the pooled heterogeneity
averages tau across the scale model matrix proportionately to the levels
observed in the data.

For models without scale regression, this returns the single tau parameter.

For multilevel (3-level) models, the returned tau is the total heterogeneity:
\code{tau = sqrt(tau_within^2 + tau_between^2)}.
}
\examples{
\dontrun{
if (requireNamespace("metadat", quietly = TRUE)) {
  data(dat.lehmann2018, package = "metadat")
  fit <- brma(
    yi      = yi,
    vi      = vi,
    data    = dat.lehmann2018,
    measure = "SMD",
    seed    = 1,
    silent  = TRUE
  )

  pooled_heterogeneity(fit)
}
}

}
\seealso{
\code{\link[=predict.brma]{predict.brma()}}, \code{\link[=pooled_effect]{pooled_effect()}}, \code{\link[=blup]{blup()}}
}
