smaffiol / ggcyto

Visualize Cytometry data with ggplot2

title	output	vignette
ggcyto : Visualize `Cytometry` data with `ggplot`	html_document fig_height fig_width keep_md 1 1 true	%\VignetteEngine{knitr::rmarkdown} %\VignetteIndexEntry{Feature summary of ggcyto}

ggcyto is a cytometry data visualization tool built around ggplot and the grammar of graphics paradigm. The software extends the popular ggplot2 framework, already familiar to many data scientists, enabling it to recog-nize the core Bioconductor flow cytometry data structures for gated and annotated cytometry data. It simplifies visualization and plotting of flow data for publication quality graphics.

There are three ways to construct the ggcyto plots. Each represents a different level of complexity and flexibility. They meet the needs of various plot applications and thus are suitable for users at different levels of coding skills.

Quick plot

This inherits the spirit from ggplot's Quick plot, which simplies the plotting job by hiding more details from users and taking more assumptions for the plot.

• see autoplot

More flexibility with ggcyto wrapper

ggcyto constructor along with overloaded + operator gives user more flexibility to fine-tune the plot yet still encapsulates lots of details that might be tedious and intimidating for many users.

See more examples of ggcyto constructor here:

• ggcyto + flowSet
• ggcyto + GatingSet

Use ggplot directly to have more controls.

The package overloads ggplot's fortify S3 method so that Cytometry data structures (e.g. flowSet/flowFrame) are fully compatible with ggplot. More examples of using ggplot directly on flowSet:

• ggplot + flowSet1d
• ggplot + flowSet2d
• ggplot + flowSet + gate
• ggplot + flowSet + overlay

quick demos of some most used features

library(ggcyto)
dataDir <- system.file("extdata",package="flowWorkspaceData")
gs <- load_gs(list.files(dataDir, pattern = "gs_bcell_auto",full = TRUE))

#plot a gate by specifying the population node name (here it is 'CD3')
autoplot(gs, "CD3")

#change the resolution
p <- autoplot(gs, "CD3", bins = 64)
p

#display the transformed value at breaks label by turning off the inverse transform
autoplot(gs, "CD3", axis_inverse_trans = FALSE)

#you can switch the limits from default `instrument` to the actual `data` range
p + ggcyto_par_set(limits = "data")

# Choose between `marker` and `channel` names for axis label text
p + labs_cyto("channel") #default is "both"

# overlay another population 'IgD-CD27-' as dots on top of the existing plot
p + geom_overlay("IgD-CD27-", alpha = 0.5, size = 0.1, color = "purple")

# plot a population without gate
fs <- getData(gs, "CD20") #extract the gated data as a flowSet
autoplot(fs, "CD20", "CD19") #plot 2D

gs1 <- gs[1]
gs2 <- gs[2]
#construct the ggcyto object for gs1
p <- ggcyto(gs1, aes(cd24, cd38)) + geom_hex(bins = 128)
p <- p + geom_gate("Transitional") #add gate
#customize the stats layer
p <- p + geom_stats(type = "count", size = 6,  color = "red", fill = "green", adjust = 0.7)
#customize the layer
p <- p + labs_cyto("channel")
#customize the axis limits
p <- p + ggcyto_par_set(limits = "instrument")
#add another population as the overlay dots
p <- p + geom_overlay("IgD-CD27-", col = "black", size = 1.2, alpha = 0.4)
#hide the legend
p <- p + guides(fill=FALSE)
p

#replace the data with gs2 and see the same visual effect
p %+% gs2

autoplot(fs, "CD20") #1d density

#extract one sample as a flowFrame
fr <- fs[[1]]
#plot 1d density on all available channels
autoplot(fr)

gh <- gs[[1]] # extract a `GatingHierarchy` object for one sample
# layout multiple cell populations with their asssociated gates in the same plot.
nodes <- getNodes(gh)[c(3:9, 14)]
p <- autoplot(gh, nodes, bins = 64)
p

#arrange it as one-row gtable object
gt <- ggcyto_arrange(p, nrow = 1)
plot(gt)