clone2vec 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.
clone2vec/tools.py ADDED
@@ -0,0 +1,633 @@
1
+ from __future__ import annotations
2
+
3
+ import scanpy as sc
4
+ import numpy as np
5
+ import pandas as pd
6
+ import scipy.sparse as sp
7
+
8
+ import sys
9
+ from contextlib import nullcontext
10
+ from typing import Any, Literal
11
+ from tqdm import tqdm
12
+ from .embeddings import (
13
+ clone2vec, clone2vec_Poi, project_clone2vec, project_clone2vec_Poi
14
+ )
15
+ from .integration import find_mnn, align
16
+ from .associations import associations, graph_associations
17
+ from .eigenvalues import eigenvalue_test
18
+ from .catboost import catboost
19
+
20
+ logg = sc.logging
21
+
22
+ __all__ = [
23
+ "clonal_nn",
24
+ "smooth",
25
+ "clone2vec",
26
+ "clone2vec_Poi",
27
+ "project_clone2vec",
28
+ "project_clone2vec_Poi",
29
+ "find_mnn",
30
+ "align",
31
+ "associations",
32
+ "group_connectivity",
33
+ "clonocluster",
34
+ "graph_associations",
35
+ "eigenvalue_test",
36
+ "catboost",
37
+ ]
38
+
39
+ def __dir__():
40
+ return sorted(__all__)
41
+
42
+
43
+ def clonal_nn(
44
+ adata: sc.AnnData,
45
+ clones: sc.AnnData,
46
+ obs_name: str | None = None,
47
+ k: int = 15,
48
+ use_rep: str = "X_pca",
49
+ obsp_name: str = "gex_adjacency",
50
+ adata_ref: sc.AnnData | None = None,
51
+ clones_ref: sc.AnnData | None = None,
52
+ nn_transfer_name: str = "ref_gex_adjacency",
53
+ random_state: None | int = 4,
54
+ split_by: str | None = None,
55
+ progress_bar: bool = False,
56
+ mask_obs: list[np.ndarray | pd.Series] | np.ndarray | pd.Series | None = None,
57
+ **kwargs,
58
+ ) -> None:
59
+ """
60
+ Computes and adds a clone-to-clone adjacency graph to a clones object.
61
+
62
+ The graph is built by finding nearest neighbors in a given representation (e.g., PCA)
63
+ and aggregating these relationships at the clone level.
64
+
65
+ Parameters
66
+ ----------
67
+ adata : AnnData
68
+ The original, cell-level annotated data matrix.
69
+ clones : AnnData
70
+ The clone-level AnnData object, typically from `create_clone_adata`.
71
+ obs_name : str | None, optional
72
+ Column in `adata.obs` containing clonal information. If None, use `clones.uns["obs_name"]`,
73
+ by default None.
74
+ k : int, optional
75
+ Number of nearest neighbors to retrieve for each cell, by default 15.
76
+ use_rep : str, optional
77
+ Representation in `adata.obsm` to build the kNN graph, by default "X_pca".
78
+ obsp_name : str, optional
79
+ Name of the new graph slot in `clones.obsp`, by default "gex_adjacency".
80
+ adata_ref : sc.AnnData | None, optional
81
+ Reference cell-level annotated data matrix for transfer, by default None.
82
+ clones_ref : sc.AnnData | None, optional
83
+ Reference clone-level AnnData object for transfer, by default None.
84
+ nn_transfer_name : str, optional
85
+ Name of the new graph slot in `clones_ref.obsp` for transfer, by default "ref_gex_adjacency".
86
+ random_state : None | int, optional
87
+ Random state for reproducibility, by default 4.
88
+ split_by : str | None, optional
89
+ Column in `clones.obs` to split the independent kNN-graph constriction, by default None.
90
+ progress_bar : bool, optional
91
+ Whether to display a progress bar in the case of split_by, by default False.
92
+ **kwargs : dict, optional
93
+ Additional keyword arguments to pass to `pynndescent.NNDescent`.
94
+
95
+ Returns
96
+ -------
97
+ None
98
+ Updates `clones` in-place with the computed adjacency graph in `.obsp[obsp_name]`.
99
+ """
100
+ start = logg.info("computing clone-to-clone adjacency graph")
101
+ import pynndescent
102
+
103
+ if obs_name is None:
104
+ try:
105
+ obs_name = clones.uns["obs_name"]
106
+ except KeyError:
107
+ raise KeyError("obs_name not found in clones.uns. Please provide obs_name.")
108
+ try:
109
+ train_adata = adata[adata.obs[obs_name].isin(clones.obs_names)]
110
+ except KeyError:
111
+ raise KeyError(f"obs_name '{obs_name}' not found in adata.obs. Please provide a valid obs_name.")
112
+
113
+ if use_rep not in train_adata.obsm:
114
+ raise KeyError(f"Representation '{use_rep}' not found in adata.obsm.")
115
+
116
+ # Explicit mapping from clone labels to indices to avoid out-of-range codes
117
+ n_clones = len(clones.obs_names)
118
+ label_to_idx = pd.Series(np.arange(n_clones, dtype=np.int32), index=pd.Index(clones.obs_names))
119
+
120
+ train_labels_encoded = label_to_idx.loc[train_adata.obs[obs_name]].to_numpy()
121
+
122
+ n_train_cells = train_adata.n_obs
123
+
124
+ if mask_obs is None:
125
+ mask_series_list: list[pd.Series] = []
126
+ mask_names: list[str] = []
127
+ else:
128
+ if isinstance(mask_obs, (np.ndarray, pd.Series)):
129
+ mask_obs = [mask_obs]
130
+ mask_series_list = []
131
+ mask_names = []
132
+ for i, m in enumerate(mask_obs):
133
+ if isinstance(m, pd.Series):
134
+ if m.index.is_unique and m.index.equals(adata.obs_names):
135
+ s = m.astype(bool)
136
+ else:
137
+ s = pd.Series(np.asarray(m).astype(bool), index=adata.obs_names)
138
+ else:
139
+ arr = np.asarray(m).astype(bool)
140
+ if arr.shape[0] != adata.n_obs:
141
+ raise ValueError("mask_obs must have length equal to adata.n_obs")
142
+ s = pd.Series(arr, index=adata.obs_names)
143
+ name = s.name if s.name is not None else f"mask_{i+1}"
144
+ mask_series_list.append(s)
145
+ mask_names.append(name)
146
+ mask_union_train = np.logical_or.reduce([ms.loc[train_adata.obs_names].to_numpy() for ms in mask_series_list]) if len(mask_series_list) > 0 else np.zeros(n_train_cells, dtype=bool)
147
+ masks_train_list = [ms.loc[train_adata.obs_names].to_numpy() for ms in mask_series_list]
148
+ if mask_obs is None:
149
+ mask_union_train = np.zeros(n_train_cells, dtype=bool)
150
+ masks_train_list = []
151
+ masked_sum_cols = None
152
+
153
+ if adata_ref is not None and clones_ref is not None:
154
+ if split_by is not None:
155
+ raise ValueError("split_by is not supported when using clones_ref.")
156
+ if use_rep not in adata_ref.obsm:
157
+ raise KeyError(f"Representation '{use_rep}' not found in adata_ref.obsm.")
158
+
159
+ index = pynndescent.NNDescent(adata_ref.obsm[use_rep], random_state=random_state, **kwargs)
160
+ neighbors_indices, _ = index.query(train_adata.obsm[use_rep], k=k)
161
+
162
+ ref_label_to_idx = pd.Series(np.arange(len(clones_ref.obs_names), dtype=np.int32), index=pd.Index(clones_ref.obs_names))
163
+ ref_labels = adata_ref.obs[obs_name].values
164
+ ref_neighbor_labels = ref_labels[neighbors_indices]
165
+ ref_neighbor_flat = pd.Series(ref_neighbor_labels.ravel()).map(ref_label_to_idx).fillna(-1).astype(np.int32).to_numpy()
166
+
167
+ row_idx = np.repeat(np.arange(n_train_cells, dtype=np.int32), k)
168
+ col_idx = ref_neighbor_flat
169
+ valid_mask = (col_idx >= 0) & (col_idx < len(clones_ref.obs_names))
170
+
171
+ nonmasked_edges = valid_mask & (~mask_union_train[row_idx])
172
+ B_sparse = sp.csr_matrix(
173
+ (np.ones(nonmasked_edges.sum(), dtype=np.int32), (row_idx[nonmasked_edges], col_idx[nonmasked_edges])),
174
+ shape=(n_train_cells, len(clones_ref.obs_names))
175
+ )
176
+
177
+ I_sparse = sp.csr_matrix(
178
+ (np.ones(n_train_cells, dtype=np.int32),
179
+ (train_labels_encoded.astype(np.int32), np.arange(n_train_cells, dtype=np.int32))),
180
+ shape=(n_clones, n_train_cells)
181
+ )
182
+
183
+ nn_transfer = I_sparse @ B_sparse
184
+
185
+ if nn_transfer_name in clones.obsm:
186
+ logg.warning(f"Overwriting existing matrix '{nn_transfer_name}' in clones.obsm")
187
+
188
+ clones.obsm[nn_transfer_name] = nn_transfer
189
+ if len(masks_train_list) > 0:
190
+ masked_cols = []
191
+ for m in masks_train_list:
192
+ masked_edges_m = valid_mask & (m[row_idx])
193
+ B_masked_m = sp.csr_matrix(
194
+ (np.ones(masked_edges_m.sum(), dtype=np.int32), (row_idx[masked_edges_m], col_idx[masked_edges_m])),
195
+ shape=(n_train_cells, len(clones_ref.obs_names))
196
+ )
197
+ masked_adj_m = I_sparse @ B_masked_m
198
+ counts_m = np.asarray(masked_adj_m.sum(axis=1)).ravel()
199
+ masked_cols.append(counts_m)
200
+ masked_nn = np.column_stack(masked_cols)
201
+ clones.obsm["masked_nn"] = np.asarray(masked_nn)
202
+ clones.uns["clonal_nn"] = {
203
+ "k": k, "use_rep": use_rep, "obsm_name": nn_transfer_name,
204
+ }
205
+ if mask_series_list:
206
+ clones.uns["clonal_nn"]["mask"] = {n: ms.loc[adata.obs_names].to_numpy() for n, ms in zip(mask_names, mask_series_list)}
207
+ lines = [
208
+ "added",
209
+ f" .obsm['{nn_transfer_name}'] clone-to-reference adjacency.",
210
+ (" .obsm['masked_nn'] masked neighbour counts." if len(mask_series_list) > 0 else None),
211
+ " .uns['clonal_nn'] parameters.",
212
+ ]
213
+ logg.info(" finished ({time_passed})", deep="\n".join([l for l in lines if l is not None]), time=start)
214
+ else:
215
+ if split_by is None:
216
+ index = pynndescent.NNDescent(train_adata.obsm[use_rep], random_state=random_state, **kwargs)
217
+ neighbors_indices, _ = index.query(train_adata.obsm[use_rep], k=k)
218
+
219
+ neighbor_labels_encoded = train_labels_encoded[neighbors_indices]
220
+
221
+ row_idx = np.repeat(np.arange(n_train_cells, dtype=np.int32), k)
222
+ col_idx = neighbor_labels_encoded.flatten().astype(np.int32)
223
+ valid_mask = (col_idx >= 0) & (col_idx < n_clones)
224
+
225
+ nonmasked_edges = valid_mask & (~mask_union_train[row_idx])
226
+ B_sparse = sp.csr_matrix(
227
+ (np.ones(nonmasked_edges.sum(), dtype=np.int32), (row_idx[nonmasked_edges], col_idx[nonmasked_edges])),
228
+ shape=(n_train_cells, n_clones)
229
+ )
230
+
231
+ I_sparse = sp.csr_matrix(
232
+ (np.ones(n_train_cells, dtype=np.int32),
233
+ (train_labels_encoded.astype(np.int32), np.arange(n_train_cells, dtype=np.int32))),
234
+ shape=(n_clones, n_train_cells)
235
+ )
236
+
237
+ gex_adjacency = I_sparse @ B_sparse
238
+ if len(masks_train_list) > 0:
239
+ masked_cols = []
240
+ for m in masks_train_list:
241
+ masked_edges_m = valid_mask & (m[row_idx])
242
+ B_masked_m = sp.csr_matrix(
243
+ (np.ones(masked_edges_m.sum(), dtype=np.int32), (row_idx[masked_edges_m], col_idx[masked_edges_m])),
244
+ shape=(n_train_cells, n_clones)
245
+ )
246
+ masked_adj_m = I_sparse @ B_masked_m
247
+ counts_m = np.asarray(masked_adj_m.sum(axis=1)).ravel()
248
+ masked_cols.append(counts_m)
249
+ masked_nn = np.column_stack(masked_cols)
250
+ clones.obsm["masked_nn"] = np.asarray(masked_nn)
251
+ else:
252
+ if split_by not in train_adata.obs:
253
+ raise KeyError(f"Column '{split_by}' not found in adata.obs.")
254
+
255
+ train_index_map = pd.Series(np.arange(n_train_cells, dtype=np.int32), index=train_adata.obs_names)
256
+ I_sparse = sp.csr_matrix(
257
+ (np.ones(n_train_cells, dtype=np.int32),
258
+ (train_labels_encoded.astype(np.int32), np.arange(n_train_cells, dtype=np.int32))),
259
+ shape=(n_clones, n_train_cells)
260
+ )
261
+
262
+ gex_adjacency = sp.csr_matrix((n_clones, n_clones), dtype=np.int32)
263
+ masked_sum_cols = None
264
+
265
+ categories = pd.unique(train_adata.obs[split_by])
266
+ categories = [c for c in categories if pd.notna(c)]
267
+
268
+ if sc.settings.verbosity.value >= 2:
269
+ prefix = " "
270
+ progress_bar = True
271
+ else:
272
+ prefix = ""
273
+
274
+ cm = tqdm(
275
+ categories,
276
+ desc=prefix + f"split-by '{split_by}'",
277
+ file=sys.stdout,
278
+ ) if progress_bar else nullcontext(categories)
279
+ with cm as iterator:
280
+ for cat in iterator:
281
+ subset = train_adata[train_adata.obs[split_by] == cat]
282
+ n_subset = subset.n_obs
283
+ if n_subset == 0:
284
+ continue
285
+ k_subset = int(min(k, n_subset))
286
+ index = pynndescent.NNDescent(subset.obsm[use_rep], random_state=random_state, **kwargs)
287
+ neighbors_indices, _ = index.query(subset.obsm[use_rep], k=k_subset)
288
+
289
+ subset_rows = train_index_map.loc[subset.obs_names].to_numpy()
290
+ subset_labels_encoded = train_labels_encoded[subset_rows]
291
+ neighbor_labels_encoded = subset_labels_encoded[neighbors_indices]
292
+
293
+ row_idx = np.repeat(subset_rows.astype(np.int32), k_subset)
294
+ col_idx = neighbor_labels_encoded.flatten().astype(np.int32)
295
+ valid_mask = (col_idx >= 0) & (col_idx < n_clones)
296
+
297
+ nonmasked_edges = valid_mask & (~mask_union_train[row_idx])
298
+ B_sparse = sp.csr_matrix(
299
+ (np.ones(nonmasked_edges.sum(), dtype=np.int32), (row_idx[nonmasked_edges], col_idx[nonmasked_edges])),
300
+ shape=(n_train_cells, n_clones)
301
+ )
302
+
303
+ gex_adjacency += I_sparse @ B_sparse
304
+ if len(masks_train_list) > 0:
305
+ cols_this = []
306
+ for m in masks_train_list:
307
+ masked_edges_m = valid_mask & (m[row_idx])
308
+ B_masked_m = sp.csr_matrix(
309
+ (np.ones(masked_edges_m.sum(), dtype=np.int32), (row_idx[masked_edges_m], col_idx[masked_edges_m])),
310
+ shape=(n_train_cells, n_clones)
311
+ )
312
+ masked_adj_m = I_sparse @ B_masked_m
313
+ counts_m = np.asarray(masked_adj_m.sum(axis=1)).ravel()
314
+ cols_this.append(counts_m)
315
+ if masked_sum_cols is None:
316
+ masked_sum_cols = np.column_stack(cols_this)
317
+ else:
318
+ masked_sum_cols += np.column_stack(cols_this)
319
+
320
+ if obsp_name in clones.obsp:
321
+ logg.warning(f"Overwriting existing graph '{obsp_name}' in clones.obsp")
322
+
323
+ clones.obsp[obsp_name] = gex_adjacency
324
+ clones.uns["clonal_nn"] = {
325
+ "k": k, "use_rep": use_rep, "obsp_name": obsp_name, "split_by": split_by,
326
+ }
327
+ if mask_series_list:
328
+ clones.uns["clonal_nn"]["mask"] = {n: ms.loc[adata.obs_names].to_numpy() for n, ms in zip(mask_names, mask_series_list)}
329
+ if masked_sum_cols is None and len(masks_train_list) > 0 and split_by is None:
330
+ masked_sum_cols = clones.obsm.get("masked_nn", None)
331
+ if isinstance(masked_sum_cols, pd.DataFrame):
332
+ masked_sum_cols = masked_sum_cols.to_numpy()
333
+ if masked_sum_cols is not None:
334
+ clones.obsm["masked_nn"] = np.asarray(masked_sum_cols)
335
+ lines = [
336
+ "added",
337
+ f" .obsp['{obsp_name}'] clone adjacency graph.",
338
+ (" .obsm['masked_nn'] masked neighbour counts." if len(mask_series_list) > 0 else None),
339
+ " .uns['clonal_nn'] parameters.",
340
+ ]
341
+ logg.info(" finished ({time_passed})", deep="\n".join([l for l in lines if l is not None]), time=start)
342
+
343
+ def smooth(
344
+ adata: sc.AnnData,
345
+ field: Literal["X", "layer", "obs", "obsm"] = "X",
346
+ names: str | list[str] | None = None,
347
+ key_added: str = "smoothed",
348
+ graph_key: str = "connectivities",
349
+ progress_bar: bool = False,
350
+ n_steps: int = 3,
351
+ ) -> None:
352
+ """
353
+ Performing kNN smoothing on `adata.X`, `adata.layers[layer]`, `adata.obs[name]`, or `adata.obsm[name]` for `n_steps` iterations using
354
+ `adata.obsp[graph_key]`.
355
+
356
+ Parameters
357
+ ----------
358
+ adata : AnnData
359
+ Annotated data matrix at the clone level.
360
+ field : Literal["X", "layer", "obs", "obsm"], optional
361
+ Field to smooth, by default "X".
362
+ names : str | list[str] | None, optional
363
+ Key(s) in `adata.layers`, `adata.obs`, or `adata.obsm` containing field to smooth, by default None.
364
+ key_added : str, optional
365
+ Key for `adata.layers`, `adata.obs`, or `adata.obsm` to store smoothed field.
366
+ graph_key : str, optional
367
+ Key in `adata.obsp` containing kNN graph, by default "connectivities".
368
+ progress_bar : bool, optional
369
+ Whether to display a progress bar, by default False.
370
+ n_steps : int, optional
371
+ Number of smoothing iterations, by default 3.
372
+
373
+ Returns
374
+ -------
375
+ None
376
+ Smoothed field is stored in `adata.layers["X_" + key_added]`, `adata.layers[name + "_" + key_added]`,
377
+ `adata.obs[name + "_" + key_added]`, or `adata.obsm[name + "_" + key_added]`.
378
+ """
379
+ start = logg.info("smoothing fields using kNN graph")
380
+
381
+ try:
382
+ A = (adata.obsp[graph_key] > 0).astype(float)
383
+ except KeyError:
384
+ raise KeyError(f"Key {graph_key} not found in adata.obsp.")
385
+
386
+ A.setdiag(1.0)
387
+ row_sums = np.array(A.sum(axis=1)).flatten()
388
+ row_normalized = sp.diags(1.0 / row_sums) @ A
389
+
390
+ Xs = []
391
+ if field == "X":
392
+ Xs.append(adata.X.copy())
393
+ names = ["X"]
394
+ elif field == "layer":
395
+ if names is None:
396
+ raise ValueError("Layer name must be provided when field is 'layer'.")
397
+ if isinstance(names, str):
398
+ names = [names]
399
+ for name in names:
400
+ if name not in adata.layers:
401
+ logg.warning(f"Layer '{name}' not found in adata.layers. Skipping.")
402
+ names.remove(name)
403
+ else:
404
+ Xs.append(adata.layers[name].copy())
405
+ elif field == "obs":
406
+ if names is None:
407
+ raise ValueError("Observation key must be provided when field is 'obs'.")
408
+ if isinstance(names, str):
409
+ names = [names]
410
+ for name in names:
411
+ if name not in adata.obs:
412
+ logg.warning(f"Observation key '{name}' not found in adata.obs. Skipping.")
413
+ names.remove(name)
414
+ else:
415
+ Xs.append(adata.obs[name].values.reshape(-1, 1).copy())
416
+ elif field == "obsm":
417
+ if names is None:
418
+ raise ValueError("Observation matrix key must be provided when field is 'obsm'.")
419
+ if isinstance(names, str):
420
+ names = [names]
421
+ for name in names:
422
+ if name not in adata.obsm:
423
+ logg.warning(f"Observation matrix key '{name}' not found in adata.obsm. Skipping.")
424
+ names.remove(name)
425
+ else:
426
+ Xs.append(adata.obsm[name].copy())
427
+
428
+ if len(Xs) == 0:
429
+ raise ValueError("No valid data to smooth. Check your input.")
430
+
431
+ if sc.settings.verbosity.value >= 2:
432
+ prefix = " "
433
+ else:
434
+ prefix = ""
435
+ for X, name in zip(Xs, names):
436
+ cm = tqdm(
437
+ range(n_steps),
438
+ desc=prefix + f"smoothing '{name}'",
439
+ file=sys.stdout,
440
+ ) if progress_bar else nullcontext(range(n_steps))
441
+ with cm as iterator:
442
+ for _ in iterator:
443
+ X = row_normalized @ X
444
+ if field == "X":
445
+ adata.layers[f"X_{key_added}"] = X
446
+ elif field == "layer":
447
+ adata.layers[f"{name}_{key_added}"] = X
448
+ elif field == "obs":
449
+ adata.obs[f"{name}_{key_added}"] = X.flatten()
450
+ elif field == "obsm":
451
+ if isinstance(adata.obsm[name], pd.DataFrame):
452
+ adata.obsm[f"{name}_{key_added}"] = pd.DataFrame(
453
+ X,
454
+ index=adata.obs_names,
455
+ columns=adata.obsm[name].columns,
456
+ )
457
+ else:
458
+ adata.obsm[f"{name}_{key_added}"] = X
459
+
460
+ lines = ["added"]
461
+ if field == "X":
462
+ lines.append(f" .layers['X_{key_added}'] smoothed matrix.")
463
+ elif field == "layer":
464
+ for name in names:
465
+ lines.append(f" .layers['{name}_{key_added}'] smoothed matrix.")
466
+ elif field == "obs":
467
+ for name in names:
468
+ lines.append(f" .obs['{name}_{key_added}'] smoothed values.")
469
+ elif field == "obsm":
470
+ for name in names:
471
+ lines.append(f" .obsm['{name}_{key_added}'] smoothed matrix.")
472
+ logg.info(" finished ({time_passed})", deep="\n".join(lines), time=start)
473
+
474
+ def clonocluster(
475
+ adata: sc.AnnData,
476
+ alpha: float = 0.2,
477
+ beta: float = 0.1,
478
+ key_added: str = "clonocluster",
479
+ graph_key: str | None = None,
480
+ lineage_graph: str = "connected",
481
+ ):
482
+ """
483
+ Performing ClonoCluster [PMID: 36819662] algorithm for lineage-informed gene expression clustering.
484
+
485
+ Parameters
486
+ ----------
487
+ adata : sc.AnnData
488
+ Annotated data matrix.
489
+ alpha : float, optional
490
+ Parameter for clonocluster algorithm, should be between 0 and 1. 0 means no inclusion of lineage information,
491
+ 1 means that only lineage information is used. Default is 0.2.
492
+ beta : float, optional
493
+ Parameter for clonocluster algorithm, should be between 0 and 1. Default is 0.1.
494
+ key_added : str, optional
495
+ Key in obsp to store clonocluster connectivities. Default is "ClonoCluster".
496
+ graph_key : str | None, optional
497
+ Key in uns to store graph. If None, looks for "neighbors". Default is None.
498
+ lineage_graph : str, optional
499
+ Key in obsp to store lineage graph. Default is "connected".
500
+ """
501
+ if not 0 <= beta <= 1:
502
+ raise ValueError("beta must be between 0 and 1")
503
+ if not 0 <= beta <= 1:
504
+ raise ValueError("alpha must be between 0 and 1")
505
+
506
+ if graph_key is None:
507
+ graph_key = "neighbors"
508
+
509
+ connectivities_key = adata.uns[graph_key]["connectivities_key"]
510
+ connectivities = adata.obsp[connectivities_key]
511
+ use_rep = adata.uns[graph_key]["params"]["use_rep"]
512
+
513
+ line_before = f" using obsp['{lineage_graph}'] and obsp['{connectivities_key}']"
514
+ start = logg.info("computing clonocluster connectivities", deep="\n" + line_before)
515
+
516
+ adata.obsp[f"{key_added}_connectivities"] = (
517
+ alpha ** beta * (adata.obsp[lineage_graph] - connectivities) +
518
+ connectivities
519
+ )
520
+
521
+ adata.uns[key_added] = {
522
+ "connectivities_key": f"{key_added}_connectivities",
523
+ "distances_key": None,
524
+ "params": {
525
+ "method": "umap",
526
+ "metric": "custom",
527
+ "n_neighbors": None,
528
+ "random_state": 0,
529
+ "use_rep": use_rep,
530
+ },
531
+ }
532
+
533
+ lines = [
534
+ "added",
535
+ f" .obsp['{key_added}_connectivities'] clonocluster connectivities",
536
+ f" .uns['{key_added}'] with graph information",
537
+ ]
538
+ logg.info(" finished ({time_passed})", deep="\n".join(lines), time=start)
539
+
540
+ def group_connectivity(
541
+ adata: sc.AnnData,
542
+ groupby: str,
543
+ graph_key: str = "connectivities",
544
+ directed: bool = True,
545
+ uns_key_added: str = "group_connectivity",
546
+ ):
547
+ """
548
+ Computes connectivities (number of observed over the number of expected edges) of groups based on the graph.
549
+
550
+ Parameters
551
+ ----------
552
+ adata : sc.AnnData
553
+ Annotated data matrix at the cell level.
554
+ groupby : str
555
+ Key in `adata.obs` to use for grouping cells.
556
+ graph_key : str, optional
557
+ Key in `adata.obsp` to use for the graph, by default "connectivities".
558
+ directed : bool, optional
559
+ Whether to assume a directed graph, by default True.
560
+ uns_key_added : str, optional
561
+ Key in `adata.uns` to store the group connectivity matrix, by default "group_connectivity".
562
+
563
+ Returns
564
+ -------
565
+ None
566
+ The `adata` object is modified in place with the group connectivity matrix stored in `.uns[uns_key_added]`.
567
+ """
568
+ start = logg.info("computing groups connectivity matrix")
569
+ n_obs = adata.n_obs
570
+
571
+ if not pd.api.types.is_categorical_dtype(adata.obs[groupby]):
572
+ adata.obs[groupby] = adata.obs[groupby].astype("category")
573
+
574
+ labels = adata.obs[groupby].cat.codes.values
575
+ label_names = adata.obs[groupby].cat.categories
576
+ k = len(label_names)
577
+
578
+ A = adata.obsp[graph_key]
579
+ B = sp.csc_matrix(
580
+ (np.ones_like(labels, dtype=int), (np.arange(n_obs), labels)),
581
+ shape=(n_obs, k)
582
+ )
583
+
584
+ if directed:
585
+ observed_edges = (B.T @ (A > 0) @ B).toarray()
586
+
587
+ cluster_out_degree = observed_edges.sum(axis=1)
588
+ cluster_in_degree = observed_edges.sum(axis=0)
589
+ total_edges = cluster_out_degree.sum()
590
+
591
+ if total_edges == 0:
592
+ return np.zeros((k, k), dtype=float)
593
+
594
+ expected_edges = np.outer(cluster_out_degree, cluster_in_degree) / total_edges
595
+
596
+ else:
597
+ A_undirected = (A + A.T) > 0
598
+
599
+ observed_edges = (B.T @ A_undirected @ B).toarray()
600
+ cluster_sizes = np.bincount(labels, minlength=k)
601
+ es = observed_edges.sum(axis=1)
602
+
603
+ if n_obs <= 1:
604
+ return np.zeros((k, k), dtype=float)
605
+
606
+ expected_edges = (
607
+ np.outer(es, cluster_sizes) + np.outer(cluster_sizes, es)
608
+ ) / (n_obs - 1)
609
+
610
+ connectivity = np.divide(
611
+ observed_edges,
612
+ expected_edges,
613
+ out=np.zeros_like(observed_edges, dtype=float),
614
+ where=expected_edges > 0
615
+ )
616
+
617
+ adata.uns[uns_key_added] = {
618
+ "groupby": groupby,
619
+ "graph_key": graph_key,
620
+ "label_names": list(label_names),
621
+ "connectivity": connectivity,
622
+ }
623
+
624
+ lines = [
625
+ "added",
626
+ f" .uns['{uns_key_added}']['connectivity'] groups connectivity matrix",
627
+ f" .uns['{uns_key_added}']['label_names'] label names",
628
+ ]
629
+ logg.info(
630
+ " finished ({time_passed})",
631
+ deep="\n".join(lines),
632
+ time=start,
633
+ )