% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/funnel.R
\name{funnel.brma}
\alias{funnel.brma}
\alias{funnel}
\title{Funnel Plot for brma Object}
\usage{
\method{funnel}{brma}(
  x,
  residual,
  type = "LOO-PIT",
  unit = "estimate",
  conditioning_depth = "marginal",
  sampling_heterogeneity = TRUE,
  sampling_bias = TRUE,
  max_samples = 10000,
  plot_type = "base",
  ...
)
}
\arguments{
\item{x}{a fitted brma object}

\item{residual}{whether to use residual mode. Defaults to not specified,
which means the function automatically determines the mode:
\itemize{
\item not specified: For intercept-only models without scale
regression, displays observed effect sizes against the fitted sampling
distribution funnel; for models with moderators or scale regression,
automatically uses residual mode.
\item \code{FALSE}: explicitly requests outcome mode.
\item \code{TRUE}: explicitly requests residual mode, displaying residuals
on the x-axis and using \code{type} to determine how those residuals are
computed.
}}

\item{type}{the type of residuals to use when in residual mode.
Options are:
\itemize{
\item \code{"LOO-PIT"} (alias: \code{"rstudent"}; default): Leave-one-out
probability integral transform residuals returned by
\code{\link{rstudent.brma}}.
\item \code{"rstandard"}: Internally standardized residuals using
\code{\link{rstandard.brma}}. Only available for normal outcome models.
\item \code{"outcome"}: Raw outcome residuals from
\code{\link{residuals.brma}} with \code{type = "outcome"}.
}
Only used when funnel is in residual mode.}

\item{unit}{output unit for residual mode. Only \code{"estimate"} is
implemented in this pass.}

\item{conditioning_depth}{residual conditioning depth for residual mode.
Options are \code{"marginal"}, \code{"cluster"}, and \code{"estimate"}.
The default LOO-PIT residual path is available only with marginal
conditioning depth.}

\item{sampling_heterogeneity}{whether heterogeneity should be incorporated
into the sampling distribution funnel. Defaults to \code{TRUE}. Only used
in outcome mode and ignored in residual mode.}

\item{sampling_bias}{whether publication bias should be incorporated into the
sampling distribution funnel. Defaults to \code{TRUE}. Only used when
\code{residual = FALSE} or when automatic mode selects outcome mode. Ignored
in residual mode. When \code{TRUE} and the model
includes selection models (weightfunction), uses selected-normal quantiles.
When \code{TRUE} and the model includes PET/PEESE, incorporates the expected
skew from these regression adjustments.}

\item{max_samples}{maximum number of posterior samples used for
model-averaged publication-bias funnel contours. Defaults to \code{10000}.
Use \code{Inf} to use all posterior samples.}

\item{plot_type}{whether to use a base plot \code{"base"} or ggplot2
\code{"ggplot"} for plotting. Defaults to \code{"base"}.}

\item{...}{additional graphical arguments to customize the plot appearance:
\describe{
\item{xlim, ylim}{numeric vectors of length 2 specifying axis limits}
\item{xlab, ylab}{character strings for axis labels}
\item{main}{character string for plot title (default: no title)}
\item{pch}{point symbol (default: 21, filled circle). Use standard R pch values.}
\item{col}{point border color (default: "black")}
\item{bg}{point fill/background color (default: "#A6A6A6")}
\item{cex}{point size multiplier for base graphics (default: 1)}
\item{size}{point size for ggplot2 (default: 2)}
\item{las}{axis-label style for base graphics (default: 1)}
\item{back}{background region color (default: "grey"). Set to \code{NA} to suppress.}
\item{shade}{funnel region fill color (default: "white"). Set to \code{NA} to suppress.}
\item{lty}{line type for funnel edges and center line (default: "dotted")}
\item{col.line}{color for funnel edge lines (default: "black")}
\item{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.}
\item{col.refline}{color of vertical reference line (default: "black")}
\item{as_data}{if \code{TRUE}, returns plot data instead of creating a plot}
}}
}
\value{
If \code{as_data = TRUE}, \code{funnel.brma} returns a list with the
data used for plotting, including the plotted points, funnel polygons,
plotting limits, labels, and reference line. Otherwise, it returns
\code{NULL} invisibly if \code{plot_type = "base"} or a ggplot object if
\code{plot_type = "ggplot"}.
}
\description{
\code{funnel.brma} creates a funnel plot for a fitted brma object.
For intercept-only models without scale regression, the default outcome mode
displays observed effect sizes against the fitted sampling distribution. For
models with location or scale moderators, the default residual mode displays
residuals against a standard-error funnel.
}
\details{
The funnel plot has two modes. If \code{residual} is not specified, the mode
is chosen automatically from the fitted model: intercept-only models without
scale regression use outcome mode, whereas models with location or scale
moderators use residual mode.

\strong{Outcome mode} (intercept-only models without scale regression):
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 \code{sampling_bias = FALSE}, this center is the pooled
effect; 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 sampling distribution, optionally incorporating heterogeneity
and publication bias.

\strong{Residual mode} (models with moderators or scale regression):
Displays residuals on the x-axis and standard errors on the
y-axis. The funnel region represents the central 95\\% region of
\eqn{N(0, \mathrm{SE}^2)}. With \code{type = "LOO-PIT"}, the plotted
residuals and standard errors are the raw-scale LOO predictive companions
returned by \code{\link{rstudent.brma}}; the PIT-normalized \code{z} values
are used by \code{\link{qqnorm.brma}} and influence diagnostics. With
\code{type = "rstandard"}, the plotted values are internally standardized
residual companions from \code{\link{rstandard.brma}}. With
\code{type = "outcome"}, these are raw outcome residuals. Under a correctly
specified model, most points should fall within this region.

The \code{type} argument controls how residuals are computed in residual
mode. See \code{\link{residuals.brma}} for details on each type.
The \code{sampling_heterogeneity} and \code{sampling_bias} arguments are
ignored in residual mode.

For GLMM models, observed effect sizes are computed from the raw frequency
data using formulas equivalent to \code{metafor::escalc}. Residual-mode
GLMM funnels use approximate effect-size-scale residual/PIT companions, not
exact PIT diagnostics for the raw count likelihood.
}
\examples{
\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)
  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")
}
}

}
\seealso{
\code{\link[=residuals.brma]{residuals.brma()}}, \code{\link[=rstandard.brma]{rstandard.brma()}}, \code{\link[=rstudent.brma]{rstudent.brma()}},
\code{\link[=predict.brma]{predict.brma()}}
}
