hglmm {hglmm}R Documentation

Fit hidden generalised linear Markov models.

Description

Fits a log linear Poisson model to a data set where the response in each “cell” of the model consists of a time series of Poisson counts whose serial dependence is modelled by a hidden Markov model.

Usage

  hglmm(formula, data, cells=NULL, K = NULL, par0 = NULL, method =
  "lm", lmc = 10, expo = TRUE, mixture = FALSE, tolerance = NULL,
  overpar=FALSE, digits = NULL, verbose = FALSE, itmax = 200,
  data.name = NULL, contr = c("treatment", "sum", "helmert"),
  crit = NULL, breaks = NULL, use.anal=FALSE, ca = FALSE)

Arguments

formula

A model formula specifying the linear predictor for the log linear model. The formula should not include state as a predictor variable. The variable state gets added to the formula automatically.

data

A data frame with columns specifying the response and the predictor varibles in the model.

cells

A character vector giving the names of the factors (columns of the data data frame) which determine what the “cells” of the model are considered to be. The cells correspond to the combinations of levels of the factors named by cells.

K

The number of states of the hidden Markov model. If K is not specified and par0 (see below) is specified and has a component tpm then K is set equal to nrow(tpm). An error is given in this setting if K is specified to a value different from nrow(tpm).

par0

A list comprising initial parameter estimates. It may have components tpm (an estimate of the transition probability matrix) and phi (a vector of estimates of the coefficients in the linear predictor in the log linear model).

method

The method used to fit the model; it may be “lm” (Levenberg-Marquardt algorithm, the default), “sw” (start with the EM algorithm and then swap to Levenberg-Marquardt), “em” (EM algorithm), “bf” (“brute force”; calls upon optim() to do the heavy lifting) or “nl” (use function nlm(), non-linear minimization).

lmc

The initial “Levenberg-Marquardt constant”.

expo

Logical variable; if TRUE then the transition probabilities of the chain are parameterized in an exponential form. It is ignored (with a warning if it has been set to FALSE) unless the method used is “em”.

mixture

Logical scalar; if TRUE then a mixture model (rather than a general hidden Markov model) is fitted. Currently mixture models can only be fitted using the EM algorithm (method = “em”.

tolerance

The convergence tolerance to be used. If not supplied defaults to sqrt(.Machine$double.eps).

overpar

Logical scalar. Should the overparameterized form of the model be returned?

digits

The number of digits to which “progress reports” are printed when verbose is TRUE. Not used if method is bf or nl.

verbose

Logical scalar; if TRUE progress reports are printed out at appropriate points in the iteration.

itmax

The maximum number of iterative steps to take. For methods “em” and “lm”, if convergence is not achieved by itmax steps, the function gives up, prints a message to this effect, and returns a value with a component converged=FALSE. Has a slightly different meaning for methods “bf” and “nl”.

data.name

A name to identify the data set to which the model was fitted. If not supplied it is taken from the data argument using deparse(substitute(data)).

contr

A text string specifying the contrasts (in respect of unordered factors) to use when producing the design matrix from the model formula. Possible values "helmert", "sum", "treatment". Defaults to "treatment". Partial matching is used, so abbreviation is permitted.

crit

A text string specifying the stopping criterion to be used. Possible values are “CLL” (scaled change in log likelihood), “L2” (scaled square root of sum of squares of the changes in the parameter estimates), “Linf” (scaled maximum of the absolute value of the changes in the parameter estimates), and “ABSGRD” (the sum of the absolute values of the entries of the gradient vector). The latter only makes sense for the Levenberg-Marquardt algorithm. The bf method can only use “CLL”; the nl method seems to use a combination of “ABSGRD” and “CLL”.

breaks

A vector of K+1 values used to construct a set of guesses at the states corresponding to each observation. These are in turn used to calculate an initial estimate of the transition probability matrix.

use.anal

Logical scalar; should “analyticals” gradient and hessian be used? This argument has effect only when the method is “nl”.

ca

Logical scalar; “check analyticals”; used when the method is “nl”, and passed on to nlm().

Value

A list with components:

params

Another list providing the estimates of the parameters of the model. It has components tpm (the estimated transition probability matrix), ispd (the estimated initial state probability distribution), phi (the vector of estimated coefficients of the linear predictor in the log linear model), and phi.over. This last consists of the coefficients of the linear predictor in their redundant form corresponding to the overparameterized expression of the model if overpar is TRUE, otherwise it is NULL.

theta

The vector of parameter estimates that the estimation procedure actually works with, consisting of the catenation of the non-redundant parameterization of the transition probability matrix and the vector phi.

hessian

(Not present for the “em” method.) The hessian matrix, i.e. the matrix of second partial derivatives of the log likelihood, evaluated at the final parameter estimates. The inverse of the negative of this matrix constitutes an estimate of the covariance matrix of the parameter estimates.

grad

(Not present for the “em” method.) The gradient of the log likelihood at the final parameter estimates; it should be effectively the zero vector.

log.like

The value of the log likelihood of the model evaluated at the parameter estimates, i.e. the (approximately) maximal value of the log likelihood.

converged

A logical scalar. For the “lm”, “swp” and “em” methods it is TRUE if convergence is achieved within itmax iterations and FALSE otherwise. For the “bf” method converged is TRUE if the convergence component of the object returned by optim(). is equal to 0 and FALSE otherwise. For the “nl” method converged is TRUE if the code component of the object returned by nlm() is less than or equal to 2.

nstep

(Not present for the “bf” method.) The number of steps (iterations) actually used by the algorithm. For the “nl” method, it is the iterations component of the object returned by nlm().

counts

Replaces nstep for the “bf” method. It is the counts component of the object returned by optim().

mixture

A logical scalar. Was a mixture model fitted?

expo

A logical scalar. Was the exponetial (logistic) parameterization used for the entries of the transition probability matrix?

formula

The formula for the model that was fitted; equal to the formula argument, augmented by state.

contrasts

The contrasts used in fitting the model.

miss.frac

The fraction or proportion of missing values in the observations.

lambda

A vector of estimated values of the Poisson parameter associated with each combination of observation and state.

fy

The Poisson probability of each observed value, for each state, calculated using the fitted parameters.

data

The data frame used to fit the model. Constructed from the data argument supplied to this function by replicating the rows once for each state and adding a state column. A column cf (“cell factor”) has also been added. This column indicates, by means of a single factor, which cell of the model a given row of data corresponds to.

data.name

The name of the data set to which the model was fitted. Equal to the data.name argument or its default value.

method

The method (“lm”, “sw”, “em”, “bf” or “nl”) used to fit the model. Equal to the method argument or its default value.

tolerance

The convergence tolerance used to fit the model. Equal to the tolerance argument or its default value.

cells

A character vector indicating the names of the factors specifying the “cells” of the model. (Equal to the cells argument.)

Author(s)

Rolf Turner r.turner@auckland.ac.nz

References

T. Rolf Turner, Murray A. Cameron, and Peter J. Thomson. Hidden Markov chains in generalized linear models. Canadian J. Statist., vol. 26, pp. 107 – 125, 1998.

Rolf Turner. Direct maximization of the likelihood of a hidden Markov model. Submitted for publication, 2007.

See Also

fitted.hglmm() rhglmm.default() rhglmm.hglmm() bcov()

Examples

    loc4 <- c("LngRf","BondiE","BondiOff","MlbrOff")
    SCC4 <- SydColCount[SydColCount$locn %in% loc4,] 
    SCC4$locn <- factor(SCC4$locn) # Get rid of unused levels.
    rownames(SCC4) <- 1:nrow(SCC4)
    fit.lm <- hglmm(y~locn+depth,SCC4,c("locn","depth"),K=2,
                    verb=TRUE)
    fit.em <- hglmm(y~locn+depth,SCC4,c("locn","depth"),K=2,
                    method="em",verb=TRUE)

[Package hglmm version 0.0-14 Index]