longCatEDA (version 0.17)

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, endt = NULL)

Arguments

y

a data matrix or data frame in wide (as opposed to long) format with cases in rows and repeated observations in columns. At most, y can have 9 unique non-missing values.

times

time points used for the x-axis in plotting. Either a vector of the same length as the number of columns in y (i.e., all cases have the same times of observation), or a matrix of the same dimension as y (i.e., individually varyin

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).

id

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

endt

An optional variable defining how far to extend the last time point for visualization purposes. The default is NULL, in which case the average time interval in times is used. It can take on a single value which is applied to all

Value

• longCat returns an object of class longCat which is a list containing at least the following components:
• data
  y
• data.sorted
  y sorted (default is NULL unless sorter has been applied to the longCat object).
• dim
  the dimension of data.
• 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 data.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 data. Not that if the unique values in y were not sequential integers starting at 1, both factors and data 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 data. If TRUE, longCatPlot treats these times as individually varying times of observation.
• nfactors
  the number of unique values in data, and is the same as the length of the factors vector. nfactors is determined by longCat, but cannot exceed 9. If users have data with more than 9 categories, continuous plotting methods are recommended (e.g., try longContPlot.)
• sorted
  a logical indicator of whether data has been sorted by the sorter function. If TRUE, data.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 data (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.data
  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).

References

Tueller, S. J., Van Dorn, R. A., and Bobashev, G. V. (2013). Visualization of Categorical Longitudinal and Times Series Data. Manuscript Under Review.

See Also

longCatPlot to plot longCat objects created by the longCat function.

Examples

# create the longcat object for Figure 2 in Tueller (2011)
times <- c(1,100,200,300,400,500)
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')
par(mfrow=c(1,1), bg='transparent')

# illustrate individually varying times of observation and the use of endt
y <- matrix(sample(1:5, 500, replace=TRUE), 100, 5)
t <- matrix(runif(600, 1, 3), 100, 6)
times <- cbind(t[,1], t[,1]+t[,2],
               t[,2]+t[,3],
               t[,3]+t[,4],
               t[,4]+t[,5])
endt <- t[,6]
lc <- longCat(y, times=times, endt=endt)
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(7.5, 100, legend=lc$factors, lty=1, col=cols, lwd=2)
par(bg='transparent', mar = c(5, 4, 4, 2) + 0.1, xpd=FALSE)

# illustrate handling factor input 
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) and the use of endt
y <- matrix(sample(1:18, 500, replace=TRUE), 100, 5)
lc <- longCat(y, endt=.5)
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)