% -*- texinfo -*-
% @deftypefn {Function File} {[@var{sequence}, @var{states}] =} hmmgenerate (@var{len}, @var{transprob}, @var{outprob})
% @deftypefnx {Function File} {} hmmgenerate (@dots{}, 'symbols', @var{symbols})
% @deftypefnx {Function File} {} hmmgenerate (@dots{}, 'statenames', @var{statenames})
% Generate an output sequence and hidden states of a hidden Markov model.
% The model starts in state @code{1} at step @code{0} but will not include
% step @code{0} in the generated states and sequence.
%
% @subheading Arguments
%
% @itemize @bullet
% @item
% @var{len} is the number of steps to generate. @var{sequence} and
% @var{states} will have @var{len} entries each.
%
% @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{sequence} is a vector of length @var{len} of the generated
% outputs. The outputs are integers ranging from @code{1} to
% @code{columns (outprob)}.
%
% @item
% @var{states} is a vector of length @var{len} of the generated hidden
% states. The states are integers ranging from @code{1} to
% @code{columns (transprob)}.
% @end itemize
%
% If @code{'symbols'} is specified, then the elements of @var{symbols} are
% used for the output sequence 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 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)
% @end group
%
% @group
% symbols = @{'A', 'B', 'C'@};
% statenames = @{'One', 'Two'@};
% [sequence, states] = hmmgenerate (25, 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