% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/barma.R
\name{barma}
\alias{barma}
\title{Fit Beta Autoregressive Moving Average (BARMA) Models via Maximum Likelihood}
\usage{
barma(y, ar = integer(0), ma = integer(0), link = "logit", xreg = NULL)
}
\arguments{
\item{y}{A time series object (`ts`) with values strictly in the open interval (0, 1).
Must have at least \eqn{\max(p,q) + 1} observations.}

\item{ar}{A numeric vector specifying autoregressive (AR) lags
(e.g., `c(1, 2)` for AR(2)). Defaults to `integer(0)`, which omits the
AR component entirely. Absence should be expressed by omitting this
argument or passing `integer(0)`.}

\item{ma}{A numeric vector specifying moving average (MA) lags
(e.g., `1` for MA(1)). Defaults to `integer(0)`, which omits the
MA component entirely. Absence should be expressed by omitting this
argument or passing `integer(0)`.}

\item{link}{The link function connecting the mean \eqn{\mu_t} to the linear predictor
\eqn{\eta_t}. One of:
\itemize{
  \item `"logit"` (default): \eqn{g(x) = \log(x/(1-x))}
  \item `"probit"`: \eqn{g(x) = \Phi^{-1}(x)}
  \item `"cloglog"`: Complementary log-log link
  \item `"loglog"`: Log-log link
}}

\item{xreg}{A matrix or data frame of external regressors (covariates), optional.
Must have the same number of rows as `y`. If provided, its columns
are included in the linear predictor with associated coefficients in `beta`.}
}
\value{
An object of class `"barma"` containing:
\item{coef}{Named vector of all estimated parameters, ordered as:
  alpha, AR parameters, MA parameters, beta parameters, phi.}
\item{vcov}{The variance-covariance matrix of the estimators, computed as
  the inverse of the observed Fisher Information Matrix.}
\item{model}{A summary table with coefficients, standard errors, z-statistics,
  and p-values for hypothesis tests \eqn{H_0: \theta_i = 0}.}
\item{fitted}{Fitted conditional mean values as a `ts` object
  (NA-padded for the first \eqn{m = \max(p,q)} observations).}
\item{muhat}{Alias for `fitted` (fitted mean values).}
\item{etahat}{Estimated linear predictor values (full vector, NA-padded).}
\item{errorhat}{Estimated errors on predictor scale (full vector, 0-padded).}
\item{loglik}{The conditional log-likelihood at the MLE.}
\item{fisher_info_mat}{The observed Fisher Information Matrix.}
\item{conv}{Convergence code from `optim` (0 = success).}
\item{alpha, beta, varphi, theta, phi}{Individual parameter estimates.}
\item{start_values}{Initial parameter values used in optimization.}
\item{call}{The original function call.}
\item{opt}{Raw output object from `optim()` call.}
}
\description{
Fits a Beta Autoregressive Moving Average (BARMA) model to time series data
valued in (0, 1) using Maximum Likelihood Estimation (MLE). The function
performs complete model estimation including parameter estimation, hypothesis
testing infrastructure, and model diagnostics.
}
\details{
Fit Beta Autoregressive Moving Average (BARMA) Models


This function fits the BARMA(p,q) model as proposed by Rocha & Cribari-Neto
(2009, with erratum 2017). It serves as the main wrapper for the optimization
process, calling specialized helper functions for likelihood computation,
gradient calculation, and Fisher Information Matrix estimation.

**Model Specification**: The BARMA model is defined as:

\deqn{g(\mu_t) = \alpha + X_t\beta + \sum_{i=1}^{p} \varphi_i 
(g(y_{t-i}) - X_{t-i}\beta) + \sum_{j=1}^{q} \theta_j \epsilon_{t-j}}

where \eqn{y_t | F_{t-1} \sim Beta(\mu_t\phi, (1-\mu_t)\phi)},
\eqn{g(\cdot)} is the link function, and \eqn{F_{t-1}} is the information
set at time t-1.

**Model Types** (specified via `ar` and `ma` arguments):
\itemize{
  \item **BARMA(p,q):** Both `ar` and `ma` are specified.
  \item **BAR(p):** Only `ar` is specified; omit `ma` or pass `integer(0)`.
  \item **BMA(q):** Only `ma` is specified; omit `ar` or pass `integer(0)`.
}

**External Regressors**: Covariates can be included via `xreg`. The model
becomes a regression BARMA, where the mean depends on current covariates
and lagged responses/errors.

**Optimization**: The function uses the BFGS quasi-Newton algorithm via
\code{\link{optim}} with analytic gradients for efficiency. Initial values
are obtained from the `start_values()` function.

**Implementation Notes**: 
- The conditional log-likelihood is computed by conditioning on the first
  \eqn{m = \max(p,q)} observations, which are required to initialize the
  recursive structure of the model.
- The 2017 Erratum corrections are implemented for correct handling of
  moving average components in the score vector and Fisher Information Matrix.
- All computations are vectorized where possible for efficiency.
}
\note{
The original version of this function was developed by Fabio M. Bayer
(Federal University of Santa Maria, \email{bayer@ufsm.br}). It has been
substantially modified and improved by Everton da Costa, with suggestions
and contributions from Francisco Cribari-Neto.
}
\examples{
\donttest{
  # Example 1: Fit a BAR(1) model (no MA component)
  set.seed(2025)
  y_sim_bar1 <- simu_barma(
    n      = 250,
    alpha  = 0.0,
    varphi = 0.6,
    phi    = 25.0,
    link   = "logit",
    freq   = 12
  )

  fit_bar1 <- barma(y_sim_bar1, ar = 1, link = "logit")
  summary(fit_bar1)
  coef(fit_bar1)

  # Example 2: Fit a BARMA(1, 1) model
  set.seed(2025)
  y_sim_barma11 <- simu_barma(
    n      = 250,
    alpha  = 0.0,
    varphi = 0.6,
    theta  = 0.3,
    phi    = 25.0,
    link   = "logit",
    freq   = 12
  )

  fit_barma11 <- barma(y_sim_barma11, ar = 1, ma = 1, link = "logit")
  summary(fit_barma11)

  # Example 3: Fit a BMA(1) model (no AR component)
  set.seed(2025)
  y_sim_bma1 <- simu_barma(
    n      = 250,
    alpha  = 0.0,
    theta  = 0.3,
    phi    = 20.0,
    link   = "logit",
    freq   = 12
  )

  fit_bma1 <- barma(y_sim_bma1, ma = 1, link = "logit")
  summary(fit_bma1)

  # Example 4: BARMA(1, 1) model with harmonic seasonal regressors
  hs <- sin(2 * pi * seq_along(y_sim_barma11) / 12)
  hc <- cos(2 * pi * seq_along(y_sim_barma11) / 12)
  X  <- cbind(hs = hs, hc = hc)

  fit_barma11_xreg <- barma(
    y_sim_barma11,
    ar   = 1,
    ma   = 1,
    link = "logit",
    xreg = X
  )
  summary(fit_barma11_xreg)
}

}
\references{
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{simu_barma}} for simulation,
\code{\link{loglik_barma}} for likelihood computation,
\code{\link{score_vector_barma}} for gradient computation,
\code{\link{fim_barma}} for Fisher Information Matrix
}
\author{
Everton da Costa (Federal University of Pernambuco, 
\email{everto.cost@gmail.com});
Francisco Cribari-Neto (Federal University of Pernambuco, 
\email{francisco.cribari@ufpe.br})
}
