Template-class {flowMatch} | R Documentation

## Template: An S4 class representing a template of a group of FC Samples.

### Description

An object of class "`Template`" summarizes a group of samples belonging to same biological-class with a class-template. A template is represented by a collection of meta-clusters (`MetaCluster`) created from samples of same class. An object of class "`Template`" therefore stores a list of `MetaCluster` objects and other necessary parameters.

### Creating Object

An object of class "`Template`" can be created using the function `create.template` :
`create.template(clustSamples, dist.type = "Mahalanobis", unmatch.penalty=999999, template.id = NA_integer_)`.

The arguments to the `create.template` function is described below:

- `clustSamples:` A list of `ClusteredSample` objects from which the template is created. The working examples describe how this objects are created by clustering FC samples.

- `dist.type:` character, indicating the method with which the dissimilarity between a pair of clusters is computed. Supported dissimilarity measures are: 'Mahalanobis', 'KL' and 'Euclidean'. If this argument is not passed then 'Mahalanobis' distance is used by default.

- `unmatch.penalty:` A numeric value denoting the penalty for leaving a cluster unmatched. This parameter should be already known or be estimated empirically estimated from data (see the reference for a discussion). Default is set to a very high value so that no cluster remains unmatched.

- `template.id:` integer, denoting the index of the template (relative to other template). Default is `NA_integer_`

### Slots

`num.metaclusters`:

  The number of meta-clusters in the template.

`metaClusters`:

  A list of length `num.metaclusters` storing the meta-clusters. Each meta-cluster is stored as an object of class `MetaCluster`.

`dimension`:

  Dimensionality of the samples from which the template is created.

`size`:

  Number of cells in the template (summation of all meta-cluster sizes).

`tree`:

  A list (similar to an `hclust` object) storing the hierarchy of the samples in a template.

`template.id`:

  integer, denoting the index of the template (relative to other templates). Default is `NA_integer_`

### Accessors

All the slot accessor functions take an object of class `Template`. I show usage of the first accessor function. Other functions can be called similarly.

`get.size`:

  Number of cells in the template (summation of all meta-cluster sizes).

  Usage: `get.size(object)`

  here `object` is a `Template` object.

`get.num.metaclusters`:

  Returns the number of meta-clusters in the template.

`get.metaClusters`:

  Returns a list of length `num.metaclusters` storing the meta-clusters. Each meta-cluster is stored as an object of class `MetaCluster`.

`get.dimension`:

  Returns the dimensionality of the samples from which the template is created.

`get.tree`:

  Returns a `hclust` object storing the hierarchy of the samples in a template.

`get.template.id`:

  Returns the index of the template (relative to other templates).

### Methods

show

  Display details about the `Template` object.

summary

  Return descriptive summary for each `MetaCluster` of a Template.

  Usage: `summary(Template)`

plot

  We plot a template as a collection of bivariate contour plots of its meta-clusters. To plot each meta-cluster we consider the clusters within the meta-cluster normally distributed and represent each cluster with an ellipsoid. The axes of an ellipsoid is estimated from the eigen values and eigen vectors of the covariance matrix of a cluster ("Applied Multivariate Statistical Analysis" by R. Johnson and D. Wichern, 5th edition, Prentice hall). We then plot the bivariate projection of the ellipsoid as 2-D ellipses.

  Usage:

  `plot(template, alpha=.05, plot.mc=FALSE, color.mc=NULL, colorbysample=FALSE, ...)`

  the arguments of the plot function are:

  - `template:` An object of class `Template` for which the plot function is invoked.

  - `alpha:` (1-alpha)*100% quantile of the distribution of the clusters or meta-cluster is plotted.

  - `plot.mc:` TRUE/FALSE, when TRUE the functions draws contour of the combined meta-cluster and when FALSE the function draws the contours of the individual clusters.

  - `color.mc:` A character vector of length `num.metaclusters` denoting the colors to be used to draw the contours. The ith color of this vector is used to draw the ellipses denoting clusters in the ith meta-cluster or the combined ith meta-cluster (depending on the argument `plot.mc`). By default an empty vector is passed and then an arbitrary color is used to draw each meta-cluster.

  - `colorbysample:` TRUE/FALSE, when TRUE the functions draws clusters from same samples in a single color and when FALSE the function draws meta-clusters in a single color.

  - `... :` Other usual plotting related parameters.

template.tree

  Plot the hierarchy of samples established while creating the template-tree. See `template.tree`

### Author(s)

Ariful Azad

### References

Azad, Ariful and Pyne, Saumyadipta and Pothen, Alex (2012), Matching phosphorylation response patterns of antigen-receptor-stimulated T cells via flow cytometry; BMC Bioinformatics, 13 (Suppl 2), S10.

### See Also

`MetaCluster`, `ClusteredSample`, `create.template`, `template.tree`

### Examples

    ## ------------------------------------------------
    ## load data
    ## ------------------------------------------------

    library(healthyFlowData)
    data(hd)

    ## ------------------------------------------------
    ## Retrieve each sample, clsuter it and store the
    ## clustered samples in a list
    ## ------------------------------------------------
    set.seed(1234) # for reproducable clustering
    cat('Clustering samples: ')
    clustSamples = list()
    for(i in 1:length(hd.flowSet))
    {
      cat(i, ' ')
      sample1 = exprs(hd.flowSet[[i]])
      clust1 = kmeans(sample1, centers=4, nstart=20)
      cluster.labels1 = clust1$cluster
      clustSample1 = ClusteredSample(labels=cluster.labels1, sample=sample1)
      clustSamples = c(clustSamples, clustSample1)
    }

    ## ------------------------------------------------
    ## Create a template from the list of clustered samples and plot functions
    ## ------------------------------------------------

    template = create.template(clustSamples)
    summary(template)

    ## plot the tree denoting the hierarchy of the samples in a template
    tree = template.tree(template)

    ## plot the template in terms of the meta-clusters
    ## option-1 (default): plot contours of each cluster of the meta-clusters
    plot(template)

    ## option-2: plot contours of each cluster of the meta-clusters with defined color
    plot(template, color.mc=c('blue','black','green3','red'))

    ## option-3: plot contours of the meta-clusters with defined color
    plot(template, plot.mc=TRUE, color.mc=c('blue','black','green3','red'))

    ## option-4: plot contours of each cluster of the meta-clusters with different colors for different samples
    plot(template, colorbysample=TRUE)

[Package flowMatch version 1.28.0 Index]