cell.process {immunoClust} | R Documentation

## Clustering of Cell-events in the immunoClust-pipeline

### Description

This function performs iterative model based clustering on cell-event data. It takes the observed cell-event data as major input and returns an object of class `immunoClust`, which contains the fitted mixture model parameter and cluster membership information. The additional arguments control the routines for data preprocessing, major loop and EMt-iteration, the model refinement routine and transformation estimation.

### Usage

    cell.process(fcs, parameters=NULL,
        apply.compensation=FALSE, classify.all=FALSE,
        N=NULL, min.count=10, max.count=10, min=NULL, max=NULL,
        I.buildup=6, I.final=4, I.trans=I.buildup,
        modelName="mvt", tol=1e-5, bias=0.3,
        sub.tol= 1e-4, sub.bias=bias, sub.thres=bias, sub.samples=1500,
        sub.extract=0.8, sub.weights=1, sub.standardize=TRUE,
        trans.estimate=TRUE, trans.minclust=10,
        trans.a=0.01, trans.b=0.0, trans.parameters=NULL)

    cell.MajorIterationLoop(dat, x=NULL, parameters=NULL,
        I.buildup=6, I.final=4,
        modelName="mvt", tol=1e-5, bias=0.3,
        sub.bias=bias, sub.thres=0.0, sub.tol=1e-4, sub.samples=1500,
        sub.extract=0.8, sub.weights=1, sub.EM="MEt", sub.standardize=TRUE)

    cell.MajorIterationTrans(fcs, x=NULL, parameters=NULL,
        I.buildup=6, I.final=4, I.trans=I.buildup,
        modelName="mvt", tol=1e-5, bias=0.3,
        sub.bias=bias, sub.thres=0.0, sub.tol=1e-4, sub.samples=1500,
        sub.extract=0.8, sub.weights=1, sub.EM="MEt", sub.standardize=TRUE,
        trans.minclust=5, trans.a=0.01, trans.decade=-1, trans.scale=1.0,
        trans.proc="vsHtransAw")

    cell.InitialModel(dat, parameters=NULL, trans.a = 0.01, trans.b = 0.0,
        trans.decade=-1, trans.scale=1.0)

    cell.classifyAll(fcs, x, apply.compensation=FALSE)

### Arguments

`fcs` | An object of class flowFrame. Rows correspond to observations and columns correspond to measured parameters.
`dat` | A numeric matrix, data frame of observations, or object of class flowFrame. Rows correspond to observations and columns correspond to measured parameters.
`x` | An object of class `immunoClust`. Used as inital model int the major iteration loop. When left unspecified the simplest model containing 1 cluster is used as initial model.

Arguments for data pre and post processing:

`parameters` | A character vector specifying the parameters (columns) to be included in clustering. When it is left unspecified, all the parameters will be used.
`apply.compensation` | A numeric indicator whether the compensation matrix in the flowFrame should be applied.
`classify.all` | A numeric indicator whether the removed over- and underexposed observations should also be classified after the clustering process.
`N` | Maximum number of observations used for clustering. When unspecified or higher than the number of observations (i.e. rows) in dat, all observations are used for clustering, otherwise only the first `N` observations.
`min.count` | An integer specifying the threshold count for filtering data points from below. The default is 10, meaning that if 10 or more data points are smaller than or equal to `min`, they will be excluded from the analysis. If `min` is `NULL`, then the minimum value of each parameter will be used. To suppress filtering, it is set to -1.
`max.count` | An integer specifying the threshold count for filtering data points from above. Interpretation is similar to that of `min.count`.
`min` | The lower limit set for data filtering. Note that it is a vector of length equal to the number of parameters (columns), implying that a different value can be set for each parameter.
`max` | The upper limit set for data filtering. Interpretation is similar to that of `min`.

Arguments for the major loop and EMt-iteration:

`I.buildup` | The number of major iterations, where the number of used observations is doubled successively.
`I.final` | The number of major iterations with all observations.
`I.trans` | The number of iterations where transformation estimation is applied.
`modelName` | Used mixture model; either `"mvt"` for a t-mixture model or `"mvn"` for a Gaussian Mixture model. With `"mvt2"` an implementation variant for `"mvt"` is given, which is more reliable for samples with cutted values at the lower or upper edges of the parameter space (e.g. for CyTOF all values below a detection limit are set to zero which leads to wrong co-variance estimators and poor clustering results).
`tol` | The tolerance used to assess the convergence of the major EM(t)-algorithms of all observations.
`bias` | The ICL-bias used in the major EMt-algorithms of all observations.

Arguments for model refinement (sub-clustering):

`sub.tol` | The tolerance used to assess the convergence of the EM-algorithms in the sub-clustering.
`sub.bias` | The ICL-bias used in the sub-clustering EMt-algorithms, in general the same as the ICL-bias.
`sub.thres` | Defines the threshold, below which an ICL-increase is meaningless. The threshold is given as the multiple (or fraction) of the costs for a single cluster.
`sub.samples` | The number of samples used for initial hierarchical clustering.
`sub.extract` | The threshold used for cluster data extraction.
`sub.weights` | Power of weights applied to hierarchical clustering, where the used weights are the probabilities of cluster membership.
`sub.EM` | Used EM-algorithm; either `"MEt"` for EMt-iteration or `"ME"` for EM-iteration without test step.
`sub.standardize` | A numeric indicating whether the samples for hierarchical clustering are standardized (mean=0, SD=1).

Arguments for transformation optimization:

`trans.estimate` | A numeric indicator whether transformation estimation should be applied.
`trans.minclust` | The minimum number of clusters required to start transformation estimation.
`trans.a` | A numeric vector, giving the (initial) scaling a for the asinh-transformation h(y) = asin(a \cdot y + b). A scaling factor of a=0 indicates that a parameter is not transformed.
`trans.b` | A numeric vector, giving the (initial) translation b for the asinh-transformation.
`trans.parameters` | A character vector, specifying the parameters (columns) to be applied for transformation. When it is left unspecified, the parameters to be transformed are obtained by the `PxDISPLAY` information of the flowFrame description parameters. All parameters with LOG display values are transformed.
`trans.decade` | A numeric scale value for the theorectical maximum of transformed observation value. If below 0, no scaling of the trasnformed values is applied, which is the default in the immunoClust-pipeline.
`trans.scale` | A numeric scaling factor for the linear (i.e. not transformed) parameters. By default the linear parameters (normally the scatter parameters) are not scaled.
`trans.proc` | An experimental switch for alternative procedures; should be "vsHtransAw".

### Details

The `cell.process` function does data preprocessing and calls the major iteration loop either with or without integrated transformation optimization. When transformation optimization is applied the transformation parameters give the initial transformation otherwise they define the fixed transformation.

The major iteration loop with included transformation optimization relies on `flowFrames` structure from the `flowCore`-package for the storage of the observed data.

The `cell.InitialModel` builds up an initial `immunoClust-object` with one cluster and the given transformation parameters.

The `cell.classifyAll` calculates the cluster membership for the removed cell events. The assigment of the cluster membership is critical for over- and underexposed obsevervations and the interpretaion is problematic.

### Value

The fitted model information in an object of class `immunoClust`.

### Note

a) The data preprocessing arguments (`min.count`, `max.count`, `min` and `max`) for removing over- and underexposed observations are adopted from `flowCust-package` with the same meaning.

b) The `sub.thres` value is given in here in relation to the single cluster costs 1/2 x P x (P+1) x log(N). An absolute increase of the log-likelihood above is reported as reasonable from the literature. From our experience a higher value is required for this increase in FC data. For the ICL-bias and the sub.thres identical values were chosen. For the CyTOF dataset this value had been adjusted to 0.05 since the absolute increase of the log-likelihood became to high due to the high number of parameters.

c) The `sub.extract` value controls the smooth data extraction for a cluster. A higher value includes more events for a cluster in the sub-clustering routine.

d) The default value of `trans.a=0.01` for the initial transformation is optimized for Fluorescence Cytometry. For CyTOF data the initial scaling value was `trans.a=1.0`.

### Author(s)

Till Sörensen till-antoni.soerensen@charite.de

### References

Sörensen, T., Baumgart, S., Durek, P., Grützkau, A. and Häupl, T. immunoClust - an automated analysis pipeline for the identification of immunophenotypic signatures in high-dimensional cytometric datasets. Cytometry A (accepted).

### See Also

`immunoClust-object`, `plot`, `splom`, `cell.FitModel`, `cell.SubClustering`, `trans.FitToData`

### Examples

    data(dat.fcs)
    res <- cell.process(dat.fcs)
    summary(res)

[Package immunoClust version 1.22.0 Index]