SEchart: Graphically display states and events in longitudinal data

Description Usage Arguments Details Value Author(s) See Also Examples

View source: R/SEchart.R

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
#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 30, 2017, 3:42 a.m.