flowViz (version 1.36.2)

xyplot,flowFrame,missing-method: 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

## S3 method for class 'flowFrame,missing':
xyplot(x, data, time, xlab, ylab = "", layout,
  prepanel = prepanel.xyplot.flowframe.time,
  panel = panel.xyplot.flowframe.time, type = "discrete", ...)
prepanel.xyplot.flowframe.time(x, y, frame, time, xlim, ylim, ...)
panel.xyplot.flowframe.time(x, y, frame, time, type = "discrete",
  nrpoints = 0, binSize = 100, ...)
## S3 method for class 'formula,flowFrame':
xyplot(x, data, filter = NULL, overlay = NULL,
  stats = FALSE, strip.text = NULL, ...)
prepanel.xyplot.flowframe(frame, channel.x.name, channel.y.name, x, y, xlim,
  ylim, ...)
panel.xyplot.flowframe(frame, filter = NULL, smooth = TRUE, margin = TRUE,
  outline = FALSE, channel.x.name, channel.y.name, pch = gp$flow.symbol$pch,
  alpha = gp$flow.symbol$alpha, cex = gp$flow.symbol$cex,
  col = gp$flow.symbol$col, gp, xbins = 0, binTrans = sqrt,
  stats = FALSE, pos = 0.5, digits = 2, abs = FALSE, overlay = NULL,
  checkName = TRUE, sample.ratio = 1, overlay.symbol = NULL, ...)
## S3 method for class 'formula,flowSet':
xyplot(x, data, ...)
prepanel.xyplot.flowset(x, frames, channel.x.name, channel.y.name, xlim, ylim,
  ...)
panel.xyplot.flowset(x, frames, filter = NULL, channel.x, channel.y,
  overlay = NULL, stats = FALSE, ...)
## S3 method for class 'formula,view':
xyplot(x, data, ...)
## S3 method for class 'view,missing':
xyplot(x, data, ...)
## S3 method for class '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.

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.

prepanel

The prepanel function. See xyplot.

panel

The panel function. See xyplot.

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.

xlim,ylim

limits for data axes. If not given, they are taken from the ranges stored in flowFrame

nrpoints

The number of points plotted on the smoothed plot in sparse regions. This is only listed here because we use a different default. See panel.smoothScatter for details.

binSize

The size of a bin (i.e., the number of events within a bin) used for the smoothed average timeline plots.

filter

A filter, filterResult or filterResultList object or a list of such objects of the same length as the flowSet. Also a filters or A filtersList can be passed to xyplot in order to plot multiple filters/gates(with the same x,y parameters) on one panel to represent multiple sub-populations. The appropriate spherical 2D representation of this filter will be superimposed on the plot if smooth=TRUE, or the result 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).

overlay

The extra cell events plotted on top of the current cell population. It is a flowSet for panel.xyplot.flowset function and a flowFrame for xyplot(c("formula","flowFrame")) method.

stats,pos,digits,abs

Arguments to control statistics that is associated with filter to be plotted Currently only population proportion/percentage is supported. stats is a logical scalar indicating whether to display statistics. Default is FALSE. pos is the numeric scalar (range within c(0,1)) or vector(length of 2,first is for x-axis,second for y-axis) to control the position of the statistics label. It is set as 0.5,which is the center. digits is an integer indicating the number of significant digits to be used when displaying the percentage of population statistics,Default is 2. see more details from format abs is a logical scalar indicating whether the pos is relative to the gate boundary or the entire xy-axis(absolute position). By default it is set as FALSE,which indicates the position is relative to gate.

strip.text

A character that customizes the text in strip. Default is NULL, which does not display the strip box at all. It is only valid when plotting a flowFrame

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. If FALSE, a graphical parameter colramp can be used to obtain a coloring of points that is indicative of their local density.

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.

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.

xbins

The argument passed to hexbin ,which is the number of bins partitioning the range of xbnds. It is set as 0 by default,which plots all the events without binning. When it is larger than 0,hexbin plot engine is used for the faster plotting. Note that it is only valid when smooth is set as FALSE .

binTrans

The argument passed to grid.hexagons ,which is a transformation function (or NULL) for the count. It is sqrt by default.

checkName

logical indicating whether to skip checking the bracket '(' in channel name

sample.ratio

numeric the ratio of sub-sampling of events to speed up plotting.

overlay.symbol

list of the lattice graphic parameters to format the overlay points.

frames

An environment containing frame-specific data.

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.

par.settings

A list of lists of graphical parameters. See flowViz.par.set for details.

...

marker.only logical specifies whether to show both channel and marker names

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 syntactically 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.

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)

## A non-smooth version of the same data with customerized color scheme
require(IDPmisc)
colramp <- colorRampPalette(IDPcolorRamp(21))
xyplot(`FSC-H` ~ `SSC-H`, GvHD[["s5a05"]], nbin = 100,
       main="A single flowFrame", smooth=FALSE,
       colramp=colramp, pch=20, cex=0.1)

## A hexbin version of non-smooth scatter plot
xyplot(`FSC-H` ~ `SSC-H`, GvHD[["s5a05"]], xbin = 128
       ,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)

## Same bivariate scatter plot with replacing default color
require(IDPmisc)
cols <- colorRampPalette(IDPcolorRamp(21))
xyplot(`SSC-H` ~ `FSC-H` | Patient:Visit, data = GvHD, colramp=cols)

## 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), xbin = 32)

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


## 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), xbin = 32)

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), xbin = 32)

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, xbin = 32)


## displaying filters with stats
n2gate.results <- filter(GvHD, n2gate)

xyplot(`SSC-H` ~ `FSC-H` | Visit, data=GvHD,
       subset=Patient == "6",
       filter=n2gate.results, smooth=FALSE, xbin = 32
       ,stats=TRUE
       ,abs=TRUE
       ,digits=3
       )


## displaying multiple filters in one panel with stats
recGate1<-rectangleGate("FL3-H"=c(2.3,4.1),"FL2-H"=c(6.8,9))
recGate2<-rectangleGate("FL3-H"=c(1,3),"FL2-H"=c(4,6))
filters1<-filters(list(recGate1,recGate2))
trans<-transform("FL2-H"=asinh,"FL3-H"=asinh)
trans_data<-transform(GvHD[1:2],trans)
#replicate filters object across samples
flist <- list(filters1 , filters1)
names(flist) <- sampleNames(trans_data)
xyplot(`FL2-H` ~ `FL3-H`
	   ,data=trans_data
       ,filter= flist
       ,stats=TRUE
       ,margin=FALSE
       , xbin = 32
       , smooth = FALSE
       )

#display recGate2 as a overlay
overlay <- Subset(trans_data,recGate1)
xyplot(`FL2-H` ~ `FL3-H`
	   ,data=trans_data
       ,filter=recGate2
       ,stats=TRUE
       ,margin=FALSE
       , smooth = FALSE
       , xbin = 32
       ,overlay= list(rect2 = overlay)
       ,par.settings = list(overlay.symbol = list(cex = 0.1))
       )