% -*- texinfo -*-
% @deftypefn {Function File} {@var{vpath} =} hmmviterbi (@var{sequence}, @var{transprob}, @var{outprob})
% @deftypefnx {Function File} {} hmmviterbi (@dots{}, 'symbols', @var{symbols})
% @deftypefnx {Function File} {} hmmviterbi (@dots{}, 'statenames', @var{statenames})
% Use the Viterbi algorithm to find the Viterbi path of a hidden Markov
% model given a sequence of outputs. The model assumes that the generation
% starts in state @code{1} at step @code{0} but does not include step
% @code{0} in the generated states and sequence.
%
% @subheading Arguments
%
% @itemize @bullet
% @item
% @var{sequence} is the vector of length @var{len} of given outputs. The
% outputs must be integers ranging from @code{1} to
% @code{columns (outprob)}.
%
% @item
% @var{transprob} is the matrix of transition probabilities of the states.
% @code{transprob(i, j)} is the probability of a transition to state
% @code{j} given state @code{i}.
%
% @item
% @var{outprob} is the matrix of output probabilities.
% @code{outprob(i, j)} is the probability of generating output @code{j}
% given state @code{i}.
% @end itemize
%
% @subheading Return values
%
% @itemize @bullet
% @item
% @var{vpath} is the vector of the same length as @var{sequence} of the
% estimated hidden states. The states are integers ranging from @code{1} to
% @code{columns (transprob)}.
% @end itemize
%
% If @code{'symbols'} is specified, then @var{sequence} is expected to be a
% sequence of the elements of @var{symbols} instead of integers ranging
% from @code{1} to @code{columns (outprob)}. @var{symbols} can be a cell array.
%
% If @code{'statenames'} is specified, then the elements of
% @var{statenames} are used for the states in @var{vpath} instead of
% integers ranging from @code{1} to @code{columns (transprob)}.
% @var{statenames} can be a cell array.
%
% @subheading Examples
%
% @example
% @group
% transprob = [0.8, 0.2; 0.4, 0.6];
% outprob = [0.2, 0.4, 0.4; 0.7, 0.2, 0.1];
% [sequence, states] = hmmgenerate (25, transprob, outprob)
% vpath = hmmviterbi (sequence, transprob, outprob)
% @end group
%
% @group
% symbols = @{'A', 'B', 'C'@};
% statenames = @{'One', 'Two'@};
% [sequence, states] = hmmgenerate (25, transprob, outprob,
% 'symbols', symbols, 'statenames', statenames)
% vpath = hmmviterbi (sequence, transprob, outprob,
% 'symbols', symbols, 'statenames', statenames)
% @end group
% @end example
%
% @subheading References
%
% @enumerate
% @item
% Wendy L. Martinez and Angel R. Martinez. @cite{Computational Statistics
% Handbook with MATLAB}. Appendix E, pages 547-557, Chapman & Hall/CRC,
% 2001.
%
% @item
% Lawrence R. Rabiner. A Tutorial on Hidden Markov Models and Selected
% Applications in Speech Recognition. @cite{Proceedings of the IEEE},
% 77(2), pages 257-286, February 1989.
% @end enumerate
% @end deftypefn