gpaSet: Multi-dimensional normalization of flow cytometry data
In flowStats: Statistical methods for the analysis of flow cytometry data

Description Usage Arguments Details Value Author(s) References Examples

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

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")

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

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 - \bar{F}||,

where s is a scalar, Q a rotational matrix, F the matrix of features, and \bar{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 \bar{F}_{ij}.

If downweight.missingFeatures is TRUE, the cost function becomes

||s W_0 FQ - W_0 \bar{F}||,

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

The normalized flowSet with "GPA" attribute.

C. J. Wong cwon2@fhcrc.org

in progress

library(flowCore)
## 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: 
library(flowCore)
## 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