seqHMM (version 1.1.0)

ssp: Define Arguments for Plotting Multichannel Sequences and/or Most Probable Paths from Hidden Markov Models

Description

Function ssp defines the arguments for plotting with plot.ssp or gridplot.

Usage

ssp(
  x,
  hidden.paths = NULL,
  plots = "obs",
  type = "d",
  tlim = 0,
  sortv = NULL,
  sort.channel = 1,
  dist.method = "OM",
  with.missing = FALSE,
  missing.color = NULL,
  title = NA,
  title.n = TRUE,
  cex.title = 1,
  title.pos = 1,
  with.legend = "auto",
  ncol.legend = "auto",
  with.missing.legend = "auto",
  legend.prop = 0.3,
  cex.legend = 1,
  hidden.states.colors = "auto",
  hidden.states.labels = "auto",
  xaxis = TRUE,
  xlab = NA,
  xtlab = NULL,
  xlab.pos = 1,
  ylab = "auto",
  hidden.states.title = "Hidden states",
  yaxis = FALSE,
  ylab.pos = "auto",
  cex.lab = 1,
  cex.axis = 1,
  withlegend,
  ...
)

Arguments

x

Either a hidden Markov model object of class hmm or a state sequence object of class stslist (created with the seqdef) function) or a list of state sequence objects.

hidden.paths

Output from hidden_paths function. Optional, if x is a hmm object or if type = "obs".

plots

What to plot. One of "obs" for observations (the default), "hidden.paths" for most probable paths of hidden states, or "both" for observations and hidden paths together.

type

The type of the plot. Available types are "I" for sequence index plots and "d" for state distribution plots (the default). See seqplot for details.

tlim

Indexes of the subjects to be plotted (the default is 0, i.e. all subjects are plotted). For example, tlim = 1:10 plots the first ten subjects in data.

sortv

A sorting variable or a sort method (one of "from.start", "from.end", "mds.obs", or "mds.hidden") for type = "I". The value "mds.hidden" is only available when hidden paths are available. Options "mds.obs" and "mds.hidden" automatically arrange the sequences according to the scores of multidimensional scaling (using cmdscale) for the observed data or hidden states paths. MDS scores are computed from distances/dissimilarities using a metric defined in argument dist.method. See plot.stslist for more details on "from.start" and "from.end".

sort.channel

The number of the channel according to which the "from.start" or "from.end" sorting is done. Sorting according to hidden states is called with value 0. The default value is 1 (the first channel).

dist.method

The metric to be used for computing the distances of the sequences if multidimensional scaling is used for sorting. One of "OM" (optimal matching, the default), "LCP" (longest common prefix), "RLCP" (reversed LCP, i.e. longest common suffix), "LCS" (longest common subsequence), "HAM" (Hamming distance), and "DHD" (dynamic Hamming distance). Transition rates are used for defining substitution costs if needed. See seqdef for more information on the metrics.

with.missing

Controls whether missing states are included in state distribution plots (type = "d"). The default is FALSE.

missing.color

Alternative color for representing missing values in the sequences. By default, this color is taken from the missing.color attribute of the sequence object.

title

Main title for the graphic. The default is NA: if title.n = TRUE, only the number of subjects is plotted. FALSE prints no title, even when title.n = TRUE.

title.n

Controls whether the number of subjects (in the first channel) is printed in the title of the plot. The default is TRUE: n is plotted if title is anything but FALSE.

cex.title

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

title.pos

Controls the position of the main title of the plot. The default value is 1. Values greater than 1 will place the title higher.

with.legend

Defines if and where the legend for the states is plotted. The default value "auto" (equivalent to TRUE and "right") creates separate legends for each requested plot and positiones them on the right-hand side of the plot. Other possible values are "bottom", "right.combined", and "bottom.combined", of which the last two create a combined legend in the selected position. FALSE prints no legend.

ncol.legend

(A vector of) the number of columns for the legend(s). The default "auto" determines number of columns depending on the position of the legend.

with.missing.legend

If set to "auto" (the default), a legend for the missing state is added automatically if one or more of the sequences in the data/channel contains missing states and type = "I". If type = "d" missing states are omitted from the legends unless with.missing = TRUE. With the value TRUE a legend for the missing state is added in any case; equivalently FALSE omits the legend for the missing state.

legend.prop

Sets the proportion of the graphic area used for plotting the legend when with.legend is not FALSE. The default value is 0.3. Takes values from 0 to 1.

cex.legend

Expansion factor for setting the size of the font for the 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.

hidden.states.colors

A vector of colors assigned to hidden states. The default value "auto" uses the colors assigned to the stslist object (created with seqdef) if hidden.paths is given; otherwise colors from colorpalette are automatically used.

hidden.states.labels

Labels for the hidden states. The default value "auto" uses the names provided in x$state_names if x is an hmm object; otherwise the number of the hidden state.

xaxis

Controls whether an x-axis is plotted below the plot at the bottom. The default value is TRUE.

xlab

An optional label for the x-axis. If set to NA, no label is drawn.

xtlab

Optional labels for the x-axis tick labels. If unspecified, the column names of the seqdata sequence object are used (see seqdef).

xlab.pos

Controls the position of the x-axis label. The default value is 1. Values greater than 1 will place the label further away from the plot.

ylab

Labels for the channels shown as labels for y-axes. A vector of names for each channel (observations). The default value "auto" uses the names provided in x$channel_names if x is an hmm object; otherwise the names of the list in x if given, or the number of the channel if names are not given. FALSE prints no labels.

hidden.states.title

Optional label for the hidden state plot (in the y-axis). The default is "Hidden states".

yaxis

Controls whether or not to plot the y-axis. The default is FALSE.

ylab.pos

Controls the position of the y axis labels (labels for channels and/or hidden states). Either "auto" or a numerical vector indicating how far away from the plots the titles are positioned. The default value "auto" positions all titles on line 1. Shorter vectors are recycled.

cex.lab

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

cex.axis

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

withlegend

Deprecated. Use with.legend instead.

...

Other arguments to be passed on to seqplot.

Value

Object of class ssp.

See Also

plot.ssp for plotting objects created with the ssp function; gridplot for plotting multiple ssp objects; build_hmm and fit_model for building and fitting hidden Markov models; hidden_paths for computing the most probable paths of hidden states; and biofam3c and hmm_biofam for information on the data and model used in the example.

Examples

# NOT RUN {
data("biofam3c")

## Building sequence objects
child_seq <- seqdef(biofam3c$children, start = 15)
marr_seq <- seqdef(biofam3c$married, start = 15)
left_seq <- seqdef(biofam3c$left, start = 15)

## Choosing colors
attr(child_seq, "cpal") <- c("#66C2A5", "#FC8D62")
attr(marr_seq, "cpal") <- c("#AB82FF", "#E6AB02", "#E7298A")
attr(left_seq, "cpal") <- c("#A6CEE3", "#E31A1C")


# Defining the plot for state distribution plots of observations
ssp1 <- ssp(list("Parenthood" = child_seq, "Marriage" = marr_seq,
                 "Residence" = left_seq))
# Plotting ssp1
plot(ssp1)

# }
# NOT RUN {
# Defining the plot for sequence index plots of observations
ssp2 <- ssp(
  list(child_seq, marr_seq, left_seq), type = "I", plots = "obs",
  # Sorting subjects according to the beginning of the 2nd channel (marr_seq)
  sortv = "from.start", sort.channel = 2,
  # Controlling the size, positions, and names for channel labels
  ylab.pos = c(1, 2, 1), cex.lab = 1, ylab = c("Children", "Married", "Residence"),
  # Plotting without legend
  with.legend = FALSE)
plot(ssp2)

# Plotting hidden Markov models

# Loading data
data("hmm_biofam")

# Plotting observations and most probable hidden states paths
ssp3 <- ssp(
  hmm_biofam, type = "I", plots = "both",
  # Sorting according to multidimensional scaling of hidden states paths
  sortv = "mds.hidden",
  # Controlling title
  title = "Biofam", cex.title = 1.5,
  # Labels for x axis and tick marks
  xtlab = 15:30, xlab = "Age")
plot(ssp3)

# Computing the most probable paths of hidden states
hid <- hidden_paths(hmm_biofam)
# Giving names for hidden states
library(TraMineR)
alphabet(hid) <- paste("Hidden state", 1:5)

# Plotting observations and hidden state paths
ssp4 <- ssp(
  hmm_biofam, type = "I", plots = "hidden.paths",
  # Sequence object of most probable paths
  hidden.paths = hid,
  # Sorting according to the end of hidden state paths
  sortv = "from.end", sort.channel = 0,
  # Contolling legend position, type, and proportion
  with.legend = "bottom.combined", legend.prop = 0.15,
  # Plotting without title and y label
  title = FALSE, ylab = FALSE)
plot(ssp4)
# }