longCat: Creation of Objects of Class longCat

In stueller/longCatEDA: Package for Plotting Categorical Longitudinal and Time-Series Data

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

y	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 recommended 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 are observed at the same time points for the same durations...
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.y (see order.y in the value section below).
events	An event matrix or data.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.
event.times	A matrix or data.frame of event times corresponding to each event in events.
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.

Value

An object of class longCat which is a list containing at least the following components: y, y.sorted, dim, times, endt, times.sorted, endt.sorted, labels, tLabels, factors, IndTime, nfactors, sorted, ascending, group, groupLabels, order.y, events, event.times, and eventLabels.

Author(s)

Stephen J. Tueller

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

longCatPlot to plot longCat objects created by the longCat function.

Examples

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

## End(Not run)

stueller/longCatEDA documentation built on March 9, 2024, 4:08 a.m.