Document heatmap clustering method

Author: pfh

R/heatmap.R

@@ -3,9 +3,15 @@
 #'
 #' Produces a heatmap as a grid grob.
 #'
-#' Clustering is performed using the "seriation" package, and is approximately a Travelling Salesman Problem ordering. If there are many features (more than a couple of thousand) clustering may be slow.
+#' This heatmap differs from other heatmaps in R in the method of clustering used:
 #'
-#' @param y A matrix of expression levels, such as a transformed counts matrix.
+#' 1. The distances used are cosine distances (i.e. the magnitude of log fold changes is not important, only the pattern).
+#'
+#' 2. \code{hclust()} is used to produce a clustering, as normal.
+#'
+#' 3. Branches in the hierarchical clustering are flipped to minimize sharp changes between neighbours, using the seriation package's OLO (Optimal Leaf Ordering) method.
+#'
+#' @param y A matrix of expression levels, such as a transformed counts matrix as produced by \code{varistran::vst}.
 #' @param cluster_samples Should samples (columns) be clustered?
 #' @param cluster_features Should features (rows) be clustered?
 #' @param sample_labels Names for each sample. If not given and y has column names, these will be used instead.
@@ -20,6 +26,15 @@
 #' Additionally $info$row_order will contain row ordering and $info$col_order will contain column ordering.
 #' @author Paul Harrison.
 #'
+#' @examples
+#'
+#' # Generate some random data.
+#' counts <- matrix(rnbinom(1000, size=1/0.01, mu=100), ncol=10)
+#'
+#' y <- varistran::vst(counts, cpm=TRUE)
+#' print( varistran::plot_heatmap(y, n=20) )
+#'
+#'
 #' @export
 plot_heatmap <- function(
         y,

R/plot.R

@@ -133,17 +133,13 @@ plot_stability <- function(y, x=NULL, design=NULL, bins=20) {
 #'
 #' Produce a ggplot object containing a biplot of expression data.
 #'
-#' Biplot based on the Singular Value Decomposition of the matrix x. The
-#' dimensions corresponding to the two largest singular values are shown.
+#' Biplot based on the Singular Value Decomposition of the matrix x, after subtracting row means. The dimensions corresponding to the two largest singular values are shown.
 #'
 #' Genes are shown in blue and samples in red.
 #'
-#' The dot product of the gene and sample vectors approximates the difference
-#' from the average expression level of that gene in that sample.
+#' The dot product of the gene and sample vectors approximates the difference from the average expression level of that gene in that sample.
 #'
-#' Sample points (red) are scaled to have the same variance in the two
-#' dimensions. Therefore the gene points (blue) may have greater variance along
-#' dimension 1 if dimension 1 explains more of the variance than dimension 2.
+#' Sample points (red) are scaled to have the same variance in the two dimensions. Therefore the gene points (blue) may have greater variance along dimension 1 if dimension 1 explains more of the variance than dimension 2.
 #'
 #' @param x Matrix of expression levels, with features (eg genes) as rows and
 #' samples as columns. For example, you could use the output of varistran::vst

_pkgdown.yml

@@ -13,6 +13,9 @@ reference:
     contents:
       - vst
       - shiny_report
+      - plot_stability
+      - plot_biplot
+      - plot_heatmap
 
   - title: Support functions
     contents: