gpaSet: Multi-dimensional normalization of flow cytometry data

In RGLab/flowStats: Statistical methods for the analysis of flow cytometry data

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

Value

The normalized flowSet with "GPA" attribute.

Author(s)

C. J. Wong [e-mail]

References

in progress

Examples

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

RGLab/flowStats documentation built on July 20, 2023, 1:33 a.m.