ClusterMatch-class {flowMatch} | R Documentation

## ClusterMatch: A class representing matching of cluster/meta-clusters across a pair of FC samples/templates

### Description

An object of class "`ClusterMatch`" represents matching of cluster/meta-clusters across a pair of FC samples/templates. A cluster (meta-cluster) from a sample (template) can match to zero, one or more than one cluster (meta-clusters) in another sample (template).

### Creating Object

An object of class "`ClusterMatch`" is usually created by calling the function `match.clusters`:

`match.clusters(object1, object2, dist.type='Mahalanobis', unmatch.penalty=999999)`.

Here, `object1` and `object2` are two objects of class `ClusteredSample` or `Template` between which the clusters or meta-clusters are matched. See the example section and also the `match.clusters` function for more details.

Unless you know exactly what you are doing, creating an object of class "`ClusterMtach`" using `new` or using the constructor is discouraged.

### Slots

Let `S1` and `S2` be two FC samples or templates with `k1` and `k2` clusters or meta-clusters respectively. Then the matching of clusters (meta-clusters) across `S1` and `S2` is represented by an object of class "`ClusterMatch`" that contains the following slots:

`match12`:

  A list of length `k1` where `match12[[i]]` stores the indices of clusters (meta-clusters) from `S2` matched to the `i-th` clustrer (meta-cluster) of `S1`. `match12[[i]]=NULL` if the `i-th` cluster (meta-cluster) of `S1` remains unmatched, otherwise, it stores a vector of matched clusters (meta-clusters) from `S2`.

`match21`:

  A list of length `k2` where `match21[[i]]` stores the indices of clusters (meta-clusters) from `S1` matched to the `i-th` clustrer (meta-cluster) of `S2`. `match21[[i]]=NULL` if the `i-th` cluster (meta-cluster) of `S2` remains unmatched, otherwise, it stores a vector of matched clusters (meta-clusters) from `S1`.

`matching.cost`:

  The cost of matching clusters (meta-clusters) across the samples. It is equal to the summation of dissimilarities of the matched clusters (meta-clusters) and penalty for the unmatched clusters (meta-clusters).

`unmatch.penalty`:

  A numeric value denoting the penalty for leaving a cluster (meta-cluster) unmatched. If we set it to a a very large value then no cluster (meta-cluster) remains unmatched giving an edge cover solution.

### Accessors

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

`get.match12`:

  Returns the matching from cluster in sample 1 to clusters in sample 2. See the slot description for details. Usage: `get.match12(object)`

  here `object` is a `ClusterMatch` object.

`get.match21`:

  Returns the matching from cluster in sample 2 to clusters in sample 1. See the slot description for details.

`get.matching.cost`:

  Returns the total cost of matching clusters (meta-clusters) across the pair samples/templates.

`get.unmatch.penalty`:

  Returns the penalty for leaving a cluster (meta-cluster) unmatched.

### Methods

show

  Display details about the `ClusterMatch` object.

summary

  Return descriptive summary of the matching of clusters (meta-clusters) across a pair of samples (templates). Shows both list and matrix format.

  Usage: `summary(ClusterMatch)`

### Author(s)

Ariful Azad

### See Also

`match.clusters`, `ClusteredSample`, `Template`

### Examples

    ## ------------------------------------------------
    ## load data and retrieve two samples
    ## ------------------------------------------------

    library(healthyFlowData)
    data(hd)
    sample1 = exprs(hd.flowSet[[1]])
    sample2 = exprs(hd.flowSet[[2]])

    ## ------------------------------------------------
    ## cluster sample using kmeans algorithm
    ## ------------------------------------------------

    clust1 = kmeans(sample1, centers=4, nstart=20)
    clust2 = kmeans(sample2, centers=4, nstart=20)
    cluster.labels1 = clust1$cluster
    cluster.labels2 = clust2$cluster

    ## ------------------------------------------------
    ## Create ClusteredSample object
    ## and compute mahalanobis distance between two clsuters
    ## ------------------------------------------------

    clustSample1 = ClusteredSample(labels=cluster.labels1, sample=sample1)
    clustSample2 = ClusteredSample(labels=cluster.labels2, sample=sample2)
    ## compute the dissimilarity matrix
    DM = dist.matrix(clustSample1, clustSample2, dist.type='Mahalanobis')

    ## ------------------------------------------------
    ## Computing matching of clusteres
    ## An object of class "ClusterMatch" is returned
    ## ------------------------------------------------

    mec = match.clusters(clustSample1, clustSample2, dist.type="Mahalanobis", unmatch.penalty=99999)
    ## show the matching
    summary(mec)

    ## **********************************************************************
    ## ************** Now matching meta-clusters across templates ***********
    ## **********************************************************************

    ## ------------------------------------------------
    ## Retrieve each sample, clsuter it and store the
    ## clustered samples in a list
    ## ------------------------------------------------

    cat('Clustering samples: ')
    clustSamples = list()
    for(i in 1:10) # read 10 samples and cluster them
    {
      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 two templates each from five samples
    ## ------------------------------------------------

    template1 = create.template(clustSamples[1:5])
    template2 = create.template(clustSamples[6:10])

    ## ------------------------------------------------
    ## Match meta-clusters across templates
    ## ------------------------------------------------

    mec = match.clusters(template1, template2, dist.type="Mahalanobis", unmatch.penalty=99999)
    summary(mec)

    ## ------------------------------------------------
    ## Another example of matching meta-clusters & clusters
    ## across a template and a sample
    ## ------------------------------------------------

    mec = match.clusters(template1, clustSample1, dist.type="Mahalanobis", unmatch.penalty=99999)
    summary(mec)

[Package flowMatch version 1.23.0 Index]