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/__init__.py +23 -0
- clone2vec/associations.py +1117 -0
- clone2vec/catboost.py +622 -0
- clone2vec/datasets.py +94 -0
- clone2vec/eigenvalues.py +187 -0
- clone2vec/embeddings.py +1204 -0
- clone2vec/integration.py +511 -0
- clone2vec/plotting.py +3540 -0
- clone2vec/preprocessing.py +660 -0
- clone2vec/seurat.py +720 -0
- clone2vec/tools.py +633 -0
- clone2vec/utils.py +618 -0
- clone2vec-0.1.0.dist-info/METADATA +86 -0
- clone2vec-0.1.0.dist-info/RECORD +16 -0
- clone2vec-0.1.0.dist-info/WHEEL +5 -0
- clone2vec-0.1.0.dist-info/top_level.txt +1 -0
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
|
+
)
|