0
# Matrix Plots
1

2
Create heatmaps and clustered heatmaps for visualizing matrix data, correlation matrices, pivot tables, and hierarchical clustering results. These functions excel at revealing patterns in high-dimensional data and relationships between variables.
3

4
## Capabilities
5

6
### Heatmaps
7

8
Plot rectangular data as a color-encoded matrix with customizable annotations and styling.
9

10
```python { .api }
11
def heatmap(
12
    data,
13
    *,
14
    vmin=None,
15
    vmax=None,
16
    cmap=None,
17
    center=None,
18
    robust=False,
19
    annot=None,
20
    fmt=".2g",
21
    annot_kws=None,
22
    linewidths=0,
23
    linecolor="white",
24
    cbar=True,
25
    cbar_kws=None,
26
    cbar_ax=None,
27
    square=False,
28
    xticklabels="auto",
29
    yticklabels="auto",
30
    mask=None,
31
    ax=None,
32
    **kwargs
33
):
34
    """
35
    Plot rectangular data as a color-encoded matrix.
36
    
37
    Parameters:
38
    - data: 2D array-like, rectangular dataset for heatmap
39
    - vmin, vmax: float, colormap range anchors
40
    - cmap: str or colormap, colormap for mapping data values to colors
41
    - center: float, value at which to center colormap
42
    - robust: bool, use robust quantiles for colormap range
43
    - annot: bool or array-like, annotate cells with data values
44
    - fmt: str, format string for annotations
45
    - annot_kws: dict, keyword arguments for annotation text
46
    - linewidths: float, width of lines dividing cells
47
    - linecolor: str, color of lines dividing cells
48
    - cbar: bool, draw colorbar
49
    - cbar_kws: dict, keyword arguments for colorbar
50
    - square: bool, make cells square-shaped
51
    - xticklabels, yticklabels: bool, list, or "auto", axis labels
52
    - mask: bool array, cells to mask (not plot)
53
    
54
    Returns:
55
    matplotlib Axes object
56
    """
57
```
58

59
### Clustered Heatmaps
60

61
Plot hierarchically-clustered heatmaps with dendrograms.
62

63
```python { .api }
64
def clustermap(
65
    data,
66
    *,
67
    pivot_kws=None,
68
    method="average",
69
    metric="euclidean",
70
    z_score=None,
71
    standard_scale=None,
72
    figsize=(10, 10),
73
    cbar_kws=None,
74
    row_cluster=True,
75
    col_cluster=True,
76
    row_linkage=None,
77
    col_linkage=None,
78
    row_colors=None,
79
    col_colors=None,
80
    mask=None,
81
    dendrogram_ratio=0.2,
82
    colors_ratio=0.03,
83
    cbar_pos=(0.02, 0.8, 0.05, 0.18),
84
    tree_kws=None,
85
    **kwargs
86
):
87
    """
88
    Plot a matrix dataset as a hierarchically-clustered heatmap.
89
    
90
    Parameters:
91
    - data: 2D array-like, rectangular dataset for clustering
92
    - method: str, linkage method for hierarchical clustering
93
    - metric: str or function, distance metric for clustering
94
    - z_score: int or None, standardize data along axis (0=rows, 1=columns)
95
    - standard_scale: int or None, normalize data along axis
96
    - figsize: tuple, figure size in inches
97
    - row_cluster, col_cluster: bool, cluster rows/columns
98
    - row_linkage, col_linkage: array-like, precomputed linkage matrices
99
    - row_colors, col_colors: list or array, colors for row/column labels
100
    - dendrogram_ratio: float, proportion of figure for dendrograms
101
    - colors_ratio: float, proportion of figure for color annotations
102
    - cbar_pos: tuple, colorbar position (left, bottom, width, height)
103
    - tree_kws: dict, keyword arguments for dendrogram
104
    - **kwargs: additional arguments passed to heatmap()
105
    
106
    Returns:
107
    ClusterGrid object with components:
108
    - .ax_heatmap: heatmap axes
109
    - .ax_row_dendrogram: row dendrogram axes  
110
    - .ax_col_dendrogram: column dendrogram axes
111
    - .ax_cbar: colorbar axes
112
    """
113
```
114

115
## Usage Examples
116

117
### Basic Heatmap
118

119
```python
120
import seaborn as sns
121
import matplotlib.pyplot as plt
122
import numpy as np
123

124
# Create sample correlation matrix
125
flights = sns.load_dataset("flights")
126
flights_pivot = flights.pivot(index="month", columns="year", values="passengers")
127

128
# Basic heatmap
129
sns.heatmap(flights_pivot)
130
plt.show()
131
```
132

133
### Correlation Matrix Heatmap
134

135
```python
136
# Correlation matrix with annotations
137
tips = sns.load_dataset("tips")
138
correlation_matrix = tips.select_dtypes(include=[np.number]).corr()
139

140
sns.heatmap(
141
    correlation_matrix,
142
    annot=True,
143
    cmap="coolwarm",
144
    center=0,
145
    square=True,
146
    fmt=".2f"
147
)
148
plt.show()
149
```
150

151
### Masked Heatmap
152

153
```python
154
# Mask upper triangle of correlation matrix
155
mask = np.triu(np.ones_like(correlation_matrix, dtype=bool))
156

157
sns.heatmap(
158
    correlation_matrix,
159
    mask=mask,
160
    annot=True,
161
    cmap="coolwarm",
162
    center=0,
163
    square=True,
164
    linewidths=0.5
165
)
166
plt.show()
167
```
168

169
### Clustered Heatmap
170

171
```python
172
# Hierarchically clustered heatmap
173
sns.clustermap(
174
    flights_pivot,
175
    cmap="viridis",
176
    standard_scale=1,  # Normalize columns
177
    figsize=(10, 8)
178
)
179
plt.show()
180
```
181

182
### Clustered Heatmap with Annotations
183

184
```python
185
# Add row and column color annotations
186
row_colors = ["red" if month in ["Dec", "Jan", "Feb"] else "blue" 
187
              for month in flights_pivot.index]
188

189
sns.clustermap(
190
    flights_pivot,
191
    row_colors=row_colors,
192
    cmap="Blues",
193
    z_score=1,  # Z-score normalize columns
194
    figsize=(12, 8),
195
    cbar_kws={"label": "Normalized Passengers"}
196
)
197
plt.show()
198
```
199

200
### Custom Colormap and Formatting
201

202
```python
203
# Custom colormap with centered scaling
204
diverging_data = np.random.randn(10, 12)
205

206
sns.heatmap(
207
    diverging_data,
208
    annot=True,
209
    fmt=".1f",
210
    cmap="RdBu_r",
211
    center=0,
212
    robust=True,
213
    linewidths=0.5,
214
    cbar_kws={"shrink": 0.8}
215
)
216
plt.show()
217
```
218

219
### Large Dataset Clustering
220

221
```python
222
# Cluster large dataset with custom parameters
223
large_data = np.random.randn(50, 50)
224

225
sns.clustermap(
226
    large_data,
227
    method="ward",          # Ward linkage
228
    metric="euclidean",     # Euclidean distance
229
    cmap="coolwarm",
230
    center=0,
231
    figsize=(15, 15),
232
    dendrogram_ratio=0.15,
233
    cbar_pos=(0.02, 0.85, 0.03, 0.12)
234
)
235
plt.show()
236
```
237

238
## Types
239

240
```python { .api }
241
# Clustering methods
242
ClusteringMethod = Literal[
243
    "single", "complete", "average", "weighted", 
244
    "centroid", "median", "ward"
245
]
246

247
# Distance metrics  
248
DistanceMetric = str | callable  # scipy.spatial.distance metrics
249

250
# ClusterGrid return object
251
class ClusterGrid:
252
    ax_heatmap: matplotlib.axes.Axes       # Main heatmap
253
    ax_row_dendrogram: matplotlib.axes.Axes  # Row dendrogram  
254
    ax_col_dendrogram: matplotlib.axes.Axes  # Column dendrogram
255
    ax_cbar: matplotlib.axes.Axes          # Colorbar
256
    dendrogram_row: dict                   # Row clustering info
257
    dendrogram_col: dict                   # Column clustering info
258
    data: pandas.DataFrame                 # Clustered data
259
```