plotly-complexheatmap

ComplexHeatmap-style visualizations built on Plotly — clustered heatmaps with dendrograms, annotation tracks, and split heatmaps using native, interactive Plotly figures.

Inspired by the R ComplexHeatmap package by Zuguang Gu, this library brings the same expressive annotation and clustering features to the Python/Plotly ecosystem with WebGL-first rendering for large matrices.

Gallery

Multi-side annotations with dendrograms

Categorical colour bars, numeric bar charts, and hierarchical clustering on three sides:

Split heatmap with per-group dendrograms

Rows split by annotation group, each clustered independently:

Single-DataFrame workflow (from_dataframe)

Pass one pandas or polars DataFrame — annotations are auto-extracted from columns:

See examples/showcase.ipynb for all 8 examples including stacked bars, box plots, violin plots, and polars integration.

Installation

pip install plotly-complexheatmap

# Optional extras
pip install plotly-complexheatmap[fast]    # fastcluster for large matrices
pip install plotly-complexheatmap[polars]  # polars DataFrame support

Quick Start

import numpy as np
import pandas as pd
from plotly_complexheatmap import ComplexHeatmap, HeatmapAnnotation

rng = np.random.default_rng(42)
df = pd.DataFrame(
    rng.standard_normal((30, 12)),
    index=[f"gene_{i}" for i in range(30)],
    columns=[f"sample_{j}" for j in range(12)],
)

# Column annotations (top)
top_ha = HeatmapAnnotation(
    group=["Control"] * 6 + ["Treatment"] * 6,
    quality={"values": rng.uniform(0.7, 1.0, 12), "type": "bar", "color": "#E8853D"},
)

# Row annotations (right)
right_ha = HeatmapAnnotation(
    pathway=["Metabolism"] * 10 + ["Signaling"] * 10 + ["Other"] * 10,
    which="row",
)

hm = ComplexHeatmap(
    df,
    top_annotation=top_ha,
    right_annotation=right_ha,
    colorscale="RdBu_r",
    normalize="row",
    name="z-score",
)
fig = hm.to_plotly()
fig.show()

Single-DataFrame shortcut

# One flat table with data + metadata columns
hm = ComplexHeatmap.from_dataframe(
    df,
    index_column="gene",
    row_annotations=["pathway", "score"],
    col_annotations={"group": ["Ctrl"] * 4 + ["Drug"] * 4},
    colorscale="RdBu_r",
    normalize="row",
)

Works with both pandas and polars DataFrames.

Features

Hierarchical Clustering

• Row and/or column clustering via scipy.cluster.hierarchy
• Configurable method (ward, complete, average, ...) and metric (euclidean, correlation, ...)
• Optional fastcluster backend for large matrices
• Dendrograms rendered as native Plotly line traces

Annotation Tracks

Pass data as keyword arguments to HeatmapAnnotation — track type is auto-detected:

Supported positions: top_annotation, bottom_annotation, left_annotation, right_annotation.

Split Heatmaps

Divide rows into groups that are clustered independently:

hm = ComplexHeatmap(
    df,
    split_rows_by=["GroupA"] * 15 + ["GroupB"] * 15,
    # Or reference an annotation track by name:
    # split_rows_by="pathway",
)

WebGL Rendering

For matrices larger than 100,000 cells, go.Heatmapgl (WebGL) is used automatically. Override with use_webgl=True/False.

Z-Score Normalisation

hm = ComplexHeatmap(df, normalize="row")    # per-row
hm = ComplexHeatmap(df, normalize="column") # per-column
hm = ComplexHeatmap(df, normalize="global") # whole matrix

API Reference

ComplexHeatmap

ComplexHeatmap.from_dataframe

HeatmapAnnotation

Dependencies

• plotly >= 5.5.0
• scipy >= 1.9.0
• numpy >= 1.22.0
• pandas >= 1.4.0
• Optional: fastcluster >= 1.2.0, polars >= 0.20.0

License

MIT