getting started with owstats - bioconductor...getting started with owstats f. hahne, n....

Getting started with flowStats

F. Hahne, N. Gopalakrishnan

November 27, 2019

Abstract

flowStats is a collection of algorithms for the statistical analysis of flow cytometry data.So far, the focus is on automated gating and normalization.

1 Introduction

Since flowStats is more a collection of algorithms, writing a coherent Vignette is somewhatdifficult. Instead, we will present a hypothetical data analysis process that also makes heavyuse of the functionality provided by flowWorkspace, primarily through GatingSets.

We start by loading the ITN data set

> library(flowCore)

> library(flowStats)

> library(flowWorkspace)

> library(ggcyto)

> data(ITN)

The data was acquired from blood samples by 3 groups of patients, each group containing 5samples. Each flowFrame includes, in addition to FSC and SSC, 5 fluoresence parameters:CD3, CD4, CD8, CD69 and HLADR.

First we need to tranform all the fluorescence channels. This is a good point to start usinga GatingSet object to keep track of our progress.

> require(scales)

> gs <- GatingSet(ITN)

> trans.func <- asinh

> inv.func <- sinh

> trans.obj <- trans_new("myAsinh", trans.func, inv.func)

> transList <- transformerList(colnames(ITN)[3:7], trans.obj)

> gs <- transform(gs, transList)

In an initial analysis step we first want to identify and subset all T-cells. This can be achievedby gating in the CD3 and SSC dimensions. However, there are several other sub-populationsand we need to either specify our selection further or segment the individual sub-populations.One solution for the latter aproach is to use the mixture modelling infrastructure provided bythe flowClust package. However, since we are only interested in one single sub-population, the

1

T-cell, it is much faster and easier to use the lymphGate function in the flowStats package.The idea here is to first do a rough preselection in the two-dimensional projection of the databased on expert knowledge or prior experience and subsequently to fit a norm2Filter to thissubset. The function also allows us to derive the pre-selection through back-gating: we knowthat CD4 positive cells are a subset of T-cells, so by estimating CD4 positive cells first we canget a rough idea on where to find the T-cells in the CD3 SSC projection.

> lg <- lymphGate(gs_cyto_data(gs), channels=c("CD3", "SSC"),

+ preselection="CD4", filterId="TCells",

+ scale=2.5)

> gs_pop_add(gs, lg)

[1] 2

> recompute(gs)

> ggcyto(gs, aes(x = CD3, y = SSC)) + geom_hex(bins = 32) + geom_gate("TCells")

sample13 sample14 sample15

sample09 sample10 sample11 sample12



2.5 5.0 7.5 10.0 2.5 5.0 7.5 10.0 2.5 5.0 7.5 10.0

2.5 5.0 7.5 10.0 2.5 5.0 7.5 10.0 2.5 5.0 7.5 10.0 2.5 5.0 7.5 10.0

2.5 5.0 7.5 10.0 2.5 5.0 7.5 10.0 2.5 5.0 7.5 10.0 2.5 5.0 7.5 10.0

2.5 5.0 7.5 10.0 2.5 5.0 7.5 10.0 2.5 5.0 7.5 10.0 2.5 5.0 7.5 10.00

250

500

750

1000

0

250

500

750

1000

0

250

500

750

1000

0

250

500

750

1000

0

250

500

750

1000

0

250

500

750

1000

0

250

500

750

1000

0

250

500

750

1000

0

250

500

750

1000

0

250

500

750

1000

0

250

500

750

1000

0

250

500

750

1000

0

250

500

750

1000

0

250

500

750

1000

0

250

500

750

1000

CD3 CD3

SS

C

root

In the next step we want to separate T-helper and NK cells using the CD4 and CD8 stains.A convenient way of doing this is to apply a quadGate, assuming that both CD4 and CD8 are

2

binary markers (cells are either positive or negative for CD4 and CD8). Often investigatorsuse negative samples to derive a split point between the postive and negative populations, andapply this constant gate on all their samples. This will only work if there are no unforseen shiftsin the fluorescence itensities between samples which are purely caused by technical variationrather than biological phenotype. Let’s take a look at this variation for the T-cell subset andall 4 remaining fluorescense channels:

> require(ggridges)

> require(gridExtra)

> pars <- colnames(gs)[c(3,4,5,7)]

> data <- gs_pop_get_data(gs, "TCells")

> plots <- lapply(pars, function(par)

+ as.ggplot(ggcyto(data, aes(x = !!par, fill = GroupID)) +

+ geom_density_ridges(mapping = aes(y = name), alpha = 0.4) +

+ theme(axis.title.y = element_blank(),

+ axis.text.y = element_blank(),

+ axis.ticks.y = element_blank()) +

+ facet_null()

+ ))

> do.call("grid.arrange", c(plots, nrow=1))

3

2.5 5.0 7.5 10.0CD8 CD8

2 4 6 8CD69 CD69

2 4 6 8CD4 CD4

2 4 6HLADr HLADr

Indeed the data, especially for CD4 and CD8, don’t align well. At this point we coulddecide to compute the quadGates for each sample separately. Alternatively, we can try tonormalize the data and then compute a common gate. The warpSet function can be used tonormalize data according to a set of landmarks, which essentially are the peaks or high-densityareas in the density estimates shown before. The ideas here are simple:

� High density areas represent particular sub-types of cells.

� Markers are binary. Cells are either positive or negative for a particular marker.

� Peaks should aline if the above statements are true.

The algorithm in warpSet performs the following steps:

1. Identify landmarks for each parameter using a curv1Filter

2. Estimate the most likely total number (k) of landmarks

3. Perform k-means clustering to classify landmarks

4. Estimate warping functions for each sample and parameter that best align the landmarks,given the underlying data. This step uses functionality from the fda package.

4

5. Transform the data using the warping functions.

The algorithm should be robust to missing peaks in some of the samples, however theclassification in step 3 becomes harder since it is not clear which cell population it represents.

While warpSet can be used directly on a flowSet, the normalize method was written tointegrate with GatingSet objects. We must first create the gate whose channels we would liketo normalize, which in this case will be done using the quadrantGate function to automaticallyestimate a quadGate in the CD4 and CD8 channels.

> qgate <- quadrantGate(gs_pop_get_data(gs, "TCells"), stains=c("CD4", "CD8"),

+ filterId="CD4CD8", sd=3)

> gs_pop_add(gs, qgate, parent = "TCells")

[1] 3 4 5 6

> recompute(gs)

We can now normalize the channels relevant to this gate using normalize, so that we cansuccessfully apply a single quadGate to all of the samples.

> gs <- normalize(gs, populations=c("CD4+CD8+", "CD4+CD8-", "CD4-CD8+", "CD4-CD8-"),

+ dims=c("CD4", "CD8"), minCountThreshold = 50)

Estimating landmarks for channel CD4 ...


Registering curves for parameter CD4 ...


The normalization aligns the peaks in the selected channels across all samples.

> data <- gs_pop_get_data(gs, "TCells")

> plots <- lapply(pars, function(par)

+ as.ggplot(ggcyto(data, aes(x = !!par, fill = GroupID)) +





+ facet_null()

+ ))

> do.call("grid.arrange", c(plots, nrow=1))

5

0.0 2.5 5.0 7.5 10.0CD8 CD8

2 4 6 8CD69 CD69

0 2 4 6 8CD4 CD4

2 4 6HLADr HLADr

This ensures that the single quadGate is appropriately placed for each sample.

> ggcyto(gs_pop_get_data(gs, "TCells"), aes(x=CD4, y=CD8)) +

+ geom_hex(bins=32) +

+ geom_gate(gs_pop_get_gate(gs, "CD4-CD8-")) +

+ geom_gate(gs_pop_get_gate(gs, "CD4-CD8+")) +

+ geom_gate(gs_pop_get_gate(gs, "CD4+CD8-")) +

+ geom_gate(gs_pop_get_gate(gs, "CD4+CD8+"))

6





0 2 4 6 8 0 2 4 6 8 0 2 4 6 8

0 2 4 6 8 0 2 4 6 8 0 2 4 6 8 0 2 4 6 8

0 2 4 6 8 0 2 4 6 8 0 2 4 6 8 0 2 4 6 8

0 2 4 6 8 0 2 4 6 8 0 2 4 6 8 0 2 4 6 80.0

2.5

5.0

7.5

10.0

0.0

2.5

5.0

7.5

10.0

0.0

2.5

5.0

7.5

10.0

0.0

2.5

5.0

7.5

10.0

0.0

2.5

5.0

7.5

10.0

0.0

2.5

5.0

7.5

10.0

0.0

2.5

5.0

7.5

10.0

0.0

2.5

5.0

7.5

10.0

0.0

2.5

5.0

7.5

10.0

0.0

2.5

5.0

7.5

10.0

0.0

2.5

5.0

7.5

10.0

0.0

2.5

5.0

7.5

10.0

0.0

2.5

5.0

7.5

10.0

0.0

2.5

5.0

7.5

10.0

0.0

2.5

5.0

7.5

10.0

CD4 CD4

CD

8 C

D8

In a final step we might be interested in finding the proportion of activated T-helper cellsby means of the CD69 stain. The rangeGate function is helpful in separating positive andnegative peaks in 1D.

> CD69rg <- rangeGate(gs_cyto_data(gs), stain="CD69",

+ alpha=0.75, filterId="CD4+CD8-CD69", sd=2.5)

> gs_pop_add(gs, CD69rg, parent="CD4+CD8-")

[1] 7

> # gs_pop_add(gs, CD69rg, parent="CD4+CD8-", name = "CD4+CD8-CD69-", negated=TRUE)

> recompute(gs)

> ggcyto(gs_pop_get_data(gs, "CD4+CD8-"), aes(x=CD69, fill = GroupID)) +





+ geom_vline(xintercept = CD69rg@min) +

7

+ facet_null() +

+ ggtitle("CD4+")

2 4 6CD69 CD69

CD4+

This channel could also benefit from normalization before determining a single rangeGate

to apply to all samples.

> gs <- normalize(gs, populations=c("CD4+CD8-CD69"),

+ dims=c("CD69"), minCountThreshold = 50)



> ggcyto(gs_pop_get_data(gs, "CD4+CD8-"), aes(x=CD69, fill = GroupID)) +





+ geom_vline(xintercept = CD69rg@min) +

+ facet_null() +

+ ggtitle("CD4+")

8

0 2 4CD69 CD69

CD4+

2 Probability Binning

A probability binning algorithm for quantitating multivariate distribution differences was de-scribed by Roederer et al. The algorithm identifies the flow parameter in a flowFrame withthe largest variance and divides the events in the flowFrame into two subgroups based on themedian of the parameter. This process continues until the number of events in each subgroupis less than a user specified threshold.

For comparison across multiple samples, probability binning algorithm can be applied toa control dataset to obtain the position of bins and the same bins can be applied to theexperimental dataset. The number of events in the control and sample bins can then becompared using the Pearsons chi-square test or the probability binning metric defined byRoederer et al.

Although probability binning can be applied simultaneously to all parameters in a flowFramewith bins in n dimensional hyperspace, we proceed with a two dimenstional example from ourprevious discussion involving CD4 and CD8 populations. This helps to simplify the demon-stration of the method and interpretation of results.

From the workflow object containing the warped data, we extract our data frame of interest.

9

We try to compare the panels using probability binning to identify patients with CD4, CD8populations different from a control flowFrame that we create using the data from all thepatients.

> dat <- gs_cyto_data(gs)

>

The dat is visualized below

> autoplot(dat, "CD4", "CD8") +

+ ggtitle("Experimental Dataset")





0.0 2.5 5.0 7.5 10.0 0.0 2.5 5.0 7.5 10.0 0.0 2.5 5.0 7.5 10.0

0.0 2.5 5.0 7.5 10.0 0.0 2.5 5.0 7.5 10.0 0.0 2.5 5.0 7.5 10.0 0.0 2.5 5.0 7.5 10.0

0.0 2.5 5.0 7.5 10.0 0.0 2.5 5.0 7.5 10.0 0.0 2.5 5.0 7.5 10.0 0.0 2.5 5.0 7.5 10.0

0.0 2.5 5.0 7.5 10.0 0.0 2.5 5.0 7.5 10.0 0.0 2.5 5.0 7.5 10.0 0.0 2.5 5.0 7.5 10.00.0

2.5

5.0

7.5

10.0

0.0

2.5

5.0

7.5

10.0

0.0

2.5

5.0

7.5

10.0

0.0

2.5

5.0

7.5

10.0

0.0

2.5

5.0

7.5

10.0

0.0

2.5

5.0

7.5

10.0

0.0

2.5

5.0

7.5

10.0

0.0

2.5

5.0

7.5

10.0

0.0

2.5

5.0

7.5

10.0

0.0

2.5

5.0

7.5

10.0

0.0

2.5

5.0

7.5

10.0

0.0

2.5

5.0

7.5

10.0

0.0

2.5

5.0

7.5

10.0

0.0

2.5

5.0

7.5

10.0

0.0

2.5

5.0

7.5

10.0

CD4 CD4

CD

8 C

D8

Experimental Dataset

The control dataset is created by combining all the flowFrames in the flowSet. TheflowFrame is then subsetted after applying a sampleFilter so that the control flowSet createdhas approximately the same number of events as the other flowSets in our example.

> datComb <- as(dat,"flowFrame")

> subCount <- nrow(exprs(datComb))/length(dat)

> sf <- sampleFilter(filterId="mySampleFilter", size=subCount)

> fres <- filter(datComb, sf)

10

> ctrlData <- Subset(datComb, fres)

> ctrlData <- ctrlData[,-ncol(ctrlData)] ##remove the column name "original"

>

The probability binning algorithm can then applied to the control data. The terminatingcondition for the algorithm is set so that the number of events in each bin is approximately 5percent of the total number of events in the control data.

> minRow=subCount*0.05

> refBins<-proBin(ctrlData,minRow,channels=c("CD4","CD8"))

>

The binned control Data can be visualized using the plotBins function. Areas in thescatter plot with a large number of data points have a higher density of bins. Each bin alsohas approximately same number of events.

> plotBins(refBins,ctrlData,channels=c("CD4","CD8"),title="Control Data")

>

0 2 4 6 8 10

24

68

10

Control Data

CD4

CD

8

The same bin positions from the control data set are then applied to each flowFrame in oursample Data set.

11

> sampBins <- fsApply(dat,function(x){

+ binByRef(refBins,x)

+ })

For each patient, the number events in the control and sample bins can be compared usingthe calcPearsonChi or using Roederers probability binning metric.

> pearsonStat <- lapply(sampBins,function(x){

+ calcPearsonChi(refBins,x)

+ })

> sCount <- fsApply(dat,nrow)

> pBStat <-lapply(seq_along(sampBins),function(x){

+ calcPBChiSquare(refBins,sampBins[[x]],subCount,sCount[x])

+ })

For each sample, the results can be visualized using the plotBins function. The residualsfrom Roeders probability binning metric or the Pearsons chi square test can be used to shadebins to highlight bins in each sample that differ the most from the control sample.

> par(mfrow=c(4,4),mar=c(1.5,1.5,1.5,1.5))

> plotBins(refBins,ctrlData,channels=c("CD4","CD8"),title="Control Data")

> patNames <-sampleNames(dat)

> tm<-lapply(seq_len(length(dat)),function(x){

+ plotBins(refBins,dat[[x]],channels=c("CD4","CD8"),

+ title=patNames[x],

+ residuals=pearsonStat[[x]]$residuals[2,],

+ shadeFactor=0.7)

+

+ }

+ )

12

0 2 4 6 8 10

24

68

10

Control Data

CD4

1 3 5 7

24

68

10

sample01

CD4

CD

8

2 4 6 8

24

68

sample02

CD4

CD

8

1 3 5 7

24

68

10

sample03

CD4

CD

8

2 4 6 8 10

24

68

10

sample04

CD4

2 4 6 8 10

12

34

56

7

sample05

CD4

CD

8

1 3 5 7

12

34

56

7

sample06

CD4

CD

8

2 4 6 8

24

68

sample07

CD4

CD

8

2 4 6 8 10

24

68

10

sample08

CD4

1 3 5 7

13

57

sample09

CD4

CD

8

0 2 4 6 8

13

57

sample10

CD4

CD

8

2 4 6 8

13

57

sample11

CD4

CD

8

2 4 6 8 10

24

68

sample12

2 4 6 8

13

57

sample13

CD

8

1 3 5 7

13

57

sample14

CD

8

1 2 3 4 5 6 7

13

57

sample15

CD

8

The patient with CD4/CD8 populations most different from that of the control group canbe identified from the magnitue of Pearson-chi square statistic(or Probability binning statistic).

13

chi Square Statistic pBin Statistic

sample01 2465.78 309.22sample02 3046.52 382.97sample03 694.41 84.25sample04 1761.65 219.79sample05 664.13 80.41sample06 3116.81 391.90sample07 2122.13 265.57sample08 921.18 113.05sample09 2962.22 372.26sample10 1540.45 191.70sample11 5535.53 699.08sample12 1156.39 142.93sample13 1044.30 128.69sample14 1768.00 220.60sample15 3726.48 469.33

14

� R Under development (unstable) (2019-10-24 r77329), x86_64-pc-linux-gnu

� Locale: LC_CTYPE=en_US.UTF-8, LC_NUMERIC=C, LC_TIME=en_US.UTF-8,LC_COLLATE=C, LC_MONETARY=en_US.UTF-8, LC_MESSAGES=en_US.UTF-8,LC_PAPER=en_US.UTF-8, LC_NAME=C, LC_ADDRESS=C, LC_TELEPHONE=C,LC_MEASUREMENT=en_US.UTF-8, LC_IDENTIFICATION=C

� Running under: Ubuntu 18.04.3 LTS

� Matrix products: default

� BLAS: /home/biocbuild/bbs-3.11-bioc/R/lib/libRblas.so

� LAPACK: /home/biocbuild/bbs-3.11-bioc/R/lib/libRlapack.so

� Base packages: base, datasets, grDevices, graphics, methods, stats, utils

� Other packages: BH 1.69.0-1, RcppArmadillo 0.9.800.1.0, flowCore 1.53.2,flowStats 3.45.2, flowWorkspace 3.35.3, ggcyto 1.15.0, ggplot2 3.2.1, ggridges 0.5.1,gridExtra 2.3, ncdfFlow 2.33.0, scales 1.1.0, xtable 1.8-4

� Loaded via a namespace (and not attached): Biobase 2.47.1, BiocGenerics 0.33.0,DEoptimR 1.0-8, IDPmisc 1.1.19, KernSmooth 2.23-16, MASS 7.3-51.4, Matrix 1.2-18,R6 2.4.1, RColorBrewer 1.1-2, RProtoBufLib 1.9.6, Rcpp 1.0.3, RcppParallel 4.4.4,Rgraphviz 2.31.0, XML 3.98-1.20, assertthat 0.2.1, cluster 2.1.0, colorspace 1.4-1,compiler 4.0.0, crayon 1.3.4, cytolib 1.9.5, data.table 1.12.6, digest 0.6.23, dplyr 0.8.3,farver 2.0.1, fda 2.4.8, flowViz 1.51.0, glue 1.3.1, graph 1.65.0, grid 4.0.0, gtable 0.3.0,hexbin 1.28.0, ks 1.11.6, labeling 0.3, lattice 0.20-38, latticeExtra 0.6-28, lazyeval 0.2.2,lifecycle 0.1.0, magrittr 1.5, matrixStats 0.55.0, mclust 5.4.5, munsell 0.5.0,mvtnorm 1.0-11, parallel 4.0.0, pcaPP 1.9-73, pillar 1.4.2, pkgconfig 2.0.3, plyr 1.8.4,purrr 0.3.3, rlang 0.4.2, robustbase 0.93-5, rrcov 1.4-9, splines 4.0.0, stats4 4.0.0,stringi 1.4.3, stringr 1.4.0, tibble 2.1.3, tidyselect 0.2.5, tools 4.0.0, withr 2.1.2,zlibbioc 1.33.0

15

getting started with owstats - bioconductor...getting started with owstats f. hahne, n....

Documents