gpaSet {flowStats} | 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 - \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 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

[Package flowStats version 3.38.0 Index]