% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/regplot.R
\name{regplot.brma}
\alias{regplot.brma}
\alias{regplot}
\title{Regression Plot (Bubble Plot) for brma Object}
\usage{
\method{regplot}{brma}(
  x,
  mod = NULL,
  pred = TRUE,
  ci = TRUE,
  pi = FALSE,
  si = FALSE,
  level = 95,
  at = NULL,
  digits = 2,
  transf = NULL,
  atransf = NULL,
  targs = NULL,
  refline = NULL,
  psize = NULL,
  plim = c(0.5, 3),
  by = NULL,
  legend = TRUE,
  xlab = NULL,
  ylab = NULL,
  xlim = NULL,
  ylim = NULL,
  sampling_bias = TRUE,
  sei = NULL,
  max_samples = 10000,
  plot_type = "base",
  as_data = FALSE,
  ...
)
}
\arguments{
\item{x}{a fitted brma object with moderators}

\item{mod}{index or name of the moderator variable to plot on the x-axis.
If not specified and only one moderator is present, that moderator is used.
If multiple moderators are present, this argument is required.}

\item{pred}{logical; whether to show the prediction line. Defaults to \code{TRUE}.}

\item{ci}{logical; whether to show credible interval bands. Defaults to \code{TRUE}.}

\item{pi}{logical; whether to show prediction interval bands. Defaults to \code{FALSE}.}

\item{si}{logical; whether to show sampling interval bands. Defaults to \code{FALSE}.
The sampling interval shows the expected range of observed effect sizes,
incorporating both heterogeneity (tau) and a representative level of
sampling error (median SE across studies by default). When the model includes
publication bias adjustments and \code{sampling_bias = TRUE}, the
sampling interval incorporates the expected distortion from the
selection process.}

\item{level}{numeric; credible/prediction interval level in percent.
Defaults to \code{95}.}

\item{at}{numeric vector; for continuous moderators, values at which to
evaluate the prediction. If not specified, uses a sequence across the
observed range.}

\item{digits}{integer; number of decimal places for labels. Defaults to \code{2}.}

\item{transf}{function; transformation to apply to the y-axis (effect sizes).
Defaults to \code{NULL} (no transformation).}

\item{atransf}{reserved for axis-label transformations. Currently not
implemented and must be \code{NULL}.}

\item{targs}{reserved for additional transformation arguments. Currently not
implemented and must be \code{NULL}.}

\item{refline}{numeric; position of horizontal reference line.
Defaults to \code{NULL} (no reference line).}

\item{psize}{numeric vector or \code{NULL}; point sizes for each study.
If scalar, it is recycled to all studies. If \code{NULL} (default), sizes
are computed based on inverse sampling variance.}

\item{plim}{numeric vector of length 2; range for point sizes.
Defaults to \code{c(0.5, 3)}.}

\item{by}{character; name of a moderator variable to use for separate
lines/colors. Defaults to \code{NULL}. If omitted and the selected
moderator enters exactly one two-way interaction, the other variable in the
interaction is used automatically. Continuous \code{by} moderators are shown
at mean - SD, mean, and mean + SD.}

\item{legend}{logical; whether to show legend when \code{by} is specified.
Defaults to \code{TRUE}.}

\item{xlab}{character; x-axis label. Defaults to the moderator name.}

\item{ylab}{character; y-axis label. Defaults to "Observed Effect Size".}

\item{xlim}{numeric vector of length 2; x-axis limits. Defaults to data range.}

\item{ylim}{numeric vector of length 2; y-axis limits. Defaults to data range.}

\item{sampling_bias}{whether publication bias should be incorporated into
plotted predictions and sampling intervals. Defaults to \code{TRUE}. For
PET/PEESE models, this includes the expected regression bias in predictions.
For selection models, sampling-bias adjustment applies to sampling intervals
when \code{si = TRUE}; the mean prediction is unchanged.}

\item{sei}{single positive numeric value used as the reference standard
error for sampling-bias and sampling-interval calculations. Defaults to the
median observed standard error.}

\item{max_samples}{maximum number of posterior samples used for prediction
summaries and interval bands. Defaults to \code{10000}. Use \code{Inf} to
use all posterior samples.}

\item{plot_type}{character; whether to use base R graphics (\code{"base"})
or ggplot2 (\code{"ggplot"}). Defaults to \code{"base"}.}

\item{as_data}{logical; if \code{TRUE}, returns plot data instead of
creating plot. Defaults to \code{FALSE}.}

\item{...}{additional graphical arguments:
\describe{
\item{main}{character string for plot title}
\item{pch}{point symbol (default: 21)}
\item{col}{point border color (default: "black")}
\item{bg}{point fill color (default: "#A6A6A6")}
\item{lcol}{line color (default: "black")}
\item{lwd}{line width (default: 2)}
\item{shade}{CI/PI/SI band shading (default: TRUE)}
\item{col.ci}{CI band color (default: "gray70")}
\item{col.pi}{PI band color (default: "gray85")}
\item{col.si}{SI band color (default: "gray92")}
\item{alpha.ci}{CI band transparency (default: 0.4)}
\item{alpha.pi}{PI band transparency (default: 0.2)}
\item{alpha.si}{SI band transparency (default: 0.15)}
\item{jitter}{jitter amount for categorical moderators (default: 0.2)}
\item{box.width}{box width for categorical interval summaries (default: 0.5)}
}}
}
\value{
\code{regplot.brma} returns \code{NULL} invisibly if
\code{plot_type = "base"} or a ggplot object if \code{plot_type = "ggplot"}.
If \code{as_data = TRUE}, returns a list with plot data components.
}
\description{
\code{regplot.brma} creates a regression plot (also known as
bubble plot) for a fitted brma object with moderators. The plot displays
observed effect sizes against a moderator variable, with point sizes
proportional to study precision.
}
\details{
The regression plot (bubble plot) is a standard visualization for
meta-regression results. It displays:
\itemize{
\item Observed effect sizes (y-axis) against moderator values (x-axis)
\item Point sizes proportional to study precision (inverse variance)
\item Prediction line showing the estimated regression relationship
\item Confidence bands showing uncertainty in the mean prediction
\item Optional prediction bands showing expected range of true effects
\item Optional sampling interval bands showing expected range of observed outcomes
}

For continuous moderators, predictions are computed across the observed
range of the moderator. For categorical moderators (factors), predictions
are computed at each factor level with optional jittering of points.

The \code{by} argument allows displaying separate regression lines for
different levels of a second moderator, useful for visualizing interactions.
}
\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,
    mods    = ~ ablat + year,
    data    = dat,
    measure = "RR"
  )
  regplot(fit, mod = "ablat")
  regplot(fit, mod = "year", pi = TRUE, si = TRUE)
  regplot(fit, mod = "ablat", plot_type = "ggplot")

  fit_cat <- brma(yi = yi, vi = vi, mods = ~ alloc, data = dat, measure = "RR")
  regplot(fit_cat)
}
}

}
\seealso{
\code{\link[=funnel.brma]{funnel.brma()}}, \code{\link[=predict.brma]{predict.brma()}}
}
