sorter:

Description

A function to sort an longCat object created by longCat. sorter must be used directly when stratified plots of subgroups is desired, or when sorting other than the default sorting is desired. Otherwise, sorter is used internally with the defaults by longCatPlot if lc$sorted=FALSE. If an object has already been sorted (lc$sort=TRUE), sorter will not resort it, but will print a code example of how to use multiple sortings.

Usage

sorter(lc, ascending = TRUE, whichColumns = NULL, num = TRUE,
                 mindur = NULL, igrpt = FALSE, customSort = NULL,
                 initFirst = FALSE, group = NULL, groupLabels = NULL,
                 ggap = NULL)

Arguments

an object of class longCat created by longCat.

ascending

logical - should sorting be done ascending. Default is TRUE.

whichColumns

a numeric list indicating which columns in lc$y should be used for sorting (.e.g., c(1, 5, 7)). Useful if, for example, an intervention occurs after data collection has started, and the user is not interested in sorting on pre-intervention observations.

num

see makePatterns for details.

mindur

see makePatterns.

igrpt

should sorter (ig)nore (r)e(p)ea(t)ed values for each row in lc$y for sorting purposes? See norpt.

customSort

a vector of the same length as the number of rows in lc$y providing a user defined variable on which to sort the data prior to secondarily applying the default sort. If group is not NULL, group will be sorted on prior to the customSort variable. Alternatively, lc$y can be sorted without calling sorter using lc$y.sorted <- lc$y[o, ] where o is the order (e.g., use o <- order(customSort)). The user must also set lc$sorted <- TRUE to prevent on-the-fly default sorting from being carried out by longCatPlot. Users unfamiliar with sorting in R should take care not to confuse order with sort. Default is NULL. If any values on customSort are missing, the function will return an error message.

initFirst

if customSort is not NULL, setting initFirst=TRUE will sort on initial values prior to the custom sorting variable.

group

a vector of the same length as the number of rows in lc$y indicating group membership. Default is NULL. If group is NA, corresponding rows in lc$y will be deleted prior to completing the sorting, and a warning indicating this has been done is printed to the console. If a large number of cases have missing data on the grouping variable, consider recoding the missings into their own group, e.g., group[is.na(group)] <- -999 and add a missing label to groupLabels, e.g. groupLabels=c('Missing', 'Group1', 'Group2', 'Etc.').

groupLabels

a vector of numeric or character labels of the same length as the number of unique values in group. Default is NULL. If group is not NULL and groupLabels is not provided, then the numeric values in group are used as the labels.

ggap

a number zero to 1. The proportion of blank rows to be plotted between groups when group is specified. The default of NULL is set to 0.05 when groups are present, 0.0 when there are no groups.

Value

Returns an object of class longCat where lc$sorted=TRUE. See longCat for values.

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 a plot like that in Figure 3 from Tueller, Van Dorn, & Bobashev (2016)
par(mfrow=c(1,2), bg='cornsilk3')
times <- c(1,100,200,300,400,500,600)
f3lc <- longCat(example3, times); f3lc$sorted <- TRUE; f3lc$y.sorted <- f3lc$y
longCatPlot(f3lc, main='Unsorted', colScheme='heat', lwd=2, legendBuffer=.2)
f3lc <- longCat(example3, times)
longCatPlot(f3lc, main='Sorted', colScheme='heat', lwd=2, legendBuffer=.2)

### sort with a grouping variable and plot
par(mfrow=c(1,1), bg='cornsilk3', mar=c(5.1, 4.1, 4.1, 9.1), xpd=TRUE)
times <- c(1,100,200,300,400,500,600)
lc <- longCat(example3, times)
group <- sample(1:3, nrow(example3), replace=TRUE)
grouplc <- sorter(lc, group=group, groupLabels=1:3)
cols <- longCatPlot(grouplc, groupBuffer=.15, main='Grouped Data', colScheme='heat', 
                    lwd=2, legendBuffer=0)
legend(610, 130, legend=1:5, col=cols, lty=1, lwd=2)
par(bg='transparent', mar = c(5, 4, 4, 2) + 0.1, xpd=FALSE)

### using the sorted data from the previous plot, repeate using ggplot2 
#   following the example of Figure 4 of bdemarest's answer on 
#   https://stackoverflow.com/questions/11513149/
#   good-ways-to-visualize-longitudinal-categorical-data-in-r/
grouplc.df <- data.frame(id=1:nrow(grouplc$group.sorted), 
                group=grouplc$group.sorted[,1], grouplc$y.sorted)
grouplc.long <- reshape(grouplc.df,
                        varying = names(grouplc$y.sorted),
                        v.names = "score",
                        timevar = "time",
                        times = times[1:ncol(grouplc$y.sorted)],
                        direction = "long")
grouplc.long$score <- factor(grouplc.long$score)
grouplc.long$group <- factor(grouplc.long$group, level=3:1)
# remove NA's introduced using group option in sorter
grouplc.long <- na.omit(grouplc.long) 
library(ggplot2)
ggplot(grouplc.long, aes(x=time, y=id, fill=score)) + 
  geom_tile(colour="transparent") +
  scale_fill_manual(values=cols) +
  facet_grid(group ~ ., space="free_y", scales="free_y")

### sort with a grouping variable and events and plot
times <- c(1,100,200,300,400,500,600)
set.seed(45962)
events <- matrix(sample(1:3, nrow(example3)*2, replace=TRUE), nrow(example3), 2)
set.seed(23498)
event.times <- matrix(sample(min(times):max(times), nrow(example3)*2, replace=TRUE), 
nrow(example3), 2)
labels <- c('Street', 'Drug Tx', 'Jail', 'Prison', 'Unknown')
eventLabels=c('Arrest', 'Drug Test', 'Hearing')
eventlc <- longCat(example3, times=times, Labels=labels,  
              events=events, event.times=event.times, 
              eventLabels=eventLabels)
set.seed(4290)              
groupevent <- sample(1:3, nrow(example3), replace=TRUE)
groupeventlc <- sorter(eventlc, group=groupevent)            
par(mfrow=c(1,1), bg='cornsilk3', mar=c(5.1, 4.1, 4.1, 12.1), xpd=TRUE)
cols <- longCatPlot(groupeventlc, legendBuffer=0, groupBuffer=0.15, 
                    main='Grouping and Events')
legend(610, 130, legend=groupeventlc$Labels, lty=1, col=cols, lwd=2)
legend(610, 60, legend=groupeventlc$eventLabels, 
       pch=1:length(groupeventlc$eventLabels))
par(bg='transparent', mar = c(5, 4, 4, 2) + 0.1, xpd=FALSE)