% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/forward_algorithms.R
\name{forward_g}
\alias{forward_g}
\title{Forward algorithm with time-varying transition probability matrix}
\usage{
forward_g(
  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}{array of transition probability matrices of dimension \code{c(nStates, nStates, nObs)}, where
the first slice of each track is ignored as there is no transition into the start of a track.

For a single track, an array of dimension \code{c(nStates, nStates, nObs-1)} is also accepted.

This function also supports continuous-time HMMs, where each slice is a Markov semigroup
\eqn{\Gamma(\Delta t) = \exp(Q \Delta t)} for generator \eqn{Q}.}

\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 with time-varying transition probabilities using the \strong{forward algorithm} (Zucchini, MacDonald & Langrock, 2016).
}
\details{
If \code{trackID} is provided, the total log-likelihood will be the sum of each track's likelihood contribution.
In this case, \code{Gamma} must be an array of dimension \code{c(nStates, nStates, nObs)}, matching the number of rows of allprobs. For each track, the transition matrix at the beginning of the track will be ignored (as there is no transition between tracks).
Additionally, \code{delta} can be a vector (same initial distribution for each track) or a matrix of dimension \code{c(nTracks, nStates)} (different initial distribution for each track).

\strong{Note:} When there are multiple tracks, for compatibility with downstream functions like \code{\link{viterbi_g}}, \code{\link{stateprobs_g}} or \code{\link{pseudo_res}}, 
\code{forward_g} should only be called \strong{once} with a \code{trackID} argument.
}
\examples{
## Simple usage
Gamma = array(c(0.9, 0.2, 0.1, 0.8), dim = c(2,2,10))
delta = c(0.5, 0.5)
allprobs = matrix(0.5, 10, 2)
forward_g(delta, Gamma, allprobs)
\donttest{
## Full model fitting example
## negative log likelihood function
nll = function(par, step, Z) {
 # parameter transformations for unconstrained optimisation
 beta = matrix(par[1:6], nrow = 2)
 Gamma = tpm_g(Z, beta) # multinomial logit link for each time point
 delta = stationary(Gamma[,,1]) # stationary HMM
 mu = exp(par[7:8])
 sigma = exp(par[9:10])
 # 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_g(delta, Gamma, allprobs)
}

## fitting an HMM to the trex data
par = c(-1.5,-1.5,        # initial tpm intercepts (logit-scale)
        rep(0, 4),        # initial tpm slopes
        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:500], Z = cosinor(trex$tod[1:500]))
}
}
\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}()},
\code{\link{forward_hsmm}()},
\code{\link{forward_ihsmm}()},
\code{\link{forward_p}()},
\code{\link{forward_phsmm}()}
}
\concept{forward algorithms}
