SEchart: Graphically display states and events in longitudinal data

In SEchart: SEchart

Description

Produces plots similar to event charts, with the additional option to include a 'state' variable (i.e., a time-varying variable), the values of which are displayed as line segments with different colors. The plots can be used to visualize associations between states and events. Furthermore, useful strategies for the vertical alignment of subjects are included in the function.

Usage

SEchart(data, idvar, timevar.start, timevar.stop, statevar = NULL,
	eventvar = NULL, eventtime= NULL, srt1 = NULL, srt2 = NULL,
	srt3 = NULL, srt4 = NULL, ord.ud = NULL, stratvar = NULL,
	xlim = NULL, xlab = "Time", ylim = NULL, ylab = NULL,
	grd = FALSE, grd.col = "grey", grd.lty = "dashed", idnum = 1,
	idnum.col = "black", idnum.cex = 1, l.base.col = "grey",
	l.base.lwd = 1,	lend = 1, l.state.col = "pal.heat.rev",
	l.state.lwd = 3, main = "SEchart", bg = "white", legnd = TRUE,
	legnd.x = "bottomright", legnd.y = NULL, legnd.cex = 1,
	legnd.txt.round = 2, legnd.bg = "white", strat.cex = 1,	
	strat.txt = NULL, strat.bg.col = "lightgrey", pch = NULL,
	p.col = NULL, p.cex = 1, p.lwd = 1, return.output = FALSE)

Arguments

data	Data frame, consisting of data collected on multiple time points, in 'long' format.
idvar	Name of the variable in data uniquely identifying the units under observation within which the longitudinal measurements are taken.
timevar.start	Name of the variable in data specifying the beginning of each time interval.
timevar.stop	Name of the variable in data specifying the end of each time interval.
statevar	Name of the variable in data specifying a subject's state in each interval. May contain NA values. If left unspecified, no state variable is plotted.
eventvar	Name(s) of the variable(s) in data specifying whether event(s) took place in each interval. Should be coded 0/1. May contain NA's. If left unspecified, no events are plotted.
eventtime	Vector of the same length as eventvar, specifying the time(s) of occurrence of event(s) within the time interval. Options are "start", "middle" and "end".
srt1	Specifies the sorting strategy used on the first level. See Details for the available options. If left unspecified, subjects are sorted only on idvar.
srt2	Similar to srt1, for the second level. If left unspecified, sorting is only performed on first level.
srt3	Similar to srt1, for the third level. If left unspecified, sorting is only performed up to the second level.
srt4	Similar to srt1, for the fourth level. If left unspecified, sorting is only performed up to the third level.
ord.ud	Vector of unique values in idvar, specifying a user-defined ordering. Overrides srt1-srt4.
stratvar	Name of numerical variable in data, the values of which are used to stratify the charts. stratvar should be time-independent.
xlim	Limits of the X-axis of the plot.
xlab	The label used for the X-axis.
ylim	Limits of the Y-axis of the plot.
ylab	The label used for the Y-axis. If left unspecified, idvar is used.
grd	Logical. Should vertical grid lines be plotted?
grd.col	Color of the grid lines.
grd.lty	Line type used for the grid lines. See par.
idnum	Specifies whether and where ID numbers should be located. 0: No ID numbers, 1: ID numbers in plot, 2: ID numbers on Y-axis.
idnum.col	Color used for the ID-numbers.
idnum.cex	Numerical value giving the amount by which the ID-numbers should be magnified relative to the default.
l.base.col	Color used for the line indicating the total time of follow-up.
l.base.lwd	Numerical value specifying the width of the line indicating the total time of follow-up.
lend	Line end style. See par.
l.state.col	Either a string specifying a color palette (see Details), or a vector of length length(unique(data[statevar][!is.na(data[statevar])])) specifying the colors used to indicate states in the plot, sorted from low to high.
l.state.lwd	Numerical value specifying the width of the lines that are used to indicate the states.
main	Title of the chart.
bg	Background color of the chart.
legnd	Logical. Should a legend be included?
legnd.x	X coordinates of the legend.
legnd.y	Y coordinates of the legend.
legnd.cex	Numerical value giving the amount by which the text in the legend should be magnified relative to the default.
legnd.txt.round	Integer value specifying the number of decimals to which the values of statevar are rounded in the legend.
legnd.bg	Background color of the legend.
strat.cex	Numerical value giving the amount by which the text used to indicate the stratvar values should be magnified relative to the default.
strat.txt	Vector with user specified text to indicate stratvar values. If left unspecified, the values of stratvar are used.
strat.bg.col	Color of the bars used to stratify the chart according to stratvar.
pch	Vector of length(eventvar) specifying the point character(s) used to indicate the event(s). See par(). If left unspecified, c(1:length(eventvar)) is used.
p.col	Vector of length length(eventvar) specifying the color(s) of the points used to indicate the event(s). If left unspecified, "black" is used for all points.
p.cex	Numerical value giving the amount by which the points used to indicate the event(s) should be magnified relative to the default.
p.lwd	Numerical value specifying the line width of the points used to indicate the event(s).
return.output	Logical. Should the function return information on the used ordering and graphical options?

Details

srt1 through srt4 are used to vertically sort the subjects in the plot. Options are:

"start.time"

Sorts the subjects by their start time.

"end.time"

Sorts the subjects by their end time.

"tot.time"

Sorts the subjects by their total duration of follow-up time.

"midpoint.time"

Sorts the subjects by their midpoint follow-up time.

"min.state"

Sorts the subjects by their minimum observed level of statevar.

"max.state"

Sorts the subjects by their maximum observed level of statevar.

"first.state"

Sorts the subjects by the level of statevar that was observed on first measurement.

"last.state"

Sorts the subjects by the level of statevar that was observed on last measurement.

"average.state"

Sorts the subjects by their average observed level of statevar per unit of time.

"sum.(eventname)"

Sorts the subjects by the sum of the number of an event. Replace (eventname) with the name of the event as specified in eventvar (without brackets or quotation marks).

"tf.(eventname)"

Sorts the subjects by whether the subject experienced an event or not. Replace (eventname) with the name of the event as specified in eventvar (without brackets or quotation marks).

"time.(eventname)"

Sorts the subjects by the time of the first occurence of an event. Replace (eventname) with the name of the event as specified in eventvar (without brackets or quotation marks).

Color palette options for l.state.col are "pal.rainbow", "pal.topo", "pal.terrain", "pal.heat", "pal.cm", "pal.topo" and "pal.gray". Adding .rev (e.g. "pal.heat.rev") reverses the colors. See rainbow and gray.colors.

Value

If return.output == TRUE, a list with objects $ord.id, $col.statevar, and $p.inf.

$ord.id

A vector indicating the used ordering of the subjects.

$col.statevar

A matrix with rows specifying the colors used for every level of statevar.

$p.inf

A matrix with rows specifying the events and the corresponding values used for pch, p.col, p.lwd and p.cex.

Author(s)

Rutger M. van den Bor, Willem M. van der Wal

See Also

event.chart

Examples

#Example using aids dataset from package JM
library(JM) 
data(aids)

#Assign class numeric to aids$patient and aids$prevOI (class factor is not allowed in function)
aids$patient <- as.numeric(aids$patient)
aids$prevOI.2 <- as.numeric(aids$prevOI)

#Categorize CD4
aids$CD4.cat <- cut(aids$CD4, breaks=10, labels=FALSE)

#For better results, use pdf()
# pdf(file = "PATH/SEchart_aids.pdf", width = 12, height = 20)

#Create SEchart for subset of aids data, with event=death and state=CD4. 
#Sort subjects by (1) occurrence of event "death" and (2) their observed end 
#time. The chart is stratified by "aids diagnosis at study entry" (variable 
#"prevOI.2").

SEchart(data=aids[aids$patient <= 100,],
	idvar="patient",
	timevar.start = "start",
	timevar.stop = "stop",
	statevar="CD4.cat",
	eventvar="event",
	eventtime="end",
	srt1="tf.event",
	srt2="end.time",
	stratvar="prevOI.2",
	strat.txt=c("No aids diagnosis at study entry", "Aids diagnosis at study entry"),
	l.state.col="pal.heat",
	idnum.cex=0.5,
	legnd = TRUE,
	)

#Close the graphics device to save as pdf
# graphics.off()

SEchart documentation built on May 2, 2019, 12:40 p.m.