% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/forward_algorithms.R
\name{forward}
\alias{forward}
\title{Forward algorithm to calculate the HMM log-likelihood}
\usage{
forward(
  delta,
  Gamma,
  allprobs,
  trackID = NULL,
  logspace = FALSE,
  bw = NULL,
  report = TRUE,
  ad = NULL
)
}
\arguments{
\item{delta}{initial distribution; either
\itemize{
  \item a vector of length \code{nStates}, or
  \item a matrix of dimension \code{c(nTracks, nStates)}, if \code{trackID} is provided.
}}

\item{Gamma}{transition probability matrix; either
\itemize{
  \item a matrix of dimension \code{c(nStates, nStates)}, or
  \item an array of dimension \code{c(nStates, nStates, nTracks)} if \code{trackID} is provided, or
  \item an array of dimension \code{c(nStates, nStates, nObs)} for time-varying transition probabilities, in which case \code{\link{forward_g}} is called internally.
}}

\item{allprobs}{matrix of state-dependent probabilities or density values of dimension \code{c(nObs, nStates)}}

\item{trackID}{optional vector of length \code{nObs} containing \code{nTracks} unique IDs that separate tracks (see \sQuote{Details}).}

\item{logspace}{logical; if \code{TRUE}, \code{allprobs} is assumed to be on the log-scale, improving numerical stability for small probabilities. Only supported with \code{RTMB}.}

\item{bw}{optional positive integer specifying the bandwidth for a banded approximation of the forward algorithm, inducing a banded Hessian w.r.t. the observations. 
Defaults to \code{NULL} (exact algorithm). Approximation error decays geometrically in \code{bw}.}

\item{report}{logical; if \code{TRUE} (default), \code{delta}, \code{Gamma}, \code{allprobs}, and \code{trackID} are reported from the fitted model. Requires \code{ad = TRUE}.}

\item{ad}{logical; whether to use automatic differentiation. Determined automatically — for debugging only.}
}
\value{
HMM log-likelihood for given data and parameters
}
\description{
Calculates the log-likelihood of a sequence of observations under a hidden Markov model
using the \strong{forward algorithm} (Zucchini, MacDonald & Langrock, 2016).
}
\details{
If \code{trackID} is provided, the total log-likelihood is the sum of each track's likelihood
contribution. In this case, \code{Gamma} can be
  \itemize{
    \item a matrix (same transition probabilities for each track),
    \item an array of dimension \code{c(nStates, nStates, nTracks)} (track-specific transition probability matrix), or
    \item an array of dimension \code{c(nStates, nStates, nObs)} for time-varying transition probabilities, in which case \code{\link{forward_g}} is called internally.
  }
Additionally, \code{delta} can be a vector (same initial distribution for each track) or a
matrix of dimension \code{c(nTracks, nStates)} (track-specific initial distributions).

\strong{Note:} When there are multiple tracks, for compatibility with downstream functions like \code{\link{viterbi}}, \code{\link{stateprobs}} or \code{\link{pseudo_res}}, 
\code{forward} should only be called \strong{once} with a \code{trackID} argument.
}
\examples{
## negative log likelihood function
nll = function(par, step) {
 # parameter transformations for unconstrained optimisation
 Gamma = tpm(par[1:2]) # multinomial logit link
 delta = stationary(Gamma) # stationary HMM
 mu = exp(par[3:4])
 sigma = exp(par[5:6])
 # calculate all state-dependent probabilities
 allprobs = matrix(1, length(step), 2)
 ind = which(!is.na(step))
 for(j in 1:2) allprobs[ind,j] = dgamma2(step[ind], mu[j], sigma[j])
 # simple forward algorithm to calculate log-likelihood
 -forward(delta, Gamma, allprobs)
}

## fitting an HMM to the trex data
par = c(-2,-2,            # initial tpm params (logit-scale)
        log(c(0.3, 2.5)), # initial means for step length (log-transformed)
        log(c(0.2, 1.5))) # initial sds for step length (log-transformed)
mod = nlm(nll, par, step = trex$step[1:1000])
}
\references{
Zucchini, W., MacDonald, I.L., & Langrock, R. (2016). 
\emph{Hidden Markov Models for Time Series: An Introduction Using R} 
(2nd ed.). Chapman & Hall/CRC.

Mews, Koslik, & Langrock (2025). 
How to build your latent Markov model: The role of time and space. 
Statistical Modelling, 25(6), 481--507.
}
\seealso{
Other forward algorithms: 
\code{\link{forward_g}()},
\code{\link{forward_hsmm}()},
\code{\link{forward_ihsmm}()},
\code{\link{forward_p}()},
\code{\link{forward_phsmm}()}
}
\concept{forward algorithms}
