% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/summary_heterogeneity.R
\name{summary_heterogeneity.brma}
\alias{summary_heterogeneity.brma}
\title{Summary of Heterogeneity for brma Objects}
\usage{
\method{summary_heterogeneity}{brma}(object, probs = c(0.025, 0.975), ...)
}
\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{...}{additional arguments (currently ignored)}
}
\value{
A list of class \code{summary_heterogeneity.brma} containing:
\itemize{
\item \code{estimates}: A \code{BayesTools_table} with heterogeneity statistics
}
}
\description{
Computes the absolute heterogeneity (tau, tau^2) and
relative measures of heterogeneity (I^2, H^2) for a fitted brma object.
}
\details{
For standard (2-level) random-effects models, the function reports:
\itemize{
\item \code{tau}: Between-study standard deviation
\item \code{tau2}: Between-study variance
\item \code{I2}: Percentage of total variance due to heterogeneity
\item \code{H2}: Ratio of total to sampling variance
}

For multilevel (3-level) models with nested effects, the function additionally
partitions heterogeneity into estimate-level and cluster-level components:
\itemize{
\item \code{rho}: Proportion of heterogeneity variance allocated to clusters
\item \code{tau [within]}: Estimate-level standard deviation
\item \code{tau [between]}: Cluster-level standard deviation
\item \code{tau2 [within]}: Estimate-level variance
\item \code{tau2 [between]}: Cluster-level variance
\item \code{I2 [within]}: Percentage of variance due to estimate-level heterogeneity
\item \code{I2 [between]}: Percentage of variance due to cluster-level heterogeneity
}

For location-scale models, \code{tau2} aggregates the observation-specific
heterogeneity variances \eqn{\tau_i^2}; the corresponding \code{tau} summary
is the square root of this aggregate variance. The relative \eqn{I^2} and
\eqn{H^2} measures average the observation-specific indices.

The I^2 and H^2 statistics are computed following the metafor package
implementation, using the "typical" sampling variance formula from
\insertCite{higgins2002quantifying;textual}{RoBMA}. For multilevel models,
the partitioned I^2 follows the approach described in the metafor documentation.
}
\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
  )

  summary_heterogeneity(fit)
}
}

}
\references{
\insertAllCited{}
}
\seealso{
\code{\link[=pooled_heterogeneity]{pooled_heterogeneity()}}, \code{\link[=summary.brma]{summary.brma()}}
}
