R Graphical Manual

Browse All

Last data update: 2014.03.03

R: Multi-dimensional normalization of flow cytometry data

gpaSet

R Documentation

Multi-dimensional normalization of flow cytometry data

Description

This function performs a multi-dimensional normalization of flow cytometry data (flowSets) using a generalized Procrustes analysis (GPA) method.

Usage

gpaSet(x, params, register="backgating", bgChannels=NULL,
       bg=NULL,  rotation.only=TRUE,
       downweight.missingFeatures=FALSE, thres.sigma=2.5,
       show.workflow=FALSE,
       ask=names(dev.cur())!="pdf")

Arguments

`x`	A `flowSet`.
`params`	A character vector of length 2 describing the channels of interest.
`register`	A character indicating the method to be used for identifying features. Available method only includes “backgating” at the point.
`bgChannels`	A character vector indicating the channels used for backgating. If NULL, `backGating` will find the appropriate backgating channels.
`bg`	A data frame as the returning value of the `backGating` function. If not NULL, `gpaSet` will skip the `backGating` process and use the given data frame to extract potential features.
`rotation.only`	Logical for coarsing a reflection matrix to a rotation matrix.
`downweight.missingFeatures`	Logical. If TRUE, the missing features, labeled as bogus features, are downweighted to zero. See details.
`thres.sigma`	A numerical value indicating the threshold of where to cut the tree, e.g., as resulting from `diana`, into several clusters. It is default to 2.5 sigma of the distribution of the heights of the cluster points.
`show.workflow`	Logical. If TRUE, the workflow of `gpaSet` will be displayed.
`ask`	Logical. If TRUE, the display operates in interactive mode.

Details

Normalization is achieved by first identifying features for each flowFrame in the flowSet for designated channels using backgating, subsequently labeling features, and finally aligning the features to a reference feature in the sense of minimizing the Frobenus norm of

||sFQ - ar{F}||,

where s is a scalar, Q a rotational matrix, F the matrix of features, and ar{F} the reference feature. Both s and Q are solved by using singular value decomposition (SVD).

Note that if feature F_{ij} is missing, it is given a bogus value as ar{F}_{ij}.

If downweight.missingFeatures is TRUE, the cost function becomes

||s W_0 FQ - W_0 ar{F}||,

where the weighting function W_0 is zero if the corresponding feature is bogus.

Value

The normalized flowSet with "GPA" attribute.

Author(s)

C. J. Wong cwon2@fhcrc.org

References

in progress

Examples

## Example 1: calling up gpaSet directly
data(ITN)
data(BackGating)

tl <- transformList(colnames(ITN)[3:7], asinh, transformationId="asinh")
dat <- transform(ITN, tl)

xy = c("FSC", "SSC")
bgChannels = c("CD8", "CD4", "CD3")
## bg <- flowStats:::backGating(dat, xy=xy, channels=bgChannels)
## using pre-generated backgating results: BackGating 
s <- gpaSet(dat, params=xy, bgChannels=bgChannels, bg=BackGating)

if(require(flowViz)) {
   d1 <- densityplot(~., s, channels=c("FSC", "SSC"), 
                     layout=c(2,1), main="After GPA using bg")
   d2 <- xyplot(FSC ~ SSC, as(s, "flowFrame"), 
                channels=c("FSC", "SSC"), main="All flowFrames")
   plot(d1)
   plot(d2)
}

## view "GPA" attribute
attr(s, "GPA")

## Not run: 
## Example 2: using work flow and normalization objects
data(ITN)
ITN <- ITN[1:8, ]
wf <- workFlow(ITN)
tl <- transformList(colnames(ITN)[3:7], asinh, transformationId="asinh")
add(wf, tl)
x <- Data(wf[["asinh"]])
## normalize 'FSC' and 'SSC' channels
norm <- normalization(normFun=function(x, parameters, ...)
        gpaSet(x, parameters, ...),
        parameters = c("FSC", "SSC"), 
	arguments=list(bgChannels=c("CD8", "CD3"),
                       register="backgating"),
	normalizationId="Procrustes")

add(wf, norm2, parent="asinh")
s <- Data(wf[["Procrustes"]])
if(require(flowViz)) {
   d1 <- densityplot(~., s, channels=c("FSC", "SSC"), 
                     layout=c(2,1), main="After GPA using bg")
   d2 <- xyplot(FSC ~ SSC, as(s, "flowFrame"), 
                channels=c("FSC", "SSC"), main="All flowFrames")
   plot(d1)
   plot(d2)
}

## End(Not run) ## end of dontrun

Results


R version 3.3.1 (2016-06-21) -- "Bug in Your Hair"
Copyright (C) 2016 The R Foundation for Statistical Computing
Platform: x86_64-pc-linux-gnu (64-bit)

R is free software and comes with ABSOLUTELY NO WARRANTY.
You are welcome to redistribute it under certain conditions.
Type 'license()' or 'licence()' for distribution details.

R is a collaborative project with many contributors.
Type 'contributors()' for more information and
'citation()' on how to cite R or R packages in publications.

Type 'demo()' for some demos, 'help()' for on-line help, or
'help.start()' for an HTML browser interface to help.
Type 'q()' to quit R.

> library(flowStats)
Loading required package: flowCore
Loading required package: fda
Loading required package: splines
Loading required package: Matrix

Attaching package: 'Matrix'

The following object is masked from 'package:flowCore':

    %&%


Attaching package: 'fda'

The following object is masked from 'package:graphics':

    matplot

Loading required package: mvoutlier
Loading required package: sgeostat
sROC 0.1-2 loaded
Loading required package: cluster
Loading required package: flowWorkspace
Loading required package: flowViz
Loading required package: lattice
Loading required package: ncdfFlow
Loading required package: RcppArmadillo
Loading required package: BH
Loading required package: gridExtra
> png(filename="/home/ddbj/snapshot/RGM3/R_BC/result/flowStats/gpaSet.Rd_%03d_medium.png", width=480, height=480)
> ### Name: gpaSet
> ### Title: Multi-dimensional normalization of flow cytometry data
> ### Aliases: gpaSet
> 
> ### ** Examples
> 
> ## Example 1: calling up gpaSet directly
> data(ITN)
> data(BackGating)
> 
> tl <- transformList(colnames(ITN)[3:7], asinh, transformationId="asinh")
> dat <- transform(ITN, tl)
> 
> xy = c("FSC", "SSC")
> bgChannels = c("CD8", "CD4", "CD3")
> ## bg <- flowStats:::backGating(dat, xy=xy, channels=bgChannels)
> ## using pre-generated backgating results: BackGating 
> s <- gpaSet(dat, params=xy, bgChannels=bgChannels, bg=BackGating)
Procrustes analysis ... 

> 
> if(require(flowViz)) {
+    d1 <- densityplot(~., s, channels=c("FSC", "SSC"), 
+                      layout=c(2,1), main="After GPA using bg")
+    d2 <- xyplot(FSC ~ SSC, as(s, "flowFrame"), 
+                 channels=c("FSC", "SSC"), main="All flowFrames")
+    plot(d1)
+    plot(d2)
+ }
> 
> ## view "GPA" attribute
> attr(s, "GPA")
$id.feature.method
[1] "backgating"

$norm.channels
[1] "FSC" "SSC"

$backgating.channels
[1] "CD8" "CD4" "CD3"

$downweight.missingFeatures
[1] FALSE

$SVD
$SVD$sample01
$SVD$sample01$Q
           [,1]        [,2]
[1,] 0.99931304 -0.03706013
[2,] 0.03706013  0.99931304

$SVD$sample01$scal
[1] 0.9625227


$SVD$sample02
$SVD$sample02$Q
           [,1]        [,2]
[1,] 0.99993547 -0.01136023
[2,] 0.01136023  0.99993547

$SVD$sample02$scal
[1] 0.9734189


$SVD$sample03
$SVD$sample03$Q
           [,1]        [,2]
[1,] 0.99862640 -0.05239564
[2,] 0.05239564  0.99862640

$SVD$sample03$scal
[1] 0.982891


$SVD$sample04
$SVD$sample04$Q
            [,1]         [,2]
[1,] 0.999961866 -0.008733015
[2,] 0.008733015  0.999961866

$SVD$sample04$scal
[1] 0.9987088


$SVD$sample05
$SVD$sample05$Q
           [,1]        [,2]
[1,] 0.99990602 -0.01370933
[2,] 0.01370933  0.99990602

$SVD$sample05$scal
[1] 1.030354


$SVD$sample06
$SVD$sample06$Q
           [,1]      [,2]
[1,]  0.9913540 0.1312147
[2,] -0.1312147 0.9913540

$SVD$sample06$scal
[1] 0.9755746


$SVD$sample07
$SVD$sample07$Q
            [,1]       [,2]
[1,]  0.99946404 0.03273581
[2,] -0.03273581 0.99946404

$SVD$sample07$scal
[1] 1.026756


$SVD$sample08
$SVD$sample08$Q
            [,1]         [,2]
[1,] 0.999996779 -0.002538264
[2,] 0.002538264  0.999996779

$SVD$sample08$scal
[1] 1.009888


$SVD$sample09
$SVD$sample09$Q
            [,1]       [,2]
[1,]  0.99967718 0.02540741
[2,] -0.02540741 0.99967718

$SVD$sample09$scal
[1] 1.047974


$SVD$sample10
$SVD$sample10$Q
           [,1]        [,2]
[1,] 0.99988051 -0.01545881
[2,] 0.01545881  0.99988051

$SVD$sample10$scal
[1] 1.047829


$SVD$sample11
$SVD$sample11$Q
             [,1]        [,2]
[1,]  0.999997795 0.002100081
[2,] -0.002100081 0.999997795

$SVD$sample11$scal
[1] 1.001366


$SVD$sample12
$SVD$sample12$Q
           [,1]        [,2]
[1,] 0.99692097 -0.07841291
[2,] 0.07841291  0.99692097

$SVD$sample12$scal
[1] 0.9295906


$SVD$sample13
$SVD$sample13$Q
           [,1]        [,2]
[1,] 0.99972719 -0.02335698
[2,] 0.02335698  0.99972719

$SVD$sample13$scal
[1] 0.9242907


$SVD$sample14
$SVD$sample14$Q
            [,1]       [,2]
[1,]  0.99890416 0.04680251
[2,] -0.04680251 0.99890416

$SVD$sample14$scal
[1] 1.034414


$SVD$sample15
$SVD$sample15$Q
            [,1]       [,2]
[1,]  0.99988333 0.01527505
[2,] -0.01527505 0.99988333

$SVD$sample15$scal
[1] 1.030511



$TransMatrix
$TransMatrix$transM1
$TransMatrix$transM1$sample01
     FSC      SSC 
555.7874 535.5376 

$TransMatrix$transM1$sample02
     FSC      SSC 
587.9359 526.7624 

$TransMatrix$transM1$sample03
     FSC      SSC 
569.0242 529.9855 

$TransMatrix$transM1$sample04
     FSC      SSC 
570.4939 536.3043 

$TransMatrix$transM1$sample05
     FSC      SSC 
579.1182 545.7071 

$TransMatrix$transM1$sample06
     FSC      SSC 
545.1075 534.5334 

$TransMatrix$transM1$sample07
     FSC      SSC 
566.1396 553.6562 

$TransMatrix$transM1$sample08
     FSC      SSC 
581.2976 488.1307 

$TransMatrix$transM1$sample09
     FSC      SSC 
562.3324 558.9888 

$TransMatrix$transM1$sample10
     FSC      SSC 
602.5846 540.7549 

$TransMatrix$transM1$sample11
     FSC      SSC 
575.6181 536.2171 

$TransMatrix$transM1$sample12
     FSC      SSC 
609.5640 553.7049 

$TransMatrix$transM1$sample13
     FSC      SSC 
579.1236 485.2325 

$TransMatrix$transM1$sample14
     FSC      SSC 
552.4801 535.5485 

$TransMatrix$transM1$sample15
     FSC      SSC 
573.4858 544.8130 

$TransMatrix$transM1$reference
     FSC      SSC 
573.6677 534.6086 


$TransMatrix$transM2
list()


$Reference
       FSC      SSC cluster    sample bogus
1 632.6743 890.0534       1 reference FALSE
2 390.0509 148.3410       2 reference FALSE
3 542.3432 794.9604       3 reference FALSE
4 729.6024 305.0796       4 reference FALSE

$Features
$Features$sample01
       FSC      SSC cluster   sample bogus
1 578.4498 913.4799       1 sample01 FALSE
2 372.7543 128.6307       2 sample01 FALSE
3 542.3432 794.9604       3 sample01  TRUE
4 729.6024 305.0796       4 sample01  TRUE

$Features$sample02
       FSC      SSC cluster   sample bogus
1 632.6743 890.0534       1 sample02  TRUE
2 414.5903 141.9965       2 sample02 FALSE
3 556.3763 805.6078       3 sample02 FALSE
4 748.1025 269.3918       4 sample02 FALSE

$Features$sample03
       FSC      SSC cluster   sample bogus
1 578.2029 872.8801       1 sample03 FALSE
2 373.1979 147.0219       2 sample03 FALSE
3 542.3432 794.9604       3 sample03  TRUE
4 782.3527 305.0796       4 sample03 FALSE

$Features$sample04
       FSC      SSC cluster   sample bogus
1 632.6743 890.0534       1 sample04  TRUE
2 391.9939 150.5816       2 sample04 FALSE
3 527.7048 799.5028       3 sample04 FALSE
4 729.6024 305.0796       4 sample04  TRUE

$Features$sample05
       FSC      SSC cluster   sample bogus
1 632.6743 889.6082       1 sample05 FALSE
2 399.6132 170.0464       2 sample05 FALSE
3 542.3432 794.9604       3 sample05  TRUE
4 741.8420 328.2133       4 sample05 FALSE

$Features$sample06
       FSC      SSC cluster   sample bogus
1 632.6743 890.0534       1 sample06  TRUE
2 343.7776 155.2441       2 sample06 FALSE
3 583.8366 819.9111       3 sample06 FALSE
4 620.1417 272.9249       4 sample06 FALSE

$Features$sample07
       FSC      SSC cluster   sample bogus
1 601.8831 893.4852       1 sample07 FALSE
2 367.5891 205.3927       2 sample07 FALSE
3 565.4836 810.6675       3 sample07 FALSE
4 729.6024 305.0796       4 sample07  TRUE

$Features$sample08
       FSC      SSC cluster   sample bogus
1 686.5305 913.2682       1 sample08 FALSE
2 391.0495 147.2266       2 sample08 FALSE
3 525.9331 537.7838       3 sample08 FALSE
4 721.6773 354.2441       4 sample08 FALSE

$Features$sample09
       FSC      SSC cluster   sample bogus
1 622.0405 892.5368       1 sample09 FALSE
2 355.3435 196.6819       2 sample09 FALSE
3 542.3432 794.9604       3 sample09  TRUE
4 729.6024 351.7762       4 sample09 FALSE

$Features$sample10
       FSC      SSC cluster   sample bogus
1 668.2995 867.0512       1 sample10 FALSE
2 428.4172 180.8759       2 sample10 FALSE
3 542.3432 794.9604       3 sample10  TRUE
4 771.2784 320.1323       4 sample10 FALSE

$Features$sample11
       FSC      SSC cluster   sample bogus
1 632.6743 890.0534       1 sample11  TRUE
2 392.6326 150.9561       2 sample11 FALSE
3 547.5629 798.7793       3 sample11 FALSE
4 729.6024 305.0796       4 sample11  TRUE

$Features$sample12
       FSC      SSC cluster   sample bogus
1 637.5803 872.2689       1 sample12 FALSE
2 356.6578 154.4716       2 sample12 FALSE
3 542.3432 794.9604       3 sample12  TRUE
4 901.6746 393.1186       4 sample12 FALSE

$Features$sample13
       FSC      SSC cluster   sample bogus
1 632.6743 890.0534       1 sample13  TRUE
2 389.0720  85.8855       2 sample13 FALSE
3 529.2155 742.3750       3 sample13 FALSE
4 765.5325 222.6163       4 sample13 FALSE

$Features$sample14
       FSC      SSC cluster   sample bogus
1 632.6743 890.0534       1 sample14  TRUE
2 408.8545 155.7136       2 sample14 FALSE
3 547.7069 791.1415       3 sample14 FALSE
4 620.6846 305.2855       4 sample14 FALSE

$Features$sample15
       FSC      SSC cluster   sample bogus
1 632.6743 890.0534       1 sample15  TRUE
2 395.9392 184.1957       2 sample15 FALSE
3 543.4004 801.4607       3 sample15 FALSE
4 721.9293 303.5423       4 sample15 FALSE


attr(,"class")
[1] "GPA"
> 
> ## Not run: 
> ##D ## Example 2: using work flow and normalization objects
> ##D data(ITN)
> ##D ITN <- ITN[1:8, ]
> ##D wf <- workFlow(ITN)
> ##D tl <- transformList(colnames(ITN)[3:7], asinh, transformationId="asinh")
> ##D add(wf, tl)
> ##D x <- Data(wf[["asinh"]])
> ##D ## normalize 'FSC' and 'SSC' channels
> ##D norm <- normalization(normFun=function(x, parameters, ...)
> ##D         gpaSet(x, parameters, ...),
> ##D         parameters = c("FSC", "SSC"), 
> ##D 	arguments=list(bgChannels=c("CD8", "CD3"),
> ##D                        register="backgating"),
> ##D 	normalizationId="Procrustes")
> ##D 
> ##D add(wf, norm2, parent="asinh")
> ##D s <- Data(wf[["Procrustes"]])
> ##D if(require(flowViz)) {
> ##D    d1 <- densityplot(~., s, channels=c("FSC", "SSC"), 
> ##D                      layout=c(2,1), main="After GPA using bg")
> ##D    d2 <- xyplot(FSC ~ SSC, as(s, "flowFrame"), 
> ##D                 channels=c("FSC", "SSC"), main="All flowFrames")
> ##D    plot(d1)
> ##D    plot(d2)
> ##D }
> ## End(Not run) ## end of dontrun
> 
> 
> 
> 
> 
> 
> dev.off()
null device 
          1 
>