% -*- texinfo -*-
% @deftypefn {Function File} {[@var{transprobest}, @var{outprobest}] =} hmmestimate (@var{sequence}, @var{states})
% @deftypefnx {Function File} {} hmmestimate (@dots{}, 'statenames', @var{statenames})
% @deftypefnx {Function File} {} hmmestimate (@dots{}, 'symbols', @var{symbols})
% @deftypefnx {Function File} {} hmmestimate (@dots{}, 'pseudotransitions', @var{pseudotransitions})
% @deftypefnx {Function File} {} hmmestimate (@dots{}, 'pseudoemissions', @var{pseudoemissions})
% Estimate the matrix of transition probabilities and the matrix of output
% probabilities of a given sequence of outputs and states generated by a
% hidden Markov model. 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 a vector of a sequence of given outputs. The outputs
% must be integers ranging from @code{1} to the number of outputs of the
% hidden Markov model.
%
% @item
% @var{states} is a vector of the same length as @var{sequence} of given
% states. The states must be integers ranging from @code{1} to the number
% of states of the hidden Markov model.
% @end itemize
%
% @subheading Return values
%
% @itemize @bullet
% @item
% @var{transprobest} is the matrix of the estimated transition
% probabilities of the states. @code{transprobest(i, j)} is the estimated
% probability of a transition to state @code{j} given state @code{i}.
%
% @item
% @var{outprobest} is the matrix of the estimated output probabilities.
% @code{outprobest(i, j)} is the estimated probability of generating
% output @code{j} given state @code{i}.
% @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.
% @var{symbols} can be a cell array.
%
% If @code{'statenames'} is specified, then @var{states} is expected to be
% a sequence of the elements of @var{statenames} instead of integers.
% @var{statenames} can be a cell array.
%
% If @code{'pseudotransitions'} is specified then the integer matrix
% @var{pseudotransitions} is used as an initial number of counted
% transitions. @code{pseudotransitions(i, j)} is the initial number of
% counted transitions from state @code{i} to state @code{j}.
% @var{transprobest} will have the same size as @var{pseudotransitions}.
% Use this if you have transitions that are very unlikely to occur.
%
% If @code{'pseudoemissions'} is specified then the integer matrix
% @var{pseudoemissions} is used as an initial number of counted outputs.
% @code{pseudoemissions(i, j)} is the initial number of counted outputs
% @code{j} given state @code{i}. If @code{'pseudoemissions'} is also
% specified then the number of rows of @var{pseudoemissions} must be the
% same as the number of rows of @var{pseudotransitions}. @var{outprobest}
% will have the same size as @var{pseudoemissions}. Use this if you have
% outputs or states that are very unlikely to occur.
%
% @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);
% [transprobest, outprobest] = hmmestimate (sequence, states)
% @end group
%
% @group
% symbols = @{'A', 'B', 'C'@};
% statenames = @{'One', 'Two'@};
% [sequence, states] = hmmgenerate (25, transprob, outprob,
% 'symbols', symbols, 'statenames', statenames);
% [transprobest, outprobest] = hmmestimate (sequence, states,
% 'symbols', symbols,
% 'statenames', statenames)
% @end group
%
% @group
% pseudotransitions = [8, 2; 4, 6];
% pseudoemissions = [2, 4, 4; 7, 2, 1];
% [sequence, states] = hmmgenerate (25, transprob, outprob);
% [transprobest, outprobest] = hmmestimate (sequence, states, 'pseudotransitions', pseudotransitions, 'pseudoemissions', pseudoemissions)
% @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