% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/plot.barma.R
\name{plot.barma}
\alias{plot.barma}
\title{Diagnostic Plots for a Fitted betaARMA Model}
\usage{
\method{plot}{barma}(
  x,
  which = c("default", "all", "fitted", "tsplot", "acf", "pacf", "ljungbox", "monti",
    "hist", "qq"),
  residual_type = c("pearson", "quantile", "link", "raw"),
  lag_max = 24,
  title = NULL,
  colour_observed = "#00BFC4",
  colour_fitted = "#F8766D",
  colour_residual = "#7CAE00",
  ...
)
}
\arguments{
\item{x}{An object of class \code{"barma"}, as returned by \code{\link{barma}}.}

\item{which}{A character string controlling which panel(s) to display. One of:
\describe{
  \item{\code{"default"} (default)}{Four-panel 2\eqn{\times}2 grid:
    observed vs. fitted (top left), residual ACF (top right),
    Ljung-Box p-values (bottom left), and residual PACF (bottom right).}
  \item{\code{"all"}}{Six-panel 3\eqn{\times}2 grid:
    observed vs. fitted (top left), residuals over time (top right),
    residual ACF (middle left), residual PACF (middle right),
    Ljung-Box p-values (bottom left), Monti p-values (bottom right).}
  \item{\code{"fitted"}}{Single panel: observed vs. fitted values.}
  \item{\code{"tsplot"}}{Single panel: residuals plotted as a time series,
    with a horizontal reference line at zero and dashed lines at
    \eqn{\pm 3} (ad hoc threshold; not shown for \code{"raw"} residuals).}
  \item{\code{"acf"}}{Single panel: residual ACF.}
  \item{\code{"pacf"}}{Single panel: residual PACF.}
  \item{\code{"ljungbox"}}{Single panel: Ljung-Box p-values.}
  \item{\code{"monti"}}{Single panel: Monti test p-values.}
  \item{\code{"hist"}}{Single panel: residual distribution histogram with
    kernel density overlay.}
  \item{\code{"qq"}}{Single panel: Normal Q-Q plot. Always uses quantile
    residuals regardless of \code{residual_type}; a message is issued if
    the type is overridden.}
}}

\item{residual_type}{Character string passed to \code{\link{residuals.barma}} controlling
which residuals are computed and displayed. One of \code{"pearson"}
(default), \code{"quantile"}, \code{"link"} or \code{"raw"}. Pearson
residuals are recommended for ACF/PACF analysis and portmanteau
tests (Scher, Cribari-Neto, Pumi, and Bayer, 2020); quantile residuals
are recommended for normality assessment (Dunn and Smyth, 1996). See also
Ferrari and Cribari-Neto (2004).}

\item{lag_max}{Maximum lag to display in the ACF, PACF, Ljung-Box, and Monti panels.
Defaults to \code{24}, appropriate for monthly series.}

\item{title}{An optional character string used as the overall title of the plot.
Defaults to \code{NULL} (no title).}

\item{colour_observed}{Colour for observed values in the fitted-values panel.
Defaults to \code{"#00BFC4"} (teal).}

\item{colour_fitted}{Colour for fitted values in the fitted-values panel.
Defaults to \code{"#F8766D"} (red).}

\item{colour_residual}{Colour for residual lines, ACF/PACF bars, portmanteau test points, and
histogram fill. Defaults to \code{"#7CAE00"} (green).}

\item{...}{Additional arguments (currently unused, included for S3 consistency).}
}
\value{
For grid requests (\code{"default"} or \code{"all"}), invisibly returns a
  \code{gtable} object produced by \code{gridExtra::arrangeGrob}, which can
  be saved with \code{ggplot2::ggsave}. For single-panel requests, invisibly
  returns the individual \code{ggplot} object.
}
\description{
Produces diagnostic plots for a \eqn{\beta}ARMA model fitted by
\code{\link{barma}}. By default (\code{which = "default"}), four panels are
displayed in a 2\eqn{\times}2 grid: observed vs. fitted values, residual
ACF, Ljung-Box p-values, and residual PACF.
}
\details{
**Residual type.** All panels (except \emph{Observed vs. Fitted}) use the
residuals selected by \code{residual_type}. The residual type is displayed
in each panel subtitle for transparency.

**Reference lines in the residuals-over-time panel.** The dashed horizontal 
lines are drawn at \eqn{\pm 3} as an ad hoc threshold for identifying 
atypical observations. No distributional assumption is made; observations 
outside these bounds may warrant individual inspection. Pearson and 
link-scale residuals do not follow a standard normal distribution, so 
normal-distribution-based quantiles (e.g., \eqn{\pm 1.96} or 
\eqn{\pm 2.576}) are not appropriate reference values for such residuals. 
Quantile residuals are approximately distributed as \eqn{N(0,1)} under a 
correctly specified model, so \eqn{\pm 3} is a conservative but reasonable 
threshold for them.

**Q-Q plot residuals.** The \code{"qq"} panel always uses quantile
residuals (Dunn and Smyth, 1996), regardless of \code{residual_type}.
Quantile residuals are the only type theoretically expected to follow
\eqn{N(0,1)} under a correctly specified model; using Pearson, raw, or
link-scale residuals in a normal Q-Q plot would produce misleading results.
A message is issued when \code{residual_type} is overridden.

**Effective sample size.** Both the Ljung-Box and Monti test statistics
rely on the effective sample size \eqn{N_{eff} = n - \max(p, q)} (where
\eqn{\max(p, q)} corresponds to the maximum lag in the model).

**Ljung-Box test.** The p-values are computed from the Ljung-Box test
statistic.
\eqn{Q_{LB}(k) = N_{eff}(N_{eff}+2)\sum_{j=1}^{k}\hat{\rho}_j^2/(N_{eff}-j)},
where \eqn{\hat{\rho}_j} is the \eqn{j}-th sample autocorrelation of the
residuals and \eqn{N_{eff} = n - \max(p, q)} is the effective sample size.
The degrees of freedom are adjusted by subtracting the total
number of estimated  AR and MA parameters,
\eqn{n_{ar} + n_{ma}} (Scher, Cribari-Neto, Pumi, and Bayer (2020)). The
 first \eqn{n_{ar} + n_{ma}} lags are set to \code{NA}
since the test statistic is not defined for \eqn{k \leq n_{ar} + n_{ma}}.

**Monti test.** The p-values are computed from the test statistic
\eqn{M(k) = N_{eff}(N_{eff}+2)\sum_{j=1}^{k}\hat{\rho}_{jj}^2/(N_{eff}-j)},
where \eqn{\hat{\rho}_{jj}} is the \eqn{j}-th sample partial autocorrelation
of the residuals, and \eqn{N_{eff} = n - \max\_lag} is the effective sample
size after stripping initial NAs. The degrees of freedom are adjusted to
\eqn{k - (n_{ar} + n_{ma})}
(Monti, 1994; Scher, Cribari-Neto, Pumi, and Bayer (2020)). The first
\eqn{n_{ar} + n_{ma}} lags are set to \code{NA} as the statistic is not
defined for \eqn{k \leq n_{ar} + n_{ma}}.
}
\examples{
data(brasilia_ts)
fit <- barma(brasilia_ts, ar = 1, ma = 1)

# Default four-panel diagnostic grid (Pearson residuals)
plot(fit)

# Six-panel diagnostic grid
plot(fit, which = "all")

# Single panel: residuals as time series
plot(fit, which = "tsplot")

# Single panel: Ljung-Box p-values only
plot(fit, which = "ljungbox")

# Single panel: Monti p-values only
plot(fit, which = "monti")

# Normal Q-Q plot (always uses quantile residuals)
plot(fit, which = "qq")

# Histogram with quantile residuals
plot(fit, which = "hist", residual_type = "quantile")

}
\references{
Dunn, P. K., & Smyth, G. K. (1996). Randomized quantile residuals.
  \emph{Journal of Computational and Graphical Statistics}, 5(3), 236--244.
  \doi{10.1080/10618600.1996.10474708}

  Ferrari, S. L. P., & Cribari-Neto, F. (2004). Beta regression for
  modelling rates and proportions. \emph{Journal of Applied Statistics},
  31(7), 799--815. \doi{10.1080/0266476042000214501}

  Monti, A. C. (1994). A proposal for a residual autocorrelation test in
  linear models. \emph{Biometrika}, 81(4), 776--780.
  \doi{10.1093/biomet/81.4.776}

  Rocha, A. V., & Cribari-Neto, F. (2009). Beta autoregressive moving
  average models. \emph{TEST}, 18(3), 529--545.
  \doi{10.1007/s11749-008-0112-z}

  Rocha, A. V., & Cribari-Neto, F. (2017). Erratum to: Beta autoregressive
  moving average models. \emph{TEST}, 26, 451--459.
  \doi{10.1007/s11749-017-0528-4}
}
\seealso{
\code{\link{barma}} for model fitting;
  \code{\link{residuals.barma}} for the residual extraction method;
  \code{\link{fitted.barma}} for the fitted-value extraction method;
  \code{\link{forecast.barma}} for out-of-sample forecasting.
}
