Skip to contents

Heterogeneity plots

Source: R/heterogeneity.R
plot_heterogeneity.Rd

Posterior distributions of CAMS between-trial standard deviations. Bayesian CAMS uses base-R tau-marginals (bayesmeta::plot.bayesmeta which = 4 style) from the stored bmr / bayesmeta objects (tau, tau_gamma). "both" is those two which plots side by side (par(mfrow)), with a shared y-axis. Frequentist CAMS uses the same two panels as profile (restricted) log-likelihoods of τ from the stored rma objects (metafor::profile.rma), also side by side with shared x- and y-axis limits (0 to the larger upper τ bound). The region between the profile and the profile cutoff is shaded; a vertical line marks the REML/ML \hat\tau; a dotted horizontal line marks the cutoff at max(ℓ) − qchisq(prob, 1)/2 for the heterogeneity summary prob (default 95%), with a small in-panel label.

Usage

plot_heterogeneity(
  x,
  which = c("both", "overall", "interaction", "combined"),
  probs = c(0.5, 0.75, 0.9),
  bins = 40L,
  digits = 2,
  colours = NULL,
  base_size = interactmeta_base_size(default = 11L),
  title = NULL,
  xlab = NULL,
  printplot = TRUE,
  prior = TRUE,
  ...
)

# S3 method for class 'interactmeta_heterogeneity'
plot(
  x,
  which = c("both", "overall", "interaction", "combined"),
  prior = TRUE,
  ...
)

Arguments

x

A interactmeta_heterogeneity object from heterogeneity(), or a interactmeta from cams() (in which case heterogeneity() is called).

which

Which components to draw: "both" (default; overall / combined and interaction side by side with a shared y-axis), "overall" / "combined" (tau), or "interaction" (tau_gamma).

probs

Quantiles to annotate on ggplot densities (default c(0.5, 0.75, 0.9)). Ignored by the bayesmeta and metafor paths.

bins

Number of equal-width histogram bins for continuous samples (default 40). Ignored by the bayesmeta and metafor paths and when tau is a discrete support.

digits

Decimal places for ggplot quantile labels (default 2).

colours

Length-2 character vector c(overall, interaction) for the ggplot path. Defaults to density slate tokens (not subgroup red/blue).

base_size

Base font size passed to interactmeta_theme_report().

title

Optional ggplot title (default NULL). Ignored by the bayesmeta and metafor paths.

xlab

Optional shared x-axis title. The default (NULL) labels each panel "heterogeneity τ" (tau) or "heterogeneity τ_γ" (tau_gamma). A supplied value is used on ggplot panels only.

printplot

If TRUE (default), print the ggplot. Ignored by the bayesmeta and metafor paths (always drawn).

prior

Overlay the tau prior density (dashed line). On the bayesmeta path this matches bayesmeta::plot.bayesmeta's prior. On the ggplot fallback, uses fit$priors when available (default TRUE).

...

Passed to heterogeneity() when x is a fit (prob, component, …). Ignored for interactmeta_heterogeneity objects except that unused names are dropped quietly.

Value

For Bayesian or frequentist CAMS with stored native objects, x invisibly after drawing base-R plots. Otherwise a ggplot2 object (invisibly when printplot = TRUE).

See also

heterogeneity(), bayesmeta::plot.bayesmeta, metafor::profile.rma, vignette("cams")

Examples

if (FALSE) { # \dontrun{
fit <- cams(es, reference = "Lower")
plot_heterogeneity(fit)
plot_heterogeneity(fit, which = "combined")
} # }