compensation-class: Class "compensation"

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

Description

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.

Usage

1
2
3
4
compensation(..., spillover,
compensationId="defaultCompensation")

compensate(x, spillover, ...)

Arguments

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.

Details

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.

Value

A compensation object for the constructor.

A flowFrame or flowSet for the compensate methods.

Objects from the Class

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

Slots

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.

Methods

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.

Author(s)

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

See Also

spillover

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
## 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)

Example output

     FL1-H    FL2-H   FL3-H   FL4-H
1 1.000000 0.240000 0.03200 0.00113
2 0.007770 1.000000 0.14000 0.00274
3 0.008690 0.170000 1.00000 0.21000
4 0.000795 0.000995 0.00323 1.00000
$`060909.001`
           FSC-H     SSC-H     FL1-H     FL2-H      FL3-H   FL1-A      FL4-H
Min.    142.0000    1.0000  1.000000  1.000000   1.000000  0.0000   1.000000
1st Qu. 386.0000  106.0000  3.162278  3.491152   2.838736  0.0000   4.613840
Median  423.0000  128.0000  4.104698  4.531584   3.651741  0.0000   7.233942
Mean    424.4648  137.7706  4.619515  5.094297   4.180982  0.0105   8.394232
3rd Qu. 462.0000  156.0000  5.376117  5.882084   4.740032  0.0000  10.181517
Max.    750.0000 1023.0000 78.438856 98.217189 125.214969 12.0000 598.885433

$`060909.002`
           FSC-H     SSC-H       FL1-H     FL2-H      FL3-H     FL1-A
Min.    142.0000    2.0000    1.240938    1.0000   1.286397    0.0000
1st Qu. 395.0000  105.0000  697.830585  173.0937  25.945527  163.0000
Median  436.0000  128.0000  930.572041  228.7573  33.376247  217.0000
Mean    437.1083  139.6543 1007.400078  249.3219  36.070674  241.4928
3rd Qu. 478.0000  158.0000 1229.826226  296.9315  42.550655  288.0000
Max.    823.0000 1023.0000 6435.669751 1746.5760 316.227766 1023.0000
             FL4-H
Min.      1.000000
1st Qu.   5.376117
Median    8.278826
Mean      9.248539
3rd Qu.  11.547820
Max.    865.964323

$`060909.003`
           FSC-H     SSC-H       FL1-H     FL2-H      FL3-H       FL1-A
Min.    143.0000    1.0000    1.000000    1.0000    1.00000   0.0000000
1st Qu. 399.0000   99.0000    8.278826  572.5488   84.29101   0.0000000
Median  438.0000  120.0000   10.181517  791.4755  114.44419   0.0000000
Mean    439.6068  131.0683   13.360873  858.8324  128.60253   0.6136273
3rd Qu. 479.0000  148.0000   12.634629 1064.9856  156.78788   0.0000000
Max.    747.0000 1023.0000 2267.089941 8058.4219 1610.76153 617.0000000
             FL4-H
Min.      1.000000
1st Qu.   6.264335
Median    9.305720
Mean     10.250156
3rd Qu.  12.863969
Max.    186.007840

$`060909.004`
           FSC-H    SSC-H       FL1-H       FL2-H       FL3-H    FL1-A
Min.    141.0000    1.000    1.000000    1.000000    1.000000   0.0000
1st Qu. 404.0000  106.000    3.367780    3.785515    3.718027   0.0000
Median  441.0000  129.000    4.371445    4.869675    4.782858   0.0000
Mean    442.2971  140.567    5.869876    8.894614    6.451100   0.2166
3rd Qu. 480.0000  159.250    5.777218    6.320934    6.264335   0.0000
Max.    882.0000 1023.000 1394.862022 2246.790092 1498.929649 342.0000
              FL4-H
Min.       1.420181
1st Qu.  289.026391
Median   358.663762
Mean     399.114158
3rd Qu.  449.100719
Max.    9910.458562

$`060909.005`
           FSC-H     SSC-H      FL1-H     FL2-H       FL3-H    FL1-A     FL4-H
Min.    140.0000    0.0000   1.000000   1.00000    1.485508   0.0000   1.00000
1st Qu. 395.0000  110.0000   3.718027  10.00000   33.677803   0.0000  15.26138
Median  429.0000  133.0000   5.002865  14.98930   63.209339   0.0000  20.90800
Mean    430.4819  143.8849   5.919921  17.25788   82.879238   0.0796  23.31498
3rd Qu. 465.0000  164.0000   6.731704  21.67392  113.419440   0.0000  28.64384
Max.    788.0000 1023.0000 889.649113 513.96968 1498.929649 203.0000 842.91009

$`060909.001`
           FSC-H     SSC-H      FL1-H      FL2-H       FL3-H   FL1-A
Min.    142.0000    1.0000  0.9748705  0.3112685   0.4886177  0.0000
1st Qu. 386.0000  106.0000  3.1216476  2.2556718   2.3423500  0.0000
Median  423.0000  128.0000  4.0434443  3.0135541   3.0634311  0.0000
Mean    424.4648  137.7706  4.5563619  3.3921168   3.5356139  0.0105
3rd Qu. 462.0000  156.0000  5.3077275  3.9840465   4.0298755  0.0000
Max.    750.0000 1023.0000 77.1379821 65.3909703 115.4837100 12.0000
               FL4-H
Min.      0.07356198
1st Qu.   4.00850577
Median    6.54383649
Mean      7.63730991
3rd Qu.   9.40467405
Max.    598.32964722

$`060909.002`
           FSC-H     SSC-H       FL1-H      FL2-H      FL3-H     FL1-A
Min.    142.0000    2.0000    1.225178  -9.500182 -14.912411    0.0000
1st Qu. 395.0000  105.0000  697.713095   1.833660   1.151590  163.0000
Median  436.0000  128.0000  930.538257   4.459861   2.742698  217.0000
Mean    437.1083  139.6543 1007.314594   7.079294   2.821286  241.4928
3rd Qu. 478.0000  158.0000 1229.743271   7.273601   4.315744  288.0000
Max.    823.0000 1023.0000 6433.872112 229.474811 111.774462 1023.0000
             FL4-H
Min.     -1.653782
1st Qu.   3.830212
Median    6.627982
Mean      7.498406
3rd Qu.   9.758926
Max.    865.056781

$`060909.003`
           FSC-H     SSC-H        FL1-H        FL2-H      FL3-H       FL1-A
Min.    143.0000    1.0000   -0.5140784    0.6126043 -10.215617   0.0000000
1st Qu. 399.0000   99.0000    2.8000828  570.5611401   2.893148   0.0000000
Median  438.0000  120.0000    3.7929212  790.0688747   6.045448   0.0000000
Mean    439.6068  131.0683    6.6322202  855.7791594   8.561511   0.6136273
3rd Qu. 479.0000  148.0000    5.0446053 1064.2509447  10.372666   0.0000000
Max.    747.0000 1023.0000 2266.5993076 7974.4423946 494.649317 617.0000000
             FL4-H
Min.    -95.220974
1st Qu.   2.443668
Median    5.522364
Mean      6.099909
3rd Qu.   8.828908
Max.    172.020884

$`060909.004`
           FSC-H    SSC-H       FL1-H       FL2-H       FL3-H    FL1-A
Min.    141.0000    1.000  -16.336878 -253.233156   -3.843461   0.0000
1st Qu. 404.0000  106.000    3.050386    2.260482    2.180202   0.0000
Median  441.0000  129.000    4.031819    3.018970    3.042886   0.0000
Mean    442.2971  140.567    5.467371    6.492448    4.080908   0.2166
3rd Qu. 480.0000  159.250    5.351827    3.977490    4.199364   0.0000
Max.    882.0000 1023.000 1394.767835 2234.708581 1503.912092 342.0000
              FL4-H
Min.      -2.189705
1st Qu.  288.656971
Median   358.057848
Mean     398.233200
3rd Qu.  448.298275
Max.    9903.460750

$`060909.005`
           FSC-H     SSC-H      FL1-H        FL2-H       FL3-H    FL1-A
Min.    140.0000    0.0000  -3.323577 -136.6745980    1.368162   0.0000
1st Qu. 395.0000  110.0000   2.937035    0.6104716   33.136154   0.0000
Median  429.0000  133.0000   4.288507    2.5916301   62.561880   0.0000
Mean    430.4819  143.8849   5.183453    1.9974478   82.414356   0.0796
3rd Qu. 465.0000  164.0000   6.060909    4.2000499  113.010888   0.0000
Max.    788.0000 1023.0000 889.542632  505.7006502 1497.934759 203.0000
              FL4-H
Min.    -99.0641730
1st Qu.   0.4953531
Median    5.7886969
Mean      5.9966387
3rd Qu.  10.8837241
Max.    838.5232587

A flowSet with 5 experiments.

  column names:
  FSC-H SSC-H FL1-H FL2-H FL3-H FL1-A FL4-H
A flowSet with 5 experiments.

  column names:
  FSC-H SSC-H FL1-H FL2-H FL3-H FL1-A FL4-H

flowCore documentation built on Sept. 13, 2017, 2:01 a.m.