compensation-class: Class "compensation"
In flowCore: flowCore: Basic structures for flow cytometry data

Description Usage Arguments Details Value Slots Objects from the Class Methods Author(s) See Also Examples

Class and methods to compensate for spillover between channels by applying a spillover matrix to a flowSet or a flowFrame assuming a simple linear combination of values.

1
2
3

compensation(..., spillover, compensationId="defaultCompensation")

compensate(x, spillover, ...)

`spillover`	The spillover or compensation matrix.
`compensationId`	The identifier for the compensation object.
`x`	An object of class `flowFrame` or `flowSet`.
`...`	Further arguments. The constructor is designed to be useful in both programmatic and interactive settings, and ... serves as a container for possible arguments. The following combinations of values are allowed: Elements in ... are `character` scalars of parameter names or `transform` objects and the colnames in `spillover` match to these parameter names. The first element in ... is a `character` vector of parameter names or a list of `character` scalars or `transform` objects and the colnames in `spillover` match to these parameter names. Argument `spillover` is missing and the first element in ... is a `matrix`, in which case it is assumed to be the spillover matrix. ... is missing, in which case all parameter names are taken from the colnames of `spillover`.

The essential premise of compensation is that some fluorochromes may register signals in detectors that do not correspond to their primary detector (usually a photomultiplier tube). To compensate for this fact, some sort of standard is used to obtain the background signal (no dye) and the amount of signal on secondary channels for each fluorochrome relative to the signal on their primary channel.

To calculate the spillover percentage we use either the mean or the median (more often the latter) of the secondary signal minus the background signal for each dye to obtain n by n matrix, S, of so-called spillover values, expressed as a percentage of the primary channel. The observed values are then considered to be a linear combination of the true fluorescence and the spillover from each other channel so we can obtain the true values by simply multiplying by the inverse of the spillover matrix.

The spillover matrix can be obtained through several means. Some flow cytometers provide a spillover matrix calculated during acquisition, possibly by the operator, that is made available in the metadata of the flowFrame. While there is a theoretical standard keyword $SPILL it can also be found in the SPILLOVER or SPILL keyword depending on the cytometry. More commonly the spillover matrix is calculated using a series of compensation cells or beads collected before the experiment. If you have set of FCS files with one file per fluorochrome as well as an unstained FCS file you can use the spillover method for flowSets to automatically calculate a spillover matrix.

The compensation class is essentially a wrapper around a matrix that allows for transformed parameters and method dispatch.

A compensation object for the constructor.

A flowFrame or flowSet for the compensate methods.

spillover: Object of class matrix; the spillover matrix.
compensationId: Object of class character. An identifier for the object.
parameters: Object of class parameters. The flow parameters for which the compensation is defined. This can also be objects of class transform, in which case the compensation is performed on the compensated parameters.

Objects should be created using the constructor compensation(). See the Usage and Arguments sections for details.

compensate

signature(x = "flowFrame", spillover = "compensation"): Apply the compensation defined in a compensation object on a flowFrame. This returns a compensated flowFrame.

Usage:

compensate(flowFrame, compensation)

compensate

signature(x = "flowFrame", spillover = "matrix"): Apply a compensation matrix to a flowFrame. This returns a compensated flowFrame.

Usage:

compensate(flowFrame, matrix)

compensate

signature(x = "flowFrame", spillover = "data.frame"):Try to coerce the data.frame to a matrix and apply that to a flowFrame. This returns a compensated flowFrame.

Usage:

compensate(flowFrame, data.frame)

identifier, identifier<-

signature(object = "compensation"): Accessor and replacement methods for the compensationId slot.

Usage:

identifier(compensation)

identifier(compensation) <- value

parameters

signature(object = "compensation"): Get the parameter names of the compensation object. This method also tries to resolve all transforms and transformReferences before returning the parameters as character vectors. Unresolvable references return NA.

Usage:

parameters(compensation)

show

signature(object = "compensation"): Print details about the object.

Usage:

This method is automatically called when the object is printed on the screen.

F.Hahne, B. Ellis, N. Le Meur

spillover

## Read sample data and a sample spillover matrix
samp   <- read.flowSet(path=system.file("extdata", "compdata", "data",
          package="flowCore")) 
cfile <- system.file("extdata","compdata","compmatrix", package="flowCore")
comp.mat <- read.table(cfile, header=TRUE, skip=2, check.names = FALSE)
comp.mat

## compensate using the spillover matrix directly
summary(samp)
samp <- compensate(samp, comp.mat)
summary(samp)

## create a compensation object and compensate using that
comp <- compensation(comp.mat)
compensate(samp, comp)

## demo the sample-specific compensation
## create a list of comps (each element could be a 
## different compensation tailored for the specific sample)
comps <- sapply(sampleNames(samp), function(sn)comp, simplify = FALSE)
# the names of comps must be matched to sample names of the flowset
compensate(samp, comps)