seqplotMD: Plot multidomain state sequences

Description

Plot function to render multidomain state sequences by domain and group. The function takes care to make the plots comparable across domains.

Usage

seqplotMD(channels, 
  group = NULL, 
  type = "i", 
  main = NULL, 
  cpal.dom = NULL, 
  missing.color = NULL, 
  ylab = NULL, 
  yaxis = "all", 
  xaxis = "all", 
  xtlab = NULL, 
  stats = "all", 
  cex.axis = 1, 
  with.legend = "auto", 
  ltext.dom = NULL, 
  cex.legend = 1, 
  legend.prop = ifelse(dom.byrow,.25,.15),
  dom.byrow = FALSE, 
  dom.crit = 0, 
  dnames=names(channels), 
  ...)

Arguments

channels: List of paired domain state sequence objects.
group: Grouping variable of length equal to the number of multidomain sequences. When not NULL, a distinct plot is generated for each level of group.
type: the type of the plot. Available types are "d" for state distribution plots (chronograms), "dH" for chronograms with overlayed entropy line, "f" for sequence frequency plots, "Ht" for transversal entropy plots, "i" for index plots of selected sequences, "I" for index plots of the whole set of sequences, "ms" for plotting the sequence of modal states, "mt" for mean times plots, "pc" for parallel coordinate plots, "r" for representative sequence plots, and "rf" for relative frequency plots.
main: Character string. Title of the graphic. Default is NULL.
cpal.dom: List. List of color palettes for the states of each domain. By default, the cpal attribute of each element of the list channels is used (see seqdef). If user specified, each element of the list should be a vector of colors of length of the alphabet of the corresponding element of channels.
missing.color: Color for representing missing values inside the sequences. By default, this color is taken for each domain from the missing.color attribute of the corresponding element of channels.
ylab: Character string or vector of strings. Optional label of the y-axis. If a vector, y-axis label of each group level. If set as NA, no label is drawn.
yaxis: Logical or one of "all" or "left". If set as TRUE or "all" (default value), sequence indexes are displayed for "i" and "I", mean time values for "mt", percentages for "d" and "f", and state/event labels for "pc". If "left" and group is used, the y-axis is displayed on plots of the left panel only. If FALSE no y-axis is drawn. Ignored when type="r". For type="f", can also be one of "pct" and "left.pct"
xaxis: Logical or one of "all" or "bottom". If set as TRUE or "all" (default value) x-axes are drawn for each plot in the graphic. If set as "bottom" is used, axes are drawn under the plots of the bottom panel only. If FALSE, no x-axis is drawn.
xtlab: Vector of length equal to the maximal length of the sequences. Optional labels of the x-axis tick labels. If unspecified, column names of the elements of channels are used (see seqdef).
stats: Logical or one of "all" or "first". When type="r", if "all" (default), stats of the MD representatives are displayed on all plots and if "first", MD stats are displayed only on the plot of the first domain. Ignored for all non-"r" types.
cex.axis: Real value. Axis annotation magnification. When type = "r" and for seqrplot(), it also determines the magnification of the plotted text and symbols. See par.
with.legend: Character string or logical. Should legends of the state colors be plotted? Default value "auto" sets the position of the legend automatically. Value TRUE is equivalent to "auto".
ltext.dom: List. List of vector of character strings of length and order corresponding to the alphabet of the corresponding elements of channels. Optional description of the states to appear in the legend. If unspecified, the label attribute of the corresponding sequence object in channels is used (see seqdef).
cex.legend: Real. Legend magnification. See legend.
legend.prop: Real in range [0,1]. Proportion of the graphic area devoted to the legends when with.legend=TRUE. Default value used depends of dom.byrow.
dom.byrow: Logical. Should domains be displayed by row?
dom.crit: Integer in range [-2,ndom] where ndom is number of domains. Applies when sortv is provided among the ... arguments and is one of "from.start" or "from.end". Domain on which sorting is done. When 0 (default), sorting is done on multidomain sequences, when -1, sorting is done on first domain then, for ties, successively on the next domains, when -2, sorting is done across domains at each successive position. Does not apply when sortv="mds" for "rf" plots.
dnames: String vector. Names of the domains.
...: arguments to be passed to the function called to produce the appropriate statistics and the associated plot method (see details), or other graphical parameters. For example, the weighted argument can be passed to control whether (un)weighted statistics are produced, and with.missing=TRUE to take missing values into account when computing cross-sectional or longitudinal state distributions. Can also include arguments of legend such as bty="n" to suppress the box surrounding the legend.

Author

Gilbert Ritschard

Details

The seqplotMD function is intended for multidomain (or multichannel) sequences, i.e. situations where each case is represented by a sequence in each of several domains. The elements (set of state sequences) of the channels list are assumed to be paired. Sequences defined in terms of the expanded alphabet formed by the combination of the domain states are called MD sequences. Although the MD sequences (which can be obtained with seqMD) may be used for some computations, seqplotMD does not plot the MD sequences themselves, but the corresponding domain sequences.

For details on the types of plot, see seqplot.

The function organizes the plot area with either domains in rows, groups in columns, and domain legend on the right of each row, or conversely when dom.byrow=FALSE. Panel titles are defined as "group level: domain", and are preceded by main when a main value is provided.

The function takes the matching constraints into account as follows:

- For index plots ("i", "I"), sequences are displayed in same order for each domain. When a sortv vector is provided among the ... list, this same sort order is applied to all domains. If a sortv method is provided, the sorting is computed on the domain specified by the dom.crit argument. When there is a which.plot argument (for type="rf") in the ... list, it cannot be "both".

- Likewise, for relative frequency plots ("rf") the same order is retained for all domains. The sortv argument is handled as for "i" and "I", except for sortv="mds", in which case the sorting is done using the provided diss matrix.

- For frequency plots ("f"), sequences displayed correspond to the most frequent MD sequences.

- For plots of representative sequences ("r"), the representatives are computed for the provided diss matrix (generally the distances between the MD sequences) and their representation in each domain are displayed. Likewise, for type="rf", the medoids of the equally sized groups are computed using the required diss matrix.

- When type="mt", mean time plot, and there is a bar.labels argument among the ... list, bar.labels should be a list of vector or matrices of bar labels by domain.

No special handling other than the domain-group titles and the organization of the plot panels is applied to other types ("d","dH","Ht","ms","pc").

References

Ritschard, G., T.F. Liao, and E. Struffolino (2023). Strategies for multidomain sequence analysis in social research. Sociological Methodology, 53(2), 288-322. tools:::Rd_expr_doi("10.1177/00811750231163833").

Examples

Run this code

data(biofam)

## Building one channel per type of event (left, children or married)
cases <- 200
bf <- as.matrix(biofam[1:cases, 10:25])
children <-  bf==4 | bf==5 | bf==6
married <- bf == 2 | bf== 3 | bf==6
left <- bf==1 | bf==3 | bf==5 | bf==6

## Building sequence objects
require(colorspace)
m.col <- sequential_hcl(2, palette = "PurpOr")
c.col <- sequential_hcl(2, palette = "Mint")
l.col <- sequential_hcl(2, palette = "OrYel")

child.seq <- seqdef(children, weights=biofam[1:cases,"wp00tbgs"], cpal=c.col)
marr.seq <- seqdef(married, weights=biofam[1:cases,"wp00tbgs"], cpal=m.col)
left.seq <- seqdef(left, weights=biofam[1:cases,"wp00tbgs"], cpal=l.col)
seqdom <- list(LeftHome=left.seq,Marr=marr.seq,Child=child.seq)


seqplotMD(seqdom, type="d", group=biofam[1:cases,"sex"], xaxis="bottom")

seqplotMD(seqdom, type="dH", group=biofam[1:cases,"sex"], dom.byrow=TRUE, 
    xaxis="bottom", yaxis="left")

seqplotMD(seqdom, type="mt", group=biofam[1:cases,"sex"])

seqplotMD(seqdom, type="I", group=biofam[1:cases,"sex"],  
    xaxis="bottom", sortv="from.end")

## sorting on first domain
seqplotMD(seqdom, type="I", group=biofam[1:cases,"sex"],  
    xaxis="bottom", sortv="from.start", dom.crit=1)

seqplotMD(seqdom, type="f", group=biofam[1:cases,"sex"],   
    xaxis="bottom", yaxis="left")

## distances betweem MD sequences
MDseq <- seqMD(seqdom, what="MDseq", ch.sep="+")
diss <- seqdist(MDseq, method="OM", sm="INDELSLOG")

seqplotMD(seqdom, type="rf", group=biofam[1:cases,"sex"],  
    xaxis="bottom", sortv="from.end", dom.crit=0, diss=diss, k=10)

seqplotMD(seqdom, type="r", group=biofam[1:cases,"sex"],  
    xaxis="bottom", dom.crit=0, diss=diss)

Run the code above in your browser using DataLab