Visualize flowSet with ggcyto

1d histogram/densityplot

ggcyto wrapper will construct the ggcyto object that inherits from ggplot class.

p <- ggcyto(fs, aes(x = `FSC-H`)) 
class(p)

## [1] "ggcyto_flowSet"  "ggcyto"          "ggplot2::ggplot" "ggplot"         
## [5] "ggplot2::gg"     "S7_object"       "gg"

is(p, "ggplot")

## [1] TRUE

Since only one dimension is specified, we can add any 1d geom layer

p1 <- p + geom_histogram() 
p1

As shown, data is facetted by samples name automatically (i.e facet_wrap(~name)).

We can overwrite the default faceting by any variables that are defined in pData

pData(fs)

##       Patient Visit Days Grade  name
## s5a05       5     5   19     3 s5a05
## s5a06       5     6   26     3 s5a06
## s6a05       6     5   19     3 s6a05
## s6a06       6     6   27     3 s6a06
## s7a05       7     5   21     3 s7a05
## s7a06       7     6   28     3 s7a06

p1 + facet_grid(Patient~Visit)

To display 1d density

p + geom_density()

Fill the same color

p + geom_density(fill = "black")

Fill different colors

ggcyto(fs, aes(x = `FSC-H`, fill = name)) + geom_density(alpha = 0.2)

Or plot in the same panel by using ggplot directly (thus removing the default facetting effect)

ggplot(fs, aes(x = `FSC-H`, fill = name)) + geom_density(alpha = 0.2)

stacked density plot

#you can use ggridges package to display stacked density plot
require(ggridges)
#stack by fcs file ('name')
p + geom_density_ridges(aes(y = name)) + facet_null() #facet_null is used to remove the default facet_wrap (by 'name' column)

#or to stack by Visit and facet by patient
p + geom_density_ridges(aes(y = Visit)) + facet_grid(~Patient)

2d scatter/dot plot

# 2d hex
p <- ggcyto(fs, aes(x = `FSC-H`, y =  `SSC-H`))
p <- p + geom_hex(bins = 128)
p

A default scale_fill_gradientn is applied to 2d hexbin plot.

To add limits

p <- p + ylim(c(10,9e2)) + xlim(c(10,9e2))   
p

To overwrite the default fill gradien

p + scale_fill_gradientn(colours = rainbow(7), trans = "sqrt")

p + scale_fill_gradient(trans = "sqrt", low = "gray", high = "black")

Add geom_gate and geom_stats layers

Firstly we create an ellipsoidGate with a data-driven method provided by flowStats package.

# estimate a lymphGate (which is an ellipsoidGate) for each sample
lg <- flowStats::lymphGate(fs, channels=c("FSC-H", "SSC-H"),scale=0.6)
# apply the ellipsoidGates to their corresponding samples
fres <- filter(fs, lg)

Then pass the gates to the gate layer

p + geom_gate(lg)

We can also plot the rectangleGate, this time we simply replicate a static gate across samples:

rect.g <- rectangleGate(list("FSC-H" =  c(300,500), "SSC-H" = c(50,200)))
rect.gates <- sapply(sampleNames(fs), function(sn)rect.g)

Similarly, supply the list of gates to the geom_gate layer

p + geom_gate(rect.gates)

Stats layer can be added on top of gate

p + geom_gate(rect.gates) + geom_stats(size = 3)

The percentage of the gated population over its parent is displayed as geom_label. Alternatively cell count can be displayed by setting type argument in geom_stats function.

Here is another example of displaying the 1d gate generated by the automated gating method gate_mindensity from openCyto package.

den.gates.x <- fsApply(fs, openCyto::gate_mindensity, channel = "FSC-H", gate_range = c(100, 300), adjust = 1)
p + geom_gate(den.gates.x) + geom_stats()

geom_gate layer supports the 1d gate on either dimension, which means it automatically determines between the vertical or horizontal lines based on the gate dimension and given aes.

den.gates.y <- fsApply(fs, openCyto::gate_mindensity, channel = "SSC-H", gate_range = c(100, 500), adjust = 1, positive = FALSE)

p + geom_gate(den.gates.y) + geom_stats(value = lapply(rect.gates, function(g)0.1))

Here we also demenstrated the option of passing the precalculated arbitary stats value to geom_stats lay instead of letting it compute on the fly,

We can also put the 1d gate on density plot

ggcyto(fs, aes(x = `FSC-H`)) + geom_density(fill = "black", aes(y = ..scaled..)) + geom_gate(den.gates.x)  + geom_stats(type = "count")

Without supplying data for geom_stats, we add stats layer for all the gate layers implicitly

p + geom_gate(lg) + geom_gate(rect.gates) + geom_stats(size = 3)

Or we can add stats layer specificly just for one of the gate layer

p + geom_gate(lg) + geom_gate(rect.gates) + geom_stats(gate = lg, size = 3)

Although ggcyto object is fully ggplot-compatible in terms of adding layers and parameters, its data slot MAY NOT be fully fortified to data.frame before it is printed/plotted.

class(p)

## [1] "ggcyto_flowSet"  "ggcyto"          "ggplot2::ggplot" "ggplot"         
## [5] "ggplot2::gg"     "S7_object"       "gg"

class(p$data)

## [1] "flowSet"
## attr(,"package")
## [1] "flowCore"

To convert it to a pure ggplot object, use as.ggplot function:

p <- as.ggplot(p)

class(p)

## [1] "ggcyto_flowSet"  "ggcyto"          "ggplot2::ggplot" "ggplot"         
## [5] "ggplot2::gg"     "S7_object"       "gg"

class(p$data)

## [1] "data.table" "data.frame"