% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/qqnorm.R
\name{qqnorm.brma}
\alias{qqnorm.brma}
\title{Normal QQ Plot for brma Object}
\usage{
\method{qqnorm}{brma}(
  y,
  type = "rstudent",
  unit = "estimate",
  conditioning_depth = "marginal",
  envelope = TRUE,
  conf_level = 95,
  bonferroni = FALSE,
  reps = 1000,
  smooth = TRUE,
  xlim,
  ylim,
  xlab,
  ylab,
  plot_type = "base",
  ...
)
}
\arguments{
\item{y}{a fitted brma object.}

\item{type}{the type of standardized residuals to use. Options are:
\itemize{
\item \code{"rstudent"} (alias: \code{"LOO-PIT"}; default): Leave-one-out
probability integral transform residuals. Works for all model types
including GLMMs and selection models. This is the recommended type for
Bayesian models as it properly accounts for estimation uncertainty and
leverage. Note: requires that loo has been computed (see
\code{\link{add_loo}}).
\item \code{"rstandard"}: Internally standardized residuals using the hat
matrix. Only available for normal outcome models without selection
(weightfunction) bias adjustment.
}}

\item{unit}{output unit. Only \code{"estimate"} is implemented currently.}

\item{conditioning_depth}{residual conditioning depth. Options are
\code{"marginal"}, \code{"cluster"}, and \code{"estimate"}.}

\item{envelope}{logical indicating whether to add a pseudo confidence
envelope to the plot. The envelope is created by simulating sets of
standard normal quantiles, providing a reference for the expected variability
under a correctly specified model. Defaults to \code{TRUE}.}

\item{conf_level}{numeric value between 0 and 100 specifying the confidence level
for the envelope bounds. Defaults to \code{95}.}

\item{bonferroni}{logical indicating whether to apply Bonferroni correction
to the envelope, so it can be regarded as a simultaneous confidence region
for all \eqn{k} residuals. Defaults to \code{FALSE}.}

\item{reps}{retained for compatibility with earlier simulation-based
envelopes. The current envelope is deterministic and does not use this
argument.}

\item{smooth}{logical indicating whether to smooth the envelope bounds using
Friedman's SuperSmoother (\code{\link[stats]{supsmu}}). Defaults to
\code{TRUE}.}

\item{xlim}{x-axis limits. If not specified, limits are computed from data.}

\item{ylim}{y-axis limits. If not specified, limits are computed from data.}

\item{xlab}{title for the x-axis. If not specified, defaults to
\code{"Theoretical Quantiles"}.}

\item{ylab}{title for the y-axis. If not specified, defaults to
\code{"Sample Quantiles"}.}

\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{pch}{point symbol (default: 21, filled circle)}
\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{shade}{fill color for the envelope region (default: "grey90").
Set to \code{NA} to suppress shading.}
\item{col.envelope}{color for envelope boundary lines
(default: "grey50")}
\item{col.refline}{color of the diagonal reference line
(default: "black")}
\item{main}{character string for plot title (default: no title)}
\item{as_data}{if \code{TRUE}, returns plot data instead of creating
the plot}
}}
}
\value{
For \code{plot_type = "base"}, returns an invisible list with
components \code{x} (theoretical quantiles) and \code{y} (sorted
residuals). For \code{plot_type = "ggplot"}, returns a ggplot object.

If \code{as_data = TRUE}, returns a list with all computed plot data
including: \code{x}, \code{y}, \code{points}, \code{refline},
\code{envelope}, \code{xlim}, \code{ylim}, \code{xlab}, and \code{ylab}.
}
\description{
\code{qqnorm.brma} creates a normal QQ plot for a fitted brma
object. The plot displays sorted standardized residuals on the vertical axis
against the theoretical quantiles of a standard normal distribution on the
horizontal axis. Under a correctly specified model, the points should fall
approximately along the diagonal reference line.
}
\details{
The normal QQ plot is a diagnostic tool for assessing whether the
standardized residuals follow a standard normal distribution, as expected
under a correctly specified model. Each point represents one estimate,
plotted at coordinates \eqn{(\Phi^{-1}(p_i), z_{(i)})} where
\eqn{p_i} are the plotting positions and \eqn{z_{(i)}} are the sorted
standardized residuals.

The default residual type is \code{"rstudent"} (LOO-PIT), which differs
from \code{metafor::qqnorm} (which defaults to \code{"rstandard"}).
LOO-PIT residuals are preferred because they are available for all model
types (including GLMMs and selection models) and properly account for
estimation uncertainty via leave-one-out cross-validation.

The confidence envelope is computed in closed form from the distribution of
normal order statistics. For the \eqn{i}-th sorted residual,
\eqn{\Phi(Z_{(i)})} follows a beta distribution with shape parameters
\eqn{i} and \eqn{k + 1 - i}. Pointwise quantile bounds are transformed back
with \eqn{\Phi^{-1}}. When \code{smooth = TRUE}, bounds are smoothed using
Friedman's SuperSmoother. When \code{bonferroni = TRUE}, the confidence
level is adjusted for simultaneous inference across all \eqn{k} comparisons.

For GLMM models, LOO-PIT residuals and the QQ plot are computed on the
approximate effect-size scale used by \code{loo}; they are not exact
count-scale PIT diagnostics.
}
\examples{
\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
  )
  fit <- add_loo(fit)

  qqnorm(fit)
  qqnorm(fit, type = "rstandard")
  qqnorm(fit, envelope = FALSE)
  qqnorm(fit, plot_type = "ggplot")
  qqnorm(fit, pch = 19, col = "blue", shade = "lightblue")
}
}

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