sorter: General Sorting Function

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 = 10)

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$data 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$data for sorting purposes? See norpt.

customSort

a vector of the same length as the number of rows in lc$data 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$data can be sorted without calling sorter using lc$data.sorted <- lc$data[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$data indicating group membership. Default is NULL. If group is NA, corresponding rows in lc$data 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 or greater. The number blank rows to be plotted between groups when group is specified. As the number of rows in lc$%data becomes large, ggap will also need to become larger than the default of 10 to ensure sufficient visual separation of groups in plots produced by longCatPlot.

Value

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

References

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

Examples

Run this code

# create a plot like that in Figure 3 from Tueller, Van Dorn, & Bobashev (2013)
par(mfrow=c(1,2), bg='cornsilk3')
times <- c(1,100,200,300,400,500)
f3lc <- longCat(example3, times); f3lc$sorted <- TRUE; f3lc$data.sorted <- f3lc$data
longCatPlot(f3lc, main='Unsorted', colScheme='heat', lwd=2)
f3lc <- longCat(example3, times)
longCatPlot(f3lc, main='Sorted', colScheme='heat', lwd=2)

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