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,886 @@
1
+ """UpSet combination matrices (`make_comb_mat`), accessors, and `UpSet` plots."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import copy
6
+ import math
7
+ from typing import Any, Callable, Sequence
8
+
9
+ import numpy as np
10
+ import pandas as pd
11
+
12
+ from ._options import _ENV
13
+ from .annotations import HeatmapAnnotation, anno_barplot, anno_text, rowAnnotation
14
+ from .colors import to_hex_rgba
15
+ from .genomic import GRanges, IRanges
16
+ from .grid import grid_lines, grid_points, grid_rect, grid_segments
17
+ from .heatmap import Heatmap
18
+ from .units import Unit, as_unit, check_gp, convertWidth, gpar, unit
19
+
20
+
21
+ def list_to_matrix(lt: dict[str, Sequence[Any]] | Sequence[Sequence[Any]], universal_set: Sequence[Any] | None = None) -> pd.DataFrame:
22
+ """Convert a dict/list of sets into a 0/1 membership matrix DataFrame (`list_to_matrix.Rd`)."""
23
+ if isinstance(lt, dict):
24
+ keys = [str(k) for k in lt.keys()]
25
+ sets = [set(v) for v in lt.values()]
26
+ else:
27
+ sets = [set(v) for v in lt]
28
+ keys = [f"set_{i + 1}" for i in range(len(sets))]
29
+
30
+ if universal_set is not None:
31
+ all_elems = list(dict.fromkeys(universal_set))
32
+ else:
33
+ seen: dict[Any, None] = {}
34
+ for s_item in lt.values() if isinstance(lt, dict) else lt:
35
+ for elem in s_item:
36
+ if elem not in seen:
37
+ seen[elem] = None
38
+ all_elems = list(seen.keys())
39
+
40
+ mat = np.zeros((len(all_elems), len(sets)), dtype=int)
41
+ for col_i, s in enumerate(sets):
42
+ for row_i, elem in enumerate(all_elems):
43
+ if elem in s:
44
+ mat[row_i, col_i] = 1
45
+ return pd.DataFrame(mat, index=all_elems, columns=keys)
46
+
47
+
48
+ class CombMat:
49
+ """Combination matrix wrapper powering `UpSet` plots (`make_comb_mat.Rd`)."""
50
+
51
+ def __init__(
52
+ self,
53
+ mat: np.ndarray,
54
+ set_names: list[str],
55
+ comb_codes: list[str],
56
+ set_sizes: np.ndarray,
57
+ comb_sizes: np.ndarray,
58
+ mode: str = "distinct",
59
+ universal_size: float | None = None,
60
+ elem_groups: dict[str, Any] | None = None,
61
+ sets_on_rows: bool = True,
62
+ ) -> None:
63
+ self.matrix = np.asarray(mat, dtype=int) # shape (n_sets, n_combs)
64
+ self._set_names = list(set_names)
65
+ self._comb_codes = list(comb_codes)
66
+ self._set_sizes = np.asarray(set_sizes, dtype=float)
67
+ self._comb_sizes = np.asarray(comb_sizes, dtype=float)
68
+ self.mode = mode
69
+ self.universal_size = universal_size
70
+ self._elem_groups = elem_groups or {}
71
+ self._sets_on_rows = bool(sets_on_rows)
72
+
73
+ @property
74
+ def shape(self) -> tuple[int, int]:
75
+ return self.matrix.shape if self._sets_on_rows else self.matrix.T.shape
76
+
77
+ @property
78
+ def nrow(self) -> int:
79
+ return self.shape[0]
80
+
81
+ @property
82
+ def ncol(self) -> int:
83
+ return self.shape[1]
84
+
85
+ @property
86
+ def set_names(self) -> list[str]:
87
+ return list(self._set_names)
88
+
89
+ @set_names.setter
90
+ def set_names(self, value: Sequence[str]) -> None:
91
+ new_nms = [str(v) for v in value]
92
+ if len(new_nms) != len(self._set_names):
93
+ raise ValueError("Length of new set names must match number of sets.")
94
+ self._set_names = new_nms
95
+
96
+ def set_name(self, new_names: Sequence[str] | None = None) -> list[str]:
97
+ if new_names is not None:
98
+ self.set_names = new_names
99
+ return list(self._set_names)
100
+
101
+ def comb_name(self, readable: bool = False) -> list[str]:
102
+ if not readable:
103
+ return list(self._comb_codes)
104
+ out = []
105
+ for code in self._comb_codes:
106
+ parts = [nm for nm, bit in zip(self._set_names, code) if bit == "1"]
107
+ if not parts:
108
+ out.append("complement")
109
+ else:
110
+ sep = " & " if self.mode in ("distinct", "intersect") else " | "
111
+ out.append(sep.join(parts))
112
+ return out
113
+
114
+ def set_size(self) -> np.ndarray:
115
+ return self._set_sizes.copy()
116
+
117
+ def comb_size(self) -> np.ndarray:
118
+ return self._comb_sizes.copy()
119
+
120
+ def comb_degree(self) -> np.ndarray:
121
+ return np.sum(self.matrix, axis=0)
122
+
123
+ def complement_size(self) -> float:
124
+ for idx, code in enumerate(self._comb_codes):
125
+ if "1" not in code:
126
+ return float(self._comb_sizes[idx])
127
+ if self.universal_size is not None:
128
+ tot_covered = float(np.sum(self._comb_sizes)) if self.mode == "distinct" else 0.0
129
+ return max(0.0, float(self.universal_size) - tot_covered)
130
+ return 0.0
131
+
132
+ def extract_comb(self, comb_name: str) -> Any:
133
+ if comb_name in self._elem_groups:
134
+ return self._elem_groups[comb_name]
135
+ # Allow readable form lookup
136
+ readable = self.comb_name(readable=True)
137
+ if comb_name in readable:
138
+ code = self._comb_codes[readable.index(comb_name)]
139
+ return self._elem_groups.get(code, [])
140
+ raise KeyError(f"Combination {comb_name!r} not found.")
141
+
142
+ def t(self) -> "CombMat":
143
+ cp = copy.deepcopy(self)
144
+ cp._sets_on_rows = not self._sets_on_rows
145
+ return cp
146
+
147
+ def copy_all(self) -> "CombMat":
148
+ return copy.deepcopy(self)
149
+
150
+ def __getitem__(self, key: Any) -> "CombMat":
151
+ if isinstance(key, tuple):
152
+ r_key, c_key = key
153
+ else:
154
+ r_key, c_key = key, slice(None)
155
+
156
+ if not self._sets_on_rows:
157
+ c_key, r_key = r_key, c_key
158
+
159
+ cp = self.copy_all()
160
+ ns, nc = cp.matrix.shape
161
+
162
+ def _res(spec: Any, n: int, nms: list[str]) -> list[int]:
163
+ if isinstance(spec, slice):
164
+ return list(range(*spec.indices(n)))
165
+ if isinstance(spec, (int, np.integer)):
166
+ i = int(spec)
167
+ return [i + n if i < 0 else i]
168
+ if isinstance(spec, str):
169
+ return [nms.index(spec)]
170
+ seq = list(spec)
171
+ if seq and all(isinstance(x, (bool, np.bool_)) for x in seq):
172
+ return [i for i, f in enumerate(seq) if f]
173
+ if seq and all(isinstance(x, str) for x in seq):
174
+ return [nms.index(s) for s in seq]
175
+ return [int(x) for x in seq]
176
+
177
+ if not (isinstance(r_key, slice) and r_key == slice(None)):
178
+ r_idx = _res(r_key, ns, cp._set_names)
179
+ cp.matrix = cp.matrix[r_idx, :]
180
+ cp._set_names = [cp._set_names[i] for i in r_idx]
181
+ cp._set_sizes = cp._set_sizes[r_idx]
182
+ # Recompute combination codes after set subsetting
183
+ cp._comb_codes = ["".join(str(int(cp.matrix[r, c])) for r in range(len(r_idx))) for c in range(cp.matrix.shape[1])]
184
+
185
+ if not (isinstance(c_key, slice) and c_key == slice(None)):
186
+ c_idx = _res(c_key, cp.matrix.shape[1], cp._comb_codes)
187
+ cp.matrix = cp.matrix[:, c_idx]
188
+ cp._comb_codes = [cp._comb_codes[j] for j in c_idx]
189
+ cp._comb_sizes = cp._comb_sizes[c_idx]
190
+
191
+ return cp
192
+
193
+ def __len__(self) -> int:
194
+ return self.matrix.size
195
+
196
+ def __repr__(self) -> str:
197
+ r_or_c = "rows" if self._sets_on_rows else "columns"
198
+ return (
199
+ f"A combination matrix with {len(self._set_names)} sets and {len(self._comb_codes)} combinations.\n"
200
+ f" mode: {self.mode}, sets on: {r_or_c}\n"
201
+ f" sets: {', '.join(self._set_names)}"
202
+ )
203
+
204
+
205
+ def _compute_genomic_comb_mat(
206
+ sets_dict: dict[str, GRanges | IRanges],
207
+ mode: str,
208
+ bin_size: float | None = None,
209
+ complement_size: float | None = None,
210
+ ) -> tuple[np.ndarray, list[str], np.ndarray, np.ndarray, dict[str, Any]]:
211
+ """Compute exact interval-partitioned combination sizes for GRanges or IRanges lists."""
212
+ set_names = list(sets_dict.keys())
213
+ n_sets = len(set_names)
214
+ first_val = next(iter(sets_dict.values()))
215
+ is_gr = isinstance(first_val, GRanges)
216
+
217
+ # Compute elementary disjoint intervals across union of breakpoints per chromosome (or single chr for IRanges)
218
+ by_chr: dict[str, list[tuple[int, int, int]]] = {} # chr -> list of (start, end, set_idx)
219
+ for si, (nm, obj) in enumerate(sets_dict.items()):
220
+ if is_gr:
221
+ assert isinstance(obj, GRanges)
222
+ for k in range(len(obj)):
223
+ by_chr.setdefault(obj.seqnames[k], []).append((int(obj.start[k]), int(obj.end[k]), si))
224
+ else:
225
+ assert isinstance(obj, IRanges)
226
+ for k in range(len(obj)):
227
+ by_chr.setdefault("_ir", []).append((int(obj.start[k]), int(obj.end[k]), si))
228
+
229
+ # Build membership intervals on disjoint elementary segments
230
+ segments: list[tuple[str, int, int, tuple[int, ...]]] = []
231
+ set_sizes = np.zeros(n_sets, dtype=float)
232
+
233
+ for ch, ivs in by_chr.items():
234
+ pts = sorted({p for s, e, _ in ivs for p in (s, e + 1)})
235
+ if len(pts) < 2:
236
+ continue
237
+ # For each elementary interval [pts[k], pts[k+1]-1] check which sets cover it
238
+ n_seg = len(pts) - 1
239
+ cov = np.zeros((n_seg, n_sets), dtype=int)
240
+ for s, e, si in ivs:
241
+ i0 = int(np.searchsorted(pts, s))
242
+ i1 = int(np.searchsorted(pts, e + 1))
243
+ if i1 > i0:
244
+ cov[i0:i1, si] = 1
245
+ seg_lens = np.diff(np.asarray(pts, dtype=np.int64))
246
+ for si in range(n_sets):
247
+ set_sizes[si] += float(np.sum(seg_lens[cov[:, si] == 1]))
248
+ for idx in range(n_seg):
249
+ mask_t = tuple(int(cov[idx, si]) for si in range(n_sets))
250
+ if any(mask_t):
251
+ segments.append((ch, int(pts[idx]), int(pts[idx + 1] - 1), mask_t))
252
+
253
+ # Group distinct combinations present
254
+ comb_dict: dict[str, list[tuple[str, int, int]]] = {}
255
+ comb_len_map: dict[str, float] = {}
256
+ for ch, s, e, mask_t in segments:
257
+ code = "".join(str(b) for b in mask_t)
258
+ comb_len_map[code] = comb_len_map.get(code, 0.0) + float(e - s + 1)
259
+ comb_dict.setdefault(code, []).append((ch, s, e))
260
+
261
+ if mode == "distinct":
262
+ codes = list(comb_len_map.keys())
263
+ sizes = np.array([comb_len_map[c] for c in codes], dtype=float)
264
+ mat = np.array([[int(b) for b in c] for c in codes], dtype=int).T if codes else np.zeros((n_sets, 0), dtype=int)
265
+ elem_groups = {}
266
+ for c, segs in comb_dict.items():
267
+ if is_gr:
268
+ elem_groups[c] = GRanges([x[0] for x in segs], IRanges([x[1] for x in segs], [x[2] for x in segs]))
269
+ else:
270
+ elem_groups[c] = IRanges([x[1] for x in segs], [x[2] for x in segs])
271
+ else:
272
+ # Intersect or union over all non-empty distinct codes
273
+ all_codes = full_comb_code(n_sets, complement=(complement_size is not None and complement_size > 0))
274
+ codes_kept: list[str] = []
275
+ sizes_list: list[float] = []
276
+ elem_groups = {}
277
+ for target_code in all_codes:
278
+ bits = np.array([int(b) for b in target_code], dtype=int)
279
+ tot = 0.0
280
+ segs_out: list[tuple[str, int, int]] = []
281
+ for seg_code, seg_len in comb_len_map.items():
282
+ s_bits = np.array([int(b) for b in seg_code], dtype=int)
283
+ if mode == "intersect":
284
+ ok = bool(np.all(s_bits[bits == 1] == 1))
285
+ else: # union
286
+ ok = bool(np.any((bits == 1) & (s_bits == 1)))
287
+ if ok:
288
+ tot += seg_len
289
+ segs_out.extend(comb_dict[seg_code])
290
+ if tot > 0:
291
+ codes_kept.append(target_code)
292
+ sizes_list.append(tot)
293
+ if is_gr:
294
+ elem_groups[target_code] = GRanges([x[0] for x in segs_out], IRanges([x[1] for x in segs_out], [x[2] for x in segs_out]))
295
+ else:
296
+ elem_groups[target_code] = IRanges([x[1] for x in segs_out], [x[2] for x in segs_out])
297
+ codes = codes_kept
298
+ sizes = np.asarray(sizes_list, dtype=float)
299
+ mat = np.array([[int(b) for b in c] for c in codes], dtype=int).T if codes else np.zeros((n_sets, 0), dtype=int)
300
+
301
+ if complement_size is not None and complement_size > 0:
302
+ z_code = "0" * n_sets
303
+ codes = [z_code] + codes
304
+ sizes = np.concatenate([[float(complement_size)], sizes])
305
+ z_col = np.zeros((n_sets, 1), dtype=int)
306
+ mat = np.hstack([z_col, mat])
307
+
308
+ return mat, codes, set_sizes, sizes, elem_groups
309
+
310
+
311
+ def make_comb_mat(
312
+ *args: Any,
313
+ mode: str = "distinct",
314
+ top_n_sets: float = np.inf,
315
+ min_set_size: float = -np.inf,
316
+ universal_set: Sequence[Any] | None = None,
317
+ complement_size: float | None = None,
318
+ remove_empty_comb_set: bool = True,
319
+ remove_complement_set: bool = False,
320
+ ) -> CombMat:
321
+ """Create a combination matrix from sets, binary matrix, or genomic ranges (`make_comb_mat.Rd`)."""
322
+ mode = str(mode).lower()
323
+ if mode not in ("distinct", "intersect", "union"):
324
+ raise ValueError("`mode` must be 'distinct', 'intersect', or 'union'.")
325
+
326
+ if not args:
327
+ raise ValueError("`make_comb_mat` requires at least one input argument.")
328
+
329
+ first = args[0]
330
+ # Support positional multiple GRanges/IRanges/sets or single dict/DataFrame/ndarray
331
+ if len(args) > 1:
332
+ lt: dict[str, Any] = {f"set_{i + 1}": a for i, a in enumerate(args)}
333
+ elif isinstance(first, dict):
334
+ lt = dict(first)
335
+ elif isinstance(first, (list, tuple)) and first and isinstance(first[0], (set, list, tuple, np.ndarray, pd.Series, GRanges, IRanges)):
336
+ lt = {f"set_{i + 1}": a for i, a in enumerate(first)}
337
+ elif isinstance(first, (pd.DataFrame, np.ndarray)):
338
+ df = first if isinstance(first, pd.DataFrame) else pd.DataFrame(first, columns=[f"set_{i + 1}" for i in range(first.shape[1])])
339
+ # Apply set filters before computing combos
340
+ bin_mat = (df.to_numpy(dtype=float) != 0).astype(int)
341
+ set_names = [str(c) for c in df.columns]
342
+ set_sizes = np.sum(bin_mat, axis=0).astype(float)
343
+ keep = set_sizes >= float(min_set_size)
344
+ if np.isfinite(top_n_sets) and np.sum(keep) > int(top_n_sets):
345
+ top_idx = np.argsort(-set_sizes)[: int(top_n_sets)]
346
+ keep2 = np.zeros(len(set_names), dtype=bool)
347
+ keep2[top_idx] = True
348
+ keep &= keep2
349
+ bin_mat = bin_mat[:, keep]
350
+ set_names = [s for s, f in zip(set_names, keep) if f]
351
+ set_sizes = set_sizes[keep]
352
+ elem_names = list(df.index)
353
+ n_elem, n_sets = bin_mat.shape
354
+
355
+ # Compute element membership codes
356
+ row_codes = ["".join(str(int(bin_mat[r, c])) for c in range(n_sets)) for r in range(n_elem)]
357
+ code_to_elems: dict[str, list[Any]] = {}
358
+ for r_i, c_str in enumerate(row_codes):
359
+ code_to_elems.setdefault(c_str, []).append(elem_names[r_i])
360
+
361
+ return _build_comb_from_membership(
362
+ bin_mat=bin_mat,
363
+ set_names=set_names,
364
+ set_sizes=set_sizes,
365
+ code_to_elems=code_to_elems,
366
+ mode=mode,
367
+ universal_size=float(n_elem),
368
+ complement_size=complement_size,
369
+ remove_empty_comb_set=remove_empty_comb_set,
370
+ remove_complement_set=remove_complement_set,
371
+ )
372
+ else:
373
+ raise TypeError(f"Unsupported input type to `make_comb_mat`: {type(first)}")
374
+
375
+ # Check if dict of GRanges / IRanges
376
+ vals = list(lt.values())
377
+ if vals and isinstance(vals[0], (GRanges, IRanges)):
378
+ mat, codes, set_sizes, comb_sizes, elem_groups = _compute_genomic_comb_mat(lt, mode=mode, complement_size=complement_size)
379
+ return CombMat(
380
+ mat=mat,
381
+ set_names=list(lt.keys()),
382
+ comb_codes=codes,
383
+ set_sizes=set_sizes,
384
+ comb_sizes=comb_sizes,
385
+ mode=mode,
386
+ elem_groups=elem_groups,
387
+ )
388
+
389
+ # Filter sets by min_set_size & top_n_sets
390
+ set_items = [(str(k), set(v)) for k, v in lt.items()]
391
+ set_items = [(k, s) for k, s in set_items if len(s) >= float(min_set_size)]
392
+ if np.isfinite(top_n_sets) and len(set_items) > int(top_n_sets):
393
+ set_items.sort(key=lambda kv: -len(kv[1]))
394
+ set_items = set_items[: int(top_n_sets)]
395
+
396
+ filtered_dict = dict(set_items)
397
+ df = list_to_matrix(filtered_dict, universal_set=universal_set)
398
+ bin_mat = df.to_numpy(dtype=int)
399
+ set_names = [str(c) for c in df.columns]
400
+ set_sizes = np.sum(bin_mat, axis=0).astype(float)
401
+ elem_names = list(df.index)
402
+ row_codes = ["".join(str(int(bin_mat[r, c])) for c in range(len(set_names))) for r in range(len(elem_names))]
403
+ code_to_elems = {}
404
+ for r_i, c_str in enumerate(row_codes):
405
+ code_to_elems.setdefault(c_str, []).append(elem_names[r_i])
406
+
407
+ eff_univ_size = float(len(elem_names)) if universal_set is not None else None
408
+ return _build_comb_from_membership(
409
+ bin_mat=bin_mat,
410
+ set_names=set_names,
411
+ set_sizes=set_sizes,
412
+ code_to_elems=code_to_elems,
413
+ mode=mode,
414
+ universal_size=eff_univ_size,
415
+ complement_size=complement_size,
416
+ remove_empty_comb_set=remove_empty_comb_set,
417
+ remove_complement_set=remove_complement_set,
418
+ )
419
+
420
+
421
+ def _build_comb_from_membership(
422
+ bin_mat: np.ndarray,
423
+ set_names: list[str],
424
+ set_sizes: np.ndarray,
425
+ code_to_elems: dict[str, list[Any]],
426
+ mode: str,
427
+ universal_size: float | None,
428
+ complement_size: float | None,
429
+ remove_empty_comb_set: bool,
430
+ remove_complement_set: bool,
431
+ ) -> CombMat:
432
+ n_sets = len(set_names)
433
+ z_code = "0" * n_sets
434
+
435
+ if complement_size is not None and complement_size > 0:
436
+ has_complement = True
437
+ elif z_code in code_to_elems and len(code_to_elems[z_code]) > 0 and not remove_complement_set:
438
+ has_complement = True
439
+ else:
440
+ has_complement = False
441
+
442
+ if mode == "distinct":
443
+ codes = list(code_to_elems.keys())
444
+ if not has_complement:
445
+ codes = [c for c in codes if c != z_code]
446
+ # Order nicely: complement last or sorted by bits/degree? Keep deterministic order (decreasing comb_size or lexicographical)
447
+ sizes = np.array([float(complement_size if (c == z_code and complement_size is not None) else len(code_to_elems.get(c, []))) for c in codes], dtype=float)
448
+ elem_groups = {c: list(code_to_elems.get(c, [])) for c in codes}
449
+ else:
450
+ all_codes = full_comb_code(n_sets, complement=has_complement)
451
+ codes_out: list[str] = []
452
+ sizes_out: list[float] = []
453
+ elem_groups = {}
454
+ for target_code in all_codes:
455
+ if target_code == z_code:
456
+ sz = float(complement_size) if complement_size is not None else float(len(code_to_elems.get(z_code, [])))
457
+ if not remove_empty_comb_set or sz > 0:
458
+ codes_out.append(z_code)
459
+ sizes_out.append(sz)
460
+ elem_groups[z_code] = list(code_to_elems.get(z_code, []))
461
+ continue
462
+ bits = np.array([int(b) for b in target_code], dtype=bool)
463
+ if mode == "intersect":
464
+ mask = np.all(bin_mat[:, bits] == 1, axis=1)
465
+ else: # union
466
+ mask = np.any(bin_mat[:, bits] == 1, axis=1)
467
+ sz = float(np.sum(mask))
468
+ if remove_empty_comb_set and sz == 0:
469
+ continue
470
+ codes_out.append(target_code)
471
+ sizes_out.append(sz)
472
+ # Extract matching elements
473
+ elems = [el for c_str, el_list in code_to_elems.items() if (
474
+ (all(c_str[k] == "1" for k in np.where(bits)[0])) if mode == "intersect"
475
+ else (any(c_str[k] == "1" for k in np.where(bits)[0]))
476
+ ) for el in el_list]
477
+ elem_groups[target_code] = elems
478
+ codes = codes_out
479
+ sizes = np.asarray(sizes_out, dtype=float)
480
+
481
+ mat = np.array([[int(b) for b in c] for c in codes], dtype=int).T if codes else np.zeros((n_sets, 0), dtype=int)
482
+ return CombMat(
483
+ mat=mat,
484
+ set_names=set_names,
485
+ comb_codes=codes,
486
+ set_sizes=set_sizes,
487
+ comb_sizes=sizes,
488
+ mode=mode,
489
+ universal_size=universal_size,
490
+ elem_groups=elem_groups,
491
+ )
492
+
493
+
494
+ def full_comb_code(n: int, complement: bool = False) -> list[str]:
495
+ """Generate all binary combination strings of length `n` (`full_comb_code.Rd`)."""
496
+ codes = []
497
+ for deg in range(1, n + 1):
498
+ from itertools import combinations
499
+ for idxs in combinations(range(n), deg):
500
+ bits = ["0"] * n
501
+ for idx in idxs:
502
+ bits[idx] = "1"
503
+ codes.append("".join(bits))
504
+ if complement:
505
+ codes.insert(0, "0" * n)
506
+ return codes
507
+
508
+
509
+ def set_name(m: CombMat, new_names: Sequence[str] | None = None) -> Any:
510
+ if new_names is not None:
511
+ cp = m.copy_all()
512
+ cp.set_names = new_names
513
+ return cp
514
+ return m.set_name()
515
+
516
+
517
+ def comb_name(m: CombMat, readable: bool = False) -> list[str]:
518
+ return m.comb_name(readable=readable)
519
+
520
+
521
+ def set_size(m: CombMat) -> np.ndarray:
522
+ return m.set_size()
523
+
524
+
525
+ def comb_size(m: CombMat) -> np.ndarray:
526
+ return m.comb_size()
527
+
528
+
529
+ def comb_degree(m: CombMat) -> np.ndarray:
530
+ return m.comb_degree()
531
+
532
+
533
+ def complement_size(m: CombMat) -> float:
534
+ return m.complement_size()
535
+
536
+
537
+ def extract_comb(m: CombMat, comb_name: str) -> Any:
538
+ return m.extract_comb(comb_name)
539
+
540
+
541
+ def order_comb_mat(m: CombMat, decreasing: bool = True) -> CombMat:
542
+ """Sort combination matrix columns by combination degree & size (`order_comb_mat.Rd`)."""
543
+ sz = m.comb_size()
544
+ deg = m.comb_degree()
545
+ order = sorted(range(len(sz)), key=lambda j: (-sz[j] if decreasing else sz[j], deg[j], m._comb_codes[j]))
546
+ return m[:, order] if m._sets_on_rows else m[order, :]
547
+
548
+
549
+ def normalize_comb_mat(*args: CombMat, full_comb_sets: bool = False) -> list[CombMat]:
550
+ """Align multiple CombMat objects to share identical set & combination ordering (`normalize_comb_mat.Rd`)."""
551
+ if len(args) == 1 and isinstance(args[0], (list, tuple)):
552
+ mats = list(args[0])
553
+ else:
554
+ mats = list(args)
555
+ if not mats:
556
+ return []
557
+ union_sets = list(dict.fromkeys(nm for m in mats for nm in m._set_names))
558
+ if full_comb_sets:
559
+ union_codes = full_comb_code(len(union_sets), complement=any("0" * len(m._set_names) in m._comb_codes for m in mats))
560
+ else:
561
+ # Map each matrix's codes onto union_sets
562
+ seen_codes: list[str] = []
563
+ seen_c: set[str] = set()
564
+ for m in mats:
565
+ s_idx = [union_sets.index(nm) for nm in m._set_names]
566
+ for c_str in m._comb_codes:
567
+ bits = ["0"] * len(union_sets)
568
+ for local_i, ch in enumerate(c_str):
569
+ if ch == "1":
570
+ bits[s_idx[local_i]] = "1"
571
+ mapped = "".join(bits)
572
+ if mapped not in seen_c:
573
+ seen_c.add(mapped)
574
+ seen_codes.append(mapped)
575
+ union_codes = seen_codes
576
+
577
+ out: list[CombMat] = []
578
+ for m in mats:
579
+ s_lookup = {nm: i for i, nm in enumerate(m._set_names)}
580
+ c_lookup = {}
581
+ for j, c_str in enumerate(m._comb_codes):
582
+ bits = ["0"] * len(union_sets)
583
+ for local_i, ch in enumerate(c_str):
584
+ if ch == "1":
585
+ bits[union_sets.index(m._set_names[local_i])] = "1"
586
+ c_lookup["".join(bits)] = j
587
+
588
+ new_set_sizes = np.array([m._set_sizes[s_lookup[nm]] if nm in s_lookup else 0.0 for nm in union_sets], dtype=float)
589
+ new_comb_sizes = np.array([m._comb_sizes[c_lookup[c_str]] if c_str in c_lookup else 0.0 for c_str in union_codes], dtype=float)
590
+ new_mat = np.array([[int(b) for b in c_str] for c_str in union_codes], dtype=int).T if union_codes else np.zeros((len(union_sets), 0), dtype=int)
591
+ out.append(
592
+ CombMat(
593
+ mat=new_mat,
594
+ set_names=union_sets,
595
+ comb_codes=union_codes,
596
+ set_sizes=new_set_sizes,
597
+ comb_sizes=new_comb_sizes,
598
+ mode=m.mode,
599
+ universal_size=m.universal_size,
600
+ sets_on_rows=m._sets_on_rows,
601
+ )
602
+ )
603
+ return out
604
+
605
+
606
+ # ---- UpSet Annotation Helpers ----
607
+
608
+ def upset_top_annotation(
609
+ m: CombMat,
610
+ gp: dict[str, Any] | None = None,
611
+ height: Unit = unit(3, "cm"),
612
+ show_annotation_name: bool = True,
613
+ annotation_name_gp: dict[str, Any] | None = None,
614
+ annotation_name_offset: Unit | None = None,
615
+ annotation_name_side: str = "left",
616
+ annotation_name_rot: float = 0.0,
617
+ bar_width: float = 0.6,
618
+ add_numbers: bool = False,
619
+ numbers_gp: dict[str, Any] | None = None,
620
+ numbers_rot: float = 0.0,
621
+ axis_param: dict[str, Any] | None = None,
622
+ which: str | None = None,
623
+ width: Unit | None = None,
624
+ **kwargs: Any,
625
+ ) -> HeatmapAnnotation:
626
+ """Default top combination-size (or set-size when transposed) barplot annotation (`upset_top_annotation.Rd`)."""
627
+ sets_on_rows = m._sets_on_rows
628
+ eff_which = which or "column"
629
+ vals = m.comb_size() if sets_on_rows else m.set_size()
630
+ lbl = "Intersection\nsize" if sets_on_rows else "Set\nsize"
631
+ if gp is None:
632
+ gp = gpar(fill="black", col=None)
633
+ anno = anno_barplot(
634
+ vals,
635
+ gp=gp,
636
+ bar_width=bar_width,
637
+ border=False,
638
+ which=eff_which,
639
+ height=height if eff_which == "column" else None,
640
+ width=width or (height if eff_which == "row" else None),
641
+ add_numbers=add_numbers,
642
+ numbers_gp=numbers_gp,
643
+ numbers_rot=numbers_rot,
644
+ axis_param=axis_param or ({"side": "left", "labels_rot": 0} if eff_which == "column" else {"side": "top"}),
645
+ **kwargs,
646
+ )
647
+ if eff_which == "column":
648
+ return HeatmapAnnotation(
649
+ **{lbl: anno},
650
+ show_annotation_name=show_annotation_name,
651
+ annotation_name_gp=annotation_name_gp or gpar(fontsize=10),
652
+ annotation_name_side=annotation_name_side,
653
+ annotation_name_rot=annotation_name_rot,
654
+ annotation_name_offset=annotation_name_offset,
655
+ )
656
+ return rowAnnotation(
657
+ **{lbl: anno},
658
+ show_annotation_name=show_annotation_name,
659
+ annotation_name_gp=annotation_name_gp or gpar(fontsize=10),
660
+ )
661
+
662
+
663
+ def upset_right_annotation(
664
+ m: CombMat,
665
+ gp: dict[str, Any] | None = None,
666
+ width: Unit = unit(2, "cm"),
667
+ bar_width: float = 0.6,
668
+ add_numbers: bool = False,
669
+ axis_param: dict[str, Any] | None = None,
670
+ show_annotation_name: bool = True,
671
+ annotation_name_gp: dict[str, Any] | None = None,
672
+ annotation_name_side: str = "bottom",
673
+ **kwargs: Any,
674
+ ) -> HeatmapAnnotation:
675
+ """Default right set-size (or comb-size when transposed) barplot annotation (`upset_right_annotation.Rd`)."""
676
+ sets_on_rows = m._sets_on_rows
677
+ vals = m.set_size() if sets_on_rows else m.comb_size()
678
+ lbl = "Set size" if sets_on_rows else "Intersection size"
679
+ if gp is None:
680
+ gp = gpar(fill="black", col=None)
681
+ ap = axis_param or {"side": "bottom", "labels_rot": 0}
682
+ user_offset = kwargs.pop("annotation_name_offset", None)
683
+ eff_offset = user_offset if user_offset is not None else (unit(7.0, "mm") if ap.get("side") == annotation_name_side else None)
684
+ anno = anno_barplot(
685
+ vals,
686
+ gp=gp,
687
+ bar_width=bar_width,
688
+ border=False,
689
+ which="row",
690
+ width=width,
691
+ add_numbers=add_numbers,
692
+ axis_param=ap,
693
+ **kwargs,
694
+ )
695
+ return rowAnnotation(
696
+ **{lbl: anno},
697
+ show_annotation_name=show_annotation_name,
698
+ annotation_name_gp=annotation_name_gp or gpar(fontsize=10),
699
+ annotation_name_side=annotation_name_side,
700
+ annotation_name_offset=eff_offset,
701
+ )
702
+
703
+
704
+ def upset_left_annotation(
705
+ m: CombMat,
706
+ gp: dict[str, Any] | None = None,
707
+ width: Unit = unit(2, "cm"),
708
+ bar_width: float = 0.6,
709
+ add_numbers: bool = False,
710
+ axis_param: dict[str, Any] | None = None,
711
+ show_annotation_name: bool = True,
712
+ annotation_name_gp: dict[str, Any] | None = None,
713
+ annotation_name_side: str = "bottom",
714
+ **kwargs: Any,
715
+ ) -> HeatmapAnnotation:
716
+ """Left-aligned inverted set-size barplot annotation (`upset_left_annotation.Rd`)."""
717
+ sets_on_rows = m._sets_on_rows
718
+ vals = m.set_size() if sets_on_rows else m.comb_size()
719
+ lbl = "Set size" if sets_on_rows else "Intersection size"
720
+ if gp is None:
721
+ gp = gpar(fill="black", col=None)
722
+ ap = axis_param or {"side": "bottom", "direction": "reverse", "labels_rot": 0}
723
+ user_offset = kwargs.pop("annotation_name_offset", None)
724
+ eff_offset = user_offset if user_offset is not None else (unit(7.0, "mm") if ap.get("side") == annotation_name_side else None)
725
+ anno = anno_barplot(
726
+ vals,
727
+ gp=gp,
728
+ bar_width=bar_width,
729
+ border=False,
730
+ which="row",
731
+ width=width,
732
+ add_numbers=add_numbers,
733
+ axis_param=ap,
734
+ **kwargs,
735
+ )
736
+ return rowAnnotation(
737
+ **{lbl: anno},
738
+ show_annotation_name=show_annotation_name,
739
+ annotation_name_gp=annotation_name_gp or gpar(fontsize=10),
740
+ annotation_name_side=annotation_name_side,
741
+ annotation_name_offset=eff_offset,
742
+ )
743
+
744
+
745
+ def UpSet(
746
+ m: CombMat,
747
+ comb_col: Any = "black",
748
+ pt_size: Unit = unit(3, "mm"),
749
+ lwd: float = 2.0,
750
+ bg_col: Any = "#F0F0F0",
751
+ bg_pt_col: Any = "#CCCCCC",
752
+ set_order: Sequence[Any] | None = None,
753
+ comb_order: Sequence[Any] | None = None,
754
+ top_annotation: Any = "default",
755
+ right_annotation: Any = "default",
756
+ left_annotation: Any = None,
757
+ bottom_annotation: Any = None,
758
+ row_names_side: str | None = None,
759
+ column_names_side: str = "bottom",
760
+ name: str | None = None,
761
+ **kwargs: Any,
762
+ ) -> Heatmap:
763
+ """Construct an UpSet plot Heatmap from a CombMat (`UpSet.Rd`)."""
764
+ if not isinstance(m, CombMat):
765
+ raise TypeError("`m` passed to `UpSet` must be a `CombMat` created by `make_comb_mat`.")
766
+
767
+ sets_on_rows = m._sets_on_rows
768
+ mat = m.matrix if sets_on_rows else m.matrix.T
769
+ nr, nc = mat.shape
770
+
771
+ if sets_on_rows:
772
+ r_names = m.set_name()
773
+ c_names = m.comb_name(readable=False)
774
+ eff_row_ord = list(range(nr)) if set_order is None else [r_names.index(s) if isinstance(s, str) else int(s) for s in set_order]
775
+ if comb_order is None:
776
+ csz = m.comb_size()
777
+ cdeg = m.comb_degree()
778
+ eff_col_ord = sorted(range(nc), key=lambda j: (cdeg[j], -csz[j]))
779
+ else:
780
+ eff_col_ord = [c_names.index(c) if isinstance(c, str) else int(c) for c in comb_order]
781
+ eff_rn_side = "left" if row_names_side is None else row_names_side
782
+ show_rn = kwargs.pop("show_row_names", True)
783
+ show_cn = kwargs.pop("show_column_names", False)
784
+ else:
785
+ r_names = m.comb_name(readable=False)
786
+ c_names = m.set_name()
787
+ if comb_order is None:
788
+ csz = m.comb_size()
789
+ cdeg = m.comb_degree()
790
+ eff_row_ord = sorted(range(nr), key=lambda i: (cdeg[i], -csz[i]))
791
+ else:
792
+ eff_row_ord = [r_names.index(c) if isinstance(c, str) else int(c) for c in comb_order]
793
+ eff_col_ord = list(range(nc)) if set_order is None else [c_names.index(s) if isinstance(s, str) else int(s) for s in set_order]
794
+ eff_rn_side = "left" if row_names_side is None else row_names_side
795
+ show_rn = kwargs.pop("show_row_names", False)
796
+ show_cn = kwargs.pop("show_column_names", True)
797
+
798
+ eff_top = upset_top_annotation(m) if top_annotation == "default" else top_annotation
799
+ eff_right = upset_right_annotation(m) if right_annotation == "default" else right_annotation
800
+ pt_u = as_unit(pt_size, "mm")
801
+
802
+ # Background stripes and active combination dots + connecting lines
803
+ bg_cols_seq = [bg_col] if isinstance(bg_col, str) else list(bg_col)
804
+ if len(bg_cols_seq) == 1:
805
+ bg_cols_seq = [bg_cols_seq[0], "#FFFFFF"]
806
+ comb_cols_raw = [comb_col] * (nc if sets_on_rows else nr) if isinstance(comb_col, (str, int, np.integer)) else list(comb_col)
807
+
808
+ from .utils import restore_matrix
809
+
810
+ def _layer_fun(j: Any, i: Any, x: Any, y: Any, w: Any, h: Any, fill: Any) -> None:
811
+ ind_mat = restore_matrix(j, i, x, y)
812
+ nr_s, nc_s = ind_mat.shape
813
+ x_npc = x.to_mm("x") if False else None
814
+ # Compute cell centers directly in npc for slice
815
+ if sets_on_rows:
816
+ # Horizontal alternating bands per row
817
+ for r in range(nr_s):
818
+ y_r = (nr_s - r - 0.5) / nr_s
819
+ c_bg = bg_cols_seq[r % len(bg_cols_seq)]
820
+ if c_bg and str(c_bg).lower() not in ("white", "#ffffff", "transparent", "na"):
821
+ grid_rect(x=unit(0.5, "npc"), y=unit(y_r, "npc"), width=unit(1.0, "npc"), height=unit(1.0 / nr_s, "npc"), gp=gpar(fill=c_bg, col=None))
822
+ # Dots & vertical lines per column
823
+ for c in range(nc_s):
824
+ pos_col = ind_mat[:, c]
825
+ orig_j = int(j[pos_col[0]])
826
+ orig_i_list = [int(i[p]) for p in pos_col]
827
+ active_rows = [r for r, oi in enumerate(orig_i_list) if mat[oi, orig_j] == 1]
828
+ x_c = (c + 0.5) / nc_s
829
+ ys_all = [(nr_s - r - 0.5) / nr_s for r in range(nr_s)]
830
+ grid_points(np.full(nr_s, x_c), np.asarray(ys_all), pch=16, size=pt_u, gp=gpar(col=bg_pt_col), default_units="npc")
831
+ c_act = to_hex_rgba(comb_cols_raw[orig_j % len(comb_cols_raw)])
832
+ if len(active_rows) >= 2:
833
+ y_top = (nr_s - min(active_rows) - 0.5) / nr_s
834
+ y_bot = (nr_s - max(active_rows) - 0.5) / nr_s
835
+ grid_segments(unit(x_c, "npc"), unit(y_bot, "npc"), unit(x_c, "npc"), unit(y_top, "npc"), gp=gpar(col=c_act, lwd=lwd))
836
+ if active_rows:
837
+ ys_act = [(nr_s - r - 0.5) / nr_s for r in active_rows]
838
+ grid_points(np.full(len(ys_act), x_c), np.asarray(ys_act), pch=16, size=pt_u, gp=gpar(col=c_act), default_units="npc")
839
+ else:
840
+ # Vertical alternating bands per column
841
+ for c in range(nc_s):
842
+ x_c = (c + 0.5) / nc_s
843
+ c_bg = bg_cols_seq[c % len(bg_cols_seq)]
844
+ if c_bg and str(c_bg).lower() not in ("white", "#ffffff", "transparent", "na"):
845
+ grid_rect(x=unit(x_c, "npc"), y=unit(0.5, "npc"), width=unit(1.0 / nc_s, "npc"), height=unit(1.0, "npc"), gp=gpar(fill=c_bg, col=None))
846
+ # Dots & horizontal lines per row
847
+ for r in range(nr_s):
848
+ pos_row = ind_mat[r, :]
849
+ orig_i = int(i[pos_row[0]])
850
+ orig_j_list = [int(j[p]) for p in pos_row]
851
+ active_cols = [c for c, oj in enumerate(orig_j_list) if mat[orig_i, oj] == 1]
852
+ y_r = (nr_s - r - 0.5) / nr_s
853
+ xs_all = [(c + 0.5) / nc_s for c in range(nc_s)]
854
+ grid_points(np.asarray(xs_all), np.full(nc_s, y_r), pch=16, size=pt_u, gp=gpar(col=bg_pt_col), default_units="npc")
855
+ c_act = to_hex_rgba(comb_cols_raw[orig_i % len(comb_cols_raw)])
856
+ if len(active_cols) >= 2:
857
+ x_left = (min(active_cols) + 0.5) / nc_s
858
+ x_right = (max(active_cols) + 0.5) / nc_s
859
+ grid_segments(unit(x_left, "npc"), unit(y_r, "npc"), unit(x_right, "npc"), unit(y_r, "npc"), gp=gpar(col=c_act, lwd=lwd))
860
+ if active_cols:
861
+ xs_act = [(c + 0.5) / nc_s for c in active_cols]
862
+ grid_points(np.asarray(xs_act), np.full(len(xs_act), y_r), pch=16, size=pt_u, gp=gpar(col=c_act), default_units="npc")
863
+
864
+ df_mat = pd.DataFrame(mat, index=r_names, columns=c_names)
865
+ ht_name = name or f"upset_{_ENV.next_heatmap_index()}"
866
+
867
+ return Heatmap(
868
+ df_mat,
869
+ name=ht_name,
870
+ rect_gp=gpar(type="none"),
871
+ layer_fun=_layer_fun,
872
+ cluster_rows=False,
873
+ cluster_columns=False,
874
+ row_order=eff_row_ord,
875
+ column_order=eff_col_ord,
876
+ show_row_names=show_rn,
877
+ row_names_side=eff_rn_side,
878
+ show_column_names=show_cn,
879
+ column_names_side=column_names_side,
880
+ top_annotation=eff_top,
881
+ right_annotation=eff_right,
882
+ left_annotation=left_annotation,
883
+ bottom_annotation=bottom_annotation,
884
+ show_heatmap_legend=False,
885
+ **kwargs,
886
+ )