mainClustering {clusterExperiment} | R Documentation

## Cluster distance matrix from subsampling

### Description

Given input data, this function will try to find the clusters based on the given ClusterFunction object.

### Usage

    ## S4 method for signature 'character'
    mainClustering(clusterFunction, ...)

    ## S4 method for signature 'ClusterFunction'
    mainClustering(clusterFunction, x = NULL,
      diss = NULL, distFunction = NA, clusterArgs = NULL, minSize = 1,
      orderBy = c("size", "best"), format = c("vector", "list"),
      checkArgs = TRUE, checkDiss = FALSE, returnData = FALSE, ...)

    ## S4 method for signature 'ClusterFunction'
    getPostProcessingArgs(clusterFunction)

### Arguments

`clusterFunction` | a `ClusterFunction` object that defines the clustering routine. See `ClusterFunction` for required format of user-defined clustering routines. User can also give a character value to the argument `clusterFunction` to indicate the use of clustering routines provided in package. Type `listBuiltInFunctions` at command prompt to see the built-in clustering routines. If `clusterFunction` is missing, the default is set to "pam".
`...` | arguments passed to the post-processing steps of the clustering. The available post-processing arguments for a `ClusterFunction` object depend on it's algorithm type and can be found by calling `getPostProcessingArgs`. See details below for documentation.
`x` | `p x n` data matrix on which to run the clustering (samples in columns).
`diss` | `n x n` data matrix of dissimilarities between the samples on which to run the clustering
`distFunction` | a distance function to be applied to `D`. Only relevant if input is only `x` (a matrix of data), and `diss=NULL`. See details of `clusterSingle` for the required format of the distance function.
`clusterArgs` | arguments to be passed directly to the `clusterFUN` slot of the `ClusterFunction` object
`minSize` | the minimum number of samples in a cluster. Clusters found below this size will be discarded and samples in the cluster will be given a cluster assignment of "-1" to indicate that they were not clustered.
`orderBy` | how to order the cluster (either by size or by maximum alpha value). If orderBy="size" the numbering of the clusters are reordered by the size of the cluster, instead of by the internal ordering of the `clusterFUN` defined in the `ClusterFunction` object (an internal ordering is only possible if slot `outputType` of the `ClusterFunction` is `"list"`).
`format` | whether to return a list of indices in a cluster or a vector of clustering assignments. List is mainly for compatibility with sequential part.
`checkArgs` | logical as to whether should give warning if arguments given that don't match clustering choices given. Otherwise, inapplicable arguments will be ignored without warning.
`checkDiss` | logical. Whether to check whether the input `diss` is valid.
`returnData` | logical as to whether to return the `diss` or `x` matrix in the output. If `FALSE` only the clustering vector is returned.

### Details

`mainClustering` is not meant to be called by the user. It is only an exported function so as to be able to clearly document the arguments for `mainClustering` which can be passed via the argument `mainClusterArgs` in functions like `clusterSingle` and `clusterMany`.

Post-processing Arguments: For post-processing the clustering, currently only type 'K' algorithms have a defined post-processing. Specifically

- "findBestK"logical, whether should find best K based on average silhouette width (only used if clusterFunction of type "K").

- "kRange"vector of integers to try for k values if findBestK=TRUE. If `k` is given in `clusterArgs`, then default is k-2 to k+20, subject to those values being greater than 2; if not the default is `2:20`. Note that default values depend on the input k, so running for different choices of k and findBestK=TRUE can give different answers unless kRange is set to be the same.

- "removeSil"logical as to whether remove the assignment of a sample to a cluster when the sample's silhouette value is less than `silCutoff`

- "silCutoff"Cutoff on the minimum silhouette width to be included in cluster (only used if removeSil=TRUE).

### Value

mainClustering returns a vector of cluster assignments (if format="vector") or a list of indices for each cluster (if format="list"). Clusters less than minSize are removed.

### Examples

    data(simData)
    cl1<-mainClustering(x=simData,clusterFunction="pam",clusterArgs=list(k=3))
    cl2<-mainClustering(simData,clusterFunction="hierarchical01",clusterArgs=list(alpha=.1))
    cl3<-mainClustering(simData,clusterFunction="tight",clusterArgs=list(alpha=.1))
    #change distance to manhattan distance
    cl4<-mainClustering(simData,clusterFunction="pam",clusterArgs=list(k=3),
         distFunction=function(x){dist(x,method="manhattan")})

    #run hierarchical method for finding blocks, with method of evaluating
    #coherence of block set to evalClusterMethod="average", and the hierarchical
    #clustering using single linkage:
    clustSubHier <- mainClustering(simData, clusterFunction="hierarchical01",
    minSize=5, clusterArgs=list(alpha=0.1,evalClusterMethod="average", method="single"))

    #do tight
    clustSubTight <- mainClustering(simData, clusterFunction="tight", clusterArgs=list(alpha=0.1),
    minSize=5)

    #two twists to pam
    clustSubPamK <- mainClustering(simData, clusterFunction="pam", silCutoff=0, minSize=5,
    removeSil=TRUE, clusterArgs=list(k=3))
    clustSubPamBestK <- mainClustering(simData, clusterFunction="pam", silCutoff=0,
    minSize=5, removeSil=TRUE, findBestK=TRUE, kRange=2:10)

    # note that passing the wrong arguments for an algorithm results in warnings
    # (which can be turned off with checkArgs=FALSE)
    clustSubTight_test <- mainClustering(simData, clusterFunction="tight",
    clusterArgs=list(alpha=0.1), minSize=5, removeSil=TRUE)
    clustSubTight_test2 <- mainClustering(simData, clusterFunction="tight",
    clusterArgs=list(alpha=0.1,evalClusterMethod="average"))

[Package clusterExperiment version 2.6.1 Index]