hidden               package:repeated               R Documentation

_D_i_s_c_r_e_t_e-_t_i_m_e _H_i_d_d_e_n _M_a_r_k_o_v _C_h_a_i_n _M_o_d_e_l_s

_D_e_s_c_r_i_p_t_i_o_n:

     'hidden' fits a two or more state hidden Markov chain model with a
     variety of distributions. All series on different individuals are
     assumed to start at the same time point. Time points are equal,
     discrete steps.

     To fit an `observed' Markov chain, as well, with Bernoulli or
     multinomial responses, use the lagged response as a time-varying
     covariate. For quantitative responses, specifying 'par' allows an
     `observed" autoregression to be fitted as well as the hidden
     Markov chain.

     All functions and formulae for the location parameter are on the
     (generalized) logit scale for the Bernoulli, binomial, and
     multinomial distributions.

     If 'cmu' and 'tvmu' are used, these two mean functions are
     additive so that interactions between time-constant and
     time-varying variables are not possible.

     The object returned can be plotted to give the probabilities of
     being in each hidden state at each time point. For distributions
     other than the multinomial, proportional odds, and continuation
     ratio, the (recursive) predicted values can be plotted using
     'mprofile' and 'iprofile'.

     See MacDonald, I.L. and Zucchini, W. (1997) Hidden Markov and
     Other Models for Discrete-valued Time Series. Chapman and Hall.

_U_s_a_g_e:

     hidden(response=NULL, totals=NULL, distribution="Bernoulli",
             mu=NULL, cmu=NULL, tvmu=NULL, pgamma, pmu=NULL, pcmu=NULL,
             ptvmu=NULL, pshape=NULL, pfamily=NULL, par=NULL, pintercept=NULL,
             delta=NULL, envir=parent.frame(), print.level=0, ndigit=10,
             gradtol=0.00001, steptol=0.00001, fscale=1, iterlim=100,
             typsiz=abs(p), stepmax=10*sqrt(p%*%p))
     plot.hidden(z, nind=1, state=NULL, smooth=FALSE, main=NULL,
             ylab=NULL, xlab="Time", xlim=NULL, ...)

_A_r_g_u_m_e_n_t_s:

response: A list of two or three column matrices with counts or
          category indicators, times, and possibly totals (if the
          distribution is binomial), for each individual, one matrix or
          dataframe of counts, or an object of class, 'response'
          (created by 'restovec') or 'repeated' (created by 'rmna' or
          'lvna'). If the 'repeated' data object contains more than one
          response variable, give that object in 'envir' and give the
          name of the response variable to be used here. If there is
          only one series, a vector of responses may be supplied
          instead.

          Multinomial and ordinal categories must be integers numbered
          from 0.

  totals: If response is a matrix, a corresponding matrix of totals if
          the distribution is binomial. Ignored if response has class,
          'response' or 'repeated'.

distribution: Bernoulli, Poisson, multinomial, proportional odds,
          continuation ratio, binomial, exponential, beta binomial,
          negative binomial, normal, inverse Gauss, logistic, gamma,
          Weibull, Cauchy, Laplace, Levy, Pareto, gen(eralized) gamma,
          gen(eralized) logistic, Hjorth, Burr, gen(eralized) Weibull,
          gen(eralized) extreme value, gen(eralized) inverse Gauss,
          power exponential, skew Laplace, or Student t. (For
          definitions of distributions, see the corresponding
          [dpqr]distribution help.)

      mu: A general location function with two possibilities: (1) a
          list of formulae (with parameters having different names) or
          functions (with one parameter vector numbering for all of
          them) each returning one value per observation; or (2) a
          single formula or function which will be used for all states
          (and all categories if multinomial) but with different
          parameter values in each so that pmu must be a vector of
          length the number of unknowns in the function or formula
          times the number of states (times the number of categories
          minus one if multinomial).

     cmu: A time-constant location function with three possibilities:
          (1) a list of formulae (with parameters having different
          names) or functions (with one parameter vector numbering for
          all of them) each returning one value per individual; (2) a
          single formula or function which will be used for all states
          (and all categories if multinomial) but with different
          parameter values in each so that pcmu must be a vector of
          length the number of unknowns in the function or formula
          times the number of states (times the number of categories
          minus one if multinomial); or (3) a function returning an
          array with one row for each individual, one column for each
          state of the hidden Markov chain, and, if multinomial, one
          layer for each category but the last. If used, this function
          or formula should contain the intercept. Ignored if 'mu' is
          supplied.

    tvmu: A time-varying location function with three possibilities:
          (1) a list of formulae (with parameters having different
          names) or functions (with one parameter vector numbering for
          all of them) each returning one value per time point; (2) a
          single formula or function which will be used for all states
          (and all categories if multinomial) but with different
          parameter values in each so that ptvmu must be a vector of
          length the number of unknowns in the function or formula
          times the number of states (times the number of categories
          minus one if multinomial); or (3) a function returning an
          array with one row for each time point, one column for each
          state of the hidden Markov chain, and, if multinomial, one
          layer for each category but the last. This function or
          formula is usually a function of time; it is the same for all
          individuals. It only contains the intercept if 'cmu' does
          not. Ignored if 'mu' is supplied.

  pgamma: A square 'mxm' matrix of initial estimates of the hidden
          Markov transition matrix, where 'm' is the number of hidden
          states. Rows must sum to one. If the matrix contains zeroes
          or ones, these are fixed and not estimated. (Ones cannot
          appear on the diagonal.) If a '1x1' matrix or a scalar value
          of 1 is given, the independence model is fitted.

     pmu: Initial estimates of the unknown parameters in 'mu'.

    pcmu: Initial estimates of the unknown parameters in 'cmu'.

   ptvmu: Initial estimates of the unknown parameters in 'tvmu'.

  pshape: Initial estimate(s) of the dispersion parameter, for those
          distributions having one. This can be one value or a vector
          with a different value for each state.

 pfamily: Initial estimate of the family parameter, for those
          distributions having one.

     par: Initial estimate of the autoregression parameter.

pintercept: For multinomial, proportional odds, and continuation ratio
          models, 'p-2' initial estimates for intercept contrasts from
          the first intercept, where 'p' is the number of categories.

   delta: Scalar or vector giving the unit of measurement (always one
          for discrete data) for each response value, set to unity by
          default. For example, if a response is measured to two
          decimals, delta=0.01. If the response is transformed, this
          must be multiplied by the Jacobian. For example, with a log
          transformation, 'delta=1/response'. Ignored if response has
          class, 'response' or 'repeated'.

   envir: Environment in which model formulae are to be interpreted or
          a data object of class, 'repeated', 'tccov', or 'tvcov'; the
          name of the response variable should be given in 'response'.
          If 'response' has class 'repeated', it is used as the
          environment.

    nind: For plotting: numbers of individuals to plot.

   state: For plotting: states to plot.

  others: Arguments controlling 'nlm'.

_V_a_l_u_e:

     A list of classes 'hidden' and 'recursive' (unless multinomial,
     proportional odds, or continuation ratio) is returned that
     contains all of the relevant information calculated, including
     error codes.

_A_u_t_h_o_r(_s):

     J.K. Lindsey and P.J. Lindsey

_R_e_f_e_r_e_n_c_e_s:

     MacDonald, I.L. and Zucchini, W. (1997) Hidden Markov and other
     Models for Discrete-valued Time Series. Chapman & Hall.

_S_e_e _A_l_s_o:

     'chidden', 'gar', 'gnlmm', 'iprofile', 'kalcount', 'mprofile',
     'nbkal', 'read.list', 'restovec', 'rmna'.

_E_x_a_m_p_l_e_s:

     # generate two random Poisson sequences with change-points
     y <- rbind(c(rpois(5,1), rpois(15,5)), c(rpois(15,1), rpois(5,5)))
     print(z <- hidden(y,dist="Poisson", cmu=~1, pcmu=c(1,5),
             pgamma=matrix(c(0.9,0.2,0.1,0.8),ncol=2)))
     # or equivalently
     mu <- function(p) array(rep(p[1:2],rep(2,2)), c(2,2))
     print(z <- hidden(y,dist="Poisson", cmu=mu, pcmu=c(1,5),
             pgamma=matrix(c(0.9,0.2,0.1,0.8),ncol=2)))
     # or
     print(z <- hidden(y,dist="Poisson", mu=~rep(a,40), pmu=c(1,5),
             pgamma=matrix(c(0.9,0.2,0.1,0.8),ncol=2)))
     par(mfrow=c(3,2))
     plot(z, nind=1:2)
     plot(z, nind=1:2, smooth=TRUE)
     plot(iprofile(z), lty=2)
     plot(mprofile(z), add=TRUE)
     plot(iprofile(z), nind=2, lty=2)
     plot(mprofile(z), nind=2, add=TRUE)

