plot.mhmm {seqHMM}

Interactive Plotting for Mixed Hidden Markov Model (mhmm)

Description

Function plot.mhmm plots a directed graph of the parameters of each model with pie charts of emission probabilities as vertices/nodes.

Usage

## S3 method for class 'mhmm'
plot(
  x,
  interactive = TRUE,
  ask = FALSE,
  which.plots = NULL,
  nrow = NA,
  ncol = NA,
  byrow = FALSE,
  row.prop = "auto",
  col.prop = "auto",
  layout = "horizontal",
  pie = TRUE,
  vertex.size = 40,
  vertex.label = "initial.probs",
  vertex.label.dist = "auto",
  vertex.label.pos = "bottom",
  vertex.label.family = "sans",
  loops = FALSE,
  edge.curved = TRUE,
  edge.label = "auto",
  edge.width = "auto",
  cex.edge.width = 1,
  edge.arrow.size = 1.5,
  edge.label.family = "sans",
  label.signif = 2,
  label.scientific = FALSE,
  label.max.length = 6,
  trim = 1e-15,
  combine.slices = 0.05,
  combined.slice.color = "white",
  combined.slice.label = "others",
  with.legend = "bottom",
  ltext = NULL,
  legend.prop = 0.5,
  cex.legend = 1,
  ncol.legend = "auto",
  cpal = "auto",
  main = "auto",
  withlegend,
  ...
)

Arguments

x

A hidden Markov model object of class mhmm created with build_mhmm (or build_mmm or build_lcm). Multichannel mhmm objects are automatically transformed into single-channel objects. See function mc_to_sc for more information on the transformation.

interactive

Whether to plot each cluster in succession or in a grid. Defaults to TRUE, i.e. clusters are plotted one after another.

ask

If TRUE and which.plots is NULL, plot.mhmm operates in interactive mode, via menu. Defaults to FALSE. Ignored if interactive = FALSE.

which.plots

The number(s) of the requested cluster(s) as an integer vector. The default NULL produces all plots.

nrow, ncol

Optional arguments to arrange plots in a grid. Ignored if interactive = TRUE.

byrow

Controls the order of plotting in a grid. Defaults to FALSE, i.e. plots are arranged column-wise. Ignored if interactive = TRUE.

row.prop

Sets the proportions of the row heights of the grid. The default value is "auto" for even row heights. Takes a vector of values from 0 to 1, with values summing to 1. Ignored if interactive = TRUE.

col.prop

Sets the proportion of the column heights of the grid. The default value is "auto" for even column widths. Takes a vector of values from 0 to 1, with values summing to 1. Ignored if interactive = TRUE.

layout

specifies the layout of vertices (nodes). Accepts a numerical matrix, a layout_ function (without quotation marks), or either of the predefined options "horizontal" (the default) and "vertical". Options "horizontal" and "vertical" position vertices at the same horizontal or vertical line. A two-column numerical matrix can be used to give x and y coordinates of the vertices. The layout_ functions available in the igraph package offer other automatic layouts for graphs.

pie

Are vertices plotted as pie charts of emission probabilities? Defaults to TRUE.

vertex.size

Size of vertices, given as a scalar or numerical vector. The default value is 40.

vertex.label

Labels for vertices. Possible options include "initial.probs", "names", NA, and a character or numerical vector. The default "initial.probs" prints the initial probabilities of the model and "names" prints the names of the hidden states as labels. NA prints no labels.

vertex.label.dist

Distance of the label of the vertex from its center. The default value "auto" places the label outside the vertex.

vertex.label.pos

Positions of vertex labels, relative to the center of the vertex. A scalar or numerical vector giving position(s) as radians or one of "bottom" (pi/2 as radians), "top" (-pi/2), "left" (pi), or "right" (0).

vertex.label.family, edge.label.family

Font family to be used for vertex/edge labels. See argument family in par for more information.

loops

Defines whether transitions back to same states are plotted.

edge.curved

Defines whether to plot curved edges (arcs, arrows) between vertices. A logical or numerical vector or scalar. Numerical values specify curvatures of edges. The default value TRUE gives curvature of 0.5 to all edges. See igraph.plotting for more information.

edge.label

Labels for edges. Possible options include "auto", NA, and a character or numerical vector. The default "auto" prints transition probabilities as edge labels. NA prints no labels.

edge.width

Width(s) for edges. The default "auto" determines widths according to transition probabilities between hidden states. Other possibilities are a scalar or a numerical vector of widths.

cex.edge.width

An expansion factor for edge widths. Defaults to 1.

edge.arrow.size

Size of the arrow in edges (constant). Defaults to 1.5.

label.signif

Rounds labels of model parameters to specified number of significant digits, 2 by default. Ignored for user-given labels.

label.scientific

Defines if scientific notation should be used to describe small numbers. Defaults to FALSE, e.g. 0.0001 instead of 1e-04. Ignored for user-given labels.

label.max.length

Maximum number of digits in labels of model parameters. Ignored for user-given labels.

trim

Scalar between 0 and 1 giving the highest probability of transitions that are plotted as edges, defaults to 1e-15.

combine.slices

Scalar between 0 and 1 giving the highest probability of emission probabilities that are combined into one state. The dafault value is 0.05.

combined.slice.color

Color of the combined slice that includes the smallest emission probabilities (only if argument "combine.slices" is greater than 0). The default color is white.

combined.slice.label

The label for combined states (when argument "combine.slices" is greater than 0) to appear in the legend.

with.legend

Defines if and where the legend of state colors is plotted. Possible values include "bottom" (the default), "top", "left", and "right". FALSE omits the legend.

ltext

Optional description of (combined) observed states to appear in the legend. A vector of character strings. See seqplot for more information.

legend.prop

Proportion used for plotting the legend. A scalar between 0 and 1, defaults to 0.5.

cex.legend

Expansion factor for setting the size of the font for labels in the legend. The default value is 1. Values lesser than 1 will reduce the size of the font, values greater than 1 will increase the size.

ncol.legend

The number of columns for the legend. The default value "auto" sets the number of columns automatically.

cpal

Optional color palette for (combinations of) observed states. The default value "auto" uses automatic color palette. Otherwise a vector of length x$n_symbols is given, i.e. the argument requires a color specified for all (combinations of) observed states even if they are not plotted (if the probability is less than combine.slices).

main

Optional main titles for plots. The default "auto" uses cluster_names as titles, NULL prints no titles.

withlegend

Deprecated. Use with.legend instead.

...

Other parameters passed on to plot.igraph such as vertex.color, vertex.label.cex, or edge.lty.

References

Helske S. and Helske J. (2019). Mixture Hidden Markov Models for Sequence Data: The seqHMM Package in R, Journal of Statistical Software, 88(3), 1-32. doi:10.18637/jss.v088.i03

See Also

build_mhmm and fit_model for building and fitting mixture hidden Markov models; plot.igraph for plotting directed graphs; and mhmm_biofam and mhmm_mvad for the models used in examples.

Examples

# Loading mixture hidden Markov model (mhmm object)
# of the biofam data
data("mhmm_biofam")

# Plotting only the first cluster
plot(mhmm_biofam, which.plots = 1)

if (interactive()) {
  # Plotting each cluster (change with Enter)
  plot(mhmm_biofam)

  # Choosing the cluster (one at a time)
  plot(mhmm_biofam, ask = TRUE)

  # Loading MHMM of the mvad data
  data("mhmm_mvad")

  # Plotting models in the same graph (in a grid)
  # Note: the plotting window must be high enough!
  set.seed(123)
  plot(mhmm_mvad,
    interactive = FALSE,
    # automatic layout, legend on the right-hand side
    layout = layout_nicely, with.legend = "right",
    # Smaller and less curved edges
    edge.curved = 0.2, cex.edge.width = 0.5, edge.arrow.size = 0.7,
    vertex.label.pos = -4 * pi / 5, vertex.label.dist = 5
  )
}