xyplot {flowViz} | R Documentation |
These functions create Trellis scatter plots (a.k.a. dot plots in the Flow Cytometry community) from flow cytometry data.
## 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, ...)
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. |
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.
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
functionstype
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.
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. 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
. 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. 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
. 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.
F. Hahne, D. Sarkar
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.
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)