funnel.brma creates fast plug-in funnel contours.
Location and bias parameters are fixed at their within-model posterior means;
heterogeneity uses the root mean square SD, \(\sqrt{E(\tau^2)}\). For
model-averaged fits, complete joint models retain their posterior model
probabilities and their plug-in sampling CDFs are averaged before the
contours are inverted. This makes the ordinary normal-model construction
directly comparable to a conventional plug-in funnel such as
metafor::funnel(..., addtau2 = TRUE).
bfunnel.brma instead averages the sampling CDF over posterior draws
before inversion. It therefore incorporates continuous parameter uncertainty
as well as model uncertainty.
Usage
# S3 method for class 'brma'
funnel(
x,
residual,
type = "LOO-PIT",
unit = "estimate",
conditioning_depth = "marginal",
sampling_heterogeneity = TRUE,
sampling_bias = TRUE,
max_samples = 10000,
plot_type = "base",
...
)
bfunnel(x, ...)
# Default S3 method
bfunnel(x, ...)
# S3 method for class 'brma'
bfunnel(
x,
sampling_heterogeneity = TRUE,
sampling_bias = TRUE,
max_samples = 10000,
plot_type = "base",
...
)Arguments
- x
a fitted brma object
- residual
whether to use residual mode. Defaults to not specified, which means the function automatically determines the mode:
not specified: Displays outcomes only for intercept-only models with one common marginal heterogeneity distribution. Otherwise it automatically uses LOO-PIT residual mode.
FALSE: explicitly requests outcome mode. This is available only for intercept-only models with common marginal heterogeneity.TRUE: explicitly requests residual mode, displaying residuals on the x-axis and usingtypeto determine how those residuals are computed.
- type
the type of residuals to use when in residual mode. Options are:
"LOO-PIT"(alias:"rstudent"; default): Leave-one-out probability integral transform residuals returned byrstudent.brma."rstandard": Internally standardized residuals usingrstandard.brma. Only available for normal outcome models."outcome": Raw outcome residuals fromresiduals.brmawithtype = "outcome". Its funnel bands are descriptive sampling-error-only reference bands.
Only used when funnel is in residual mode.
- unit
output unit for residual mode. Only
"estimate"is currently implemented.- conditioning_depth
conditioning depth for non-LOO residual mode. Options are
"marginal","cluster", and"estimate". Omit this argument fortype = "LOO-PIT"(the default) or its"rstudent"alias: the estimate-deletion context determines the LOO predictive target.- sampling_heterogeneity
whether heterogeneity should be incorporated into the sampling distribution funnel. Defaults to
TRUE. Only used in outcome mode and ignored in residual mode.- sampling_bias
whether publication bias should be incorporated into the sampling distribution funnel. Defaults to
TRUE. Only used whenresidual = FALSEor when automatic mode selects outcome mode. Ignored in residual mode. WhenTRUEand the model includes selection models (weightfunction), uses selected-normal quantiles where the fitted source and publication structure admit a scalar calculation. Unsupported joint-selection configurations fail explicitly; usesampling_bias = FALSEfor bias-adjusted contours. Exact-zero integrated selected cells require an existing positive-weight cancellation certificate; otherwise the selected contour is unavailable.sampling_bias = FALSEremains an explicitly unselected reference. Ordinary and constant-positive step-selection rows are evaluated as exact Gaussian components before conditioned-source quadrature. Remaining selected rows are unavailable when the required odd quadrature order exceeds the existing 401-node cap or is nonfinite; the call then stops with an error of classRoBMA_funnel_quadrature_rejected, whose parent class isRoBMA_numerical_unavailable, carrying the standard deviationratio, therequired_orderand themaximumorder.max_samplescontrols posterior rows and does not increase this quadrature budget. WhenTRUEand the model includes PET/PEESE, incorporates the expected skew from these regression adjustments.- max_samples
maximum number of posterior draws used by
bfunnel(). Defaults to10000; useInffor all draws.funnel()uses all draws to estimate conditional plug-in values and posterior model probabilities, then evaluates only one CDF per joint model.- plot_type
whether to use a base plot
"base"or ggplot2"ggplot"for plotting. Defaults to"base".- ...
additional graphical arguments to customize the plot appearance:
- xlim, ylim
numeric vectors of length 2 specifying axis limits
- xlab, ylab
character strings for axis labels
- main
character string for plot title (default: no title)
- pch
point symbol (default: 21, filled circle). Use standard R pch values.
- col
point border color (default: "black")
- bg
point fill/background color (default: "#A6A6A6")
- cex
point size multiplier for base graphics (default: 1)
- size
point size for ggplot2 (default: 2)
- las
axis-label style for base graphics (default: 1)
- back
background region color (default: "grey"). Set to
NAto suppress.- shade
funnel region fill color (default: "white"). Set to
NAto suppress.- lty
line type for funnel edges and center line (default: "dotted")
- col.line
color for funnel edge lines (default: "black")
- refline
numeric override for the reference line. By default, residual mode uses 0, while outcome mode uses the center of the fitted sampling distribution, which may be curved when PET/PEESE bias adjustment is incorporated.
- col.refline
color of vertical reference line (default: "black")
- as_data
if
TRUE, returns plot data instead of creating a plot
Value
If as_data = TRUE, funnel.brma and
bfunnel.brma return a list with the
data used for plotting, including the plotted points, funnel polygons,
plotting limits, labels, reference line, and outcome-funnel estimand. GLMM
outcome-mode data of funnel.brma also
contain an approximation record identifying the descriptive normal
effect-size approximation and stating that it is not fitted discrete-
likelihood coverage (bfunnel.brma is available only for normal
outcome models). Otherwise, it returns
NULL invisibly if plot_type = "base" or a ggplot object if
plot_type = "ggplot".
Details
The ordinary funnel() has outcome and residual modes. If
residual is not specified, outcomes are used only when the fitted
model is intercept-only and its marginal heterogeneity is identical across
studies. The latter check uses fitted row-marginal random-effect variances,
including complete \(ZGZ'\) contributions for brma.mv() random-
formula models. All other models use residual mode.
Outcome mode (intercept-only models with common heterogeneity):
Displays observed effect sizes on the x-axis and standard errors on the
y-axis. The reference line follows the center of the fitted sampling
distribution. When sampling_bias = FALSE, this center is the plug-in
mixture median (the pooled effect in a single model); when PET/PEESE bias
adjustment is incorporated, the center line can vary with the standard
error. The funnel region represents the central 95\
region of the plug-in sampling distribution, optionally incorporating
heterogeneity and publication bias. Location and bias parameters use posterior
means, and heterogeneity uses the square root of the posterior mean variance,
separately within every complete joint model. Integrated and conditioned
variance components are averaged on the variance scale. The resulting
model-specific CDFs are averaged with posterior model probabilities and only
then inverted; neither parameters nor contour endpoints are averaged across
models.
For normal models, these contours use the marginal response target:
heterogeneity represents newly realized latent effects and fitted study
effects are not retained.
For correlated known-V brma.mv() models, outcome-mode funnels
use the diagonal of V for Gaussian marginal contours. The contour
describes a new, independent estimate at each hypothetical standard error,
so the fitted rows' correlations do not enter it: under
weight_rule = "product" such an estimate forms its own dependency
block and its selected law is the scalar selected normal at that standard
error, mixed over the population law of any conditioned source. Nonconstant
joint selection under a best weight rule instead weighs an estimate against
the others of its publication; it requires a full publication design at each
hypothetical standard error and remains unavailable in the scalar contour
calculation. Conditioning every applicable selection source cancels positive
weights and therefore retains the Gaussian contours. The observed estimates'
own selected marginals inside a correlated block differ from this new-study
contour; use zplot() to display them at the fitted publication
designs.
Residual mode follows the fitted estimate-unit residual target.
bfunnel() is available only for intercept-only normal models with
common marginal heterogeneity. It has no residual mode: explicitly supplied
residual, type, unit, or conditioning_depth
arguments are refused. It averages the same sampling CDF over
posterior draws and then inverts the averaged CDF. Thus it incorporates
posterior uncertainty in the effect, heterogeneity, PET/PEESE coefficients,
and selection parameters in addition to model uncertainty. For models
without a common outcome-scale target, use the default LOO-PIT residual
funnel from funnel().
Residual mode (models without a common outcome-scale target):
Displays residuals on the x-axis and standard errors on the
y-axis. The funnel region is bounded by the 0.025 and 0.975 normal quantiles
times the displayed standard error. It is a descriptive reference band, not
a posterior-predictive coverage interval. With type = "LOO-PIT", the
plotted x-coordinate is the PIT-normalized z value returned by
rstudent.brma multiplied by its LOO predictive standard
deviation. Consequently, each plotted x / se is exactly its LOO-PIT
z. This reduces to the ordinary raw deleted residual when the LOO
predictive distribution is normal and extends the same funnel geometry to
non-normal continuous predictive mixtures. With
type = "rstandard", the plotted values are internally standardized
residual companions from rstandard.brma. With
type = "outcome", these are raw outcome residuals and the band uses
sampling error only; it does not incorporate fitted heterogeneity.
The type argument controls how residuals are computed in residual
mode. See residuals.brma for details on each type.
The sampling_heterogeneity and sampling_bias arguments are
ignored in residual mode.
For GLMM models, outcome-mode observed effect sizes are computed from the raw
frequency data using formulas equivalent to metafor::escalc. Their
contours use the corresponding continuity-corrected effect-size estimates
and approximate standard errors in a normal reference calculation. The
default x-axis label and a warning identify this as a descriptive
approximation; it is not a coverage interval from the fitted binomial or
Poisson likelihood and does not use the prior-nuisance marginal GLMM response
target from predict(). Exact discrete-likelihood coverage cannot be
indexed by a scalar standard error alone because it also depends on arm
totals or exposures and nuisance rates.
LOO-PIT residual mode of GLMMs uses the descriptive normal approximation on
the effect-size scale of residuals.brma (the fitted predictive
distribution is discrete); the default x-axis label identifies it. The
sampling-error-only bands of the residual funnel are not exact diagnostics
for the fitted count likelihood.
Outcome-mode plot data carry the canonical RoBMA_target attribute.
Its reference_law identifies the independently published new-estimate
product-rule law; estimand separately records plug-in versus
posterior-predictive averaging. Declared source roles retain their provenance.
Examples
if (FALSE) { # \dontrun{
if (requireNamespace("metadat", quietly = TRUE) &&
requireNamespace("metafor", quietly = TRUE)) {
data(dat.bcg, package = "metadat")
dat <- metafor::escalc(
measure = "RR",
ai = tpos,
bi = tneg,
ci = cpos,
di = cneg,
data = dat.bcg
)
fit <- brma(yi = yi, vi = vi, data = dat, measure = "RR")
funnel(fit)
bfunnel(fit)
funnel(fit, pch = 19, col = "blue", bg = "lightblue")
fit_reg <- brma(
yi = yi,
vi = vi,
mods = ~ ablat + year,
data = dat,
measure = "RR"
)
fit_reg <- add_loo(fit_reg)
funnel(fit_reg)
funnel(fit_reg, type = "outcome")
funnel_data <- funnel(fit, as_data = TRUE)
funnel(fit, plot_type = "ggplot")
}
} # }