longCat: Creation of Objects of Class longCat

Description

Function to create objects of class longCat.

Usage

longCat(y, times = NULL, Labels = NULL, tLabels = NULL, id = NULL, 
        events = NULL, event.times = NULL, eventLabels = NULL)

Arguments

a data matrix or data frame of numeric states in wide (as opposed to long) format with cases in rows and repeated observations in columns. It is reccomended that y have 9 or fewer unique non-missing levels. Labels for the numeric states are given in Labels.

times

The times object designates start and stop points for each plotted interval. It is either a vector with length being the number of columns in y plus one, NULL, or a matrix with the same number of rows as y and one more column than in y. Negative values are allowed such as would be the case if time is centered at an intervention point, negative values represent times prior to the intervention, and positive times represent times after the intervention. If times is a vector, it is assumed that cases in each row in y is observed at the same time points for the same durations. For example, if times=c(0,6,12,13), this indicates a design were cases were observed at 0, 6, and 12 time units. When applying longCatPlot, the first observation for each case with extend from 0 to 6, the second observation for each case will extend from 6 to 12, and the third observation will extend from 12 to 13. The value selected at the end may be arbitrary as cases may not have been followed for any additional time. A value may be selected to maintain consistent interval sizes. Continuing the example, one could use times=c(0,6,12,18) instead of times=c(0,6,12,13) even though cases weren't actually followed past month 12. Unequal spacing is allow, for example times=c(0,3,12,18). In this case, participants are observed for at baseline, 3 time units, and 12 time units, where the final status is either intentionally or arbitrarily extended 18-12=6 time units at the right end of the plot. Missing values are not allowed. If times=NULL (the default), times=0:ncol(y) will be assigned (i.e., starting at 0 times units and increase to 1 time unit, 2 time units, etc.). When times is a matrix, each case has a unique set of observation times. In this case, missing values are allowed, but each case should have at least one observation and a start and stop point for that observation. If available timing data is a matrix of the same size as y and represents start points, the user must add a column at the end designating how far to the right time points should be extended. As noted above, this value may be arbitrary and should be large enough to show what state cases end in. If available timing data is a matrix of the same size as y and represents end points, the user must add a column at the beginning of the matrix designating designating start points. If available timing data represents duration instead of time points, the user must recode the data into cumulative time. For example, if a participant was in their first three states for 5, 7, and 11 time units, their row of times should be recoded to be c(0,5,12,23). The times and event.times matrices can be realigned using the alignTime function, or this can be done on the fly by accessing the alginTime options in the longCatPlot function.

Labels

a vector of numeric or character labels for the response options in y. Must be the same length as the number of unique non-missing values in y. Default is NULL and is assigned the values 1:max(unique(y)).

tLabels

numeric or character labels for the time points in times. Default is NULL and is assigned the values 1:ncol(y).

An optional variable identifying or naming the rows of y. Returned as the first column of the matrix order.y (see order.y in the value section below).

events

An event matrix or y.frame which may be numeric or character (see eventLabels). Whereas the data in y are states in which each case resides for some period of time, events are instantaneous events (or very short lived states) that can be attached to a single point in time at event.times. The number of rows in events and event.times must equal the number of rows in y, but can have as many columns as needed to capture all events of interest. Large numbers of events may cloud the resulting figures created by longCatPlot.

event.times

A matrix or data.frame of event times corresponding to each event in events. As opposed to the times matrix, which contains durations (except possibly the first column as described above), the event.times matrix is the time the event takes place (i.e., cumulative time). The times and event.times matrices can be realigned using the alignTime function, or this can be done on the fly by accessing the alginTime options in the longCatPlot function.

eventLabels

If events is a character matrix, eventLabels should be left NULL and labels will be pulled from the data in events. If events is numeric, corresponding eventLabels can be supplied by the user as a character vector, for example, c('event1', 'event2', 'etc.'). The number of unique events (and correpsonding event labels) should be kept small if possible, otherwise the event legend on Figures produced by longCatPlot may be truncated.

Value

longCat returns an object of class longCat which is a list containing at least the following components:

y

y.sorted

y sorted (default is NULL unless sorter has been applied to the longCat object).

dim

the dimension of y.

times

the times object as described above.

endt

the endt object as described above.

times.sorted

if times is a matrix of the same dimension as y, times.sorted contains a matrix of individually varying times of observation with the same sorting as y.sorted.

endt.sorted

endt sorted after an lc object is passed to sorter

labels

the labels vector as described above

tLabels

the tLabels vector as described above

factors

a vector containing the unique values in y. Not that if the unique values in y were not sequential integers starting at 1, both factors and y are recoded such that they contain sequential integers starting at 1.

IndTime

a logical indicator of whether times is a matrix of the same dimension as y. If TRUE, longCatPlot treats these times as individually varying times of observation.

nfactors

the number of unique values in y, and is the same as the length of the factors vector. nfactors is determined by longCat. If users have data with more than 9 categories, continuous plotting methods are recommended via warning (e.g., try longContPlot.)

sorted

a logical indicator of whether y has been sorted by the sorter function. If TRUE, y.sorted (and times.sorted if IndTime is TRUE) will not be NULL.

ascending

logical indicator. If sorted is TRUE, this will indicate whether sorting was done ascending. (default is NULL unless sorter has been applied to the longCat object).

group

a vector of the same length as the number of rows in y (default is NULL unless sorter has been applied to the longCat object along with a grouping variable).

groupLabels

a optional vector of character or numeric labels for the group variable (see sorter).

order.y

A matrix with identification (see input id above) and sorting information. Rows of the matrix correspond to rows of y and the columns are id, and order variable, and a variable representing the unique data patterns in y. The former is returned only if id is provided to longCat. The latter two are only returned by sorter. If only unique data patterns are desired, use makePatterns; see example(makePatterns).

events

A matrix of events.

event.times

A matrix of event times.

eventLabels

A vector of event labels.

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

Examples

Run this code

# create the longcat object similar to Figure 2 in Tueller (2016)
times <- c(1,100,200,300,400,500,600)
f2lc <- longCat(example2cat, times)

# object summary
summary(f2lc)

# compare growth curves to longCat
par(mfrow=c(1,2), bg='cornsilk3')
longContPlot(example2cat, times, ylim=c(1,5), 
  main='Growth Curves', ylab='', xlab='Days')
longCatPlot(f2lc, lwd=4, main='Horizontal Line Plot', colScheme='heat', legendBuffer=.2)
par(mfrow=c(1,1), bg='transparent')

# illustrate individually varying times of observation 
set.seed(642531)
y <- matrix(sample(1:5, 500, replace=TRUE), 100, 5)
set.seed(963854)
times <- matrix(runif(600, 1, 3), 100, 6)
# times must be cumulative
times <- t(apply(times, 1, cumsum))
lc <- longCat(y, times=times)
par(mfrow=c(1,1), bg='cornsilk3', mar=c(5.1, 4.1, 4.1, 10.1), xpd=TRUE)
cols <- longCatPlot(lc, legendBuffer=0, groupBuffer=0, 
	main='Individually Varying Times of Observation')
legend(15.5, 100, legend=lc$Labels, lty=1, col=cols, lwd=2)
par(bg='transparent', mar = c(5, 4, 4, 2) + 0.1, xpd=FALSE)

# illustrate the adding event indicators
set.seed(45962)
events <- matrix(sample(1:3, 200, replace=TRUE), 100, 2)
set.seed(23498)
event.times <- matrix(sample(c(times), 200, replace=FALSE), 100, 2)
labels <- c('Street', 'Drug Tx', 'Jail', 'Prison', 'Unknown')
eventLabels=c('Arrest', 'Drug Test', 'Hearing')
lc <- longCat(y, times=times, Labels=labels,  
              events=events, event.times=event.times, 
              eventLabels=eventLabels)
par(mfrow=c(1,1), bg='cornsilk3', mar=c(5.1, 4.1, 4.1, 12.1), xpd=TRUE)
cols <- longCatPlot(lc, legendBuffer=0, groupBuffer=0, 
                    main='Superimpose Events Over States')
legend(15.5, 100, legend=lc$Labels, lty=1, col=cols, lwd=2)
legend(15.5, 40, legend=lc$eventLabels, pch=1:length(lc$eventLabels))
par(bg='transparent', mar = c(5, 4, 4, 2) + 0.1, xpd=FALSE)

## Not run: ------------------------------------
# # illustrate handling non time-ordered input (e.g., factor analysis data)
# y <- matrix(sample(c('1', '2', '3', '4', '5'), 500, replace=TRUE), 100, 5)
# lc <- longCat(y)
# par(mfrow=c(1,1), bg='cornsilk3', mar=c(5.1, 4.1, 4.1, 8.1), xpd=TRUE)
# cols <- longCatPlot(lc, legendBuffer=0)
# legend(6, 100, legend=lc$factors, lty=1, col=cols, lwd=2)
# par(bg='transparent', mar = c(5, 4, 4, 2) + 0.1, xpd=FALSE)
# 
# # illustrate plotting with more than 9 categories 
# # (a warning is issued) 
# y <- matrix(sample(1:18, 500, replace=TRUE), 100, 5)
# lc <- longCat(y)
# par(mfrow=c(1,1), bg='cornsilk3', mar=c(5.1, 4.1, 4.1, 8.1), xpd=TRUE)
# cols <- longCatPlot(lc, legendBuffer=0)
# legend(6, 100, legend=lc$factors, lty=1, col=cols, lwd=2)
# par(bg='transparent', mar = c(5, 4, 4, 2) + 0.1, xpd=FALSE)
## ---------------------------------------------