special-heatmap 3.1.2.1

A Python reproduction of the MATLAB Special Heatmap project.

Python Special Heatmap

Disclaimer: This project was implemented with the assistance of AI (Google Gemini).
声明：本项目代码由 AI (Google Gemini) 辅助生成。

介绍 / Introduction

A Python reproduction of the MATLAB special heatmap project. It uses matplotlib to draw advanced heatmaps with various shapes (square, circle, hexagon, pie, etc.) and triangular layouts.

基于 MATLAB 版 special heatmap 的 Python 复现。本项目使用 matplotlib 实现具有多种形状（正方形、圆形、六边形、饼图等）和三角矩阵布局的高级热图绘制。

1. 安装 / Installation

pip install special-heatmap

2. 基础使用 / Basic Use

2.1 绘制非负矩阵热图 (Draw positive heat map)

import numpy as np
import matplotlib.pyplot as plt
from special_heatmap import SHeatmap

data = np.random.rand(15, 15)
shm = SHeatmap(data, fmt='sq')
shm.draw()
plt.show()

2.2 绘制含负数热图 (Contains negative numbers)

data = np.random.rand(15, 15) - 0.5
shm = SHeatmap(data, fmt='sq')
shm.draw()
plt.show()

2.3 绘制有文本和 NaN 的热图 (Draw heat map with texts and NaN)

data = np.random.rand(12, 12) - 0.5
data[3, 3] = np.nan
shm = SHeatmap(data, fmt='sq')
shm.draw()
shm.set_text(fontsize=8)
plt.show()

3. 各类型热图 / Various Formats

支持的格式 (fmt 参数):

• sq (Square): 正方形 (Default)
• pie (Pie Chart): 饼图
• donut (Donut Chart): 环形饼图(甜甜圈图)
• circ (Circle): 圆形
• bcirc (Circle with box): 有底色的圆形
• oval (Oval): 椭圆形
• hex (Hexagon): 六边形
• star (Star): 五角星
• tril / trill: 下三角形状
• triu / triur: 上三角形状
• trilr: 右下三角形状
• triul: 左上三角形状
• asq (Auto-Square): 自适应大小的正方形
• acirc (Auto-Circle): 自适应大小的圆形
• cust / acust: 自定义形状（配合 sdata 参数传入多边形顶点坐标）

# 示例：绘制星形格式
shm = SHeatmap(data, fmt='star')
shm.draw()

Format	Positive Data (A)	Mixed Data (B)
sq (Square)
pie (Pie Chart)
donut (Donut)
circ (Circle)
bcirc (Circle w/ Box)
hex (Hexagon)
oval (Oval)
star (Star)
tril (Lower Triangle)
triu (Upper Triangle)
trilr (Lower-Right Tri)
triul (Upper-Left Tri)
asq (Auto-Square)
acirc (Auto-Circle)

自定义形状示例 (cust / acust):

cust (Custom)	acust (Auto-Custom)

4. 显示显著性 (Significance Stars)

可以使用 show_stars 方法根据 p-value 矩阵在热图上标注显著性星号。

pval_matrix = np.random.rand(12, 12) * 0.1
shm = SHeatmap(data, fmt='sq')
shm.draw()
shm.set_text()
# 默认 levels 为 [0.05, 0.01, 0.001]
shm.show_stars(pval_matrix)
plt.show()

5. 三角布局 / Triangular Layouts

支持以下布局类型 (set_type 方法):

• triu : 上三角 (Upper Triangle)
• tril : 下三角 (Lower Triangle)
• triu0 : 上三角无对角线 (Upper without Diagonal)
• tril0 : 下三角无对角线 (Lower without Diagonal)

data = np.random.rand(12, 12)
shm = SHeatmap(data, fmt='sq')
shm.set_type('tril') # 设置为下三角
shm.draw()
shm.set_text()
plt.show()

Type	Result
triu
tril
triu0
tril0

6. 树状图与聚类色块 / Dendrogram and Grouping

新增了对 SDendrogram 和 SClusterBlock 的支持，以实现热图边缘的高级注释。

from special_heatmap import SDendrogram, SClusterBlock

# 请参考源代码 tests/test_gallery.py 中的具体实现示例

Feature	Result
Tree (Dendrogram)
Group (Cluster Block)
Multilayer (Nested Group)
Tree & Group

7. 开源协议 / License

本项目采用 GPL v2 开源协议。详细内容请参阅 LICENSE 文件。 This project is licensed under the GPL v2 License. See the LICENSE file for details.

---

Original MATLAB project by slandarer