Computes heterogeneity (tau) of a fitted brma object at the average fitted scale design (the mean of the observation-specific tau) and, for random-formula models, at the average expanded random-effect design.
Usage
# S3 method for class 'brma'
pooled_heterogeneity(
object,
probs = c(0.025, 0.975),
conditional = FALSE,
component = "all",
...
)Arguments
- object
a fitted brma object
- probs
quantiles of the posterior distribution to be displayed. Defaults to
c(.025, .975)for 95% credible intervals.- conditional
whether to return the pooled heterogeneity conditional on the heterogeneity component for RoBMA product-space objects. Defaults to
FALSE.- component
heterogeneity component to return for
brma.mv()models. Defaults to"all". Use"total"for the variance-additive total heterogeneity.- ...
additional arguments passed to
predict.brma(as_measure,V_new, andconditioning_depth); wrapper arguments such asnewdata,type, andquietare fixed (supplying one is R's error for an argument matched twice, as forpredict()), and other unknown arguments are unused and trigger a warning.
Value
A brma_samples object containing posterior samples. When printed,
displays a summary table. For decomposed brma.mv() models, a named
list of brma_samples objects is returned. Use summary() on an
individual object (as.data.frame() of an individual object returns its
draws) or as.data.frame() on the complete result to obtain
a summary data frame with component and parameter identifiers. Use
as.data.frame(format = "list") to retain separate component tables.
The samples can be converted to posterior draws formats using
as_draws().
Details
For location-scale models, the function returns the arithmetic mean over the
fitted rows of the observation-specific tau, as in 4.0.0; it equals
rowMeans(predict(object, type = "terms.scale")). It is not the root
mean square heterogeneity across the observed rows. Use
summary_heterogeneity() for the latter.
For models without scale regression, this returns the single tau parameter.
For multilevel (3-level) models, the returned tau is the total heterogeneity:
tau = sqrt(tau_within^2 + tau_between^2).
For brma.mv() models, one ordinary selected component is named
tau; a genuine variance-additive total is named tau_total; and a
mean-variance allocation anchor is named tau_common. These quantities
are available when a random formula is declared. For random-formula models,
component = "all"
returns one brma_samples object when there is a single heterogeneity
component and a named list when there are multiple components.
component = "total" computes the variance-additive total at the
average random-effect design. Random slopes are evaluated as
\(\bar q^T G \bar q\), including within-block correlations. Default and
named allocation components retain their declared scale anchors; explicit
totals and pooled-effect prediction intervals use the full covariance of
the average design, including allocation-owned blocks.
With a known group covariance \(R\), the
reported sd is the fitted multiplier of that kernel. It need not equal
every row's marginal standard deviation when \(\mathrm{diag}(R)\) is not
one. Row-specific marginal standard deviations are available from
predict(type = "terms.scale"). A scale formula of a random-formula model
enters the average random-effect design as the arithmetic mean of the
observation-specific tau, as for the univariate models.
predict(object, newdata = TRUE, type = "terms.scale") returns the same
component result: a named list for several components and one
brma_samples object for a single component.
For brma.mv() models and models with factor-specific or random-slope
terms, the average expanded random-effect design can be synthetic and need
not correspond to a single realizable outcome or study. The result is the
heterogeneity of that linear composite, not typical heterogeneity across the
observed designs. Interpret it only when the composite has a meaningful
scientific interpretation; use summary_heterogeneity() for
observed-design heterogeneity or predict(..., newdata = ...) for a
specified realizable design.
Examples
if (FALSE) { # \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)
}
} # }