Creation of Objects of Class longCat

Share:

Description

Function to create objects of class longCat.

Usage

1
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 varying times of observation). Note that times may have one more column than y, see endt below. Default is NULL and is assigned the value 1:ncol(y).

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 cases (e.g., endt=1), be set to a vector values of the same length as the number of rows in y, or be a matrix of values with the same number of rows as y and one column. If the times argument is a matrix with one more column than y, endt will be set to the last column of times.

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

Author(s)

Stephen Tueller

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

 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
38
39
40
41
42
43
44
45
46
47
48
# 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)

## Not run: 
# 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)

## End(Not run)