clusterDendrogram {clusterExperiment} | R Documentation

## Accessing and manipulating the dendrograms

### Description

These functions are for accessing and manipulating the dendrograms stored in a `ClusterExperiment` object. We also document the required format of these dendrograms here.

### Usage

    ## S4 method for signature 'ClusterExperiment'
    clusterDendrogram(x)

    ## S4 method for signature 'ClusterExperiment'
    sampleDendrogram(x)

    ## S4 method for signature 'ClusterExperiment'
    nInternalNodes(x)

    ## S4 method for signature 'ClusterExperiment'
    nTips(x)

    ## S4 method for signature 'ClusterExperiment'
    nNodes(x)

    ## S4 replacement method for signature 'ClusterExperiment'
    nodeLabels(x, ...) <- value

    ## S4 method for signature 'ClusterExperiment,phylo4d,phylo4d'
    checkDendrogram(x, dendroCluster, dendroSample, whichCluster = "dendro")

    ## S4 method for signature 'ClusterExperiment'
    nodeLabels(x)

    ## S4 method for signature 'ClusterExperiment'
    nodeIds(x, type = c("all", "internal", "tip"))

    ## S4 method for signature 'ClusterExperiment'
    convertToDendrogram(x)

### Arguments

`x` | a ClusterExperiment object
`...` | additional options passed to `nodeLabels<-` (ignored)
`value` | replacement value for `nodeLabels`. See details.
`dendroCluster` | a `phylo4d` to be check as for being cluster hierarchy
`dendroSample` | a `phylo4d` to be check as for being cluster hierarchy
`whichCluster` | argument that can be a single numeric or character value indicating the single clustering to be used. Giving values that result in more than one clustering will result in an error. See details of `getClusterIndex`.
`type` | the type of node to return results from. One of "all", "internal", and "tip".

### Details

Two dendrograms are stored in a `ClusterExperiment` object. One is a dendrogram that describes the hierarchy between the clusters (`@dendro_clusters`), and the other is a dendrogram that extends that hierarchy to include the clusters (`@dendro_samples`). The clustering that is used to make these hierarchies is saved in as well (`@dendro_index`)

The dendrograms stored in a `ClusterExperiment` object are required to be a `phylo4d-class` from the package `phylobase` (which uses the basic format of the S3 class `phylo` in the `ape` package to store the edges; `phylobase` makes it a S4 class with some useful helpers). This class allows storage of a data.frame of information corresponding to information on each node (see `tdata`).

Additional requirements are made of these dendrograms to be a valid for the slots of the `ClusterExperiment` class, described below, regarding the data that must be stored with it and the labels which can be assigned. Possible dendrograms can be checked for validity with the function `checkDendrogram`. The reason for the restrictions on the labels is so as to not duplicate storage of the names, see below descriptions for where to save user-defined names.

- LabelsThe cluster dendrogram can only have labels on the internal nodes. Labels on the internal nodes of the cluster dendrogram can be set by the user (the function `nodeLabels<-` is defined to work on a `ClusterExperiment` object to make this easy). The tips of the cluster dendrogram, corresponding to the clusters, cannot have labels; users can set the labels (e.g. for plotting, etc) in the `clusterLegend` slot using the function `renameClusters`.

- Data The cluster hierarchy must have data stored with it that has the following columns (additional ones are allowed):

  - NodeIdThe permanent node id for the node. Must be of the format "NodeIdX" where "X" is a integer.

  - PositionThe type of node, in terms of its position. The internal nodes should have the values "cluster hierarchy node" while the tips should have "cluster hierarchy tip".

  - ClusterIdDendroOnly for tips of dendrogram, should have the id that corresponds to its cluster in the clustering of the @dendro_index. Of the form "ClusterIdX", where "X" is the internal cluster id (see `clusterLegend`). Internal nodes should have NA values.

  - ClusterIdMergeThe id that corresponds to the cluster in the clustering of the @merge_index, if it exists. Of the form "ClusterIdX", where "X" is the internal cluster id (see `clusterLegend`

- LabelsThe sample dendrogram is not allowed to have ANY labels. The names for those nodes that correspond to the cluster hierarchy will be pulled from the names in the cluster hierarchy for plotting, etc. and should be set there (see above). Sample names for the tips of the tree will be pulled from `colnames` of the object and should be set there.

- Data The cluster hierarchy must have data stored with it that has the following columns (additional ones are allowed):

  - NodeIdFor those nodes that correspond to a node in the cluster hierarchy, should have its permanent node id in this column. Other nodes should be NA.

  - PositionThe type of node, in terms of its position. The internal nodes should have the values "cluster hierarchy node" while the tips should have "cluster hierarchy tip".

  - SampleIndexOnly for tips of dendrogram, the index of the sample at that tip to the samples in the object.

For setting the node labels of the cluster dendrogram via `nodeLabels<-`, the replacement value has to have names that match the internal ids of the cluster dendrogram (the `NodeId` column).

### Value

`clusterDendrogram` returns the dendrogram describing the clustering hierarchy.

`sampleDendrogram` returns the dendrogram that expands the cluster hierarchy to the samples.

`nInternalNodes` returns the number of internal nodes of the cluster hierarchy.

`nTips` returns the number of tips of the cluster hierarchy (same as number of non-negative clusters in the dendrogram clustering)

`nNodes` returns the number of total nodes of the cluster hierarchy

`nodeLabels<-` sets the node labels of the cluster dendrogram

`checkClusterDendrogram` checks if a `phylo4d` objects are valid for the cluster and sample dendrogram slots of the given `ClusterExperiment` object. Returns `TRUE` if there are no problems. Otherwise creates error.

`nodeLabels` returns the node labels of the cluster dendrogram

`nodeIds` returns the internal (permanent) node ids of the cluster dendrogram

`convertToDendrogram` returns the sample dendrogram converted to a `dendrogram` class.

### The Stored Dendrograms

NA

### Cluster Hierarchy

NA

### Sample Hierarchy

NA

### Helper Functions

NA

### See Also

`makeDendrogram`, `phylo4d-class`, `phylo`

`dendrogram`

### Examples

    data(rsecFluidigm)
    # retrieve the dendrogram of the clusters:
    head(clusterDendrogram(rsecFluidigm),5)
    # retrieve the dendrogram of the samples:
    head(sampleDendrogram(rsecFluidigm),5)
    # Return # internal nodes from cluster hierarchy
    nInternalNodes(rsecFluidigm)
    # Return # tips from cluster hierarchy (i.e. # clusters)
    nTips(rsecFluidigm)
    # Return internal node ids
    nodeIds(rsecFluidigm,type="internal")
    # Labels assigned to internal nodes
    nodeLabels(rsecFluidigm)
    # Assign new labels to the internal nodes of the cluster hierarchy
    l1<-paste("A", 1:nInternalNodes(rsecFluidigm),sep=":")
    names(l1)<-nodeIds(rsecFluidigm,type="internal")
    nodeLabels(rsecFluidigm)<-l1
    nodeLabels(rsecFluidigm)

[Package clusterExperiment version 2.10.1 Index]