Heatmaps

Graphs for showing a 2D matrix.

A graph showing a heatmap. See HeatmapGraphData and HeatmapGraphConfiguration .

function heatmap_graph(;
    [figure_title::Maybe{AbstractString} = nothing,
    x_axis_title::Maybe{AbstractString} = nothing,
    y_axis_title::Maybe{AbstractString} = nothing,
    entries_colors_title::Maybe{AbstractString} = nothing,
    entries_values::Maybe{AbstractMatrix{<:Real}} = Float32[;;],
    rows_names::Maybe{AbstractVector{<:AbstractString}} = nothing,
    columns_names::Maybe{AbstractVector{<:AbstractString}} = nothing,
    entries_hovers::Maybe{AbstractMatrix{<:AbstractString}} = nothing,
    rows_hovers::Maybe{AbstractVector{<:AbstractString}} = nothing,
    columns_hovers::Maybe{AbstractVector{<:AbstractString}} = nothing,
    rows_annotations::AbstractVector{AnnotationData} = AnnotationData[],
    columns_annotations::AbstractVector{AnnotationData} = AnnotationData[],
    rows_arrange_by::Maybe{AbstractMatrix{<:Real}} = nothing,
    columns_arrange_by::Maybe{AbstractMatrix{<:Real}} = nothing,
    rows_order::Maybe{Union{Hclust, AbstractVector{<:Integer}}} = nothing,
    columns_order::Maybe{Union{Hclust, AbstractVector{<:Integer}}} = nothing,
    rows_groups::Maybe{AbstractVector} = nothing,
    columns_groups::Maybe{AbstractVector} = nothing,
    configuration::HeatmapGraphConfiguration = HeatmapGraphConfiguration()]
)::HeatmapGraph

Create a HeatmapGraph by initializing only the HeatmapGraphData fields (with an optional HeatmapGraphConfiguration ).

@kwdef mutable struct HeatmapGraphData <: AbstractGraphData
    figure_title::Maybe{AbstractString} = nothing
    x_axis_title::Maybe{AbstractString} = nothing
    y_axis_title::Maybe{AbstractString} = nothing
    entries_colors_title::Maybe{AbstractString} = nothing
    entries_values::Maybe{AbstractMatrix{<:Real}} = Float32[;;]
    rows_names::Maybe{AbstractVector{<:AbstractString}} = nothing
    columns_names::Maybe{AbstractVector{<:AbstractString}} = nothing
    entries_hovers::Maybe{AbstractMatrix{<:AbstractString}} = nothing
    rows_hovers::Maybe{AbstractVector{<:AbstractString}} = nothing
    columns_hovers::Maybe{AbstractVector{<:AbstractString}} = nothing
    rows_annotations::AbstractVector{AnnotationData} = AnnotationData[]
    columns_annotations::AbstractVector{AnnotationData} = AnnotationData[]
    rows_arrange_by::Maybe{AbstractMatrix{<:Real}} = nothing
    columns_arrange_by::Maybe{AbstractMatrix{<:Real}} = nothing
    rows_order::Maybe{Union{Hclust, AbstractVector{<:Integer}}} = nothing
    columns_order::Maybe{Union{Hclust, AbstractVector{<:Integer}}} = nothing
    rows_groups::Maybe{AbstractVector} = nothing
    columns_groups::Maybe{AbstractVector} = nothing
end

The data for a graph showing a heatmap (matrix) of entries.

This is shown as a 2D image where each matrix entry is a small rectangle with some color. Due to Plotly limitation, colors must be continuous. The hover for each rectangle is a combination of the entries_hovers , rows_hovers and columns_hovers for the entry.

By default, if reordering the data, this is based on the entries_values . You can override this by specifying an an ..._arrange_by matrix of the same size. For efficiency the rows_arrange_by matrix should be in row-major layout, but that's not critical.

Alternatively you can force the order of the data by specifying the ..._order permutation. You can also specify an Hclust object as the order. If you ask for a dendogram and did not specify such a clustering, one will be computed.

If ..._groups are specified, then a gap can be added between entries of different groups. Groups can also be used to constrain the computed clustering.

Valid combinations of the fields controlling order and clustering are:

data order	data arrange_by	data groups	config reorder	config dendogram_size	config linkage	config metric	result tree	result order	notes
nothing	nothing	ignored	nothing	nothing	nothing	nothing	Not computed	Original data order	Do not cluster, use the original data order (default)
nothing	nothing / AbstractMatrix{<:Real}	ignored	nothing	Any	nothing / Any	nothing / Any	ehclust of original order with linkage or WardLinkage	Original data order	Cluster, preserving the original order
nothing	nothing	ignored	SameOrder	nothing / Any	nothing	nothing	Same as other axis	Same as other axis	Square matrices only
nothing	nothing / AbstractMatrix{<:Real}	nothing	OptimalHclust / RCompatibleHclust	nothing / Any	nothing / Any	nothing / Any	hclust with linkage or WardLinkage	hclust with reorder	Cluster using linkage and branch reorder
nothing	nothing / AbstractMatrix{<:Real}	Any	OptimalHclust / RCompatibleHclust	nothing / Any	nothing / Any	nothing / Any	ehclust with groups and linkage or WardLinkage	hclust with groups and reorder	Cluster using groups , linkage and branch reorder
nothing	nothing / AbstractMatrix{<:Real}	nothing	SlantedHclust / SlantedPreSquaredHclust	nothing / Any	nothing / Any	nothing / Any	hclust with linkage or WardLinkage , then reorder_hclust by slanted_orders	reorder_hclust by slanted_orders	Cluster, then slant preserving the tree
nothing	nothing / AbstractMatrix{<:Real}	Any	SlantedHclust / SlantedPreSquaredHclust	nothing / Any	nothing / Any	nothing / Any	hclust with groups and linkage or WardLinkage , then reorder_hclust by slanted_orders	reorder_hclust by slanted_orders	Cluster using groups , then slant preserving the tree
nothing	nothing / AbstractMatrix{<:Real}	ignored	SlantedOrder / SlantedPreSquaredOrder	nothing / Any	nothing / Any	nothing / Any	ehclust of slanted_orders with linkage or WardLinkage	slanted_orders	Slant, then cluster preserving the slanted order
Hclust	nothing	ignored	nothing	nothing / Any	nothing	nothing	Hclust tree	Hclust order	Force a specific tree and order on the data
Hclust	nothing / AbstractMatrix{<:Real}	ignored	SlantedHclust / SlantedPreSquaredHclust	nothing / Any	nothing	nothing	reorder_hclust by slanted_orders	reorder_hclust by slanted_orders	Slant, preserving a given tree
AbstractVector{<:Integer}	nothing	ignored	nothing	nothing	nothing	nothing	Not computed	order permutation	Do not cluster, use the specified order
AbstractVector{<:Integer}	nothing	ignored	nothing	Any	nothing / Any	nothing / Any	ehclust of order with linkage or WardLinkage	order permutation	Cluster, preserving the specified order
AbstractVector{<:Integer}	nothing	nothing	ReorderHclust	nothing / Any	nothing / Any	nothing / Any	hclust with linkage or WardLinkage	reorder_hclust by data order	Cluster, then reorder branches to be close to order
AbstractVector{<:Integer}	nothing	Any	ReorderHclust	nothing / Any	nothing / Any	nothing / Any	ehclust with groups and linkage or WardLinkage	reorder_hclust by data order	Cluster, then reorder branches to be close to order

All other combinations are invalid. Note:

• When calling hclust and/or ehclust and/or slanted_orders , then specifying arrange_by will use it instead of the displayed data matrix.

• When calling hclust and/or ehclust , then specifying a metric will be used instead of Euclidean to compute the distances matrix.

• Specifying groups only impacts the tree and order when computing a new clustering without other order constraints. They can still be specified to denote gaps in the heatmap, even when they do not impact the tree and/or order.

@kwdef mutable struct HeatmapGraphConfiguration <: AbstractGraphConfiguration
    figure::FigureConfiguration = FigureConfiguration()
    entries_colors::ColorsConfiguration = ColorsConfiguration()
    rows_annotations::AnnotationSize = AnnotationSize()
    columns_annotations::AnnotationSize = AnnotationSize()
    rows_reorder::Maybe{HeatmapReorder} = nothing
    columns_reorder::Maybe{HeatmapReorder} = nothing
    rows_linkage::Maybe{HeatmapLinkage} = nothing
    columns_linkage::Maybe{HeatmapLinkage} = nothing
    rows_metric::Maybe{PreMetric} = nothing
    columns_metric::Maybe{PreMetric} = nothing
    rows_groups_gap::Maybe{Integer} = 1
    columns_groups_gap::Maybe{Integer} = 1
    rows_dendogram_size::Real = nothing
    columns_dendogram_size::Maybe{Real} = nothing
    rows_dendogram_line::LineConfiguration = LineConfiguration()
    columns_dendogram_line::LineConfiguration = LineConfiguration()
    origin::HeatmapOrigin = HeatmapBottomLeft
end

Configure a graph showing a heatmap.

This displays a matrix of values using a rectangle at each position. Due to Plotly's limitations, you still to manually tweak the graph size for best results; there's no way to directly control the width and height of the rectangles. In addition, the only supported color configurations are using continuous color palettes.

You can use ..._reorder reorder the data. When specifying ..._linkage , by default, the clustering uses the Euclidean distance metric. You can override this by specifying the ..._metric .

If groups are specified for some entries (rows and/or columns), they can be used to constrain the clustering, and/or to create visible gaps in the heatmap (between entries of different groups). groups. The size of the gaps is the number of fake entries to added between the separated entries. That is, the default gap of 1 will add a blank gap of one entry between adjacent entries of different groups. A gap of nothing will not be shown.

If you specify ..._dendogram_size , then you should either specify linkage (for computing a clustering) or must specify Hclust order in the data. The dendogram tree will be shown to the side of the data. The size is specified in the usual inconvenient units (fractions of the total graph size) because Plotly.

If a dendogram tree is shown, the ..._dendogram_line can be used to control it. The default color is black. The is_filled field shouldn't be set as it has no meaning here.

Specify how to reorder the rows and/or columns.

• OptimalHclust orders hclust branches using the (better) Bar-Joseph method.
• RCompatibleHclust orders hclust branches in the same (bad) way that R does.
• ReorderHclust reorders hclust branches to be as close as possible to a given order (using reorder_hclust ).
• SlantedHclust and SlantedPreSquaredHclust orders hclust branches using Slanter (using slanted_orders and reorder_hclust ).
• SlantedOrder and SlantedPreSquaredOrder uses slanted_orders (if a tree is needed, uses ehclust to create a tree preserving this order).
• SameOrder orders the rows/columns in the same way as the other axis. This can only be applied to square matrices and can't be specified for both axes.

Specify the linkage to use when performing hierarchical clustering ( hclust / ehclust ). The default is WardLinkage .

Specify where the origin (row 1 column 1) should be displayed. The Plotly default is HeatmapBottomLeft .