seqsplot: Plot survival curves of the states in sequences

Description

High level plot function for state sequence objects that produces survival curves of states in sequences. Usage is similar to the generic seqplot function of TraMineR, with a special handling of the group argument when per.state=TRUE is included in the ... list.

Usage

seqsplot(seqdata, group = NULL, main = "auto",
  cpal = NULL, missing.color = NULL,
  ylab = NULL, yaxis = "all",
  xaxis = "all", xtlab = NULL,
  cex.axis = 1, with.legend = "auto", ltext = NULL, cex.legend = 1,
  use.layout = (!is.null(group) | with.legend != FALSE), legend.prop = NA,
  rows = NA, cols = NA, which.states = NULL,
  title, cex.plot, withlegend, axes, ...)

Arguments

seqdata: State sequence object created with the seqdef function.
group: Grouping variable of length equal to the number of sequences. When per.state = FALSE (default), a distinct plot is generated for each level of group. When per.state = TRUE, the curves for each group level are drawn in a same plot for each distinct value of alphabet(seqdata).
main: Character string. Title for the graphic. Default is "auto", i.e., group levels or, when per.state=TRUE, the state labels. If a single string, the string is pasted with the group or state label. Set as NULL to suppress titles. Can also be a vector.
cpal: Vector. Color palette used for the states or the groups when per.state=TRUE is given along the ... list. Default is NULL, in which case the cpal attribute of the seqdata sequence object is used (see seqdef) or the default colors assigned to groups when type="s" and per.state=TRUE. If user specified, a vector of colors of length and order corresponding to alphabet(seqdata) or, if for groups, the number of levels of the group variable.
missing.color: Color for representing missing values inside the sequences. By default, this color is taken from the missing.color attribute of seqdata.
ylab: Character string or vector of strings. Optional label of the y-axis. If a vector, y-axis label of each group (or state) level. If set as NA, no label is drawn.
yaxis: Logical or one of "all" or "left". If set as TRUE or "all" (default), the y-axis is displayed on all plots. In case of multiple plots (when per.state=TRUE or group is used), if set as "left", the y-axis is only displayed on plots of the left panel. If FALSE no y-axis is drawn.
xaxis: Logical or one of "all" or "bottom". If set as TRUE or "all" (default value) the x-axis is drawn on each plot in the graphic. In case of multiple plots (when per.state=TRUE or group is used), if set as "bottom", the x-axis is drawn only under the plots of the bottom panel. If FALSE, no x-axis is drawn.
xtlab: Vector of length equal to the number of columns of seqdata. Optional labels for the x-axis tick labels. If unspecified, the column names of the seqdata sequence object are used (see seqdef).
cex.axis: Real. Axis annotation magnification. See par.
with.legend: Character string or logical. Defines if and where the legend of the state colors is plotted. The default value "auto" sets the position of the legend automatically. Other possible value is "right". Obsolete value TRUE is equivalent to "auto".
ltext: Vector of character strings of length and order corresponding to alphabet(seqdata) or, when for groups, to the levels of the group variable. Optional description for the color legend. If unspecified, the label attribute of the seqdata sequence object is used (see seqdef) or, when for groups, the levels of the group variable.
cex.legend: Real. Legend magnification. See legend.
use.layout: Logical. Should layout be used to arrange plots when using the group option or plotting a legend? When layout is activated, the standard 'par(mfrow=....)' for arranging plots does not work. With with.legend=FALSE and group=NULL, layout is automatically deactivated and 'par(mfrow=....)' can be used.
legend.prop: Real in range [0,1]. Proportion of the graphic area devoted to the legend plot when use.layout=TRUE and with.legend=TRUE. Default value is set according to the place (bottom or right of the graphic area) where the legend is plotted.
rows,cols: Integers. Number of rows and columns of the plot panel when use.layout=TRUE.
which.states: Vector of short state names. List of the states for which survival curves should be plotted.
title: Deprecated. Use main instead.
cex.plot: Deprecated. Use cex.axis instead.
withlegend: Deprecated. Use with.legend instead.
axes: Deprecated. Use xaxis instead.
...: 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 per.spell argument will typically be used for survival plots. Can also include arguments of legend such as bty="n" to suppress the box surrounding the legend.

Author

Gilbert Ritschard (based on TraMineR seqplot function)

Details

This is a specific version of seqplot for type="s". It implements a dedicated handling of the group variable passed as group argument when per.sate=TRUE is included in the ... list.

Invalid or non observed states are removed the list given as which.states argument. When which.states = NULL, which.states will be defined as the list of states present in the data.

When per.sate=TRUE, a distinct plot is generated for each state in the which.states list and, when a grouping variable is provided, the survival curves of all groups are plotted in each plot.

When per.state=FALSE, a distinct plot is generated for each group and the survival curves of all states listed as which.states are plotted in each plot.

References

Gabadinho, A., G. Ritschard, N. S. Müller and M. Studer (2011). Analyzing and Visualizing State Sequences in R with TraMineR. Journal of Statistical Software 40(4), 1-37.

Examples

Run this code

## ======================================================
## Creating state sequence objects from example data sets
## ======================================================

data(biofam)
biofam.lab <- c("Parent", "Left", "Married", "Left+Marr",
                "Child", "Left+Child", "Left+Marr+Child", "Divorced")
biofam.short <- c("P","L","M","LM","C","LC","LMC","D")

sple <- 1:200  ## only the first 200 sequences
seqstatl(biofam[sple,10:25]) ## state 4 not present
biofam <- biofam[sple,]

biofam.seq <- seqdef(biofam[,10:25], alphabet=0:7, states=biofam.short, labels=biofam.lab)

## defining two birth cohorts
biofam$wwii <- factor(biofam$birthyr > 1945,
  labels=c("Born Before End of Word War II","Born After Word War II"))

## ==============================
## Plots of state survival curves
## ==============================

seqsplot(biofam.seq) ## all states, no group
seqsplot(biofam.seq, group=biofam$wwii, lwd=2) ## all states for each group
seqsplot(biofam.seq, group=biofam$wwii, per.state=TRUE, lwd=2) ## groups for each state

## For a selection of states only

seqsplot(biofam.seq, group=biofam$wwii, which.states= c('LM'), lwd=2)
## changing default color
seqsplot(biofam.seq, group=biofam$wwii, which.states= c('LM'),
  cpal="orange", lwd=2)
seqsplot(biofam.seq, group=biofam$wwii, which.states= c('LM','LMC'),
  cpal=c("orange","brown"), lwd=2)
seqsplot(biofam.seq, group=biofam$wwii, which.states= c('LM','LMC'), per.state=TRUE)

Run the code above in your browser using DataLab