cubeheatmap

Publication-quality square-cell heatmaps for matplotlib

cubeheatmap renders clean, equal-sized square-cell heatmaps designed for scientific publications, reports, and presentations. Works with numpy arrays, pandas DataFrames, and any 2-D numerical data.

Features

• Square cells - every cell is a perfect square, sized automatically
• Multiple input formats - from_matrix(), from_dataframe()
• Annotations - display values inside cells with auto-contrast text
• Significance markers - overlay stars or custom symbols with sig_mask
• Grid layouts - draw_grid() for multi-panel figures
• Fully customisable - 36+ style parameters: colors, fonts, rounded corners, dark themes
• Domain presets - citation networks, software dependencies, data pipelines, web graphs, social networks

Installation

pip install cubeheatmap

Quick Start

import numpy as np
import cubeheatmap as ch

data = np.random.uniform(-4, 4, (10, 3))
hm = ch.CubeHeatmap.from_matrix(
    data,
    row_labels=[f"Gene_{i}" for i in range(10)],
    col_labels=["Day14", "Day21", "Day40"],
)

style = ch.Style(cmap="RdBu_r", vmin=-4, vmax=4, colorbar_label="log2FC")
ax = ch.draw(hm, title="My Heatmap", style=style)
ax.figure.savefig("heatmap.png", dpi=150, bbox_inches="tight")

For presets, customization and transforms see docs/usage.md.

Gallery

Annotated	Significance markers	Dark theme
Grid layout	Rounded corners	Likert survey
Citation network	Model benchmark	Dense microarray

Examples

16 runnable scripts covering all features and presets - see docs/examples.md for the full list with previews.

cd examples && python generate_all.py

Citation

If you use cubeheatmap in a publication, please cite it:

APA:

dam2452. (2026). cubeheatmap: Publication-quality square-cell heatmaps for Python (Version 0.1.1). https://github.com/dam2452/cubeheatmap

BibTeX:

@software{cubeheatmap2026,
  title   = {cubeheatmap: Publication-quality square-cell heatmaps for Python},
  author  = {dam2452},
  year    = {2026},
  version = {0.1.1},
  url     = {https://github.com/dam2452/cubeheatmap}
}

Contributing

Contributions are welcome! Here's how you can help:

1. Bug reports - Open an issue with a minimal reproducible example
2. Feature requests - Open an issue describing the use case
3. Code contributions - Fork, create a feature branch, and open a pull request
4. New presets - Add a new submodule under cubeheatmap/presets/ with a to_heatmap() function and an example

Development setup

git clone https://github.com/dam2452/cubeheatmap.git
cd cubeheatmap
pip install -e ".[dev]"
pytest tests/

License

This project is licensed under CC BY-NC 4.0 - Creative Commons Attribution-NonCommercial 4.0 International.

• Use it freely - for research, education, personal projects
• Cite the author - attribution required in publications and derivative works
• No commercial use - you may not sell or monetize this software

See LICENSE for full details.