Given a matrix expressing the cross-similarity between two (possibly different) sets of entities, this will reorder it to move the high values close to the diagonal, for a better visualization.

sheatmap(
data,
...,
order_data = NULL,
annotation_col = NULL,
annotation_row = NULL,
order_rows = TRUE,
order_cols = TRUE,
squared_order = TRUE,
same_order = FALSE,
patch_cols_order = NULL,
patch_rows_order = NULL,
discount_outliers = TRUE,
cluster_rows = TRUE,
cluster_cols = TRUE,
oclust_rows = TRUE,
oclust_cols = TRUE,
clustering_distance_rows = "euclidian",
clustering_distance_cols = "euclidian",
clustering_method = "ward.D2",
clustering_callback = NA
)

## Arguments

data A rectangular matrix to plot, of non-negative values (unless order_data is specified). Additional flags to pass to pheatmap. An optional matrix of non-negative values of the same size to use for computing the orders. Optional data frame describing each column. Optional data frame describing each row. Whether to reorder the rows. Otherwise, use the current order. Whether to reorder the columns. Otherwise, use the current order. Whether to reorder to minimize the l2 norm (otherwise minimizes the l1 norm). Whether to apply the same order to both rows and columns (if reordering both). For a square matrix, may also contain 'row' or 'column' to force the order of one axis to apply to both. Optional function that may be applied to the columns order, returning a better order. Optional function that may be applied to the rows order, returning a better order. Whether to do a final order phase discounting outlier values far from the diagonal. Whether to cluster the rows, or the clustering to use. Whether to cluster the columns, or the clustering to use. Whether to use oclust instead of hclust for the rows (if clustering them). Whether to use oclust instead of hclust for the columns (if clustering them). The default method for computing row distances (by default, euclidian). The default method for computing column distances (by default, euclidian). The default method to use for hierarchical clustering (by default, ward.D2 and *not* complete). Is not supported.

## Value

Whatever pheatmap returns.

## Details

If you have an a-priori order for the rows and/or columns, you can prevent reordering either or both by specifying order_rows=FALSE and/or order_cols=FALSE. Otherwise, slanted_orders is used to compute the "ideal" slanted order for the data.

By default, the rows and columns are ordered independently from each other. If the matrix is asymmetric but square (e.g., a matrix of weights of a directed graph such as a K-nearest-neighbors graph), then you can can specify same_order=TRUE to force both rows and columns to the same order. You can also specify same_order='row' to force the columns to use the same order as the rows, or same_order='column' to force the rows to use the same order as the columns.

You can also specify a patch_cols_order and/or a patch_rows_order function that takes the computed "ideal" order and returns a patched order. For example, this can be used to force special values (such as "outliers") to the side of the heatmap.

There are four options for controlling clustering:

* By default, sheatmap will generate a clustering tree using oclust, to generate the "best" clustering that is also compatible with the slanted order.

* Request that sheatmap will use the same hclust as pheatmap (e.g., oclust_rows=FALSE). In this case, the tree is reordered to be the "most compatible" with the target slanted order. That is, sheatmap will invoke reorder_hclust so that, for each node of the tree, the order of the two sub-trees will be chosen to best match the target slanted order. The end result need not be identical to the slanted order, but is as close as possible given the hclust clustering tree.

* Specify an explicit clustering (e.g., cluster_rows=hclust(...)). In this case, sheatmap will again merely reorder the tree but will not modify it.

In addition, you can give this function any of the pheatmap flags, and it will just pass them on. This allows full control over the diagram's features.

Note that clustering_callback is not supported. In addition, the default clustering_method here is ward.D2 instead of complete, since the only methods supported by oclust are ward.D and ward.D2.

## Examples

slanter::sheatmap(cor(t(mtcars)))
slanter::sheatmap(cor(t(mtcars)), oclust_rows=FALSE, oclust_cols=FALSE)
pheatmap::pheatmap(cor(t(mtcars)))