getHeatmapOrder determines an order for the rows or columns of a matrix or an assay so that similar entities are placed next to each other. The order can be used to sort heatmaps, and it is used internally by plotting functions such as plotHeatmap and plotLoadings.

getHeatmapOrder(x, ...)

# S4 method for class 'SummarizedExperiment'
getHeatmapOrder(x, assay.type = "counts", ...)

# S4 method for class 'dist'
getHeatmapOrder(x, method = "MDS_angle", control = NULL, ...)

# S4 method for class 'ANY'
getHeatmapOrder(
  x,
  method = "PCA_angle",
  MARGIN = "rows",
  decreasing = TRUE,
  control = NULL,
  ...
)

Arguments

x

A matrix, a dist object or a SummarizedExperiment object.

...

Additional arguments. Currently not used.

assay.type

Character scalar. Specifies the assay to use when x is a SummarizedExperiment. (Default: "counts")

method

Character scalar or BlusterParam object. Specifies the ordering method. See details. (Default: "PCA_angle", or "MDS_angle" when x is a dist object)

control

NULL or list. Control parameters passed to seriation::seriate(). (Default: NULL)

MARGIN

Character scalar. Specifies whether to order "rows" or "cols". Ignored when x is a dist object. (Default: "rows")

decreasing

Logical scalar. When ordering based on a single variable, should the order be decreasing? (Default: TRUE)

Value

An integer vector of row or column indices in the sorted order.

Details

The ordering method is specified with method:

  • Single variable: If method is a name of a column (when MARGIN = "rows") or a row (when MARGIN = "cols"), entities are ordered based on the values of that variable. For instance, features of a loadings matrix can be ordered based on a single principal component.

  • Seriation: Other character values specify a seriation method that is passed to seriation::seriate(). See seriation::list_seriation_methods("matrix") for available methods. For example, "PCA_angle" orders entities by their angle in the space of the first two principal components (NeatMap ordering, see Rajaram & Oono 2010), and "Heatmap" uses hierarchical clustering with optimal leaf ordering.

  • Clustering: If method is a BlusterParam object, entities are clustered with bluster::clusterRows(), and entities belonging to the same cluster are placed next to each other.

If x is a dist object, seriation methods for distances (see seriation::list_seriation_methods("dist")), such as "MDS_angle" (NeatMap-like angular ordering in the space of classical multidimensional scaling) or "OLO" (hierarchical clustering with optimal leaf ordering), are applied to the distances directly. Other methods are applied to the full distance matrix, i.e., each entity is described by its distances to all entities.

References

Rajaram S & Oono Y (2010) NeatMap - non-clustering heat map alternatives in R. BMC Bioinformatics 11, 45. doi:10.1186/1471-2105-11-45

Hahsler M, Hornik K & Buchta C (2008) Getting Things in Order: An Introduction to the R Package seriation. Journal of Statistical Software 25(3), 1-34. doi:10.18637/jss.v025.i03

Examples

library(mia)
data(GlobalPatterns)
tse <- agglomerateByRank(GlobalPatterns, rank = "Phylum")
tse <- subsetBy(tse, rows = rowMeans(counts > 0) > 0.5, collapse = TRUE)
tse <- transformAssay(tse, method = "clr", pseudocount = 0.5)

# Order features with NeatMap-like angular ordering
row_order <- getHeatmapOrder(tse, assay.type = "clr")
#> Registered S3 method overwritten by 'seriation':
#>   method         from 
#>   reorder.hclust vegan
# Order samples with hierarchical clustering
col_order <- getHeatmapOrder(
    tse, assay.type = "clr", method = "Heatmap", MARGIN = "cols")
tse <- tse[row_order, col_order]

# Order based on clustering
row_order <- getHeatmapOrder(
    tse, assay.type = "clr", method = bluster::KmeansParam(3))

# Order features of a matrix based on a single column
mat <- assay(tse, "clr")
getHeatmapOrder(mat, method = "CL3")
#>  [1] 30 29 28 31 32 26  3 33 22 25 34  4  8 19 27  2 23 11 17  6 21 35 20  9 18
#> [26] 14 24 10  5 12  7 13  1 15 16

# Order samples based on dissimilarities
diss <- getDissimilarity(tse, method = "euclidean", assay.type = "clr")
getHeatmapOrder(diss)
#>  [1] 23 17 22 18 20 21 19 16  2  3  1  4  7 11  6  5  8  9 12 10 13 15 14 26 24
#> [26] 25