% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/fim_barma.R
\name{fim_barma}
\alias{fim_barma}
\title{Compute Fisher Information Matrix for Beta Autoregressive
Moving Average Models}
\usage{
fim_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, 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}, the ridge penalty of Cribari-Neto, Costa and
Fonseca (2025) is added to the Fisher Information Matrix, yielding the
penalized FIM \eqn{K_{\text{pen}}(\boldsymbol{\nu}) = K(\boldsymbol{\nu})
+ 2(n-a)\Lambda}, where \eqn{\Lambda =
\text{diag}\{\lambda_n,\ldots,\lambda_n, 0,\ldots,0\}} with
\eqn{\lambda_n = 1/(n-a)^{0.9}} applied to \eqn{\alpha},
\eqn{\boldsymbol{\varphi}}, and \eqn{\boldsymbol{\theta}} only.
Defaults to \code{FALSE}.}
}
\value{
A list containing:
\item{fisher_info_mat}{The Fisher Information Matrix (numeric matrix).
  Dimensions: \code{(k+p+q+2) x (k+p+q+2)} where k is number of regressors,
  p is AR order, q is MA order. The matrix is symmetric and should be
  positive definite at the MLE.}
\item{fitted_ts}{The fitted values (conditional mean) as a \code{ts} object,
  with the same time index as the input \code{y}. Values for the first
  \eqn{m = \max(p,q)} observations are \code{NA}.}
\item{muhat_effective}{The fitted conditional means (numeric vector)
  excluding the first \eqn{m} observations.}
\item{etahat_full}{The estimated linear predictor values (numeric vector,
  length = length(y)), with \code{NA} for the first \eqn{m} observations.}
\item{errorhat_full}{The estimated errors on the predictor scale
  (numeric vector, length = length(y)), zero-padded for the first
  \eqn{m} observations.}
}
\description{
Computes the expected Fisher Information Matrix (FIM) of a Beta
Autoregressive Moving Average (BARMA) model. This function also
efficiently returns auxiliary values like fitted values and residuals.

This function is designed for users who:
\itemize{
  \item Compute standard errors of parameter estimates
  \item Construct confidence intervals
  \item Perform hypothesis tests
  \item Verify theoretical properties
  \item Conduct simulation studies
}
}
\details{
Fisher Information Matrix for BARMA Models


The expected Fisher Information Matrix is computed analytically using
the trigamma-based expressions from Rocha and Cribari-Neto (2009).
Standard errors are obtained via \code{sqrt(diag(solve(FIM)))}.

**Non-Diagonal Structure**: Unlike generalized linear models, the FIM
is not block-diagonal due to the coupling introduced by the ARMA
dynamics. This is documented in the Rocha & Cribari-Neto (2009) paper.

**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), beta (regressors), phi.
This matches the parameter order used by \code{\link{barma}}.
}
\examples{
\donttest{
  # Example 1: Fisher Information Matrix 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
  )

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

  # Check positive definiteness
  fim <- result_bar1$fisher_info_mat
  all(eigen(fim)$values > 0)

  # Standard errors from inverse of FIM
  sqrt(diag(solve(fim)))

  # Example 2: Fisher Information Matrix 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
  )

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

  sqrt(diag(solve(result_barma11$fisher_info_mat)))

  # Example 3: Fisher Information Matrix 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
  )

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

  sqrt(diag(solve(result_bma1$fisher_info_mat)))
}

}
\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{loglik_barma}} for log-likelihood computation,
\code{\link{score_vector_barma}} for score vector (gradient)
}
