heatmap_plus            package:Heatplus            R Documentation

_D_i_s_p_l_a_y _a_n _A_n_n_o_t_a_t_e_d _H_e_a_t_m_a_p

_D_e_s_c_r_i_p_t_i_o_n:

     This function displays an expression data matrix as a heatmap with
     a column dendrogram. A given clustering will be shown in color. 
     Additionally, a number of binary and interval scaled covariates
     can be added to characterize these clusters.

_U_s_a_g_e:

     heatmap_plus(x, addvar, covariate = NULL, picket.control = list(), h, clus,
                  cluscol, cluslabel = NULL, Rowv, Colv, reorder = c(TRUE, TRUE),
                              distfun = dist, hclustfun = hclust, scale = c("row", "column",
                              "none"), na.rm = TRUE, do.dendro = TRUE, col = heat.colors(12),
                              trim, equalize = FALSE, ...)

_A_r_g_u_m_e_n_t_s:

       x: the numerical data matrix to be displayed.

  addvar: data frame with (mostly binary) covariates.

covariate: integer indicating the one column in 'addvar' that is
          interval scaled.

picket.control: list of option for drawing the covariates, passed to
          'picketplot'.

       h: height at which to cut the dendrogram, as in 'cutree';
          overrides 'clus'.

    clus: an explicit vector of cluster memberships for the columns of
          'x', if no dendrogram is used; ignored if 'do.dendro=TRUE'
          and 'h' is specified.

 cluscol: a vector of colors used to indicate clusters.

cluslabel: labels to designate cluster names.

    Rowv: either a dendrogram or a vector of reordering indexes for the
          rows.

    Colv: either a dendrogram or a vector of reordering indexes for the
          columns.

 reorder: logical vector of length two, indicating whether the rows and
          columns (in this order) should be reordered using
          'order.dendrogram'.

 distfun: function to compute the distances between rows and columns.
          Defaults to 'dist'.

hclustfun: function used to cluster rows and columns. Defaults to
          'hclust'.

   scale: indicates whether values should be scaled by either by row,
          column, or not at all. Defaults to 'row'.

   na.rm: logical indicating whther to remove NAs.

do.dendro: logical indicating whether to draw the column dendrogram.

     col: the color scheme for 'image'. The default sucks.

    trim: Percentage of values to be trimmed. This helps to keep an
          informative color scale, see Details.

equalize: logical indicating whther to use the ranks of the data for
          setting the color scheme; alternative to 'trim', see Details.

     ...: extra arguments to 'image'.

_D_e_t_a_i_l_s:

     This is a heavily modified version of 'heatmap_2', which is a
     heavily modfied version of an old version of 'heatmap' in package
     'stats', so some of the arguments are described in more detail
     there. The main distinguishing feature of this routine is the
     possibility to color a cluster solution, and to add a covariate
     display.

     Covariates are assumed to be binary, coded as 0 and 1 (or 'FALSE'
     and 'TRUE' respectively). One of the covariates can be interval
     scaled, the column index of this variable is supplied via argument
     'covariate'. The details of the added display are handled by the
     function 'picketplot'.

     Setting 'trim' to a number between 0 and 1 uses equidistant
     classes between the ('trim')- and (1-'trim')-quantile, and lumps
     the values below and above this range into separate open-ended
     classes. If the data comes from a heavy-tailed distribution, this
     can save the display from putting too many values into to few
     classes. Alternatively, you can set 'equal=TRUE', which uses an
     equidistant color scheme for the ranks of the values.

_V_a_l_u_e:

     A list with components 

  rowInd: indices of the rows of the display in terms of the rows of
          'x'.

  colInd: ditto for the columns of the display.

    clus: the cluster indices of the columns of the display.

_A_u_t_h_o_r(_s):

     Original by Andy Liaw, with revisions by Robert Gentleman and
     Martin Maechler.

     Alexander Ploner for the modifications documented here.

_S_e_e _A_l_s_o:

     'heatmap_2', 'heatmap', 'picketplot', 'cutplot.dendrogram',
     'RGBColVec'

_E_x_a_m_p_l_e_s:

     # create data
     mm = matrix(rnorm(1000, m=1), 100,10)
     mm = cbind(mm, matrix(rnorm(2000), 100, 20))
     mm = cbind(mm, matrix(rnorm(1500, m=-1), 100, 15))
     mm2 = matrix(rnorm(450), 30, 15)
     mm2 = cbind(mm2, matrix(rnorm(900,m=1.5), 30,30))
     mm=rbind(mm, mm2)
     colnames(mm) = paste("Sample", 1:45)
     rownames(mm) = paste("Gene", 1:130)
     addvar = data.frame(Var1=rep(c(0,1,0),c(10,20,15)),
                         Var2=rep(c(1,0,0),c(10,20,15)),
                         Var3=rep(c(1,0), c(15,30)),
                         Var4=rep(seq(0,1,length=4), c(10,5,15,15))+rnorm(45, sd=0.5))
     addvar[3,3] = addvar[17,2] = addvar[34,1] =NA
     colnames(addvar) = c("Variable X","Variable Y", "ZZ","Interval")

     # the lame default, without clustering
     # Labels do not look too hot that way
     heatmap_plus(mm)

     # without labels, but with cluster
     dimnames(mm)=NULL
     heatmap_plus(mm, h=40)

     # add some covariates, with nice names
     heatmap_plus(mm, addvar=addvar, cov=4)

     # covariates and clustering
     heatmap_plus(mm, addvar=addvar, cov=4, h=20, col=RGBColVec(64), equal=TRUE)

     # Clustering without the dendrogram
     cc = cutree(hclust(dist(t(mm))), k=5)
     heatmap_plus(mm, addvar=addvar, cov=4, clus=cc, do.dendro=FALSE)

