xyplot {flowViz}R Documentation

Methods implementing Lattice xyplots for flow data.

Description

These functions create Trellis scatter plots (a.k.a. dot plots in the Flow Cytometry community) from flow cytometry data.

Usage

## Method for 'flowFrame' objects without a formula.
## This creates plots of all flow parameters agains
## time. 
## S4 method for signature 'flowFrame, missing':
xyplot(
    x,
    data,
    time,
    xlab,
    ylab="",
    layout,
    prepanel=prepanel.xyplot.flowframe.time,
    panel=panel.xyplot.flowframe.time,
    type="discrete",
    ...)

## prepanel function for time line plots of flowFrames
prepanel.xyplot.flowframe.time(
    x,
    y,
    frame,
    time,
    ...)

## panel function for time line plots of flowFrames
panel.xyplot.flowframe.time(
    x, 
    y,
    frame,
    time,
    type="discrete",
    nrpoints=0,
    binSize=100,
    ...)


## method for formulae with 'flowFrame' objects
## S4 method for signature 'formula, flowFrame':
xyplot(
    x,
    data,
    smooth=TRUE,
    prepanel=prepanel.xyplot.flowframe,
    panel=panel.xyplot.flowframe,
    ...)

## prepanel function for generic xyplots of flowFrames
prepanel.xyplot.flowframe(
    frame,
    channel.x.name,
    channel.y.name,
    ...)
   

## panel function for generic xyplots of flowFrames
panel.xyplot.flowframe(
    x,
    y,
    frame,
    filter=NULL,
    smooth=TRUE,
    margin=TRUE,
    outline=FALSE,
    channel.x.name,
    channel.y.name,
    pch=gpar$flow.symbol$pch,
    alpha=gpar$flow.symbol$alpha,
    cex=gpar$flow.symbol$cex,
    col=gpar$flow.symbol$col,
    gp,
    ...)


## method for 'flowSet' objects
## S4 method for signature 'formula, flowSet':
xyplot(
    x,
    data,
    xlab,
    ylab,
    as.table=TRUE,
    prepanel=prepanel.xyplot.flowset,
    panel=panel.xyplot.flowset,
    pch = ".",
    smooth = TRUE,
    filter = NULL,
    par.settings=NULL,
    ...)

## prepanel function for generic xyplots of flowSets
prepanel.xyplot.flowset(
    x,
    frames,
    channel.x.name,
    channel.y.name,
    ...)

## panel function for generic xyplots of flowSets
panel.xyplot.flowset(
    x,
    frames,
    filter=NULL,
    channel.x,
    channel.y,
    ...)

## method for various workflow objects
## S4 method for signature 'formula, view':
xyplot(
    x,
    data,
    ...)

## S4 method for signature 'view, missing':
xyplot(
    x,
    data,
    ...) 

## S4 method for signature 'formula, gateView':
xyplot(
    x,
    data,
    filter=NULL,
    par.settings,
    ...)

Arguments

x A formula describing the structure of the plot and the variables to be used in the display. In the prepanel and panel functions, also the names of flowFrames or any of the annotation data columns in the phenoData slot.
data, y, frame a flowSet or flowFrame object that serves as the source of data. For the workflow methods, this can also be various view or actionItem objects.
time A character string giving the name of the data column recording time. If not provided, we try to guess from the available parameters.
xlab, ylab Labels for data axes, with suitable defaults taken from the formula.
as.table, layout These arguments are passed unchanged to the corresponding methods in lattice, and are listed here only because they provide different defaults. See documentation for the original methods for details.
type type of rendering; see panel.xyplot for details. For the basic flowFrame method without a detailed formula, the addtional type discrete is available, which plots a smoothed average of the flow cytometry values against time.
nrpoints
binSize
channel.x.name, channel.y.name Character strings giving corresponding names used to match filter parameters if applicable.
smooth Logical. If TRUE, panel.smoothScatter is used to display a partially smoothed version of the data. Otherwise, events are plotted individually, as in a standard scatter plot.
filter A filter, filterResult or filterResultList object or a list of such objects of the same length as the flowSet. The appropriate spherical 2D representation of this filter will be superimposed on the plot if smooth=TRUE, or the resukt of the filtering operation will be indicated by grouping if smooth=FALSE . The software will figure out whether the filter needs to be evaluated in order to be plotted (in which case providing a filterResult can speed things up considerably).
margin Logical indicating whether to truncate the density estimation on the margins of the measurement range and plot margin events as lines if smooth=TRUE. To avoid visual artifacts it is highly recommended to set this option to TRUE.
outline Logical, specifying whether to add the boundaries of a gate to the plot when smooth=FALSE in addition to the grouping. Defaults to FALSE.
pch, cex, col, alpha Graphical parameters used when smooth=FALSE. These mostly exist for conveniance and much more control is available throught the lattice-like par.setting and flowViz.par.set customization. See flowViz.par.set for details.
par.settings A list of lists of graphical parameters. See flowViz.par.set for details.
gp A list of graphical parameters that are passed down to the low level panel functions. This is for internal use only. The public user interface to set graphical parameters is either par.settings for customization of a single call or flowViz.par.set for customization of session-wide defaults.
prepanel The prepanel function. See xyplot.
panel The panel function. See xyplot.
channel.x, channel.y Expressions defining the x and y variables in terms of columns in the data. Can involve functions or multiple columns from the data, however this usage is discouraged.
frames An environment containing frame-specific data.
... More arguments, usually passed on to the underlying lattice methods.

Details

The implementation of xyplot in flowViz is very close to the original lattice version. Concepts like conditioning and the use of panels apply directly to the flow cytometry data. The single fundamental difference is that conditioning variables are not evaluated in the context of the raw data, but rather in the phenoData slot environment (only for the flowSet methods. Thus, we can directly condition on pheotypic variables like sample groups, patients or treatments.

In the formula interface, the primary and secondary variables (separated by the tilde) have to be valid parameter names. Please note that frequently used variants like FSC-H and SSC-H are not syntatically correct R symbols, and need to be wrapped in `. E.g., `FSC-H`. For flowSets, the use of a conditioning variable is optional. We implicitely condition on flowFrames and the default is to arrange panels by sample names.

Methods

xyplot
signature(x = "flowFrame", data = "missing"): Creates diagnostic time series plots of flow parameter values against time. These plots are useful to detect quality issues in the raw data. If not provided explicitely via the tine argument, the time parameter will be automatically detected. The additional arguments xlab, ylab, nrpoints, and layout are only listed because flowViz provides different defaults. Internally, they are directly passed on to the underlying lattice functions
. Argument type can be a combination of any of the types allowed in lattice xyplots, or discrete, in which case a smoothed average of the parameter against time is plotted. binSize controls the binning that is used for the smoothing procedure.

xyplot
signature(x = "formula", data = "flowFrame"): Creates scatter plots (a.k.a. dot plots) of a pair of FCM channels. Depending on the setting of the smooth argument, the data will be rendered as a partially smoothed density estimate (smooth=TRUE, the default) or as a regular scatter plot with separate points for individual events. The formula interface allows for fairly general plotting, however there are certain limitations on the use of expressions as part of the formulae. Unless you are sure about what you are doing, you should transform the raw data in a separate step using one of the tools in the flowCore package rather than inline using the formula interface. The method allows to superimpose gating results though the filter argument. If smooth=TRUE, we try to add spherical 2D representations of the gates if applicable. For smooth=FALSE, gates are indicated by a grouping mechanism using different point shapes or colors (unless outline is also TRUE, in which case the gate outlines are superimposed in addition to the grouping). Argument margins controls how events on the margins of the measurement range are treated. The default (TRUE) is to discard them from any density estimation and later add them as separate glyphs. See flowViz.par.set for details on controlling graphical parameters in these plots.
xyplot
signature(x = "formula", data = "flowSet"): Scatter plots from a flowSet object. We allow for conditioning on variables in the phenoData slot of the flowSet. All additional arguments that apply to the flowFrame method are also valid for flowSets.
xyplot
signature(x = "formula", data = "view"): Scatter plots from a view object. Depending on the particulars of the view, the method tries to come up with reasonable defaults. Full customization is also available though all the before mentioned arguments.
xyplot
signature(x = "view", data = "missing"): Scatter plots from a view object. This is the fallback method in the case of absolutely no customization. It serves as the default plot method for all views.
xyplot
signature(x = "formula", data = "gateView"): Scatter plots from a gateView object. This allows for customization of the gateView plots but still provides reasonable defaults, e.g., for added gates.

Author(s)

F. Hahne, D. Sarkar

See Also

Not all standard lattice arguments will have the intended effect, but many should. For a fuller description of possible arguments and their effects, consult documentation on lattice.

Examples


data(GvHD)
GvHD <- GvHD[pData(GvHD)$Patient %in% 5:6]

## a bivariate scatterplot
## by default ('smooth=TRUE') panel.smoothScatter is used
xyplot(`FSC-H` ~ `SSC-H`, GvHD[["s5a05"]], nbin = 100,
main="A single flowFrame")

## A non-smooth version of the same data
xyplot(`FSC-H` ~ `SSC-H`, GvHD[["s5a05"]], nbin = 100,
main="A single flowFrame", smooth=FALSE)

## Visual artifacts created by the pileup of margin events
xyplot(`FSC-H` ~ `SSC-H`, GvHD[["s5a05"]], nbin = 100,
main="A single flowFrame", margin=FALSE)

## simple bivariate scatter plot (a.k.a. dot plot)
## for the whole flowSet, conditioning on Patient and
## Visit
xyplot(`SSC-H` ~ `FSC-H` | Patient:Visit, data = GvHD)

## several examples with time on the X axis
## first for a flowFrame
xyplot(GvHD[[1]])

## and for flowSets
xyplot(`FSC-H` ~ Time | Visit, GvHD, 
       smooth = FALSE, type = "l", 
       subset = (Patient == 5))

xyplot(`FSC-H` ~ Time | Patient+Visit, GvHD, 
       smooth = FALSE, type = "a",
       strip = FALSE, strip.left = TRUE,
       aspect = "xy")

## combine plots for two channels
ssc.time <- 

    xyplot(`SSC-H` ~ Time | factor(Patient):factor(Visit), GvHD, 
           smooth = FALSE, type = "a",
           strip = FALSE,
           strip.left = strip.custom(horizontal = TRUE),
           par.strip.text = list(lines = 3),
           between = list(y = rep(c(0, 0.5), c(6, 1))),
           scales = list(x = list(axs = "i"), y = list(draw = FALSE)),
           layout = c(1, 14))

fsc.time <- 
    xyplot(`FSC-H` ~ Time | factor(Patient):factor(Visit), GvHD, 
           smooth = FALSE, type = "a",
           strip = FALSE,
           strip.left = strip.custom(horizontal = TRUE),
           par.strip.text = list(lines = 3),
           between = list(y = rep(c(0, 0.5), c(6, 1))),
           scales = list(x = list(axs = "i"), y = list(draw = FALSE)),
           layout = c(1, 14))

plot(fsc.time, split = c(1, 1, 2, 1))
plot(ssc.time, split = c(2, 1, 2, 1), newpage = FALSE)

## saving plots as variables allows more manipulation
plot(update(fsc.time[8:14], layout = c(1, 7)),
     split = c(1, 1, 1, 2))

plot(update(ssc.time[8:14], layout = c(1, 7)),
     split = c(1, 2, 1, 2), newpage = FALSE)

## displaying filters
n2gate <- norm2Filter("SSC-H", "FSC-H")

xyplot(`SSC-H` ~ `FSC-H` | Patient:Visit, data = GvHD,
       filter=n2gate, subset=Patient==5)

xyplot(`SSC-H` ~ `FSC-H` | Patient:Visit,
       data=transform("SSC-H"=asinh,"FSC-H"=asinh) %on% GvHD,
       smooth=FALSE, filter=n2gate, subset=Patient==5)

n2gate.results <- filter(GvHD, n2gate)

xyplot(`SSC-H` ~ `FSC-H` | Visit, data=GvHD,
       subset=Patient == "6",
       filter=n2gate.results, smooth=FALSE)
[Package flowViz version 1.6.2 Index]