How to plot gated data

Usage

plotGate(x, y, ...)

Arguments

x
GatingSet or GatingHierarchy object

y
character the node name (in the form of full or partial gating path) or numeric representing the node index in the GatingHierarchy. or missing which will plot all gates.

other arguments

Examples

plot gating tree

# plot the entire gating tree
plot(gs)
# plot a sub-tree
plot(gs, "CD3+")
plot(gs, "CD4")

plot of chunk unnamed-chunk-3plot of chunk unnamed-chunk-3plot of chunk unnamed-chunk-3

plotGate

Change resolution

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

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

# default xbin = 32      
plotGate(gs[[1]], "CD4/38+ DR+", main = "default (xbin = 32)") 
# increase the resolution
plotGate(gs[[1]], "CD4/38+ DR+", xbin = 128, main = "xbin = 128") 
# have the highest resolution by disabling hexbin 
plotGate(gs[[1]], "CD4/38+ DR+", xbin = 0, main = "xbin = 0 (no binning)") 
# speed up plotting by sub-sampling the data points
# most of them it is subsampled data is sufficient to represent the 
# population distribution
plotGate(gs[[1]], "CD4/38+ DR+", sample.ratio = 0.4, main = "sample.ratio = 0.4") 

plot of chunk unnamed-chunk-4plot of chunk unnamed-chunk-4plot of chunk unnamed-chunk-4plot of chunk unnamed-chunk-4

Change strip text

strip specifies whether to show pop name in strip box,only valid when x is GatingHierarchy

path A character or numeric scalar passed to getNodes method (used to control how the gating/node path is displayed)

# hide the strip
plotGate(gs[[1]], "CD4/38+ DR+", strip = FALSE, main = "strip = FALSE")       
# change the gating path length in strip 
plotGate(gs[[1]], "CD4/38+ DR+", path = "full", main = "path = 'full'")
plotGate(gs[[1]], "CD4/38+ DR+", path = 2, main = "path = 2")

plot of chunk unnamed-chunk-5plot of chunk unnamed-chunk-5plot of chunk unnamed-chunk-5

Change statistics

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.

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.

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

# hide the pop stats
plotGate(gs[[1]], "CD4/38+ DR+", stats = FALSE, main = "stats = FALSE")
# adjust the location, size, background of the stats
plotGate(gs[[1]], "CD4/38+ DR+"
                , pos = c(0.6, 0.9)
                , digits = 4
                , par.settings = list(gate.text = list(background = list(fill = "yellow") #stats background
                                                        , cex = 2 #stats font size

                                                      )
                                      )
         )

plot of chunk unnamed-chunk-6plot of chunk unnamed-chunk-6

Change the scale and label text of x,y axis

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

raw.scale whether to show the axis in raw(untransformed) scale

xlim, ylim can be either “instrument” or “data” which determines the x, y axis scale either by instrument measurement range or the actual data range. or numeric which specifies customized range.

# show the tranformed scale instead of raw scale
plotGate(gs[[1]], "CD4/38+ DR+", raw.scale = FALSE, main = "raw.scale = FALSE")
# use the actual data range instead of instrument range
plotGate(gs[[1]], "CD4/38+ DR+", xlim = "data", ylim = "data", main = "xlim = 'data'")       
# zooming by manually set xlim and ylim
plotGate(gs[[1]], "CD4/38+ DR+", xlim = c(1000, 4000), ylim = c(1000, 4000), main = "xlim = c(1000, 4000)")       
# hide the channel names and only show the marker names in x,y labs
plotGate(gs[[1]], "CD4/38+ DR+", marker.only = TRUE, main = "marker.only = TRUE")      

plot of chunk unnamed-chunk-7plot of chunk unnamed-chunk-7plot of chunk unnamed-chunk-7plot of chunk unnamed-chunk-7

Change the lattice graphic settings of plots

par.settings list of graphical parameters passed to lattice;

# change the gate color and width
plotGate(gs[[1]], "CD4/38+ DR+"
                , par.settings = list(gate = list(col = "black"
                                                  , lwd = 3
                                                  , lty = "dotted")
                                      )
         )
# change the panel background and axis label size
plotGate(gs[[1]], "CD4/38+ DR+"
                , par.settings = list(panel.background = list(col = "white")
                                    , par.xlab.text = list(cex = 1.5)
                                    , par.ylab.text = list(cex = 1.5)
                                    , axis.text = list(cex = 1.5)
                                      ) 
         )

plot of chunk unnamed-chunk-8plot of chunk unnamed-chunk-8

Overlay the popluations

overlay indicating the index of a gate/populationwithin the GatingHierarchy or a logical vector that indicates the cell event indices representing a sub-cell population. This cell population is going to be plotted on top of the existing gates(defined by y argument) as an overlay.

# display one population as an overlay on top of another population      
plotGate(gs[[1]], "CD4/CCR7- 45RA+", overlay = "CD4/38+ DR+")
#adjust the overlay symbol
plotGate(gs[[1]], "CD4/CCR7- 45RA+"
              , overlay = "CD4/38+ DR+"
              , par.settings = list(overlay.symbol = list(cex = 0.1
                                                          , fill = "black" 
                                                          , bg.alpha = 0.1 #dim the background density
                                                          )
                                    )
         )
#add multiple overlays
plotGate(gs[[1]], "CD4/CCR7- 45RA+"
              , overlay = c("CD4/CCR7+ 45RA+", "CD4/CCR7+ 45RA-")
              , par.settings = list(overlay.symbol = list(cex = 0.05, bg.alpha = 0.1))
         )
# customize the symbol and legend
plotGate(gs[[1]], "CD4/CCR7- 45RA+"
              , overlay = c("CD4/CCR7+ 45RA+", "CD4/CCR7+ 45RA-")
              , par.settings = list(overlay.symbol = list(cex = 0.05, bg.alpha = 0.1))
              , overlay.symbol = list(`CCR7+ 45RA+` = list(fill = "black") #this overwrite the par.settings
                                      , `CD4/CCR7+ 45RA-` = list(fill = "darkgreen")
                                      )
              , key = list(text = list(c("CCR7+ 45RA+", "CCR7+ 45RA-")) # add legend
                          , points = list(col = c("black", "darkgreen"), pch = 19, cex = 0.5)
                          , columns = 2
                           )
         )

plot of chunk unnamed-chunk-9plot of chunk unnamed-chunk-9plot of chunk unnamed-chunk-9plot of chunk unnamed-chunk-9

plot multiple populations

merge logical indicating whether to draw multiple gates on the same plot if these gates share the same parent population and same x,y dimensions/parameters;

arrange.main The title of the main page of the plot. Default is the sample name. Only valid when x is GatingHierarchy

gpar list of grid parameters passed to grid.layout;

arrange logical indicating whether to arrange different populations/nodes on the same page via grid.arrange call.

projections list of character vectors used to customize x,y axis. By default, the x,y axis are determined by the respective gate parameters. The elements of the list are named by the population name or path (see y). Each element is a pair of named character specifying the channel name(or marker name) for x, y axis. Short form of channel or marker names (e.g. “APC” or “CD3”) can be used as long as they can be uniquely matched to the dimentions of flow data. For example, projections = list("lymph" = c(x = "SSC-A", y = "FSC-A"), "CD3" = c(x = "CD3", y = "SSC-A"))

# plot multiple populations (gates are merged into same panel if they share the same parent and projections)      
plotGate(gs[[1]], c("CD4", "CD8"))      
# flip the projection
plotGate(gs[[1]], c("CD4", "CD8"), projections = list("CD4" = c(x = "CD8", y = "CD4")))      
# dot not merge the gates
plotGate(gs[[1]], c("CD4", "CD8"), merge = FALSE) 
# use gpar to change layout 
# use arrange.main to change the default title
plotGate(gs[[1]], c("CD4", "CD8"), merge = FALSE, gpar = list(nrow = 1), arrange.main = "CD4 vs CD8")      

plot of chunk unnamed-chunk-11plot of chunk unnamed-chunk-11plot of chunk unnamed-chunk-11plot of chunk unnamed-chunk-11

# or return populations as individual trellis objects
#and arrange them manually
latticeObjs <- plotGate(gs[[1]], c("CD4", "CD8"), merge = FALSE, arrange = FALSE)      
do.call(grid.arrange, c(latticeObjs, nrow = 1, main = "Tcell subsets"))

Facetting on study variables

cond the conditioning variable to be passed to lattice plot.

# condition on `Stim` and `PTID`
plotGate(gs, "CD4/38+ DR+", cond = "Stim+PTID")
# to put the second condition variable to the y axis
latticeExtra::useOuterStrips(plotGate(gs, "CD4/38+ DR+", cond = "Stim+PTID"))

plot of chunk unnamed-chunk-14plot of chunk unnamed-chunk-14

Plot 1-d gate

type either xyplot or densityplot. Default is xyplot default.y specifiying y channel for xyplot when plotting a 1d gate. Default is SSC-A. fitGate used to disable behavior of plotting the gate region in 1d densityplot stack whether to stack all samples (vetically) in one panel

plotGate(gs[c(1,3)], "CD3+") 
# change the default y axis
plotGate(gs[c(1,3)], "CD3+", default.y = "<B710-A>") 
# change the plot type
plotGate(gs[c(1,3)], "CD3+", type = "densityplot") 
# fit the 1d gate onto 1d density 
plotGate(gs[c(1,3)], "CD3+", type = "densityplot", fitGate = TRUE) 
# stack them together
plotGate(gs[c(1,3)], "CD3+", type = "densityplot", stack = TRUE) 

plot of chunk unnamed-chunk-15plot of chunk unnamed-chunk-15plot of chunk unnamed-chunk-15plot of chunk unnamed-chunk-15plot of chunk unnamed-chunk-15

Plot all the gates

plotGate(gs[[3]], gpar = list(nrow = 2))

plot of chunk unnamed-chunk-16