longCatEDA (version 0.31)

longCatPlot:

Description

Function to plot longCat objects created by longCat.

Usage

longCatPlot(lc, xlab = "Days", 
  ylab = NULL, cols = NULL, 
  colScheme = "heat", reverse = FALSE, lwd = 0.5, lcex = 1, llwd = 3, 
  legendBuffer = 0.12, groupBuffer = 0, groupRotation = 90, gcex = 1, 
  seg.len = 1, xlas = 0, xcex = 1, ecex = .5, event.col=1, 
  plot.events=TRUE, which.events=NULL, 
  n.events=NULL, event.pch=NULL, 
  texclude=NULL, sort=TRUE,
  which.state=NULL, nth.state=NULL, not.state=FALSE,
  which.event=NULL, nth.event=NULL, not.event=FALSE, ...)

Arguments

lc

an object of class longCat created by longCat. See par.

xlab

a label for the x-axis. Default is "Days". See par.

ylab

a label for the y-axis. Default is NULL which is changed to "Each Line Represents a Participant" with the sample size appended (lc$dim[1], see longCat). See par.

cols

a numeric or character list of colors. See par. Default is NULL. To use internal color schemes, use colScheme.

colScheme

select a color scheme. See colChoose for available options.

reverse

color schemes are applied from the lowest to highest level of categorical data in lc$y or lc$y.sorted. Set reverse=TRUE to reverse this. Default is FALSE.

lwd

set the width of horizontal lines. Default is .5. lwd should be reduced proportionally to the number of rows in lc$y to avoid overlap in plotting.

lcex

character expansion factor for the legend text. Default is 1. See par.

llwd

set the width of lines in the legend. default is 3. See lwd.

legendBuffer

set proportion of the plot to retain for legends, must be in [0,1]. Note that the legend is very sensitive to the scaling of the graphics device. Users are advised to maximize their device and rerun, or call dev.new() and resize prior to running longCatPlot. Default is .12 (i.e., 12% of the vertical plot area is retained for the legend). Set to 0 if no legend is desired. See the examples for moving the legend outside of the plotting margins.

groupBuffer

similar to legendBuffer, but for group labels on the left side of the plot. Default is 0 (i.e., 0% of the horizontal plot area is retained for group labels). Can take on any value in [0,1].

groupRotation

if lc$groupLabels are long (see longCat), rotation of the labels can be used reduce the needed size of groupBuffer. The value is in degrees ranging from -360 to +360.

gcex

character expansion factor for group labels. Default is 1. See par.

seg.len

Length of lines in the upper legend. Default is 1. See legend.

xlas

see las in par. Applied to the x-axis when tLabels are provided to longCat.

xcex

see axis.cex in par and axis. Applied to the x-axis when tLabels are provided to longCat.

ecex

see cex in points. This is used to size the points used to plot event points if events is not NULL.

event.col

color for ploting event indicators.

plot.events

logical - should events be plotted?

which.events

numeric vector - which events should be plotted? For example, if the events have values c(1,2,3,4,5), you can specify that only which.events=c(2,5) be plotted.

n.events

how many events should be plotted, e.g., n.events=3 plots the first three events for each participant.

event.pch

what plotting characters should be used. See points.

texclude

a vector of length 2 indicating the range of times and event.times to be plotted, e.g., texclude=c(10,20) will plot data for time points 10 and larger up to and including 20.

sort

logical - should longCatPlot sort the data on the fly using intelligent defaults? If data are already sorted via sorter, this will be ignored.

which.state

see alignTime.

nth.state

see alignTime.

not.state

see alignTime.

which.event

see alignTime.

nth.event

see alignTime.

not.event

see alignTime.

…

Arguments to be passed to plot (see par).

References

Tueller, S. J., Van Dorn, R. A., & Bobashev, G. V. (2016). Visualization of categorical longitudinal and times series data (Report No. MR-0033-1602). Research Triangle Park, NC: RTI Press. http://www.rti.org/publication/visualization-categorical-longitudinal-and-times-series-data

See Also

longCat.

Examples

# Illustrate longCatPlot with the legend outside the plot
par(mfrow=c(1,1), bg='cornsilk3', mar=c(5.1, 4.1, 4.1, 8.1), xpd=TRUE)
cols <- longCatPlot(
  longCat(example3),
  legendBuffer=0,
  main='Horizontal Line Plot')
legend(7.1, 100, legend=1:5, col=cols, lty=1, lwd=2)
par(bg='transparent', mar = c(5, 4, 4, 2) + 0.1, xpd=FALSE)

### visualizing multivariate data: 3 items at 4 time points
library(MASS)
Sigma <- matrix(.25, 12, 12)
diag(Sigma) <- 1
set.seed(9845)
mu <- rep(c(-.5, 0, .5), 4) + rnorm(12, 0, .25)
set.seed(539)
ymv <- apply(mvrnorm(n=100, mu=mu, Sigma = Sigma), 2, cut, breaks=c(-Inf, 0, Inf), labels=c(0,1))
apply(ymv, 2, table)
(items <- rep(1:3, 4))
(times <- sort(rep(1:4, 3)))
tLabels <- paste('Time', 1:4)
 Labels <- paste('Item', 1:3)
 
# plot time points within items
par(mfrow=c(2,2), bg='cornsilk3', mar=c(5.1, 4.1, 4.1, 8.1), xpd=TRUE)

item1  <- longCat(y=ymv[,items==1], tLabels=tLabels)
cols <- longCatPlot(item1, ylab='', main='Item 1', legendBuffer=0, xlab="", xlas=2)
legend(length(unique(times))+.1, nrow(ymv), legend=0:1, col=cols, lty=1, lwd=2, title='Response')

item2 <- longCat(y=ymv[,items==2], tLabels=tLabels)
longCatPlot(item2, ylab='', main='Item 2', legendBuffer=0, xlab="", xlas=2)
legend(length(unique(times))+.1, nrow(ymv), legend=0:1, col=cols, lty=1, lwd=2, title='Response')

item3 <- longCat(y=ymv[,items==3], tLabels=tLabels)
longCatPlot(item3, ylab='', main='Item 3', legendBuffer=0, xlab="", xlas=2)
legend(length(unique(times))+.1, nrow(ymv), legend=0:1, col=cols, lty=1, lwd=2, title='Response')

par(bg='transparent', mar = c(5, 4, 4, 2) + 0.1, xpd=FALSE)

# plot items within time points
par(mfrow=c(2,2), bg='cornsilk3', mar=c(5.1, 4.1, 4.1, 8.1), xpd=TRUE)

time1  <- longCat(y=ymv[,times==1], tLabels=Labels)
cols <- longCatPlot(time1, ylab='', main='Time 1', legendBuffer=0, xlab="")
legend(length(unique(times))+.1, nrow(ymv), legend=0:1, col=cols, lty=1, lwd=2, title='Response')

time2  <- longCat(y=ymv[,times==2], tLabels=Labels)
cols <- longCatPlot(time2, ylab='', main='Time 2', legendBuffer=0, xlab="")
legend(length(unique(times))+.1, nrow(ymv), legend=0:1, col=cols, lty=1, lwd=2, title='Response')

time3  <- longCat(y=ymv[,times==3], tLabels=Labels)
cols <- longCatPlot(time3, ylab='', main='Time 3', legendBuffer=0, xlab="")
legend(length(unique(times))+.1, nrow(ymv), legend=0:1, col=cols, lty=1, lwd=2, title='Response')

time4  <- longCat(y=ymv[,times==4], tLabels=Labels)
cols <- longCatPlot(time4, ylab='', main='Time 4', legendBuffer=0, xlab="")
legend(length(unique(times))+.1, nrow(ymv), legend=0:1, col=cols, lty=1, lwd=2, title='Response')

par(mfrow=c(1,1), bg='transparent', mar = c(5, 4, 4, 2) + 0.1, xpd=FALSE)

## Not run: ------------------------------------
# # for data sets with many rows, writing directly to a file 
# # is much faster and unaffected by device resizing, see ?pdf
# pdf('C:/mydir/mysubdir/myfile.pdf')
# par(bg='cornsilk3')
# longCatPlot(f3lc, main='Sorted', colScheme='heat', lwd=2)
# par(mfrow=c(1,1), bg='transparent')
# dev.off()
# # see ?jpeg for picture file options
## ---------------------------------------------