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,276 @@
1
+ """Density heatmaps, frequency heatmaps, and KS-distance clustering."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from builtins import range as _range
6
+ from typing import Any, Callable, Sequence
7
+
8
+ import numpy as np
9
+ import pandas as pd
10
+ from scipy.stats import gaussian_kde, ks_2samp
11
+
12
+ from ._options import _ENV
13
+ from .annotations import HeatmapAnnotation, anno_lines, anno_points
14
+ from .colors import brewer_pal, colorRamp2
15
+ from .decorate import decorate_heatmap_body
16
+ from .dendrogram import DistMatrix, as_dist
17
+ from .grid import grid_lines, grid_segments, grid_text, grid_yaxis
18
+ from .heatmap import Heatmap
19
+ from .units import Unit, as_unit, check_gp, gpar, unit
20
+
21
+
22
+ def _to_column_series_list(data: Any) -> tuple[list[np.ndarray], list[str] | None]:
23
+ if isinstance(data, dict):
24
+ names = [str(k) for k in data.keys()]
25
+ vecs = [np.asarray(v, dtype=float).ravel() for v in data.values()]
26
+ return [v[np.isfinite(v)] for v in vecs], names
27
+ if isinstance(data, pd.DataFrame):
28
+ names = [str(c) for c in data.columns]
29
+ vecs = [data[c].to_numpy(dtype=float).ravel() for c in data.columns]
30
+ return [v[np.isfinite(v)] for v in vecs], names
31
+ if isinstance(data, np.ndarray):
32
+ if data.ndim == 1:
33
+ v = data.astype(float)
34
+ return [v[np.isfinite(v)]], None
35
+ vecs = [data[:, c].astype(float) for c in range(data.shape[1])]
36
+ return [v[np.isfinite(v)] for v in vecs], None
37
+ if isinstance(data, (list, tuple)):
38
+ if data and isinstance(data[0], (list, tuple, np.ndarray, pd.Series)):
39
+ vecs = [np.asarray(v, dtype=float).ravel() for v in data]
40
+ return [v[np.isfinite(v)] for v in vecs], None
41
+ v = np.asarray(data, dtype=float).ravel()
42
+ return [v[np.isfinite(v)]], None
43
+ raise TypeError(f"Unsupported input type for densityHeatmap/frequencyHeatmap: {type(data)}")
44
+
45
+
46
+ def ks_dist(mat: Any, mc_cores: int = 1) -> DistMatrix:
47
+ """Pairwise Kolmogorov-Smirnov distance matrix across columns of `mat` (`ks_dist.Rd`)."""
48
+ vecs, labels = _to_column_series_list(mat)
49
+ n = len(vecs)
50
+ d = np.zeros((n, n), dtype=float)
51
+ for i in range(n):
52
+ for j in range(i + 1, n):
53
+ if len(vecs[i]) == 0 or len(vecs[j]) == 0:
54
+ val = 1.0
55
+ else:
56
+ val = float(ks_2samp(vecs[i], vecs[j]).statistic)
57
+ d[i, j] = d[j, i] = val
58
+ return as_dist(d, labels=labels, method="ks")
59
+
60
+
61
+ def densityHeatmap(
62
+ data: Any,
63
+ col: Sequence[str] | None = None,
64
+ color_space: str = "LAB",
65
+ anno: HeatmapAnnotation | None = None,
66
+ ylab: str = "value",
67
+ title: str | None = None,
68
+ ylim: Sequence[float] | None = None,
69
+ range: Sequence[float] | None = None,
70
+ cluster_columns: Any = False,
71
+ clustering_distance_columns: Any = "ks",
72
+ clustering_method_columns: str = "complete",
73
+ mc_cores: int = 1,
74
+ show_quantiles: bool = True,
75
+ quantile_gp: dict[str, Any] | None = None,
76
+ n_grid: int = 200,
77
+ name: str | None = None,
78
+ **kwargs: Any,
79
+ ) -> Heatmap:
80
+ """Visualize distribution densities across columns or distributions (`densityHeatmap.Rd`)."""
81
+ vecs, col_names = _to_column_series_list(data)
82
+ if not vecs:
83
+ raise ValueError("`data` cannot be empty.")
84
+ n_cols = len(vecs)
85
+
86
+ all_vals = np.concatenate([v for v in vecs if len(v) > 0]) if any(len(v) > 0 for v in vecs) else np.array([0.0, 1.0])
87
+ if ylim is not None:
88
+ ymin, ymax = float(ylim[0]), float(ylim[1])
89
+ elif range is not None:
90
+ ymin, ymax = float(range[0]), float(range[1])
91
+ else:
92
+ ymin, ymax = float(np.min(all_vals)), float(np.max(all_vals))
93
+ if ymin == ymax:
94
+ ymin -= 1.0
95
+ ymax += 1.0
96
+
97
+ y_grid = np.linspace(ymin, ymax, int(n_grid))
98
+ # Reverse top-to-bottom so largest value is at top row 0
99
+ y_desc = y_grid[::-1]
100
+ dens_mat = np.zeros((int(n_grid), n_cols), dtype=float)
101
+ quantiles_mat = np.full((5, n_cols), np.nan, dtype=float) # 0, 25, 50, 75, 100
102
+
103
+ for c_i, v in enumerate(vecs):
104
+ if len(v) < 2 or float(np.std(v)) < 1e-12:
105
+ if len(v) > 0:
106
+ quantiles_mat[:, c_i] = float(v[0])
107
+ nearest = int(np.argmin(np.abs(y_desc - float(v[0]))))
108
+ dens_mat[nearest, c_i] = 1.0
109
+ else:
110
+ quantiles_mat[:, c_i] = np.quantile(v, [0.0, 0.25, 0.50, 0.75, 1.0])
111
+ kde = gaussian_kde(v)
112
+ dens_mat[:, c_i] = kde(y_desc)
113
+
114
+ if col is None:
115
+ cols_pal = brewer_pal(9, "Spectral")[::-1]
116
+ else:
117
+ cols_pal = list(col)
118
+
119
+ dmax = float(np.nanmax(dens_mat))
120
+ if dmax <= 0:
121
+ dmax = 1.0
122
+ col_fun = colorRamp2(np.linspace(0.0, dmax, len(cols_pal)), cols_pal, space=color_space)
123
+
124
+ ht_name = name or f"density_{_ENV.next_heatmap_index()}"
125
+
126
+ # Y-axis range mapping inside body viewport
127
+ eff_distance = ks_dist(data) if clustering_distance_columns == "ks" else clustering_distance_columns
128
+ # Notice if ks distance DF is passed, wrap clustering_distance_columns cleanly via callable returning matrix
129
+ if clustering_distance_columns == "ks" and cluster_columns:
130
+ ks_d = ks_dist(data)
131
+ def _ks_fn(_sub: np.ndarray) -> DistMatrix:
132
+ return ks_d
133
+ eff_distance_arg: Any = _ks_fn
134
+ else:
135
+ eff_distance_arg = eff_distance
136
+
137
+ q_gp = check_gp(gpar(lty="dashed", col="#222222", lwd=1.0) if quantile_gp is None else quantile_gp)
138
+
139
+ def _layer_fun(j: Any, i: Any, x: Any, y: Any, w: Any, h: Any, fill: Any) -> None:
140
+ if not show_quantiles:
141
+ return
142
+ # Order of columns in current slice
143
+ uniq_cols = []
144
+ seen_c: set[int] = set()
145
+ for jj in j:
146
+ ji = int(jj)
147
+ if ji not in seen_c:
148
+ seen_c.add(ji)
149
+ uniq_cols.append(ji)
150
+ m_c = len(uniq_cols)
151
+ if m_c == 0:
152
+ return
153
+ xs_npc = (np.arange(m_c, dtype=float) + 0.5) / m_c
154
+ span = max(1e-12, ymax - ymin)
155
+ q_labels = ["min", "25%", "median", "75%", "max"]
156
+ for qi in _range(5):
157
+ ys_npc = np.array([(quantiles_mat[qi, ci] - ymin) / span for ci in uniq_cols], dtype=float)
158
+ valid = np.isfinite(ys_npc)
159
+ if np.sum(valid) >= 2:
160
+ grid_lines(unit(xs_npc[valid], "npc"), unit(ys_npc[valid], "npc"), gp=q_gp)
161
+ if np.any(valid):
162
+ last_y = float(ys_npc[np.where(valid)[0][-1]])
163
+ grid_text(q_labels[qi], x=unit(1.0, "npc") + unit(1.5, "mm"), y=unit(last_y, "npc"), just="left", gp=gpar(fontsize=8, col=q_gp.get("col", "#222222")))
164
+
165
+ # Add y-axis left gap via empty/left annotation or post_fun
166
+ user_post = kwargs.pop("post_fun", None)
167
+
168
+ def _draw_yaxis_post(ht_list: Any) -> None:
169
+ try:
170
+ with decorate_heatmap_body(ht_name):
171
+ pushViewport(Viewport(xscale=(0.0, 1.0), yscale=(ymin, ymax), clip=False))
172
+ try:
173
+ grid_yaxis()
174
+ grid_text(ylab, x=unit(-11, "mm"), y=unit(0.5, "npc"), rot=90, gp=gpar(fontsize=10))
175
+ finally:
176
+ popViewport()
177
+ except Exception:
178
+ pass
179
+ if user_post is not None:
180
+ user_post(ht_list)
181
+
182
+ df_dens = pd.DataFrame(dens_mat, columns=col_names)
183
+ hm_kwargs: dict[str, Any] = dict(
184
+ col=col_fun,
185
+ name=ht_name,
186
+ column_title=title if title is not None else [],
187
+ top_annotation=anno,
188
+ cluster_rows=False,
189
+ cluster_columns=bool(cluster_columns),
190
+ clustering_distance_columns=eff_distance_arg,
191
+ clustering_method_columns=clustering_method_columns,
192
+ show_row_names=False,
193
+ show_column_names=col_names is not None,
194
+ layer_fun=_layer_fun,
195
+ post_fun=_draw_yaxis_post,
196
+ heatmap_legend_param=kwargs.pop("heatmap_legend_param", {"title": "density"}),
197
+ )
198
+ hm_kwargs.update(kwargs)
199
+ return Heatmap(df_dens, **hm_kwargs)
200
+
201
+
202
+ def frequencyHeatmap(
203
+ data: Any,
204
+ breaks: Any = "Sturges",
205
+ stat: str = "count",
206
+ use_3d: bool = False,
207
+ col: Sequence[str] | None = None,
208
+ ylim: Sequence[float] | None = None,
209
+ title: str | None = None,
210
+ ylab: str = "value",
211
+ cluster_columns: Any = False,
212
+ name: str | None = None,
213
+ **kwargs: Any,
214
+ ) -> Heatmap:
215
+ """Visualize binned frequency/proportion matrix across columns or distributions (`frequencyHeatmap.Rd`)."""
216
+ vecs, col_names = _to_column_series_list(data)
217
+ if not vecs:
218
+ raise ValueError("`data` cannot be empty.")
219
+ all_vals = np.concatenate([v for v in vecs if len(v) > 0])
220
+ if ylim is not None:
221
+ range_vals = (float(ylim[0]), float(ylim[1]))
222
+ else:
223
+ range_vals = (float(np.min(all_vals)), float(np.max(all_vals)))
224
+ if range_vals[0] == range_vals[1]:
225
+ range_vals = (range_vals[0] - 0.5, range_vals[1] + 0.5)
226
+
227
+ breaks_arg = breaks.lower() if isinstance(breaks, str) else breaks
228
+ _, edges = np.histogram(all_vals, bins=breaks_arg, range=range_vals)
229
+ n_bins = len(edges) - 1
230
+ n_cols = len(vecs)
231
+ freq_mat = np.zeros((n_bins, n_cols), dtype=float)
232
+ for c_i, v in enumerate(vecs):
233
+ cnts, _ = np.histogram(v, bins=edges)
234
+ cnts_f = cnts.astype(float)
235
+ if stat == "proportion" and len(v) > 0:
236
+ cnts_f /= float(len(v))
237
+ elif stat == "density" and len(v) > 0:
238
+ cnts_f = cnts_f / (float(len(v)) * np.diff(edges))
239
+ freq_mat[:, c_i] = cnts_f[::-1] # largest bin at top
240
+
241
+ row_labels = [f"[{edges[i]:.3g}, {edges[i+1]:.3g}]" for i in range(n_bins)][::-1]
242
+ if col is None:
243
+ cols_pal = brewer_pal(9, "Spectral")[::-1]
244
+ else:
245
+ cols_pal = list(col)
246
+
247
+ vmax = float(np.nanmax(freq_mat))
248
+ if vmax <= 0:
249
+ vmax = 1.0
250
+ col_fun = colorRamp2(np.linspace(0.0, vmax, len(cols_pal)), cols_pal)
251
+ df_freq = pd.DataFrame(freq_mat, index=row_labels, columns=col_names)
252
+ ht_name = name or f"freq_{_ENV.next_heatmap_index()}"
253
+
254
+ if use_3d:
255
+ from .three_d import Heatmap3D
256
+ return Heatmap3D(
257
+ df_freq,
258
+ col=col_fun,
259
+ name=ht_name,
260
+ column_title=title if title is not None else [],
261
+ cluster_rows=False,
262
+ cluster_columns=cluster_columns,
263
+ heatmap_legend_param=kwargs.pop("heatmap_legend_param", {"title": stat}),
264
+ **kwargs,
265
+ )
266
+
267
+ return Heatmap(
268
+ df_freq,
269
+ col=col_fun,
270
+ name=ht_name,
271
+ column_title=title if title is not None else [],
272
+ cluster_rows=False,
273
+ cluster_columns=cluster_columns,
274
+ heatmap_legend_param=kwargs.pop("heatmap_legend_param", {"title": stat}),
275
+ **kwargs,
276
+ )
@@ -0,0 +1,348 @@
1
+ """Lightweight genomic interval classes (`IRanges`, `GRanges`) and binning helpers."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import Any, Callable, Sequence
6
+
7
+ import numpy as np
8
+ import pandas as pd
9
+
10
+
11
+ _CHROM_SIZES: dict[str, dict[str, int]] = {
12
+ "hg19": {
13
+ "chr1": 249250621, "chr2": 243199373, "chr3": 198022430, "chr4": 191154276,
14
+ "chr5": 180915260, "chr6": 171115067, "chr7": 159138663, "chr8": 146364022,
15
+ "chr9": 141213431, "chr10": 135534747, "chr11": 135006516, "chr12": 133851895,
16
+ "chr13": 115169878, "chr14": 107349540, "chr15": 102531392, "chr16": 90354753,
17
+ "chr17": 81195210, "chr18": 78077248, "chr19": 59128983, "chr20": 63025520,
18
+ "chr21": 48129895, "chr22": 51304566, "chrX": 155270560, "chrY": 59373566,
19
+ },
20
+ "hg38": {
21
+ "chr1": 248956422, "chr2": 242193529, "chr3": 198295559, "chr4": 190214555,
22
+ "chr5": 181538259, "chr6": 170805979, "chr7": 159345973, "chr8": 145138636,
23
+ "chr9": 138394717, "chr10": 133797422, "chr11": 135086622, "chr12": 133275309,
24
+ "chr13": 114364328, "chr14": 107043718, "chr15": 101991189, "chr16": 90338345,
25
+ "chr17": 83257441, "chr18": 80373285, "chr19": 58617616, "chr20": 64444167,
26
+ "chr21": 46709983, "chr22": 50818468, "chrX": 156040895, "chrY": 57227415,
27
+ },
28
+ "mm10": {
29
+ "chr1": 195471971, "chr2": 182113224, "chr3": 160039680, "chr4": 156508116,
30
+ "chr5": 151834684, "chr6": 149736546, "chr7": 145441459, "chr8": 129401213,
31
+ "chr9": 124595110, "chr10": 130694993, "chr11": 122082543, "chr12": 120129022,
32
+ "chr13": 120421639, "chr14": 124902244, "chr15": 104043685, "chr16": 98207768,
33
+ "chr17": 94987271, "chr18": 90702639, "chr19": 61431566, "chrX": 171031299, "chrY": 91744698,
34
+ },
35
+ "mm9": {
36
+ "chr1": 197195432, "chr2": 181748087, "chr3": 159599783, "chr4": 155630120,
37
+ "chr5": 152537259, "chr6": 149517037, "chr7": 152524553, "chr8": 131738871,
38
+ "chr9": 124076172, "chr10": 129993255, "chr11": 121843856, "chr12": 121257530,
39
+ "chr13": 120284312, "chr14": 125194864, "chr15": 103494974, "chr16": 98319150,
40
+ "chr17": 95272651, "chr18": 90772031, "chr19": 61342430, "chrX": 166650296, "chrY": 15902555,
41
+ },
42
+ }
43
+
44
+
45
+ class IRanges:
46
+ """1-based closed integer interval collection analogous to Bioconductor `IRanges`."""
47
+
48
+ def __init__(self, start: Sequence[int], end: Sequence[int] | None = None, width: Sequence[int] | None = None, names: Sequence[str] | None = None) -> None:
49
+ self.start = np.asarray(start, dtype=np.int64)
50
+ if end is not None:
51
+ self.end = np.asarray(end, dtype=np.int64)
52
+ elif width is not None:
53
+ self.end = self.start + np.asarray(width, dtype=np.int64) - 1
54
+ else:
55
+ raise ValueError("Either `end` or `width` must be supplied to `IRanges`.")
56
+ self.names = list(names) if names is not None else None
57
+
58
+ @property
59
+ def width(self) -> np.ndarray:
60
+ return np.maximum(0, self.end - self.start + 1)
61
+
62
+ def __len__(self) -> int:
63
+ return len(self.start)
64
+
65
+ def __repr__(self) -> str:
66
+ return f"IRanges(n={len(self)})"
67
+
68
+
69
+ class GRanges:
70
+ """Genomic interval collection analogous to Bioconductor `GenomicRanges::GRanges`."""
71
+
72
+ def __init__(
73
+ self,
74
+ seqnames: Sequence[str],
75
+ ranges: IRanges | None = None,
76
+ *,
77
+ start: Sequence[int] | None = None,
78
+ end: Sequence[int] | None = None,
79
+ strand: Sequence[str] | str = "*",
80
+ **mcols: Any,
81
+ ) -> None:
82
+ self.seqnames = [str(s) for s in seqnames]
83
+ n = len(self.seqnames)
84
+ if ranges is not None:
85
+ self.ranges = ranges
86
+ elif start is not None and end is not None:
87
+ self.ranges = IRanges(start=start, end=end)
88
+ else:
89
+ raise ValueError("Provide either `ranges=IRanges(...)` or both `start` and `end`.")
90
+ if len(self.ranges) != n:
91
+ raise ValueError("Length of `seqnames` must match `ranges`.")
92
+ self.strand = [strand] * n if isinstance(strand, str) else list(strand)
93
+ self.mcols = pd.DataFrame({k: np.asarray(v) for k, v in mcols.items()}) if mcols else pd.DataFrame(index=range(n))
94
+
95
+ @property
96
+ def start(self) -> np.ndarray:
97
+ return self.ranges.start
98
+
99
+ @property
100
+ def end(self) -> np.ndarray:
101
+ return self.ranges.end
102
+
103
+ @property
104
+ def width(self) -> np.ndarray:
105
+ return self.ranges.width
106
+
107
+ def __len__(self) -> int:
108
+ return len(self.seqnames)
109
+
110
+ def __getitem__(self, idx: Any) -> "GRanges":
111
+ if isinstance(idx, (int, np.integer)):
112
+ sl = [int(idx)]
113
+ elif isinstance(idx, slice):
114
+ sl = list(range(*idx.indices(len(self))))
115
+ else:
116
+ arr_i = np.asarray(idx)
117
+ sl = np.where(arr_i)[0].tolist() if arr_i.dtype == bool else arr_i.tolist()
118
+ new_mcols = self.mcols.iloc[sl].reset_index(drop=True) if len(self.mcols.columns) else pd.DataFrame(index=range(len(sl)))
119
+ return GRanges(
120
+ [self.seqnames[i] for i in sl],
121
+ IRanges(self.start[sl], self.end[sl]),
122
+ strand=[self.strand[i] for i in sl],
123
+ **{c: new_mcols[c].to_numpy() for c in new_mcols.columns},
124
+ )
125
+
126
+ def to_dataframe(self) -> pd.DataFrame:
127
+ df = pd.DataFrame({"seqnames": self.seqnames, "start": self.start, "end": self.end, "strand": self.strand})
128
+ for col in self.mcols.columns:
129
+ df[col] = self.mcols[col].to_numpy()
130
+ return df
131
+
132
+ def __repr__(self) -> str:
133
+ return f"GRanges(n={len(self)}, mcols={list(self.mcols.columns)})"
134
+
135
+
136
+ def findOverlaps(query: GRanges | IRanges, subject: GRanges | IRanges) -> tuple[np.ndarray, np.ndarray]:
137
+ """Find overlapping interval index pairs `(queryHits, subjectHits)`."""
138
+ if isinstance(query, IRanges) and isinstance(subject, IRanges):
139
+ q_idx: list[int] = []
140
+ s_idx: list[int] = []
141
+ order_s = np.argsort(subject.start)
142
+ s_start = subject.start[order_s]
143
+ s_end = subject.end[order_s]
144
+ for qi in range(len(query)):
145
+ qs, qe = int(query.start[qi]), int(query.end[qi])
146
+ hi = int(np.searchsorted(s_start, qe, side="right"))
147
+ for pos in range(hi):
148
+ if s_end[pos] >= qs:
149
+ q_idx.append(qi)
150
+ s_idx.append(int(order_s[pos]))
151
+ return np.asarray(q_idx, dtype=int), np.asarray(s_idx, dtype=int)
152
+
153
+ if isinstance(query, GRanges) and isinstance(subject, GRanges):
154
+ q_idx = []
155
+ s_idx = []
156
+ by_chr: dict[str, list[int]] = {}
157
+ for si, ch in enumerate(subject.seqnames):
158
+ by_chr.setdefault(ch, []).append(si)
159
+ for ch, q_list in _group_by_chr(query.seqnames).items():
160
+ if ch not in by_chr:
161
+ continue
162
+ s_list = np.asarray(by_chr[ch], dtype=int)
163
+ sub_s = subject.start[s_list]
164
+ sub_e = subject.end[s_list]
165
+ ord_s = np.argsort(sub_s)
166
+ sub_s = sub_s[ord_s]
167
+ sub_e = sub_e[ord_s]
168
+ s_orig = s_list[ord_s]
169
+ for qi in q_list:
170
+ qs, qe = int(query.start[qi]), int(query.end[qi])
171
+ hi = int(np.searchsorted(sub_s, qe, side="right"))
172
+ for pos in range(hi):
173
+ if sub_e[pos] >= qs:
174
+ q_idx.append(qi)
175
+ s_idx.append(int(s_orig[pos]))
176
+ return np.asarray(q_idx, dtype=int), np.asarray(s_idx, dtype=int)
177
+
178
+ raise TypeError("`query` and `subject` must both be GRanges or both be IRanges.")
179
+
180
+
181
+ def _group_by_chr(seqnames: Sequence[str]) -> dict[str, list[int]]:
182
+ out: dict[str, list[int]] = {}
183
+ for i, ch in enumerate(seqnames):
184
+ out.setdefault(ch, []).append(i)
185
+ return out
186
+
187
+
188
+ def generateRandomBed(
189
+ nr: int = 10000,
190
+ nc: int = 10,
191
+ fun: Callable[[int], np.ndarray] | None = None,
192
+ species: str = "hg19",
193
+ seed: int | None = None,
194
+ ) -> pd.DataFrame:
195
+ """Generate random genomic intervals with random numeric value columns (`generateRandomBed`)."""
196
+ rng = np.random.default_rng(seed)
197
+ chrom_sizes = _CHROM_SIZES.get(species, _CHROM_SIZES["hg19"])
198
+ chrs = list(chrom_sizes.keys())
199
+ lengths = np.array([chrom_sizes[c] for c in chrs], dtype=float)
200
+ probs = lengths / np.sum(lengths)
201
+ chosen = rng.choice(len(chrs), size=nr, p=probs)
202
+ seqnames = [chrs[i] for i in chosen]
203
+ starts = np.array([int(rng.integers(1, max(2, chrom_sizes[c] - 1000))) for c in seqnames], dtype=np.int64)
204
+ widths = rng.integers(100, 10000, size=nr, dtype=np.int64)
205
+ ends = np.minimum(starts + widths, np.array([chrom_sizes[c] for c in seqnames], dtype=np.int64))
206
+ df = pd.DataFrame({"chr": seqnames, "start": starts, "end": ends})
207
+ if fun is None:
208
+ fun = lambda k: rng.standard_normal(k)
209
+ for ci in range(nc):
210
+ df[f"value{ci + 1}"] = fun(nr)
211
+ return df
212
+
213
+
214
+ def bin_genome(
215
+ species: str = "hg19",
216
+ bin_size: int = 1_000_000,
217
+ bins: int | None = None,
218
+ chromosomes: Sequence[str] | None = None,
219
+ chr_len: dict[str, int] | None = None,
220
+ ) -> GRanges:
221
+ """Partition a reference genome into fixed-size chromosome bins (`bin_genome.Rd`)."""
222
+ if chr_len is not None:
223
+ sizes = dict(chr_len)
224
+ elif species in _CHROM_SIZES:
225
+ sizes = dict(_CHROM_SIZES[species])
226
+ else:
227
+ raise KeyError(f"Unknown species {species!r}; supported: {list(_CHROM_SIZES.keys())} or pass `chr_len`.")
228
+
229
+ if chromosomes is not None:
230
+ sizes = {k: sizes[k] for k in chromosomes if k in sizes}
231
+
232
+ seq_out: list[str] = []
233
+ st_out: list[int] = []
234
+ en_out: list[int] = []
235
+
236
+ if bins is not None:
237
+ tot_len = sum(sizes.values())
238
+ eff_bin_size = max(1, int(tot_len // max(1, int(bins))))
239
+ else:
240
+ eff_bin_size = max(1, int(bin_size))
241
+
242
+ for ch, clen in sizes.items():
243
+ pos = 1
244
+ while pos <= clen:
245
+ en = min(clen, pos + eff_bin_size - 1)
246
+ seq_out.append(ch)
247
+ st_out.append(pos)
248
+ en_out.append(en)
249
+ pos = en + 1
250
+
251
+ return GRanges(seq_out, IRanges(st_out, en_out))
252
+
253
+
254
+ def normalize_genomic_signals_to_bins(
255
+ gr: GRanges | pd.DataFrame,
256
+ value_column: str | Sequence[str] | Sequence[int] | None = None,
257
+ method: str = "weighted",
258
+ empty_value: float = np.nan,
259
+ bins: GRanges | None = None,
260
+ species: str = "hg19",
261
+ bin_size: int = 1_000_000,
262
+ ) -> tuple[GRanges, np.ndarray] | GRanges:
263
+ """Summarize genomic signals over uniform genomic bins (`normalize_genomic_signals_to_bins.Rd`)."""
264
+ method = str(method).lower()
265
+ if method not in ("weighted", "w0", "absolute", "number"):
266
+ raise ValueError("`method` must be 'weighted', 'w0', 'absolute', or 'number'.")
267
+
268
+ if isinstance(gr, pd.DataFrame):
269
+ cols = list(gr.columns)
270
+ ch_col = cols[0]
271
+ st_col = cols[1]
272
+ en_col = cols[2]
273
+ mcols = {c: gr[c].to_numpy() for c in cols[3:]}
274
+ gr_obj = GRanges(gr[ch_col].tolist(), IRanges(gr[st_col].to_numpy(), gr[en_col].to_numpy()), **mcols)
275
+ else:
276
+ gr_obj = gr
277
+
278
+ target_bins = bins if bins is not None else bin_genome(species=species, bin_size=bin_size)
279
+
280
+ if value_column is None:
281
+ val_cols = list(gr_obj.mcols.columns)
282
+ elif isinstance(value_column, str):
283
+ val_cols = [value_column]
284
+ elif isinstance(value_column, (list, tuple)):
285
+ if val_is_int := (value_column and isinstance(value_column[0], (int, np.integer))):
286
+ val_cols = [list(gr_obj.mcols.columns)[int(i)] for i in value_column]
287
+ else:
288
+ val_cols = [str(v) for v in value_column]
289
+ else:
290
+ val_cols = [list(gr_obj.mcols.columns)[int(value_column)]]
291
+
292
+ n_bins = len(target_bins)
293
+ n_vals = max(1, len(val_cols))
294
+ out_mat = np.full((n_bins, n_vals), float(empty_value), dtype=float)
295
+
296
+ qh, sh = findOverlaps(target_bins, gr_obj)
297
+ if len(qh) > 0:
298
+ ov_start = np.maximum(target_bins.start[qh], gr_obj.start[sh])
299
+ ov_end = np.minimum(target_bins.end[qh], gr_obj.end[sh])
300
+ ov_w = np.maximum(0, ov_end - ov_start + 1).astype(float)
301
+ bin_w = target_bins.width.astype(float)
302
+
303
+ if not val_cols:
304
+ # Count or fraction covered
305
+ for b in np.unique(qh):
306
+ mask = qh == b
307
+ if method == "number":
308
+ out_mat[b, 0] = float(np.sum(mask))
309
+ else:
310
+ out_mat[b, 0] = float(np.sum(ov_w[mask])) / bin_w[b]
311
+ else:
312
+ val_arr = gr_obj.mcols[val_cols].to_numpy(dtype=float)
313
+ # Group by bin id
314
+ order_b = np.argsort(qh)
315
+ qh_s = qh[order_b]
316
+ sh_s = sh[order_b]
317
+ ow_s = ov_w[order_b]
318
+ uniq_b, starts_b = np.unique(qh_s, return_index=True)
319
+ ends_b = np.append(starts_b[1:], len(qh_s))
320
+ for idx_u, b in enumerate(uniq_b):
321
+ s0, s1 = int(starts_b[idx_u]), int(ends_b[idx_u])
322
+ s_hits = sh_s[s0:s1]
323
+ w_hits = ow_s[s0:s1]
324
+ vals_b = val_arr[s_hits, :]
325
+ if method == "number":
326
+ out_mat[b, :] = float(len(s_hits))
327
+ elif method == "absolute":
328
+ out_mat[b, :] = np.nanmean(vals_b, axis=0)
329
+ elif method == "w0":
330
+ out_mat[b, :] = np.nansum(vals_b * w_hits[:, None], axis=0) / bin_w[b]
331
+ else: # weighted
332
+ tot_w = float(np.sum(w_hits))
333
+ if tot_w > 0:
334
+ out_mat[b, :] = np.nansum(vals_b * w_hits[:, None], axis=0) / tot_w
335
+
336
+ res_df = target_bins.to_dataframe()
337
+ if val_cols:
338
+ for ci, cn in enumerate(val_cols):
339
+ res_df[cn] = out_mat[:, ci]
340
+ else:
341
+ res_df["value"] = out_mat[:, 0]
342
+ res_gr = GRanges(
343
+ res_df["seqnames"].tolist(),
344
+ IRanges(res_df["start"].to_numpy(), res_df["end"].to_numpy()),
345
+ strand=res_df["strand"].tolist(),
346
+ **{c: res_df[c].to_numpy() for c in res_df.columns[4:]},
347
+ )
348
+ return res_gr