% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/loglik_barma.R
\name{loglik_barma}
\alias{loglik_barma}
\title{Compute Conditional Log-Likelihood for Beta Autoregressive
Moving Average Models}
\usage{
loglik_barma(
  y,
  ar = integer(0),
  ma = integer(0),
  alpha,
  varphi = numeric(0),
  theta = numeric(0),
  phi,
  link = "logit",
  xreg = NULL,
  beta = NULL,
  penalty = FALSE
)
}
\arguments{
\item{y}{A numeric vector representing the time series data, with values
strictly in (0, 1).}

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

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

\item{alpha}{The intercept term (numeric scalar).}

\item{varphi}{A numeric vector of autoregressive (AR) parameters.
Absence should be expressed by omitting this argument or passing
\code{numeric(0)}.}

\item{theta}{A numeric vector of moving average (MA) parameters.
Absence should be expressed by omitting this argument or passing
\code{numeric(0)}.}

\item{phi}{The precision parameter of the BARMA model (must be positive and finite).
Larger values indicate less variance for a given mean.}

\item{link}{A character string specifying the link function:
\code{"logit"} (default), \code{"probit"}, or \code{"cloglog"}.}

\item{xreg}{A matrix or data frame of static regressors (optional).
Must have the same number of rows as length of \code{y}.}

\item{beta}{A numeric vector of regression coefficients for \code{xreg} (optional).
Length must match number of columns in \code{xreg}.}

\item{penalty}{Logical. If \code{TRUE}, a ridge penalty is subtracted from the
conditional log-likelihood, yielding the penalized conditional
log-likelihood proposed by Cribari-Neto, Costa and Fonseca (2025).
The penalty term is \eqn{(n - a) \lambda_n \|\boldsymbol{\nu}\|^2},
where \eqn{\lambda_n = 1/(n - a)^{0.9}} and \eqn{\boldsymbol{\nu}}
collects \eqn{\alpha}, \eqn{\boldsymbol{\varphi}}, and
\eqn{\boldsymbol{\theta}} (the precision parameter \eqn{\phi} and
regression coefficients \eqn{\boldsymbol{\beta}} are excluded).
Defaults to \code{FALSE}.}
}
\value{
A numeric scalar representing the (penalized) conditional log-likelihood
value. When \code{penalty = FALSE} (default), the standard conditional
log-likelihood is returned. When \code{penalty = TRUE}, the ridge-penalized
conditional log-likelihood of Cribari-Neto, Costa and Fonseca (2025) is
returned instead.
Returns \code{-Inf} if:
\itemize{
  \item \code{phi} is non-positive or non-finite
  \item Insufficient observations for specified lag structure
  \item Fitted values are outside (0, 1)
  \item Any numerical issues occur
}
}
\description{
Computes the conditional log-likelihood of a Beta Autoregressive
Moving Average (BARMA) model. This function is designed for users who:
\itemize{
  \item Implement custom optimization algorithms
  \item Verify theoretical properties
  \item Conduct simulation studies
  \item Debug model fitting
  \item Integrate BARMA models into their own workflows
}
}
\details{
Log-Likelihood for BARMA Models


The log-likelihood is computed as:
\deqn{\ell = \sum_{t=m+1}^{n} \log f(y_t | \mu_t, \phi)}

where \eqn{f} is the Beta density with shape parameters
\eqn{shape1 = \mu_t * \phi} and \eqn{shape2 = (1-\mu_t)*\phi}.

The linear predictor is constructed as:
\deqn{\eta_t = \alpha + X_t \beta + \sum_{i=1}^{p} \varphi_i
(y_{t-i} - X_{t-i}\beta) + \sum_{j=1}^{q} \theta_j \epsilon_{t-j}}

**Important**: This function implements the corrections from the 2017
Erratum (Rocha & Cribari-Neto, 2017) for moving average components.
See References section for details.

**Parameter Order**: Parameters should be supplied in the order:
alpha, varphi (AR), theta (MA), phi, beta (regressors).
This matches the parameter order used by \code{\link{barma}}.
}
\examples{
\donttest{
  # Example 1: Log-likelihood for 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
  )

  loglik_barma(
    y      = y_sim_bar1,
    ar     = 1,
    alpha  = 0.0,
    varphi = 0.6,
    theta  = numeric(0),
    phi    = 25.0,
    link   = "logit"
  )

  # Example 2: Log-likelihood for 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
  )

  loglik_barma(
    y      = y_sim_barma11,
    ar     = 1,
    ma     = 1,
    alpha  = 0.0,
    varphi = 0.6,
    theta  = 0.3,
    phi    = 25.0,
    link   = "logit"
  )

  # Example 3: Log-likelihood for 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
  )

  loglik_barma(
    y      = y_sim_bma1,
    ma     = 1,
    alpha  = 0.0,
    varphi = numeric(0),
    theta  = 0.3,
    phi    = 20.0,
    link   = "logit"
  )

  # Example 4: Ridge-penalized log-likelihood for a BARMA(1, 1) model
  # Uses penalty = TRUE as recommended by Cribari-Neto, Costa and
  # Fonseca (2025, BJPS) to improve numerical stability.
  loglik_barma(
    y       = y_sim_barma11,
    ar      = 1,
    ma      = 1,
    alpha   = 0.0,
    varphi  = 0.6,
    theta   = 0.3,
    phi     = 25.0,
    link    = "logit",
    penalty = TRUE
  )
}

}
\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}

Cribari-Neto, F., Costa, E., & Fonseca, R.V. (2025). Numerical stability
enhancements in beta autoregressive moving average model estimation.
\emph{Brazilian Journal of Probability and Statistics}, 39(4), 410-437.
\doi{10.1214/25-BJPS645}
}
\seealso{
\code{\link{barma}} for model fitting,
\code{\link{score_vector_barma}} for gradient computation,
\code{\link{fim_barma}} for Fisher Information Matrix
}
