plotbraids: plotbraids

In VizOR: Graphical Visualization Tools for Complex Observational Data with Focus on Health Sciences

Description

Braided streams plot for cohort visualization

Usage

plotbraids(formula, data, idvar = "id", stratify = FALSE, steps = 1:3,
  color.by = paste(formula[[2]], 1, sep = "."), outside = FALSE,
  xlab = NULL, ..., x.scales.labels = paste(formula[[2]], steps, sep = "."),
  x.scales = list(alternating = FALSE, relation = "same", labels =
  x.scales.labels, at = seq(length(steps)) - 0.5), scales = list(x = x.scales,
  y = list(draw = FALSE, relation = "free")), strip = TRUE,
  lattice.options = list(axis.padding = list(numeric = 0, factor = 0)))

Arguments

formula	A formula of the form trt ~ seq or trt ~ seq | cond, where trt is a treatment factor, seq is an integer sequence number, and the optional cond is a conditioning factor used to trellis the braided stream plot. Probably only two-valued conditioning factors will produce visually acceptable plots.
data	A data frame with columns named on the LHS and RHS of argument formula
idvar	A character vector naming columns of data that identify multiple records from the same individual, used to reshape data into wide form
stratify	A logical value, indicating whether whitespace should be introduced to stratify the braids by initial treatment
steps	Which values of the sequence number should be included in the plot. Presently, only vectors of the form 1:n (for some integer n) are supported.
color.by	The name of a factor by which individuals are to be tracked into colored braids. This may as a special case be one of the seq.<step> factors in the constructed wide data table.
outside	A logical value determining whether the state labels are to appear outside the panel.
xlab	x-axis label
x.scales.labels	Labels for the treatment states
x.scales	Provides a hook for modifying the basically sensible default layout and labeling of the x-axis
scales	Provides a hook for modifying the basically sensible default layout of both x- and y-axes
strip	Allows user to provide a strip function if the default does not suffice
lattice.options	Allows specification of plot-specific lattice options
...	Additional arguments passed to delegates

Details

Displays 'paths' taken by individuals passing through a sequence of discrete states, such as a sequence of treatments.

Value

A trellis plot object

Author(s)

David C. Norris

Examples

## We demonstrate a simple braided stream plot based on the built-in occupationalStatus data set.
## It should be noted that the semantics of these data are very slightly at odds with the intended
## application of the braided stream plot, since the index cases in this data set were the _sons_,
## rather than the fathers. Thus, although time goes left-to-right in this figure, the streamlines
## run right-to-left epidemiologically. Notwithstanding this minor technicality, the figure gives
## a lively, compelling and meaningful visualization of these data.
## 1. Build a 'wide-form' data set from the table 'occupationalStatus'
df.wide <- data.frame(status.1=rep(1:8, 8),
                      status.2=rep(1:8, each=8),
                      N=as.vector(occupationalStatus))
df.wide <- df.wide[rep(1:64, times=df.wide$N),-3]
## 2. Reshape this to the 'long-form' data set expected by 'plotbraids'
df.long <- reshape(df.wide, varying=paste("status", 1:2, sep="."), direction="long", timevar="gen")
df.long <- df.long[order(df.long$id),]
## TODO: Generate appropriate 'class' labels for status.
## TODO: Use this opportunity to demonstrate meaningful application of a colored factor.
## 3. Plot the braided stream plot
plotbraids(status ~ gen, df.long, stratify=TRUE, steps=1:2,
           outside=TRUE, xlab="Generation",
           x.scales.labels=c("Father","Son"))

VizOR documentation built on May 30, 2017, 5:29 a.m.