seqsplot: Plot survival curves of the states in sequences
In TraMineRextras: TraMineR Extension

seqsplot

R Documentation

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.

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.

Author(s)

Gilbert Ritschard (based on TraMineR seqplot function)

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

## ======================================================
## 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)

TraMineRextras documentation built on Sept. 11, 2024, 6:52 p.m.