Last chance! 50% off unlimited learning
Sale ends in
longCat
.longCat(y, times = NULL, Labels = NULL, tLabels = NULL, id = NULL,
events = NULL, event.times = NULL, eventLabels = NULL)
y
have 9 or fewer unique non-missing levels. Labels for the numeric states are given in Labels
.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.
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))
.times
. Default is NULL
and is assigned the values 1:ncol(y)
.y
. Returned as the first column of the matrix order.y
(see order.y
in the value section below).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
.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.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.longCat
returns an object of class longCat
which is a list containing at least the following components:
y
y
sorted (default is NULL
unless sorter
has been applied to the longCat
object).y
.times
object as described above.endt
object as described above.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 after an lc
object is passed to sorter
labels
vector as described abovetLabels
vector as described abovey
. 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.times
is a matrix of the same dimension as y
. If TRUE
, longCatPlot
treats these times as individually varying times of observation.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
.)y
has been sorted by the sorter
function. If TRUE
, y.sorted
(and times.sorted
if IndTime
is TRUE
) will not be NULL
. sorted
is TRUE
, this will indicate whether sorting was done ascending. (default is NULL
unless sorter
has been applied to the longCat
object).y
(default is NULL
unless sorter
has been applied to the longCat
object along with a grouping variable).group
variable (see sorter
).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)
.longCatPlot
to plot longCat
objects created by the longCat
function.# 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)
## ---------------------------------------------
Run the code above in your browser using DataLab