ComplexHeatmap-py 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. ComplexHeatmap.py +7 -0
  2. complexheatmap/__init__.py +221 -0
  3. complexheatmap/_base.py +56 -0
  4. complexheatmap/_options.py +165 -0
  5. complexheatmap/anno_funcs.py +2781 -0
  6. complexheatmap/annotations.py +1611 -0
  7. complexheatmap/colors.py +848 -0
  8. complexheatmap/data/dmr_summary/cgi_anno.csv +9 -0
  9. complexheatmap/data/dmr_summary/dist_tss.csv +9 -0
  10. complexheatmap/data/dmr_summary/gene_anno.csv +9 -0
  11. complexheatmap/data/dmr_summary/label.csv +9 -0
  12. complexheatmap/data/dmr_summary/mat_enrich_gf.csv +9 -0
  13. complexheatmap/data/dmr_summary/mat_enrich_st.csv +9 -0
  14. complexheatmap/data/dmr_summary/mat_pct_st.csv +9 -0
  15. complexheatmap/data/dmr_summary/mean_meth.csv +9 -0
  16. complexheatmap/data/dmr_summary/n_corr.csv +9 -0
  17. complexheatmap/data/dmr_summary/n_gr.csv +9 -0
  18. complexheatmap/data/gene_expression.csv +156 -0
  19. complexheatmap/data/gr.csv +2416 -0
  20. complexheatmap/data/measles.csv +60 -0
  21. complexheatmap/data/meth/enhancer.csv +1001 -0
  22. complexheatmap/data/meth/expr.csv +1001 -0
  23. complexheatmap/data/meth/meth.csv +1001 -0
  24. complexheatmap/data/meth/row_meta.csv +1001 -0
  25. complexheatmap/data/rand_mat.csv +19 -0
  26. complexheatmap/data/random_meth_expr_data/anno.csv +21 -0
  27. complexheatmap/data/random_meth_expr_data/anno_states.csv +1001 -0
  28. complexheatmap/data/random_meth_expr_data/mat_expr.csv +1001 -0
  29. complexheatmap/data/random_meth_expr_data/mat_meth.csv +1001 -0
  30. complexheatmap/data/random_meth_expr_data/row_meta.csv +1001 -0
  31. complexheatmap/data/sample_order.txt +172 -0
  32. complexheatmap/data/tcga_lung_adenocarcinoma.csv +27 -0
  33. complexheatmap/decorate.py +159 -0
  34. complexheatmap/dendrogram.py +937 -0
  35. complexheatmap/density.py +276 -0
  36. complexheatmap/genomic.py +348 -0
  37. complexheatmap/grid.py +1580 -0
  38. complexheatmap/heatmap.py +2244 -0
  39. complexheatmap/heatmap_list.py +1569 -0
  40. complexheatmap/legend.py +992 -0
  41. complexheatmap/oncoprint.py +488 -0
  42. complexheatmap/text.py +655 -0
  43. complexheatmap/three_d.py +188 -0
  44. complexheatmap/translate.py +338 -0
  45. complexheatmap/units.py +718 -0
  46. complexheatmap/upset.py +886 -0
  47. complexheatmap/utils.py +183 -0
  48. complexheatmap_py-0.1.0.dist-info/METADATA +96 -0
  49. complexheatmap_py-0.1.0.dist-info/RECORD +52 -0
  50. complexheatmap_py-0.1.0.dist-info/WHEEL +5 -0
  51. complexheatmap_py-0.1.0.dist-info/licenses/LICENSE +24 -0
  52. complexheatmap_py-0.1.0.dist-info/top_level.txt +2 -0
@@ -0,0 +1,937 @@
1
+ """Distance metrics, hierarchical clustering, Dendrogram trees, and grid.dendrogram."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import copy
6
+ from typing import Any, Callable, Sequence
7
+
8
+ import numpy as np
9
+ from scipy.cluster.hierarchy import linkage as scipy_linkage
10
+ from scipy.spatial.distance import pdist as scipy_pdist, squareform
11
+ from scipy.stats import kendalltau, pearsonr, spearmanr
12
+
13
+ from .colors import brewer_pal, to_hex_rgba
14
+ from .grid import (
15
+ GTree,
16
+ Viewport,
17
+ current_device,
18
+ grid_newpage,
19
+ grid_rect,
20
+ grid_xaxis,
21
+ grid_yaxis,
22
+ pointsGrob,
23
+ popViewport,
24
+ pushViewport,
25
+ segmentsGrob,
26
+ )
27
+ from .units import Unit, check_gp, gpar, unit, unit_c
28
+
29
+
30
+ class DistMatrix:
31
+ """Condensed distance object mirroring R `stats::dist`."""
32
+
33
+ def __init__(self, condensed: np.ndarray, n: int, labels: list[str] | None = None, method: str = "euclidean") -> None:
34
+ self.condensed = np.asarray(condensed, dtype=float)
35
+ self.n = int(n)
36
+ self.labels = list(labels) if labels is not None else None
37
+ self.method = method
38
+
39
+ def to_square(self) -> np.ndarray:
40
+ return squareform(self.condensed)
41
+
42
+ def __sub__(self, other: "DistMatrix | np.ndarray") -> np.ndarray:
43
+ if isinstance(other, DistMatrix):
44
+ return self.condensed - other.condensed
45
+ return self.condensed - np.asarray(other)
46
+
47
+ def __len__(self) -> int:
48
+ return len(self.condensed)
49
+
50
+ def __repr__(self) -> str:
51
+ return f"DistMatrix(n={self.n}, method={self.method!r})"
52
+
53
+
54
+ def as_dist(mat: Any, labels: list[str] | None = None, method: str = "custom") -> DistMatrix:
55
+ if isinstance(mat, DistMatrix):
56
+ return mat
57
+ arr = np.asarray(mat, dtype=float)
58
+ if arr.ndim == 1:
59
+ n = int(round((1 + np.sqrt(1 + 8 * len(arr))) / 2))
60
+ return DistMatrix(arr, n=n, labels=labels, method=method)
61
+ if arr.ndim == 2 and arr.shape[0] == arr.shape[1]:
62
+ n = arr.shape[0]
63
+ # Read lower triangle column-wise/row-wise symmetrically via upper triangle indices
64
+ arr_sym = arr.copy()
65
+ np.fill_diagonal(arr_sym, 0.0)
66
+ # If upper triangle is zero/NaN (lower-triangle matrix like R), mirror lower to upper
67
+ iu = np.triu_indices(n, k=1)
68
+ il = (iu[1], iu[0])
69
+ if np.all(np.isnan(arr_sym[iu])) or np.all(arr_sym[iu] == 0):
70
+ arr_sym[iu] = arr_sym[il]
71
+ condensed = arr_sym[iu]
72
+ return DistMatrix(condensed, n=n, labels=labels, method=method)
73
+ raise ValueError("Cannot convert input to DistMatrix.")
74
+
75
+
76
+ def dist(x: Any, method: str = "euclidean") -> DistMatrix:
77
+ """Compute row-wise pairwise distances analogous to R `stats::dist` plus correlation distances."""
78
+ arr = np.asarray(x, dtype=float)
79
+ if arr.ndim == 1:
80
+ arr = arr[:, None]
81
+ n = arr.shape[0]
82
+ if n < 2:
83
+ return DistMatrix(np.array([], dtype=float), n=n, method=method)
84
+
85
+ m = method.lower()
86
+ if m in ("euclidean", "maximum", "chebyshev", "manhattan", "cityblock", "canberra", "binary", "jaccard", "minkowski"):
87
+ scipy_m = {
88
+ "maximum": "chebyshev",
89
+ "manhattan": "cityblock",
90
+ "binary": "jaccard",
91
+ }.get(m, m)
92
+ if m == "binary":
93
+ arr_b = (arr != 0).astype(float)
94
+ cond = scipy_pdist(arr_b, metric="jaccard")
95
+ cond = np.nan_to_num(cond, nan=0.0)
96
+ else:
97
+ # Handle NAs pairwise if any NaN exists
98
+ if np.isnan(arr).any():
99
+ cond = _pairwise_dist_with_na(arr, m)
100
+ else:
101
+ cond = scipy_pdist(arr, metric=scipy_m)
102
+ return DistMatrix(cond, n=n, method=m)
103
+
104
+ if m in ("pearson", "spearman", "kendall"):
105
+ # R: (1 - cor(t(mat), method=method, use="pairwise.complete.obs")) / 2
106
+ cond = []
107
+ for i in range(n):
108
+ for j in range(i + 1, n):
109
+ xi, xj = arr[i], arr[j]
110
+ mask = np.isfinite(xi) & np.isfinite(xj)
111
+ if np.sum(mask) < 2:
112
+ r = 0.0
113
+ else:
114
+ a, b = xi[mask], xj[mask]
115
+ if np.std(a) == 0 or np.std(b) == 0:
116
+ r = 0.0
117
+ elif m == "pearson":
118
+ r, _ = pearsonr(a, b)
119
+ elif m == "spearman":
120
+ r, _ = spearmanr(a, b)
121
+ else:
122
+ r, _ = kendalltau(a, b)
123
+ cond.append(0.5 * (1.0 - float(r)))
124
+ return DistMatrix(np.asarray(cond, dtype=float), n=n, method=m)
125
+
126
+ raise ValueError(f"Unsupported distance method: {method!r}")
127
+
128
+
129
+ def _pairwise_dist_with_na(arr: np.ndarray, m: str) -> np.ndarray:
130
+ n, p = arr.shape
131
+ cond = []
132
+ for i in range(n):
133
+ for j in range(i + 1, n):
134
+ xi, xj = arr[i], arr[j]
135
+ mask = np.isfinite(xi) & np.isfinite(xj)
136
+ k = int(np.sum(mask))
137
+ if k == 0:
138
+ cond.append(0.0)
139
+ continue
140
+ d = xi[mask] - xj[mask]
141
+ if m == "euclidean":
142
+ cond.append(float(np.sqrt(np.sum(d * d) * (p / k))))
143
+ elif m in ("manhattan", "cityblock"):
144
+ cond.append(float(np.sum(np.abs(d)) * (p / k)))
145
+ elif m in ("maximum", "chebyshev"):
146
+ cond.append(float(np.max(np.abs(d))))
147
+ elif m == "canberra":
148
+ denom = np.abs(xi[mask]) + np.abs(xj[mask])
149
+ nz = denom > 0
150
+ cond.append(float(np.sum(np.abs(d[nz]) / denom[nz]) * (p / k)) if np.any(nz) else 0.0)
151
+ else:
152
+ cond.append(float(np.sqrt(np.sum(d * d) * (p / k))))
153
+ return np.asarray(cond, dtype=float)
154
+
155
+
156
+ def dist2(x: Any, pairwise_fun: Callable[[Any, Any], float] | None = None, **kwargs: Any) -> DistMatrix:
157
+ """Pairwise distance matrix using custom 2-arg function on matrix rows or list elements."""
158
+ if pairwise_fun is None:
159
+ def pairwise_fun(a: Any, b: Any) -> float:
160
+ aa = np.asarray(a, dtype=float)
161
+ bb = np.asarray(b, dtype=float)
162
+ return float(np.sqrt(np.sum((aa - bb) ** 2)))
163
+
164
+ if isinstance(x, np.ndarray) or (hasattr(x, "values") and hasattr(x, "index")):
165
+ labels = list(x.index) if hasattr(x, "index") else None
166
+ arr = np.asarray(x)
167
+ nr = arr.shape[0]
168
+ if nr < 2:
169
+ raise ValueError("`x` must have >= 2 rows.")
170
+ cond = []
171
+ for i in range(nr):
172
+ for j in range(i + 1, nr):
173
+ cond.append(float(pairwise_fun(arr[i], arr[j], **kwargs)))
174
+ return DistMatrix(np.asarray(cond, dtype=float), n=nr, labels=labels, method="dist2")
175
+
176
+ if isinstance(x, dict):
177
+ labels = list(x.keys())
178
+ items = list(x.values())
179
+ elif isinstance(x, (list, tuple)):
180
+ labels = None
181
+ items = list(x)
182
+ else:
183
+ items = list(x)
184
+ labels = None
185
+
186
+ nr = len(items)
187
+ if nr < 2:
188
+ raise ValueError("`x` must have >= 2 elements.")
189
+ cond = []
190
+ for i in range(nr):
191
+ for j in range(i + 1, nr):
192
+ cond.append(float(pairwise_fun(items[i], items[j], **kwargs)))
193
+ return DistMatrix(np.asarray(cond, dtype=float), n=nr, labels=labels, method="dist2")
194
+
195
+
196
+ class Hclust:
197
+ """Hierarchical clustering result wrapping SciPy linkage matrix."""
198
+
199
+ def __init__(self, linkage_mat: np.ndarray, n: int, labels: list[str] | None = None, method: str = "complete") -> None:
200
+ self.linkage = np.asarray(linkage_mat, dtype=float)
201
+ self.n = int(n)
202
+ self.labels = labels
203
+ self.method = method
204
+ self.height = self.linkage[:, 2].copy() if len(self.linkage) else np.array([], dtype=float)
205
+ self.order = _linkage_order(self.linkage, self.n)
206
+
207
+ def __repr__(self) -> str:
208
+ return f"Hclust(n={self.n}, method={self.method!r})"
209
+
210
+
211
+ def _linkage_order(Z: np.ndarray, n: int) -> list[int]:
212
+ if n == 0:
213
+ return []
214
+ if n == 1:
215
+ return [0]
216
+ def _walk(node_id: int) -> list[int]:
217
+ if node_id < n:
218
+ return [int(node_id)]
219
+ row = Z[node_id - n]
220
+ return _walk(int(row[0])) + _walk(int(row[1]))
221
+ return _walk(2 * n - 2)
222
+
223
+
224
+ def hclust(d: DistMatrix | np.ndarray, method: str = "complete") -> Hclust:
225
+ """Perform hierarchical clustering equivalent to R `stats::hclust`."""
226
+ dm = as_dist(d)
227
+ if dm.n <= 1:
228
+ return Hclust(np.zeros((0, 4), dtype=float), n=dm.n, labels=dm.labels, method=method)
229
+ m_map = {
230
+ "ward.d": "ward",
231
+ "ward.d2": "ward",
232
+ "ward": "ward",
233
+ "mcquitty": "weighted",
234
+ "median": "median",
235
+ "centroid": "centroid",
236
+ "single": "single",
237
+ "complete": "complete",
238
+ "average": "average",
239
+ }
240
+ sp_m = m_map.get(method.lower(), method)
241
+ cond = np.nan_to_num(dm.condensed, nan=0.0)
242
+ Z = scipy_linkage(cond, method=sp_m)
243
+ return Hclust(Z, n=dm.n, labels=dm.labels, method=method)
244
+
245
+
246
+ class Dendrogram:
247
+ """Tree node representing a hierarchical dendrogram with R-compatible attributes."""
248
+
249
+ def __init__(
250
+ self,
251
+ children: list["Dendrogram"] | None = None,
252
+ height: float = 0.0,
253
+ leaf: bool = False,
254
+ value: int | None = None,
255
+ label: Any = None,
256
+ members: int = 1,
257
+ x: Any = None,
258
+ midpoint: float | None = None,
259
+ edge_par: dict[str, Any] | None = None,
260
+ node_par: dict[str, Any] | None = None,
261
+ class_label: Any = None,
262
+ ) -> None:
263
+ self.children: list[Dendrogram] = list(children) if children is not None else []
264
+ self.height = float(height)
265
+ self.leaf = bool(leaf)
266
+ self.value = value
267
+ self.label = label
268
+ self.members = int(members)
269
+ self.x = x
270
+ self.midpoint = midpoint
271
+ self.edge_par: dict[str, Any] = dict(edge_par) if edge_par else {}
272
+ self.node_par: dict[str, Any] = dict(node_par) if node_par else {}
273
+ self.class_label = class_label
274
+
275
+ @property
276
+ def is_leaf(self) -> bool:
277
+ return self.leaf or len(self.children) == 0
278
+
279
+ def __len__(self) -> int:
280
+ return len(self.children)
281
+
282
+ def __getitem__(self, idx: int) -> "Dendrogram":
283
+ return self.children[idx]
284
+
285
+ def __setitem__(self, idx: int, val: "Dendrogram") -> None:
286
+ self.children[idx] = val
287
+
288
+ def copy(self) -> "Dendrogram":
289
+ return copy.deepcopy(self)
290
+
291
+ def nobs(self) -> int:
292
+ if self.is_leaf:
293
+ return 1
294
+ return sum(ch.nobs() for ch in self.children)
295
+
296
+ def order(self) -> list[int]:
297
+ if self.is_leaf:
298
+ return [int(self.value if self.value is not None else 0)]
299
+ out: list[int] = []
300
+ for ch in self.children:
301
+ out.extend(ch.order())
302
+ return out
303
+
304
+ def set_order(self, values: Sequence[int]) -> None:
305
+ it = iter(values)
306
+ def _assign(node: Dendrogram) -> None:
307
+ if node.is_leaf:
308
+ node.value = int(next(it))
309
+ else:
310
+ for ch in node.children:
311
+ _assign(ch)
312
+ _assign(self)
313
+
314
+ def __repr__(self) -> str:
315
+ return f"Dendrogram(members={self.nobs()}, height={self.height:.4g}, leaf={self.is_leaf})"
316
+
317
+
318
+ def order_dendrogram(dend: Dendrogram) -> list[int]:
319
+ return dend.order()
320
+
321
+
322
+ def nobs(obj: Any) -> int:
323
+ if hasattr(obj, "nobs") and callable(obj.nobs):
324
+ return obj.nobs()
325
+ if isinstance(obj, Dendrogram):
326
+ return obj.nobs()
327
+ raise TypeError(f"Cannot compute nobs for {type(obj).__name__}.")
328
+
329
+
330
+ def as_dendrogram(obj: Any) -> Dendrogram:
331
+ """Convert Hclust, SciPy linkage array, or Dendrogram into a Dendrogram tree."""
332
+ if isinstance(obj, Dendrogram):
333
+ return obj
334
+ if isinstance(obj, np.ndarray) and obj.ndim == 2 and obj.shape[1] == 4:
335
+ n = obj.shape[0] + 1
336
+ obj = Hclust(obj, n=n)
337
+ if isinstance(obj, Hclust):
338
+ n = obj.n
339
+ if n == 0:
340
+ return Dendrogram(leaf=True, value=0, height=0.0, members=0)
341
+ if n == 1:
342
+ lbl = obj.labels[0] if obj.labels else 0
343
+ return Dendrogram(leaf=True, value=0, label=lbl, height=0.0, members=1, midpoint=0.0)
344
+ nodes: dict[int, Dendrogram] = {}
345
+ for i in range(n):
346
+ lbl = obj.labels[i] if obj.labels and i < len(obj.labels) else i
347
+ nodes[i] = Dendrogram(leaf=True, value=i, label=lbl, height=0.0, members=1, midpoint=0.0)
348
+ Z = obj.linkage
349
+ for k, row in enumerate(Z):
350
+ c1, c2, h, cnt = int(row[0]), int(row[1]), float(row[2]), int(row[3])
351
+ n1, n2 = nodes[c1], nodes[c2]
352
+ nodes[n + k] = Dendrogram(
353
+ children=[n1, n2],
354
+ height=h,
355
+ leaf=False,
356
+ members=cnt,
357
+ )
358
+ root = nodes[2 * n - 2]
359
+ _recompute_midpoints(root)
360
+ return root
361
+ raise TypeError(f"Cannot convert {type(obj).__name__} to Dendrogram.")
362
+
363
+
364
+ def _recompute_midpoints(node: Dendrogram) -> int:
365
+ if node.is_leaf:
366
+ node.members = 1
367
+ node.midpoint = 0.0
368
+ return 1
369
+ m_left = _recompute_midpoints(node.children[0])
370
+ total = m_left
371
+ for ch in node.children[1:]:
372
+ total += _recompute_midpoints(ch)
373
+ node.members = total
374
+ # Match R midpoint calculation
375
+ node.midpoint = 0.5 * (node.children[0].midpoint + (total - node.children[-1].members + node.children[-1].midpoint))
376
+ return total
377
+
378
+
379
+ def reorder_dendrogram(dend: Dendrogram, wts: Sequence[float], agglo_fun: Callable[[Sequence[float]], float] = np.mean) -> Dendrogram:
380
+ """Reorder dendrogram branches by leaf weights `wts` (indexed by 0-based leaf value)."""
381
+ d = dend.copy()
382
+ w = np.asarray(wts, dtype=float)
383
+
384
+ def _rec(node: Dendrogram) -> float:
385
+ if node.is_leaf:
386
+ val = float(w[node.value]) if node.value is not None and node.value < len(w) else 0.0
387
+ return val
388
+ child_vals = [_rec(ch) for ch in node.children]
389
+ if len(node.children) > 1:
390
+ order_idx = sorted(range(len(node.children)), key=lambda i: child_vals[i])
391
+ node.children = [node.children[i] for i in order_idx]
392
+ return float(agglo_fun(child_vals))
393
+
394
+ _rec(d)
395
+ _recompute_midpoints(d)
396
+ return d
397
+
398
+
399
+ def dend_branches_heights(dend: Dendrogram) -> list[float]:
400
+ if dend.is_leaf:
401
+ return []
402
+ out = [dend.height]
403
+ for ch in dend.children:
404
+ out.extend(dend_branches_heights(ch))
405
+ return out
406
+
407
+
408
+ def cut_dendrogram(dend: Dendrogram, k: int) -> dict[str, Any]:
409
+ """Cut dendrogram into `k` subtrees, returning `{'upper': Dendrogram, 'lower': list[Dendrogram]}`."""
410
+ h = sorted(dend_branches_heights(dend), reverse=True)
411
+ if k <= 1 or len(h) == 0:
412
+ upper = Dendrogram(leaf=True, value=0, height=dend.height, members=1)
413
+ return {"upper": upper, "lower": [dend.copy()]}
414
+ if k > len(h):
415
+ cut_h = 0.0
416
+ else:
417
+ cut_h = 0.5 * (h[k - 2] + h[k - 1])
418
+
419
+ lower: list[Dendrogram] = []
420
+
421
+ def _cut(node: Dendrogram) -> Dendrogram:
422
+ if node.is_leaf or node.height <= cut_h + 1e-12:
423
+ leaf_idx = len(lower)
424
+ sub = node.copy()
425
+ lower.append(sub)
426
+ return Dendrogram(leaf=True, value=leaf_idx, height=node.height, members=1)
427
+ new_children = [_cut(ch) for ch in node.children]
428
+ return Dendrogram(
429
+ children=new_children,
430
+ height=node.height,
431
+ leaf=False,
432
+ members=len(lower),
433
+ edge_par=node.edge_par,
434
+ node_par=node.node_par,
435
+ )
436
+
437
+ upper = _cut(dend)
438
+ _recompute_midpoints(upper)
439
+ return {"upper": upper, "lower": lower}
440
+
441
+
442
+ def cutree(hc: Hclust | Dendrogram, k: int) -> np.ndarray:
443
+ """Cut clustering tree into `k` cluster labels `1..k` ordered by observation index."""
444
+ dend = as_dendrogram(hc)
445
+ ct = cut_dendrogram(dend, k)
446
+ n = dend.nobs()
447
+ res = np.zeros(n, dtype=int)
448
+ for cl_id, sub in enumerate(ct["lower"], start=1):
449
+ for leaf_v in sub.order():
450
+ res[leaf_v] = cl_id
451
+ return res
452
+
453
+
454
+ def adjust_dend_by_x(dend: Dendrogram, leaf_pos: Any = None) -> Dendrogram:
455
+ """Assign `x` positions to every leaf and internal node (bottom-up)."""
456
+ d = dend.copy()
457
+ n = d.nobs()
458
+ if leaf_pos is None:
459
+ leaf_pos = np.arange(n, dtype=float) + 0.5
460
+ if isinstance(leaf_pos, Unit):
461
+ if len(leaf_pos) != n:
462
+ raise ValueError("`leaf_pos` length must match number of leaves in `dend`.")
463
+ pos_list = [leaf_pos[i] for i in range(n)]
464
+ is_u = True
465
+ else:
466
+ arr = np.asarray(leaf_pos, dtype=float)
467
+ if len(arr) != n:
468
+ raise ValueError("`leaf_pos` length must match number of leaves in `dend`.")
469
+ pos_list = [float(v) for v in arr]
470
+ is_u = False
471
+
472
+ od = d.order()
473
+ # Map leaf value -> position index in traversal order
474
+ val_to_idx = {val: i for i, val in enumerate(od)}
475
+ counter = [0]
476
+
477
+ def _walk(node: Dendrogram) -> None:
478
+ if node.is_leaf:
479
+ i = counter[0]
480
+ counter[0] += 1
481
+ node.x = pos_list[i]
482
+ else:
483
+ for ch in node.children:
484
+ _walk(ch)
485
+ x0 = node.children[0].x
486
+ x1 = node.children[-1].x
487
+ node.x = (x0 + x1) * 0.5
488
+
489
+ _walk(d)
490
+ return d
491
+
492
+
493
+ def dend_heights(x: Any) -> Any:
494
+ if x is None:
495
+ return 0.0
496
+ if isinstance(x, Dendrogram):
497
+ return float(x.height)
498
+ return [float(d.height) for d in x]
499
+
500
+
501
+ def dend_xy(dend: Dendrogram) -> dict[str, Any]:
502
+ """Return leaf positions `x` and vertical range `y = [0, height]`."""
503
+ d = dend if dend.x is not None else adjust_dend_by_x(dend)
504
+ xs: list[Any] = []
505
+
506
+ def _collect(node: Dendrogram) -> None:
507
+ if node.is_leaf:
508
+ xs.append(node.x)
509
+ else:
510
+ for ch in node.children:
511
+ _collect(ch)
512
+
513
+ _collect(d)
514
+ if xs and isinstance(xs[0], Unit):
515
+ x_out: Any = unit_c(*xs)
516
+ else:
517
+ x_out = np.asarray(xs, dtype=float)
518
+ return {"x": x_out, "y": np.array([0.0, float(dend_heights(d))], dtype=float)}
519
+
520
+
521
+ def merge_dendrogram(parent: Dendrogram, children: Sequence[Dendrogram], only_parent: bool = False) -> Dendrogram:
522
+ """Connect parent dendrogram to child dendrograms at its leaves."""
523
+ p = parent.copy()
524
+ ch_list = [c.copy() for c in children]
525
+ n = p.nobs()
526
+ if n != len(ch_list):
527
+ raise ValueError("Number of children dendrograms must equal number of leaves in `parent`.")
528
+
529
+ children_height = [float(c.height) for c in ch_list]
530
+ children_height_max = max(children_height) if children_height else 0.0
531
+ parent_height_min = min(dend_branches_heights(p), default=0.0)
532
+ h_line = children_height_max + parent_height_min * 0.1
533
+
534
+ od_parent = p.order()
535
+ od2index = {val: i for i, val in enumerate(od_parent)}
536
+
537
+ def _update_heights(node: Dendrogram) -> None:
538
+ if node.is_leaf:
539
+ idx = node.value if node.value is not None else 0
540
+ node.height = children_height[idx] if idx < len(children_height) else 0.0
541
+ else:
542
+ node.height = node.height + children_height_max
543
+ for ch in node.children:
544
+ _update_heights(ch)
545
+
546
+ _update_heights(p)
547
+ if only_parent:
548
+ return p
549
+
550
+ def _replace_leaves(node: Dendrogram) -> Dendrogram:
551
+ if node.is_leaf:
552
+ idx = node.value if node.value is not None else 0
553
+ return ch_list[idx]
554
+ node.children = [_replace_leaves(ch) for ch in node.children]
555
+ return node
556
+
557
+ merged = _replace_leaves(p)
558
+ merged.members = sum(c.nobs() for c in ch_list)
559
+
560
+ # Re-index leaf values consecutively across children in parent leaf order
561
+ offset = 0
562
+ new_orders: list[int] = []
563
+ for p_idx in od_parent:
564
+ c_ord = ch_list[p_idx].order()
565
+ ranks = np.argsort(np.argsort(c_ord))
566
+ shifted = (ranks + offset).tolist()
567
+ ch_list[p_idx].set_order(shifted)
568
+ new_orders.extend(shifted)
569
+ offset += len(c_ord)
570
+ merged.set_order(new_orders)
571
+ merged._children_height = children_height # type: ignore[attr-defined]
572
+ merged._parent_height = parent.height # type: ignore[attr-defined]
573
+ merged._h_line = h_line # type: ignore[attr-defined]
574
+ return merged
575
+
576
+
577
+ def color_branches(dend: Dendrogram, k: int | None = None, h: float | None = None, col: Any = None) -> Dendrogram:
578
+ """Color dendrogram branches across `k` clusters or cut height `h` (dendextend::color_branches)."""
579
+ d = dend.copy()
580
+ if k is None and h is None:
581
+ k = 1
582
+ if k is None and h is not None:
583
+ # Count clusters above h
584
+ hs = sorted(dend_branches_heights(d), reverse=True)
585
+ k = 1 + sum(1 for v in hs if v > h)
586
+ assert k is not None
587
+
588
+ if col is None:
589
+ cols = brewer_pal(max(k, 3), "Set1")[:k] if k <= 9 else [to_hex_rgba(i + 1) for i in range(k)]
590
+ elif isinstance(col, (str, int, np.integer)):
591
+ cols = [to_hex_rgba(col)] * k
592
+ else:
593
+ cols = [to_hex_rgba(c) for c in col]
594
+ if len(cols) < k:
595
+ cols = [cols[i % len(cols)] for i in range(k)]
596
+
597
+ if k == 1:
598
+ c0 = cols[0]
599
+ def _set_all(node: Dendrogram) -> None:
600
+ node.edge_par["col"] = c0
601
+ for ch in node.children:
602
+ _set_all(ch)
603
+ _set_all(d)
604
+ return d
605
+
606
+ hs = sorted(dend_branches_heights(d), reverse=True)
607
+ cut_h = 0.5 * (hs[k - 2] + hs[k - 1]) if k <= len(hs) else 0.0
608
+ cluster_idx = [0]
609
+
610
+ def _color_rec(node: Dendrogram, active_col: str | None) -> None:
611
+ if active_col is not None:
612
+ node.edge_par["col"] = active_col
613
+ for ch in node.children:
614
+ _color_rec(ch, active_col)
615
+ return
616
+ if node.is_leaf or node.height <= cut_h + 1e-12:
617
+ c = cols[cluster_idx[0] % len(cols)]
618
+ cluster_idx[0] += 1
619
+ node.edge_par["col"] = c
620
+ for ch in node.children:
621
+ _color_rec(ch, c)
622
+ else:
623
+ for ch in node.children:
624
+ _color_rec(ch, None)
625
+
626
+ _color_rec(d, None)
627
+ return d
628
+
629
+
630
+ def cluster_within_group(mat: Any, factor: Sequence[Any]) -> Dendrogram:
631
+ """Cluster columns of `mat` within each level of `factor`, then cluster group means."""
632
+ arr = np.asarray(mat, dtype=float)
633
+ fa = [str(v) for v in factor]
634
+ levels = list(dict.fromkeys(fa))
635
+ dend_list: list[Dendrogram] = []
636
+ order_list: list[list[int]] = []
637
+ group_means: list[np.ndarray] = []
638
+
639
+ for le in levels:
640
+ cols_idx = [i for i, v in enumerate(fa) if v == le]
641
+ sub = arr[:, cols_idx]
642
+ if len(cols_idx) == 1:
643
+ d_sub = Dendrogram(leaf=True, value=cols_idx[0], height=0.0, members=1)
644
+ ord_sub = cols_idx
645
+ else:
646
+ hc1 = hclust(dist(sub.T))
647
+ d_sub = as_dendrogram(hc1)
648
+ ord_sub = [cols_idx[i] for i in d_sub.order()]
649
+ d_sub.set_order(ord_sub)
650
+ # Flatten within-group heights to 0
651
+ def _zero_h(node: Dendrogram) -> None:
652
+ node.height = 0.0
653
+ for ch in node.children:
654
+ _zero_h(ch)
655
+ _zero_h(d_sub)
656
+ d_sub.class_label = le
657
+ dend_list.append(d_sub)
658
+ order_list.append(ord_sub)
659
+ group_means.append(np.mean(sub, axis=1))
660
+
661
+ if len(levels) == 1:
662
+ return dend_list[0]
663
+ parent = as_dendrogram(hclust(dist(np.vstack(group_means))))
664
+ parent_order = parent.order()
665
+ merged = merge_dendrogram(parent, dend_list)
666
+ flat_order = [idx for p_i in parent_order for idx in order_list[p_i]]
667
+ merged.set_order(flat_order)
668
+ return merged
669
+
670
+
671
+ def cluster_between_groups(mat: Any, factor: Sequence[Any]) -> Dendrogram:
672
+ """Keep column order within each factor level while clustering between group means."""
673
+ arr = np.asarray(mat, dtype=float)
674
+ fa = [str(v) for v in factor]
675
+ levels = list(dict.fromkeys(fa))
676
+ dend_list: list[Dendrogram] = []
677
+ order_list: list[list[int]] = []
678
+ group_means: list[np.ndarray] = []
679
+
680
+ for le in levels:
681
+ cols_idx = [i for i, v in enumerate(fa) if v == le]
682
+ sub = arr[:, cols_idx]
683
+ if len(cols_idx) == 1:
684
+ d_sub = Dendrogram(leaf=True, value=cols_idx[0], height=0.0, members=1)
685
+ else:
686
+ hc1 = hclust(dist(np.arange(len(cols_idx), dtype=float)[:, None]))
687
+ d_sub = reorder_dendrogram(as_dendrogram(hc1), np.arange(len(cols_idx), dtype=float), np.mean)
688
+ d_sub.set_order(cols_idx)
689
+ def _zero_h(node: Dendrogram) -> None:
690
+ node.height = 0.0
691
+ for ch in node.children:
692
+ _zero_h(ch)
693
+ _zero_h(d_sub)
694
+ d_sub.class_label = le
695
+ dend_list.append(d_sub)
696
+ order_list.append(cols_idx)
697
+ group_means.append(np.mean(sub, axis=1))
698
+
699
+ if len(levels) == 1:
700
+ return dend_list[0]
701
+ parent = as_dendrogram(hclust(dist(np.vstack(group_means))))
702
+ parent_order = parent.order()
703
+ merged = merge_dendrogram(parent, dend_list)
704
+ flat_order = [idx for p_i in parent_order for idx in order_list[p_i]]
705
+ merged.set_order(flat_order)
706
+ return merged
707
+
708
+
709
+ def _construct_dend_segments(dend: Dendrogram, gp: dict[str, Any]) -> dict[str, Any]:
710
+ if dend.x is None:
711
+ dend = adjust_dend_by_x(dend)
712
+ if dend.is_leaf:
713
+ return {}
714
+
715
+ x_is_unit = isinstance(dend.x, Unit)
716
+ x0_list: list[Any] = []
717
+ x1_list: list[Any] = []
718
+ y0_list: list[float] = []
719
+ y1_list: list[float] = []
720
+ cols: list[Any] = []
721
+ lwds: list[float] = []
722
+ ltys: list[Any] = []
723
+
724
+ node_x: list[Any] = []
725
+ node_y: list[float] = []
726
+ node_col: list[Any] = []
727
+ node_fill: list[Any] = []
728
+ node_pch: list[Any] = []
729
+ node_size: list[Any] = []
730
+ node_flag: list[bool] = []
731
+
732
+ def _add_node_par(node: Dendrogram, xval: Any, yval: float) -> None:
733
+ np_d = node.node_par
734
+ has_np = any(k in np_d for k in ("col", "fill", "pch", "cex", "size"))
735
+ node_flag.append(has_np)
736
+ node_x.append(xval)
737
+ node_y.append(yval)
738
+ node_col.append(np_d.get("col", "black"))
739
+ node_fill.append(np_d.get("fill", "transparent"))
740
+ node_pch.append(np_d.get("pch", 1))
741
+ node_size.append(np_d.get("size", unit(1.0, "char")))
742
+
743
+ _add_node_par(dend, dend.x, dend.height)
744
+
745
+ queue: list[Dendrogram] = [dend]
746
+ while queue:
747
+ next_q: list[Dendrogram] = []
748
+ for parent in queue:
749
+ if parent.is_leaf:
750
+ continue
751
+ h = float(parent.height)
752
+ h_zero = abs(h) < 1e-10
753
+ xl = [ch.x for ch in parent.children]
754
+ yl = [float(ch.height) for ch in parent.children]
755
+ if x_is_unit:
756
+ # For mid_x of unit children
757
+ mid_x = (xl[0] + xl[-1]) * 0.5
758
+ else:
759
+ mid_x = 0.5 * (min(xl) + max(xl))
760
+ nc = len(parent.children)
761
+ idx_order = [i for i in range(1, nc - 1)] + ([0, nc - 1] if nc > 1 else [0])
762
+ for i in idx_order:
763
+ ch = parent.children[i]
764
+ ep = ch.edge_par
765
+ c_val = ep.get("col", "black")
766
+ lw_val = ep.get("lwd", 1.0)
767
+ lt_val = ep.get("lty", "solid")
768
+ _add_node_par(ch, xl[i], yl[i])
769
+ if h_zero:
770
+ x0_list.append(xl[i])
771
+ x1_list.append(mid_x)
772
+ y0_list.append(h)
773
+ y1_list.append(h)
774
+ cols.append(c_val)
775
+ lwds.append(lw_val)
776
+ ltys.append(lt_val)
777
+ else:
778
+ x0_list.extend([xl[i], xl[i]])
779
+ x1_list.extend([xl[i], mid_x])
780
+ y0_list.extend([yl[i], h])
781
+ y1_list.extend([h, h])
782
+ cols.extend([c_val, c_val])
783
+ lwds.extend([lw_val, lw_val])
784
+ ltys.extend([lt_val, lt_val])
785
+ for ch in parent.children:
786
+ if not ch.is_leaf:
787
+ next_q.append(ch)
788
+ queue = next_q
789
+
790
+ gp_d = check_gp(gp)
791
+ if "col" in gp_d:
792
+ cols = gp_d["col"]
793
+ if "lwd" in gp_d:
794
+ lwds = gp_d["lwd"]
795
+ if "lty" in gp_d:
796
+ ltys = gp_d["lty"]
797
+
798
+ return {
799
+ "x0": unit_c(*x0_list) if x_is_unit else np.asarray(x0_list, dtype=float),
800
+ "x1": unit_c(*x1_list) if x_is_unit else np.asarray(x1_list, dtype=float),
801
+ "y0": np.asarray(y0_list, dtype=float),
802
+ "y1": np.asarray(y1_list, dtype=float),
803
+ "col": cols,
804
+ "lwd": lwds,
805
+ "lty": ltys,
806
+ "node": np.asarray(node_flag, dtype=bool),
807
+ "node_x": unit_c(*node_x) if x_is_unit else np.asarray(node_x, dtype=float),
808
+ "node_y": np.asarray(node_y, dtype=float),
809
+ "node_col": node_col,
810
+ "node_fill": node_fill,
811
+ "node_pch": node_pch,
812
+ "node_size": unit_c(*node_size) if node_size else unit([], "char"),
813
+ }
814
+
815
+
816
+ def dendrogramGrob(
817
+ dend: Dendrogram,
818
+ facing: str = "bottom",
819
+ order: str = "normal",
820
+ gp: dict[str, Any] | None = None,
821
+ ) -> GTree:
822
+ """Build a GTree representing a dendrogram with given `facing` and `order`."""
823
+ facing = facing.lower()
824
+ order = order.lower()
825
+ if facing not in ("bottom", "top", "left", "right"):
826
+ raise ValueError(f"Invalid `facing`: {facing!r}")
827
+ if order not in ("normal", "reverse"):
828
+ raise ValueError(f"Invalid `order`: {order!r}")
829
+
830
+ lt = _construct_dend_segments(dend, gp or {})
831
+ if not lt:
832
+ gt = GTree(children=[])
833
+ gt.facing = facing # type: ignore[attr-defined]
834
+ return gt
835
+
836
+ x0, x1 = lt["x0"], lt["x1"]
837
+ y0, y1 = lt["y0"], lt["y1"]
838
+ nx, ny = lt["node_x"], lt["node_y"]
839
+
840
+ if order == "reverse":
841
+ ux0 = x0 if isinstance(x0, Unit) else unit(x0, "native")
842
+ ux1 = x1 if isinstance(x1, Unit) else unit(x1, "native")
843
+ unx = nx if isinstance(nx, Unit) else unit(nx, "native")
844
+ x0 = unit(1.0, "npc") - ux0
845
+ x1 = unit(1.0, "npc") - ux1
846
+ nx = unit(1.0, "npc") - unx
847
+
848
+ if facing in ("top", "right"):
849
+ y0 = unit(1.0, "npc") - unit(y0, "native")
850
+ y1 = unit(1.0, "npc") - unit(y1, "native")
851
+ ny = unit(1.0, "npc") - unit(ny, "native")
852
+
853
+ seg_gp = gpar(col=lt["col"], lwd=lt["lwd"], lty=lt["lty"])
854
+ children: list[Any] = []
855
+ if facing in ("bottom", "top"):
856
+ children.append(segmentsGrob(x0, y0, x1, y1, gp=seg_gp, default_units="native"))
857
+ if np.any(lt["node"]):
858
+ mask = lt["node"]
859
+ idxs = np.where(mask)[0]
860
+ children.append(
861
+ pointsGrob(
862
+ nx[mask] if isinstance(nx, Unit) else nx[mask],
863
+ ny[mask],
864
+ pch=[lt["node_pch"][i] for i in idxs],
865
+ size=lt["node_size"][mask],
866
+ gp=gpar(
867
+ col=[lt["node_col"][i] for i in idxs],
868
+ fill=[lt["node_fill"][i] for i in idxs],
869
+ ),
870
+ default_units="native",
871
+ )
872
+ )
873
+ else:
874
+ children.append(segmentsGrob(y0, x0, y1, x1, gp=seg_gp, default_units="native"))
875
+ if np.any(lt["node"]):
876
+ mask = lt["node"]
877
+ idxs = np.where(mask)[0]
878
+ children.append(
879
+ pointsGrob(
880
+ ny[mask],
881
+ nx[mask],
882
+ pch=[lt["node_pch"][i] for i in idxs],
883
+ size=lt["node_size"][mask],
884
+ gp=gpar(
885
+ col=[lt["node_col"][i] for i in idxs],
886
+ fill=[lt["node_fill"][i] for i in idxs],
887
+ ),
888
+ default_units="native",
889
+ )
890
+ )
891
+
892
+ gt = GTree(children=children)
893
+ gt.facing = facing # type: ignore[attr-defined]
894
+ return gt
895
+
896
+
897
+ def grid_dendrogram(dend: Dendrogram, facing: str = "bottom", order: str = "normal", gp: dict[str, Any] | None = None, test: bool = False) -> GTree:
898
+ """Draw a `Dendrogram` object into the current viewport (or a test viewport if `test=True`)."""
899
+ gb = dendrogramGrob(dend, facing=facing, order=order, gp=gp)
900
+ if test:
901
+ h = float(dend_heights(dend))
902
+ if h <= 0:
903
+ h = 1.0
904
+ n = dend.nobs()
905
+ grid_newpage()
906
+ xy = dend_xy(dend)
907
+ is_u = isinstance(xy["x"], Unit)
908
+ if is_u:
909
+ max_x = max(float(v) for v in xy["x"].to_mm("x")) / 10.0
910
+ xmin, xmax = -0.5, max(n + 0.5, max_x + 0.5)
911
+ else:
912
+ xmin, xmax = -0.5, n + 0.5
913
+ if facing in ("top", "bottom"):
914
+ pushViewport(
915
+ Viewport(
916
+ xscale=(xmin, xmax),
917
+ yscale=(-h * 0.05, h * 1.05),
918
+ width=unit(1, "npc") - unit(4, "cm"),
919
+ height=unit(1, "npc") - unit(4, "cm"),
920
+ )
921
+ )
922
+ else:
923
+ pushViewport(
924
+ Viewport(
925
+ yscale=(xmin, xmax),
926
+ xscale=(-h * 0.05, h * 1.05),
927
+ width=unit(1, "npc") - unit(4, "cm"),
928
+ height=unit(1, "npc") - unit(4, "cm"),
929
+ )
930
+ )
931
+ gb.draw()
932
+ if test:
933
+ grid_xaxis()
934
+ grid_yaxis()
935
+ grid_rect()
936
+ popViewport()
937
+ return gb