MmgraphR (version 0.3-1)

trmatplot: Transition Matrix Plot

Description

A parallel coordinate plot which maps each element in the probability transition matrix (of any order) as a line, where each line is weighted by probability. Users can apply filters to emphasize the most (or least) probable state sequences overall, or by initial state. Various color palettes using the Hue-Chroma-Luminance color scheme can be easily selected by the user. Input is either an object of class matrix, array, depmix.fitted, or a list of class msm, hmm or of class dthmm.

Usage

## S3 method for classes 'matrix', 'array', 
## 'depmix.fitted', 'dthmm', 'hmm', and 'msm'
trmatplot ( d, seed = NULL, rowconstraint = TRUE, morder = 1,
cspal = NULL, cpal = NULL, main = NULL, 
xlab = NULL, ylab = NULL, ylim = NULL, xtlab = NULL, ytlab = NULL,
pfilter = NULL, shade.col = "grey80", num = NULL, 
hide.col = NULL, lorder = NULL, plot = TRUE, 
verbose = FALSE, ...)

Arguments

d

Object to be plotted. A transition matrix of probabilities. Can be of any order. An object of class matrix, array, depmix.fitted, dthmm, hmm, or msm. See Details.

seed

A single value, interpreted as an integer, or NULL (default). See Details.

rowconstraint

Logical. Checks if the row constraint is satisfied, i.e. the sum of each row of the transition probability matrix equals one. Default is TRUE.

morder

Numeric. The order of the probability transition matrix, d, to be plotted. Default is 1. See Details.

cspal

A color palette that can be specified as one of: "dynamic", "harmonic", "cold", "warm", "heat", or "terrain". The rainbow_hcl, heat_hcl, and terrain_hcl commands are used to generate color palettes. The rainbow_hcl command is used to generate a color palette if none is specified.

cpal

Color palette vector when coloring probability sequences. Cannot specify both cspal and cpal.

main

Title for the graphic. Default is Probability Transition Matrix.

xlab

Label for the x axis. Default is Time.

ylab

Label for the y axis. Default is States.

ylim

Numeric vector of length 2 giving the y coordinates range.

xtlab

Labels for the x axis ticks. Default is time (t, t+1,...).

ytlab

Labels for the y axis ticks.

pfilter

Probability filter. Can be specified as one of "tmax", "tmin", "smax", "smin". See Details.

shade.col

The color for sequences shaded out using the pfilter argument. Default is "grey80". See Details.

num

Numeric. The number of sequences to be highlighted, a whole number from 1 to length(d) - 1. Must be specified only when using pfilter="tmax" or pfilter="tmin". Default is NULL.

hide.col

The color for sequences shaded out using the filter argument. Default is "grey80". See Details.

lorder

Line order. Either "background" or "foreground". When pfilter is used lorder is set by default.

plot

Logical. Should the object be plotted. Default is TRUE.

verbose

Logical. Reports extra information on progress. Default is FALSE.

...

Additional arguments, such as graphical parameters, to be passed on. See par and seqpcplot.

Value

trmatplot returns an object of class trmatplot. Some of the arguments are inherent in par and seqpcplot.

Details

The object d to be plotted, is a probability transition matrix that can be of class matrix, array, depmix.fitted, dthmm, hmm, msm. If the probability transition matrix is the output of packages implemented using S3 methods and classes, such as msm, HiddenMarkov, HMM, or seqHMM it is a matrix which is element of a list. More specifically, using the package HMM, the function initHMM returns a list containing the element transProbs with the probability transition matrix. Within the HiddenMarkov, dthmm returns a list of class dthmm with the element Pi which is a probability transition matrix, either user-defined or estimated. Similarly, the seqHMM functions build_mm and build_hmm return a list of class hmm containing the element transition_probs with the estimated probability transition matrix. The package msm proposes the pmatrix.msm and pmatrix.piecewise.msm to extract the probability transition matrix from a fitted multi-state model (a list of class msm), as returned by msm. If the object d to be plotted is an object of msm, the function pmatrix.msm is used with the default settings to extract the probability transition matrix. In the case of depmixS4, which uses S4 classes, a probability transition matrix may be obtained depending on the type of model computed using depmix followed by fit and is embedded in an object of class depmix.fitted.

Setting a seed allows the graphic to be replicated.

If morder > 1, in other words, the order of the probability transition matrix d is of order greater than one, then d must be specified in reduced form. Structural zeroes are not accepted.

The pfilter argument serves to highlight probability sequences that are either most probable while shading out those that are less probable in shade.col and vice-versa. The four options for pfilter are described below, and are illustrated in Examples.

"smax"

For each initial state the most probable next state is highlighed.

"smin"

For each initial state the least probable next state is highlighed.

"tmax"

The sequence of states with the highest probability overall is highlighed. To highlight the n most probable sequences of states, set num = n.

"tmin"

The sequence of states with the lowest probability overall is highlighed. To highlight the n least probable sequences of states, set num = n.

The filter and hide.col arguments are inherent in and may be passed on to seqpcplot. The filter argument serves to specify filters to gray less interesting patterns. The filtered-out patterns are displayed in the hide.col color. The filter argument expects a list with at least elements type and value. Most relevant within the context of probabilities is type = "sequence", which highlights the specific pattern. See Examples.

References

Buergin, R. and G. Ritschard (2014), "A decorated parallel coordinate plot for categorical longitudinal data", The American Statistician. Vol. 68(2), pp. 98-103.

Zeileis, A.; Hornik, K. and P. Murrell (2009), "Escaping RGBland: Selecting Colors for Statistical Graphics", Computational Statistics & Data Analysis. Vol. 53, pp. 3259-3270.

See Also

seqpcplot, par.

Examples

# NOT RUN {
##########################################
# Plotting a probability transition matrix
##########################################

trMat<-matrix(c(0.1, 0.05, 0.05, 0.80,
  0.06, 0.02, 0.03, 0.89,
  0.03, 0.01, 0.01, 0.95,
  0, 0, 0, 1), nrow = 4, ncol = 4, byrow = TRUE)

trmatplot(trMat)

#--- Setting a seed so that the graphic can be replicated

trmatplot(trMat, seed = 2)

#--- Adjusting line width

trmatplot(trMat, seed = 2, lwd = 0.8)

#--- Defining a second order probability transition matrix as an array

trMatArray <- array(c(
  0.30, 0.70,
  0.65, 0.35, 
  0.05, 0.95,
  0.99, 0.01), dim = c(1, 2, 4))

#--- Plotting with user-defined colors

trmatplot(trMatArray, seed = 3, morder = 2, cpal = c("grey40", "grey70"))

###########################################################
# cspal: ready-to-use color palettes using colorspace
###########################################################

#--- Color palette "dynamic"

trmatplot(trMat, seed = 2, cspal = "dynamic")

#--- Color palette "harmonic"

trmatplot(trMat, seed = 2, cspal = "harmonic")

#--- Color palette "cold"

trmatplot(trMat, seed = 2, cspal = "cold")

#--- Color palette "warm"

trmatplot(trMat, seed = 2, cspal = "warm")

#--- Color palette "heat"

trmatplot(trMat, seed = 2, cspal = "heat")

#--- Color palette "terrain"

trmatplot(trMat, seed = 2, cspal = "terrain")

###########################################################
# pfilter: Filtering out most (or least) probable sequences
###########################################################

#--- The most probable sequence given a state

trmatplot(trMat, seed = 2, pfilter = "smax")

#--- The least probable sequence given a state

trmatplot(trMat, seed = 2, pfilter = "smin")

#--- The two most probable sequnces

trmatplot(trMat, seed = 2, pfilter = "tmax", num = 2 )

#--- The ten least probable sequences

trmatplot(trMat, seed = 2, pfilter = "tmin", num = 10 )

######################################################
# filter: Highlighting a specific sequence of interest
######################################################

#--- Highlight the probability that a sequence is initially in state 1 and then in state 4

trmatplot(trMat, seed = 2, filter = list(type = "sequence", value = "(1)-(4)"))
# }