dendromat: Plot a dendrogram with a colorgram underneath

Description

Plot a dendrogram with a colorgram underneath. The colorgram typically indicates characteristics about each element in the dendrogram.

Usage

dendromat(x, mat, 
         labRow = rownames(mat), labCol = colnames(mat),
         height = NA, gap = 0, matlabside = 2, border = NA, 
         cex.lab = par('cex.axis'), ...)

Arguments

An object of type hclust or dendrogram.

mat

A matrix or data frame of colors, with each row corresponding to an item in the dendrogram.

labRow

Labels of items, to be placed underneath the matrix.

labCol

Labels for characteristics, to be placed next to the matrix.

height

Fraction of the plot area to reserve for the color matrix. If NA, the spacing is set automatically.

gap

Extra space (in lines) to add between the dendrogram and the matrix.

matlabside

Which side of the matrix to put labCol (2 or 4).

border

Border color for the color matrix.

cex.lab

Relative text size for the item labels.

…

Further arguments passed to plot.dendrogram.

Value

none.

Details

The order of labRow and the rows of mat should correspond to the input to hclust (or whatever function created x). This function reorders mat and labRow to match the dendrogram, using order.dendrogram.

This function combines two plots using layout; therefore it is incompatible with other multiple-plot schemes (e.g. par(mfrow)).

If height == NA (the default), the function tries to leave enough room for the item labels at the bottom, and enough room for the color matrix in the middle. The leftover plotting area on the top is used for the dendrogram. The lower margin setting (see par) is ignored.

If labRow is set to NULL, or is equal to NULL because mat lacks rownames, then the item labels are taken from x instead.

Examples

Run this code

# NOT RUN {
## Motor Trend car road test data
mt.dend <- hclust(dist(mtcars[,1:7]))
mt.mat <- mtcars[,8:11]

## A minimal dendromat
dendromat(mt.dend, mt.mat)

## The same plot, but with a few enhancements
names(mt.mat) <- c('Straight', 'Manual', '# gears', '# carbs')
dendromat(mt.dend, mt.mat, gap = 0.5, border = 'gray', las = 2, 
  ylab = 'Euclidean distance', 
  main = 'mtcars, clustered by performance')
legend('topright', legend = 0:8, fill = 0:8)

## US state data, with color keys
us.dend <- hclust(dist(scale(state.x77)))

income <- state.x77[, 'Income']
frost <- state.x77[, 'Frost']
murder <- state.x77[, 'Murder']

income.cmap <- makecmap(income, n = 5, colFn = colorRampPalette(c('black', 'green')))
frost.cmap <- makecmap(frost, n = 5, colFn = colorRampPalette(c('black', 'blue')))
murder.cmap <- makecmap(murder, n = 5, colFn = colorRampPalette(c('black', 'red')))

us.mat <- data.frame(Frost = cmap(frost, frost.cmap),
                     Murder = cmap(murder, murder.cmap),
                     Income = cmap(income, income.cmap))

par(mar = c(5,4,4,3)+0.1)
dendromat(us.dend, us.mat,
  ylab = 'Distance', main = 'US states')

vkey(frost.cmap, 'Frost')
vkey(murder.cmap, 'Murder', y = 0.3)
vkey(income.cmap, 'Income', y = 0.7)

# }