[jiajic]

showClusterHeatmap() gains cluster_custom_order, to lay the clusters out in a given order on both axes, for example a cluster tree's leaf order:

tree <- Giotto::calculateClusterTree(g, cluster_column = "leiden_clus", feats = hvf)
showClusterHeatmap(g, cluster_column = "leiden_clus", feats = hvf,
    cluster_custom_order = tree$labels[tree$order])

When given, the clusters are not clustered and no dendrogram is drawn. The order only arranges the clusters, so the plot shows the correlations without claiming a structure. The correlations are computed from the data shown, as before.

Why an order, not a tree

An earlier version of this PR took tree = and drew its branches. In every other tree consumer, the tree drives the operation: it defines the comparisons in findClusterTreeMarkers() and the groups in annotateClusterTree(). Here it would only have set the layout while the colors were recomputed. Its branches could then describe different data than the plot, with a warning in the best case and silently in the worst: a re-clustered object with the same label set passes every check. An order makes no such claim. A plot of a tree's own correlation matrix belongs with the tree itself (a possible plot(tree, what = "heatmap") from its recorded matrix), not with a function that recomputes from the object.

The name follows plotHeatmap() and dotPlot() (cluster_custom_order), not plotMetaDataHeatmap()'s custom_cluster_order. Aligning those names is part of the heatmap consolidation, to be filed as a separate issue.

Also

• Any expression name: expression_values accepts any expression name. It used to reject anything other than "normalized" / "scaled" / "custom", such as "raw". The validation now matches Giotto's.
• Docs: @returns now says it returns a ComplexHeatmap Heatmap object. It previously said ggplot.
• Validation: cluster_custom_order must name every cluster shown, exactly once. Otherwise the error lists what's missing or not in the data.

Verification

New test-cluster-heatmap-order.R:

• the matrix follows the given order and no dendrogram is drawn
• the values are the unordered heatmap's matrix, rearranged
• with no order, it still clusters and draws its own dendrogram
• incomplete, extra or duplicated orders error

The tests don't need Giotto. All 45 tests pass (100 expectations).

🤖 Generated with Claude Code