clusterDendrogram: Accessing and manipulating the dendrograms

In epurdom/clusterCells: Compare Clusterings for Single-Cell Sequencing

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)

epurdom/clusterCells documentation built on April 28, 2024, 8:14 p.m.