% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/HMM.R
\name{HMM}
\alias{HMM}
\title{HMM Parameter Estimation via Matrix/Tensor Decomposition}
\usage{
HMM(
  Y,
  K,
  N = NULL,
  solver = c("symNMF", "SVD", "CP", "TT"),
  Beta = 2,
  order = 2L,
  lag = 1L,
  smooth = 1e-10,
  num.iter = 100L,
  thr = 1e-10,
  verbose = FALSE
)
}
\arguments{
\item{Y}{Integer vector of observations (values in 1:N), or a list of
integer vectors for multiple sequences.}

\item{K}{Number of hidden states}

\item{N}{Number of distinct observation symbols. If NULL, inferred from data.}

\item{solver}{Decomposition method:
\describe{
  \item{\code{"symNMF"}}{Symmetric NMF via \code{symTensor::symNMF} (default)}
  \item{\code{"SVD"}}{Truncated SVD of the co-occurrence matrix}
  \item{\code{"CP"}}{CP decomposition of the 3rd-order co-occurrence tensor via \code{rTensor::cp}}
  \item{\code{"TT"}}{Tensor-Train approximation (via Tucker + reshape)}
}}

\item{Beta}{Beta-divergence parameter for symNMF (default: 2). Ignored for other solvers.}

\item{order}{Co-occurrence order for Seq2Prob: 2 (default) or 3.
\code{order = 3} is required for \code{solver = "CP"}.}

\item{lag}{Lag for pairwise co-occurrence (default: 1)}

\item{smooth}{Laplace smoothing pseudo-count (default: 1e-10)}

\item{num.iter}{Maximum iterations for iterative solvers (default: 100)}

\item{thr}{Convergence threshold (default: 1e-10)}

\item{verbose}{Logical (default: FALSE)}
}
\value{
A list with components:
  \describe{
    \item{T_mat}{Estimated transition matrix (K x K)}
    \item{O}{Estimated emission matrix (K x N)}
    \item{pi0}{Estimated initial distribution (length K)}
    \item{Omega}{Co-occurrence matrix/tensor used}
    \item{decomp}{Raw decomposition result}
    \item{solver}{Solver used}
    \item{RecError}{Reconstruction error (if available)}
  }
}
\description{
Estimates HMM parameters by decomposing the observation co-occurrence
matrix/tensor. Supports multiple decomposition solvers.
}
\details{
The pipeline:
\enumerate{
  \item Convert observations to co-occurrence matrix \eqn{\Omega = P_{2,1}} via \code{\link{Seq2Prob}}
  \item Decompose \eqn{\Omega} using the chosen solver
  \item Recover HMM parameters (T, O, pi) from the decomposition
}

For NMF-based methods, \eqn{\Omega \approx M \Theta M^\top} where
M relates to the emission matrix O and \eqn{\Theta} to \code{diag(pi) \%*\% T}.
}
\examples{
set.seed(42)
toy <- toyModel(type = "simple")
result <- HMM(toy$Y, K = toy$K, N = toy$N, solver = "symNMF")
result$T_mat
}
