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/utils.py
ADDED
|
@@ -0,0 +1,618 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
from pickle import ADDITEMS
|
|
3
|
+
|
|
4
|
+
import scanpy as sc
|
|
5
|
+
import numpy as np
|
|
6
|
+
import scipy.sparse as sp
|
|
7
|
+
import pandas as pd
|
|
8
|
+
|
|
9
|
+
logg = sc.logging
|
|
10
|
+
|
|
11
|
+
__all__ = [
|
|
12
|
+
"stack_layers",
|
|
13
|
+
"correct_shap",
|
|
14
|
+
"connect_clones",
|
|
15
|
+
"get_connectivity_matrix",
|
|
16
|
+
"gs",
|
|
17
|
+
"regress_categories",
|
|
18
|
+
]
|
|
19
|
+
|
|
20
|
+
def __dir__():
|
|
21
|
+
return sorted(__all__)
|
|
22
|
+
|
|
23
|
+
def regress_categories(
|
|
24
|
+
adata: sc.AnnData,
|
|
25
|
+
obs_key: str | list[str],
|
|
26
|
+
layer: str | None = None,
|
|
27
|
+
key_added: str = "regressed",
|
|
28
|
+
) -> None:
|
|
29
|
+
"""
|
|
30
|
+
Performs expression regression on categorical variables in obs_key. Instead of
|
|
31
|
+
calculation of full regression model, it calculates mean centering. Can be effectively used
|
|
32
|
+
to exclude effect of the cell type signature from the expression matrix.
|
|
33
|
+
|
|
34
|
+
Parameters
|
|
35
|
+
----------
|
|
36
|
+
adata : sc.AnnData
|
|
37
|
+
AnnData object with expression data.
|
|
38
|
+
obs_key : str | list[str]
|
|
39
|
+
Categorical variables in obs to regress.
|
|
40
|
+
layer : str | None, optional
|
|
41
|
+
Layer in adata.layers to regress. If None, use adata.X. Default is None.
|
|
42
|
+
key_added : str, optional
|
|
43
|
+
Key in adata.layers to add regressed expression. Default is "regressed".
|
|
44
|
+
"""
|
|
45
|
+
if layer is None:
|
|
46
|
+
layer = "X"
|
|
47
|
+
use_X = True
|
|
48
|
+
else:
|
|
49
|
+
use_X = False
|
|
50
|
+
|
|
51
|
+
start = logg.info(f"regressing categories {obs_key} on layer {layer}")
|
|
52
|
+
if isinstance(obs_key, str):
|
|
53
|
+
obs_key = [obs_key]
|
|
54
|
+
for key in obs_key:
|
|
55
|
+
if key not in adata.obs.columns:
|
|
56
|
+
raise ValueError(f"obs_key {key} not found in adata.obs")
|
|
57
|
+
elif adata.obs[key].dtype.kind in ["i", "f"]:
|
|
58
|
+
raise ValueError(f"obs_key {key} is numerical")
|
|
59
|
+
if use_X:
|
|
60
|
+
X = adata.X
|
|
61
|
+
else:
|
|
62
|
+
X = adata.layers[layer]
|
|
63
|
+
|
|
64
|
+
regressed = X.copy()
|
|
65
|
+
if sp.issparse(X):
|
|
66
|
+
logg.warning("expression matrix is sparse, converting to dense")
|
|
67
|
+
regressed = regressed.todense()
|
|
68
|
+
|
|
69
|
+
for key in obs_key:
|
|
70
|
+
categories = list(set(adata.obs[key]))
|
|
71
|
+
for category in categories:
|
|
72
|
+
mask = (adata.obs[key] == category).values
|
|
73
|
+
group_mean = regressed[mask, :].mean(axis=0)
|
|
74
|
+
regressed[mask, :] -= group_mean
|
|
75
|
+
|
|
76
|
+
adata.layers[f"{layer}_{key_added}"] = np.asarray(regressed)
|
|
77
|
+
lines = [
|
|
78
|
+
"added",
|
|
79
|
+
f" .layers['{layer}_{key_added}'] regressed expression",
|
|
80
|
+
]
|
|
81
|
+
logg.info(" finished ({time_passed})", deep="\n".join(lines), time=start)
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
def get_connectivity_matrix(
|
|
85
|
+
adata: sc.AnnData,
|
|
86
|
+
uns_key: str = "group_connectivity",
|
|
87
|
+
) -> pd.DataFrame:
|
|
88
|
+
"""
|
|
89
|
+
Get group connectivity matrix from adata.uns[uns_key].
|
|
90
|
+
|
|
91
|
+
Parameters
|
|
92
|
+
----------
|
|
93
|
+
adata : sc.AnnData
|
|
94
|
+
AnnData object with group connectivity matrix in adata.uns[uns_key].
|
|
95
|
+
uns_key : str, optional
|
|
96
|
+
Key in adata.uns to group connectivity matrix. Default is "group_connectivity".
|
|
97
|
+
|
|
98
|
+
Returns
|
|
99
|
+
-------
|
|
100
|
+
pd.DataFrame
|
|
101
|
+
Group connectivity matrix.
|
|
102
|
+
"""
|
|
103
|
+
return pd.DataFrame(
|
|
104
|
+
adata.uns[uns_key]["connectivity"],
|
|
105
|
+
index=adata.uns[uns_key]["label_names"],
|
|
106
|
+
columns=adata.uns[uns_key]["label_names"],
|
|
107
|
+
)
|
|
108
|
+
|
|
109
|
+
def stack_layers(
|
|
110
|
+
adata: sc.AnnData,
|
|
111
|
+
layers: list[str] | None = None,
|
|
112
|
+
layer_col_added: str = "layer",
|
|
113
|
+
mask_key: str | None | Liretal[False] = None,
|
|
114
|
+
) -> None:
|
|
115
|
+
"""
|
|
116
|
+
Function stacks layers of an AnnData object into a single layer in adata.X.
|
|
117
|
+
|
|
118
|
+
Parameters
|
|
119
|
+
----------
|
|
120
|
+
adata : sc.AnnData
|
|
121
|
+
AnnData object with layers to stack.
|
|
122
|
+
layers : list[str] | None, optional
|
|
123
|
+
Layers to stack. If None, all layers are stacked. Default is None.
|
|
124
|
+
layer_col_added : str, optional
|
|
125
|
+
Name of the column added to obs to indicate the layer. Default is "layer".
|
|
126
|
+
mask_key : str | None | Literal[False], optional
|
|
127
|
+
Key in obsm to boolean mask of cells to include in the stack. If None, tries to use "mask_key" in adata.uns. Default is None.
|
|
128
|
+
"""
|
|
129
|
+
if mask_key is None and "mask_key" in adata.uns.keys():
|
|
130
|
+
mask_key = adata.uns["mask_key"]
|
|
131
|
+
|
|
132
|
+
if layer_col_added in adata.obs.columns:
|
|
133
|
+
logg.warning(f"'{layer_col_added}' column already exists in adata.obs. Overwriting.")
|
|
134
|
+
|
|
135
|
+
if layers is None:
|
|
136
|
+
layers = list(adata.layers.keys())
|
|
137
|
+
line_before = f"\n using layers {layers}"
|
|
138
|
+
start = logg.info("stacking layers into a new AnnData object", deep=line_before)
|
|
139
|
+
|
|
140
|
+
Xs = [adata.layers[layer] for layer in layers]
|
|
141
|
+
if mask_key:
|
|
142
|
+
masks = [adata.obsm[mask_key][layer].values for layer in layers]
|
|
143
|
+
else:
|
|
144
|
+
masks = [np.ones(adata.shape[0], dtype=bool) for layer in layers]
|
|
145
|
+
|
|
146
|
+
masks = [mask & ~_nan_mask(X) for X, mask in zip(Xs, masks)]
|
|
147
|
+
Xs = [X[mask] for X, mask in zip(Xs, masks)]
|
|
148
|
+
|
|
149
|
+
if sp.issparse(Xs[0]):
|
|
150
|
+
X = sp.vstack(Xs, format="csr")
|
|
151
|
+
else:
|
|
152
|
+
X = np.vstack(Xs)
|
|
153
|
+
del Xs
|
|
154
|
+
|
|
155
|
+
mask = np.concatenate(masks)
|
|
156
|
+
|
|
157
|
+
obs = [adata.obs.values] * len(layers)
|
|
158
|
+
obs = [
|
|
159
|
+
np.hstack([obs_i, np.array([layer] * len(obs_i))[:, None]])
|
|
160
|
+
for obs_i, layer in zip(obs, layers)
|
|
161
|
+
]
|
|
162
|
+
obs = np.vstack(obs)
|
|
163
|
+
obs = pd.DataFrame(
|
|
164
|
+
index=np.concatenate([layer + ":" + adata.obs.index.astype(str) for layer in layers]),
|
|
165
|
+
data=obs,
|
|
166
|
+
columns=list(adata.obs.columns) + [layer_col_added],
|
|
167
|
+
)[mask]
|
|
168
|
+
|
|
169
|
+
obsm = {}
|
|
170
|
+
for obsm_key in adata.obsm.keys():
|
|
171
|
+
obsm[obsm_key] = np.vstack([adata.obsm[obsm_key]] * len(layers))[mask]
|
|
172
|
+
if isinstance(adata.obsm[obsm_key], pd.DataFrame):
|
|
173
|
+
obsm[obsm_key] = pd.DataFrame(obsm[obsm_key])
|
|
174
|
+
obsm[obsm_key].index = obs.index
|
|
175
|
+
obsm[obsm_key].columns = adata.obsm[obsm_key].columns
|
|
176
|
+
|
|
177
|
+
new_adata = sc.AnnData(
|
|
178
|
+
X=X,
|
|
179
|
+
obs=obs,
|
|
180
|
+
var=pd.DataFrame(index=adata.var_names),
|
|
181
|
+
varm=adata.varm,
|
|
182
|
+
varp=adata.varp,
|
|
183
|
+
obsm=obsm,
|
|
184
|
+
uns=adata.uns,
|
|
185
|
+
)
|
|
186
|
+
|
|
187
|
+
if "mask_key" in new_adata.uns.keys():
|
|
188
|
+
del new_adata.uns["mask_key"]
|
|
189
|
+
|
|
190
|
+
lines = [
|
|
191
|
+
"created stacked AnnData with",
|
|
192
|
+
" '.X' stacked matrix (layers × cells)",
|
|
193
|
+
f" .obs['{layer_col_added}'] layer labels",
|
|
194
|
+
" .obsm['<existing>'] stacked to match new index",
|
|
195
|
+
" .var, .varp, and .uns are inherited from the original adata",
|
|
196
|
+
]
|
|
197
|
+
logg.info(" finished ({time_passed})", deep="\n".join(lines), time=start)
|
|
198
|
+
return new_adata
|
|
199
|
+
|
|
200
|
+
def connect_clones(
|
|
201
|
+
clones: sc.AnnData,
|
|
202
|
+
groupby: str,
|
|
203
|
+
graph_key_added: str = "connected",
|
|
204
|
+
orient_col: str | None = None,
|
|
205
|
+
orient_rule: Literal["all_increase", "all_decrease", "increase", "decrease"] | "Callable" | None = None,
|
|
206
|
+
ignore_names: list[str] | str | None = None,
|
|
207
|
+
weight_edges: bool = False,
|
|
208
|
+
):
|
|
209
|
+
"""
|
|
210
|
+
Creates a graph of connected clones based on a grouping variable.
|
|
211
|
+
|
|
212
|
+
Parameters
|
|
213
|
+
----------
|
|
214
|
+
clones : sc.AnnData
|
|
215
|
+
AnnData object with clone information.
|
|
216
|
+
groupby : str
|
|
217
|
+
Name of the column in obs to group by.
|
|
218
|
+
graph_key_added : str, optional
|
|
219
|
+
Name of the key added to obsp to store the graph. Default is "connected".
|
|
220
|
+
orient_col : str | None, optional
|
|
221
|
+
Name of the column in obs to orient the graph. If None, all pairs of clones are connected. Default is None.
|
|
222
|
+
orient_rule : Literal["all_increase", "all_decrease", "increase", "decrease"] | "Callable" | None, optional
|
|
223
|
+
Rule to orient the graph. If None, uses "increase" if `orient_col` is provided. Default is None.
|
|
224
|
+
ignore_names : list[str] | str | None, optional
|
|
225
|
+
Names of clones to ignore. If None, no clones are ignored. Default is None.
|
|
226
|
+
weight_edges : bool, optional
|
|
227
|
+
Whether to weight edges by the inverse of the number of connected clones. Default is False.
|
|
228
|
+
|
|
229
|
+
Returns
|
|
230
|
+
-------
|
|
231
|
+
None
|
|
232
|
+
Adds a graph to clones.obsp[graph_key_added].
|
|
233
|
+
"""
|
|
234
|
+
line_before = f"\n using .obs['{groupby}'] to group clones"
|
|
235
|
+
start = logg.info(f"connecting clones", deep=line_before)
|
|
236
|
+
|
|
237
|
+
from itertools import combinations
|
|
238
|
+
|
|
239
|
+
if orient_col and (orient_rule is None):
|
|
240
|
+
orient_rule = "increase"
|
|
241
|
+
obs_idx = dict(zip(clones.obs_names, np.arange(len(clones))))
|
|
242
|
+
|
|
243
|
+
if isinstance(ignore_names, str):
|
|
244
|
+
ignore_names = [ignore_names]
|
|
245
|
+
|
|
246
|
+
rows = []
|
|
247
|
+
cols = []
|
|
248
|
+
data = []
|
|
249
|
+
|
|
250
|
+
ignore_set = set(ignore_names) if ignore_names is not None else None
|
|
251
|
+
for name, connected_component in clones.obs.groupby(groupby, observed=True):
|
|
252
|
+
if ignore_set is not None and name in ignore_set:
|
|
253
|
+
continue
|
|
254
|
+
if len(connected_component) > 1:
|
|
255
|
+
w = (1.0 / len(connected_component)) if weight_edges else 1.0
|
|
256
|
+
if orient_col:
|
|
257
|
+
if isinstance(orient_rule, str):
|
|
258
|
+
if orient_rule.endswith("increase"):
|
|
259
|
+
ascending = True
|
|
260
|
+
else:
|
|
261
|
+
ascending = False
|
|
262
|
+
connected_component = connected_component.sort_values(orient_col, ascending=ascending)
|
|
263
|
+
obs_names = connected_component.index
|
|
264
|
+
if orient_rule.startswith("all"):
|
|
265
|
+
for i in range(len(obs_names)):
|
|
266
|
+
for j in range(i + 1, len(obs_names)):
|
|
267
|
+
rows.append(obs_idx[obs_names[i]])
|
|
268
|
+
cols.append(obs_idx[obs_names[j]])
|
|
269
|
+
data.append(w)
|
|
270
|
+
else:
|
|
271
|
+
for i in range(len(obs_names) - 1):
|
|
272
|
+
rows.append(obs_idx[obs_names[i]])
|
|
273
|
+
cols.append(obs_idx[obs_names[i + 1]])
|
|
274
|
+
data.append(w)
|
|
275
|
+
else:
|
|
276
|
+
for i, j in orient_rule(connected_component):
|
|
277
|
+
rows += [obs_idx[i]]
|
|
278
|
+
cols += [obs_idx[j]]
|
|
279
|
+
data += [w]
|
|
280
|
+
else:
|
|
281
|
+
for i, j in combinations(connected_component.index, 2):
|
|
282
|
+
rows += [obs_idx[i], obs_idx[j]]
|
|
283
|
+
cols += [obs_idx[j], obs_idx[i]]
|
|
284
|
+
data += [w, w]
|
|
285
|
+
|
|
286
|
+
clones.obsp[graph_key_added] = sp.csr_matrix(
|
|
287
|
+
(np.asarray(data, dtype=np.float32), (rows, cols)),
|
|
288
|
+
shape=(clones.n_obs, clones.n_obs),
|
|
289
|
+
)
|
|
290
|
+
lines = [
|
|
291
|
+
f"added",
|
|
292
|
+
f" .obsp['{graph_key_added}'] with graph of connected clones",
|
|
293
|
+
]
|
|
294
|
+
logg.info(" finished ({time_passed})", deep="\n".join(lines), time=start)
|
|
295
|
+
|
|
296
|
+
def correct_shap(
|
|
297
|
+
shapdata: sc.AnnData,
|
|
298
|
+
shap_key: str = "mean_shap",
|
|
299
|
+
corr_key: str = "gex_r",
|
|
300
|
+
correct_sign: bool = True,
|
|
301
|
+
normalize: bool = False,
|
|
302
|
+
key_added: str | None = None,
|
|
303
|
+
) -> None:
|
|
304
|
+
"""
|
|
305
|
+
Correct SHAP values by dividing by the maximum absolute value of SHAP values for each feature.
|
|
306
|
+
|
|
307
|
+
Parameters
|
|
308
|
+
----------
|
|
309
|
+
shapdata : sc.AnnData
|
|
310
|
+
AnnData object with SHAP values in varm[shap_key].
|
|
311
|
+
shap_key : str, optional
|
|
312
|
+
Key in varm to store SHAP values. Default is "mean_shap".
|
|
313
|
+
corr_key : str, optional
|
|
314
|
+
Key in varm to store correlation values. Default is "gex_r".
|
|
315
|
+
correct_sign : bool, optional
|
|
316
|
+
Whether to correct the sign of SHAP values based on the correlation sign. Default is True.
|
|
317
|
+
normalize : bool, optional
|
|
318
|
+
Whether to normalize SHAP values by dividing by the maximum absolute value for each prediction column.
|
|
319
|
+
Default is True.
|
|
320
|
+
key_added : str, optional
|
|
321
|
+
Key in varm to store normalized SHAP values. Default is "norm_mean_shap".
|
|
322
|
+
|
|
323
|
+
Returns
|
|
324
|
+
-------
|
|
325
|
+
None
|
|
326
|
+
Corrected SHAP values are stored in varm[key_added].
|
|
327
|
+
"""
|
|
328
|
+
line_before = f" using varm['{shap_key}'] and varm['{corr_key}']"
|
|
329
|
+
start = logg.info("correcting SHAP values", deep="\n" + line_before)
|
|
330
|
+
if normalize:
|
|
331
|
+
norm_shap = shapdata.varm[shap_key].copy() / shapdata.varm[shap_key].max(axis=0)
|
|
332
|
+
else:
|
|
333
|
+
norm_shap = shapdata.varm[shap_key].copy()
|
|
334
|
+
if correct_sign:
|
|
335
|
+
norm_shap *= np.sign(shapdata.varm[corr_key])
|
|
336
|
+
|
|
337
|
+
if key_added is None:
|
|
338
|
+
key_added = shap_key
|
|
339
|
+
if normalize:
|
|
340
|
+
key_added = "norm_" + key_added
|
|
341
|
+
if correct_sign:
|
|
342
|
+
key_added = "signed_" + key_added
|
|
343
|
+
|
|
344
|
+
shapdata.varm[key_added] = norm_shap
|
|
345
|
+
lines = ["added", f" .varm['{key_added}'] corrected SHAP values"]
|
|
346
|
+
logg.info(" finished ({time_passed})", deep="\n".join(lines), time=start)
|
|
347
|
+
|
|
348
|
+
def impute(
|
|
349
|
+
adata: sc.AnnData,
|
|
350
|
+
obs_name: str,
|
|
351
|
+
value_to_impute: str = "NA",
|
|
352
|
+
use_rep: str = "X_pca",
|
|
353
|
+
weights: Literal["gaussian", "linear"] | None = None,
|
|
354
|
+
classification_obsm: str = "impute_prob",
|
|
355
|
+
key_added: str = "imputed",
|
|
356
|
+
gaus_sigma: float | None = None,
|
|
357
|
+
k: int = 10,
|
|
358
|
+
):
|
|
359
|
+
"""
|
|
360
|
+
Impute missing values in an observation column using k-nearest neighbors.
|
|
361
|
+
|
|
362
|
+
Parameters
|
|
363
|
+
----------
|
|
364
|
+
adata : sc.AnnData
|
|
365
|
+
AnnData object with observation values in obs[obs_name].
|
|
366
|
+
obs_name : str
|
|
367
|
+
Name of the observation column to impute.
|
|
368
|
+
value_to_impute : str, optional
|
|
369
|
+
Value in obs_name to impute. Default is "NA".
|
|
370
|
+
use_rep : str, optional
|
|
371
|
+
Key in obsm to use for neighbor search. Default is "X_pca".
|
|
372
|
+
weights : Literal["gaussian", "linear"] | None, optional
|
|
373
|
+
Weighting scheme for imputation. Default is None.
|
|
374
|
+
classification_obsm : str, optional
|
|
375
|
+
Key in obsm to use for classification probabilities. Default is "impute_prob".
|
|
376
|
+
key_added : str, optional
|
|
377
|
+
Key in obs to store imputed values. Default is "imputed".
|
|
378
|
+
gaus_sigma : float | None, optional
|
|
379
|
+
Sigma for Gaussian weighting. If None, use median distance of positive neighbors. Default is None.
|
|
380
|
+
k : int, optional
|
|
381
|
+
Number of neighbors to use for imputation. Default is 10.
|
|
382
|
+
|
|
383
|
+
Returns
|
|
384
|
+
-------
|
|
385
|
+
None
|
|
386
|
+
Imputed values are stored in obs[f"{obs_name}_{key_added}"].
|
|
387
|
+
"""
|
|
388
|
+
import pynndescent
|
|
389
|
+
|
|
390
|
+
line_before = f"\n using obsm['{use_rep}'] for neighbor search"
|
|
391
|
+
start = logg.info("imputing observation values", deep=line_before)
|
|
392
|
+
|
|
393
|
+
labels = adata.obs[obs_name]
|
|
394
|
+
if not adata.obs_names.is_unique:
|
|
395
|
+
adata.obs_names_make_unique()
|
|
396
|
+
|
|
397
|
+
Xrep = adata.obsm[use_rep]
|
|
398
|
+
X_values = Xrep.values if isinstance(Xrep, pd.DataFrame) else (Xrep.toarray() if sp.issparse(Xrep) else np.asarray(Xrep))
|
|
399
|
+
|
|
400
|
+
mask_target = labels.astype(str).values == str(value_to_impute)
|
|
401
|
+
mask_donor = ~mask_target
|
|
402
|
+
|
|
403
|
+
if mask_target.sum() == 0:
|
|
404
|
+
adata.obs[f"{obs_name}_{key_added}"] = labels.copy()
|
|
405
|
+
return None
|
|
406
|
+
if mask_donor.sum() == 0:
|
|
407
|
+
raise ValueError("No donor cells available for imputation")
|
|
408
|
+
|
|
409
|
+
donors_idx = np.where(mask_donor)[0]
|
|
410
|
+
targets_idx = np.where(mask_target)[0]
|
|
411
|
+
|
|
412
|
+
X_donors = X_values[donors_idx]
|
|
413
|
+
X_targets = X_values[targets_idx]
|
|
414
|
+
|
|
415
|
+
index = pynndescent.NNDescent(X_donors, n_neighbors=k, metric="euclidean")
|
|
416
|
+
nn_idx, nn_dist = index.query(X_targets, k=k)
|
|
417
|
+
|
|
418
|
+
if weights is None:
|
|
419
|
+
W = np.ones_like(nn_dist, dtype=float)
|
|
420
|
+
elif weights == "linear":
|
|
421
|
+
eps = 1e-12
|
|
422
|
+
W = 1.0 / (nn_dist + eps)
|
|
423
|
+
elif weights == "gaussian":
|
|
424
|
+
dpos = nn_dist[np.isfinite(nn_dist) & (nn_dist > 0)]
|
|
425
|
+
if gaus_sigma is None:
|
|
426
|
+
gaus_sigma = np.median(dpos) if dpos.size > 0 else 1.0
|
|
427
|
+
W = np.exp(-(nn_dist ** 2) / (2.0 * gaus_sigma ** 2))
|
|
428
|
+
else:
|
|
429
|
+
raise ValueError("weights must be one of {None, 'gaussian', 'linear'}")
|
|
430
|
+
|
|
431
|
+
W[~np.isfinite(W)] = 0.0
|
|
432
|
+
row_sum = W.sum(axis=1, keepdims=True)
|
|
433
|
+
row_sum[row_sum == 0] = 1.0
|
|
434
|
+
W = W / row_sum
|
|
435
|
+
|
|
436
|
+
is_numeric = pd.api.types.is_numeric_dtype(labels)
|
|
437
|
+
if is_numeric:
|
|
438
|
+
y_donors = pd.to_numeric(labels.values[mask_donor], errors="coerce")
|
|
439
|
+
y_neighbors = y_donors[nn_idx]
|
|
440
|
+
y_pred = (W * y_neighbors).sum(axis=1)
|
|
441
|
+
imputed = labels.astype(float).copy()
|
|
442
|
+
imputed.values[mask_target] = y_pred
|
|
443
|
+
adata.obs[f"{obs_name}_{key_added}"] = imputed
|
|
444
|
+
lines = [
|
|
445
|
+
"added",
|
|
446
|
+
f" .obs['{obs_name}_{key_added}'] imputed numeric values",
|
|
447
|
+
]
|
|
448
|
+
logg.info(" finished ({time_passed})", deep="\n".join(lines), time=start)
|
|
449
|
+
else:
|
|
450
|
+
donor_classes = labels.astype(str).values[mask_donor]
|
|
451
|
+
classes = pd.Index(sorted(pd.unique(donor_classes)))
|
|
452
|
+
prob = np.zeros((adata.n_obs, len(classes)), dtype=float)
|
|
453
|
+
for i_row in range(nn_idx.shape[0]):
|
|
454
|
+
cls_i = donor_classes[nn_idx[i_row]]
|
|
455
|
+
w_i = W[i_row]
|
|
456
|
+
for c, w in zip(cls_i, w_i):
|
|
457
|
+
j = classes.get_indexer([c])[0]
|
|
458
|
+
if j >= 0:
|
|
459
|
+
prob[targets_idx[i_row], j] += w
|
|
460
|
+
prob_df = pd.DataFrame(prob, index=adata.obs_names, columns=classes)
|
|
461
|
+
adata.obsm[classification_obsm] = prob_df
|
|
462
|
+
pred_idx = np.argmax(prob[targets_idx], axis=1)
|
|
463
|
+
pred_vals = classes.values[pred_idx]
|
|
464
|
+
imputed = labels.astype(str).copy()
|
|
465
|
+
imputed.values[mask_target] = pred_vals
|
|
466
|
+
adata.obs[f"{obs_name}_{key_added}"] = imputed
|
|
467
|
+
lines = [
|
|
468
|
+
"added",
|
|
469
|
+
f" .obsm['{classification_obsm}'] class probabilities",
|
|
470
|
+
f" .obs['{obs_name}_{key_added}'] imputed categorical values",
|
|
471
|
+
]
|
|
472
|
+
logg.info(" finished ({time_passed})", deep="\n".join(lines), time=start)
|
|
473
|
+
|
|
474
|
+
def _nan_mask(X: np.ndarray | sp.sparse.csr_matrix) -> np.ndarray:
|
|
475
|
+
"""
|
|
476
|
+
Create a mask for NaN-contaminated rows in a sparse or dense matrix.
|
|
477
|
+
|
|
478
|
+
Parameters
|
|
479
|
+
----------
|
|
480
|
+
X : np.ndarray or sp.sparse.csr_matrix
|
|
481
|
+
Input matrix.
|
|
482
|
+
|
|
483
|
+
Returns
|
|
484
|
+
-------
|
|
485
|
+
np.ndarray
|
|
486
|
+
Boolean mask where True indicates NaN-contaminated rows.
|
|
487
|
+
"""
|
|
488
|
+
|
|
489
|
+
if sp.issparse(X):
|
|
490
|
+
X_csr = X.tocsr()
|
|
491
|
+
indptr = X_csr.indptr
|
|
492
|
+
data = X_csr.data
|
|
493
|
+
if data.size == 0:
|
|
494
|
+
mask = np.zeros(X_csr.shape[0], dtype=bool)
|
|
495
|
+
else:
|
|
496
|
+
rows_for_data = np.repeat(np.arange(X_csr.shape[0]), np.diff(indptr))
|
|
497
|
+
nan_data = np.isnan(data)
|
|
498
|
+
mask = np.zeros(X_csr.shape[0], dtype=bool)
|
|
499
|
+
if nan_data.any():
|
|
500
|
+
mask[np.unique(rows_for_data[nan_data])] = True
|
|
501
|
+
return mask
|
|
502
|
+
else:
|
|
503
|
+
arr = np.asarray(X)
|
|
504
|
+
if arr.dtype.kind == "O":
|
|
505
|
+
mask = pd.isna(arr).any(axis=1)
|
|
506
|
+
else:
|
|
507
|
+
mask = np.isnan(arr).any(axis=1)
|
|
508
|
+
return mask
|
|
509
|
+
|
|
510
|
+
def gs(
|
|
511
|
+
adata: sc.AnnData,
|
|
512
|
+
use_rep: str = "X_pca",
|
|
513
|
+
batch_key: str | None = None,
|
|
514
|
+
n: float | int = 0.2,
|
|
515
|
+
obs_key: str = "gs",
|
|
516
|
+
random_state: int = 42,
|
|
517
|
+
progress_bar: bool = False,
|
|
518
|
+
) -> None:
|
|
519
|
+
"""
|
|
520
|
+
Function to perform geometric sketching on an AnnData object. Might be useful to identify test and validation
|
|
521
|
+
sets for model training. If batch_key is provided, the sketching is performed within each batch.
|
|
522
|
+
|
|
523
|
+
Parameters
|
|
524
|
+
----------
|
|
525
|
+
adata : sc.AnnData
|
|
526
|
+
Annotated data matrix at the cell level.
|
|
527
|
+
use_rep : str, optional
|
|
528
|
+
Representation to use for geometric sketching, by default "X_pca".
|
|
529
|
+
batch_key : str | None, optional
|
|
530
|
+
Key in `adata.obs` to use for batch-specific sketching, by default None.
|
|
531
|
+
n : float | int, optional
|
|
532
|
+
Either a fraction between 0 and 1 or an integer between 1 and the number of cells to sketch, by default 0.2.
|
|
533
|
+
obs_key : str, optional
|
|
534
|
+
Name of the new column in `adata.obs` to store sketching labels, by default "gs".
|
|
535
|
+
random_state : int, optional
|
|
536
|
+
Random seed for reproducibility, by default 42.
|
|
537
|
+
progress_bar : bool, optional
|
|
538
|
+
Whether to display a progress bar, by default False.
|
|
539
|
+
|
|
540
|
+
Returns
|
|
541
|
+
-------
|
|
542
|
+
None
|
|
543
|
+
The `adata` object is modified in place with the new sketching labels stored in `.obs[obs_key]`.
|
|
544
|
+
The parameters used for the sketching are stored in `adata.uns["gs"]`.
|
|
545
|
+
"""
|
|
546
|
+
start = logg.info("performing geometric sketching")
|
|
547
|
+
from geosketch import gs
|
|
548
|
+
from tqdm import tqdm
|
|
549
|
+
from contextlib import nullcontext
|
|
550
|
+
import sys
|
|
551
|
+
|
|
552
|
+
if use_rep == "X":
|
|
553
|
+
logg.warning("Using 'X' as representation may not be appropriate for geometric sketching.")
|
|
554
|
+
X = adata.X
|
|
555
|
+
# Ensure array-like for geosketch; convert sparse to dense
|
|
556
|
+
if hasattr(X, "toarray"):
|
|
557
|
+
X = X.toarray()
|
|
558
|
+
else:
|
|
559
|
+
try:
|
|
560
|
+
X = adata.obsm[use_rep]
|
|
561
|
+
except KeyError:
|
|
562
|
+
raise KeyError(f"Representation '{use_rep}' not found in adata.obsm. Please provide a valid representation.")
|
|
563
|
+
|
|
564
|
+
if obs_key in adata.obs:
|
|
565
|
+
logg.warning(f"obs_key '{obs_key}' already exists in adata.obs. Overwriting.")
|
|
566
|
+
|
|
567
|
+
n_cells = adata.shape[0]
|
|
568
|
+
if n > n_cells:
|
|
569
|
+
raise ValueError("n must be less than or equal to the number of cells in adata.")
|
|
570
|
+
elif 1 < n <= n_cells:
|
|
571
|
+
alpha = n / n_cells
|
|
572
|
+
elif 0 < n <= 1:
|
|
573
|
+
alpha = n
|
|
574
|
+
elif n <= 0:
|
|
575
|
+
raise ValueError("n must be a positive value.")
|
|
576
|
+
|
|
577
|
+
gs_res = np.array(["full"] * len(adata), dtype=object)
|
|
578
|
+
|
|
579
|
+
if sc.settings.verbosity.value >= 3:
|
|
580
|
+
prefix = " "
|
|
581
|
+
else:
|
|
582
|
+
prefix = ""
|
|
583
|
+
|
|
584
|
+
if batch_key:
|
|
585
|
+
cm = tqdm(
|
|
586
|
+
adata.obs[batch_key].cat.categories,
|
|
587
|
+
desc=prefix + "dataset batches",
|
|
588
|
+
file=sys.stdout,
|
|
589
|
+
) if progress_bar else nullcontext(adata.obs[batch_key].cat.categories)
|
|
590
|
+
with cm as iterator:
|
|
591
|
+
for batch in iterator:
|
|
592
|
+
mask = adata.obs[batch_key] == batch
|
|
593
|
+
X_batch = X[mask]
|
|
594
|
+
n_rows_b = X_batch.shape[0]
|
|
595
|
+
idx_batch = gs(X=X_batch, N=np.round(alpha * n_rows_b).astype(int), seed=random_state)
|
|
596
|
+
batch_rows = np.flatnonzero(mask.to_numpy())
|
|
597
|
+
sel_rows = batch_rows[idx_batch]
|
|
598
|
+
gs_res[sel_rows] = "sketch"
|
|
599
|
+
else:
|
|
600
|
+
n_rows = X.shape[0]
|
|
601
|
+
idx = gs(X=X, N=np.round(alpha * n_rows).astype(int), seed=random_state)
|
|
602
|
+
gs_res[idx] = "sketch"
|
|
603
|
+
|
|
604
|
+
adata.obs[obs_key] = gs_res
|
|
605
|
+
adata.uns["gs"] = {
|
|
606
|
+
"use_rep": use_rep,
|
|
607
|
+
"batch_key": batch_key,
|
|
608
|
+
"n": n,
|
|
609
|
+
"obs_key": obs_key,
|
|
610
|
+
"random_state": random_state,
|
|
611
|
+
"keys": {"validation": "sketch", "train": "full"},
|
|
612
|
+
}
|
|
613
|
+
lines = [
|
|
614
|
+
"added",
|
|
615
|
+
f" .obs['{obs_key}'] geometric sketching labels",
|
|
616
|
+
" .uns['gs'] parameters",
|
|
617
|
+
]
|
|
618
|
+
logg.info(" finished ({time_passed})", deep="\n".join(lines), time=start)
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: clone2vec
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Package for an analysis of lineage-tracing scRNA-Seq data
|
|
5
|
+
Home-page: https://github.com/kharchenkolab/clone2vec
|
|
6
|
+
Author: Sergey Isaev
|
|
7
|
+
Author-email: s@isaev.cc
|
|
8
|
+
Classifier: Programming Language :: Python :: 3
|
|
9
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
10
|
+
Classifier: Operating System :: OS Independent
|
|
11
|
+
Requires-Python: >=3.8
|
|
12
|
+
Description-Content-Type: text/markdown
|
|
13
|
+
Requires-Dist: pynndescent
|
|
14
|
+
Requires-Dist: scanpy
|
|
15
|
+
Requires-Dist: scikit-learn
|
|
16
|
+
Requires-Dist: torch
|
|
17
|
+
Requires-Dist: joblib
|
|
18
|
+
Requires-Dist: statsmodels
|
|
19
|
+
Requires-Dist: tqdm
|
|
20
|
+
Provides-Extra: test
|
|
21
|
+
Requires-Dist: catboost; extra == "test"
|
|
22
|
+
Requires-Dist: geosketch; extra == "test"
|
|
23
|
+
Requires-Dist: fastglmpca; extra == "test"
|
|
24
|
+
Requires-Dist: mpltern; extra == "test"
|
|
25
|
+
Requires-Dist: textalloc; extra == "test"
|
|
26
|
+
Provides-Extra: full
|
|
27
|
+
Requires-Dist: catboost; extra == "full"
|
|
28
|
+
Requires-Dist: geosketch; extra == "full"
|
|
29
|
+
Requires-Dist: fastglmpca; extra == "full"
|
|
30
|
+
Requires-Dist: mpltern; extra == "full"
|
|
31
|
+
Requires-Dist: textalloc; extra == "full"
|
|
32
|
+
Requires-Dist: anywidget; extra == "full"
|
|
33
|
+
Requires-Dist: ipywidgets; extra == "full"
|
|
34
|
+
Requires-Dist: jupyter-scatter; extra == "full"
|
|
35
|
+
Requires-Dist: rpy2; extra == "full"
|
|
36
|
+
Requires-Dist: mudata; extra == "full"
|
|
37
|
+
|
|
38
|
+
<p align="center"><a href="https://clone2vec.readthedocs.io/en/latest/"><img src="docs/source/logo.png" height="150"></a></p>
|
|
39
|
+
|
|
40
|
+
# clone2vec
|
|
41
|
+
|
|
42
|
+

|
|
43
|
+

|
|
44
|
+

|
|
45
|
+
|
|
46
|
+
clone2vec is a Python package for analysis of lineage tracing coupled with single-cell RNA-Seq.
|
|
47
|
+
|
|
48
|
+
The main key of the package are clonal embeddings — vector representations of the whole clones
|
|
49
|
+
in low dimensional space. These representations is a dropout-robust and cluster-free
|
|
50
|
+
way of representation of heterogeneity within clonal behaviour for cell type tree-free hypothesis
|
|
51
|
+
generation regarding cells' multipotency.
|
|
52
|
+
|
|
53
|
+
clone2vec builds representation of clones in exact same way with popular word embedding algorithm — word2vec —
|
|
54
|
+
via construction two-layers fully connected neural network (it uses Skip-Gram architecture) that
|
|
55
|
+
aims to predict neighbour cells clonal labellings by clonal label of cells. As a result, clones that exist in
|
|
56
|
+
similar context in gene expression space will have similar weights in this neural network, and these weights
|
|
57
|
+
will be used as embedding for further analysis.
|
|
58
|
+
|
|
59
|
+
## Benchmarking illustrations
|
|
60
|
+
|
|
61
|
+
See [Technical Note](https://github.com/kharchenkolab/clone2vec/blob/main/docs/Technical_note.pdf) for more details.
|
|
62
|
+
|
|
63
|
+
## Installation
|
|
64
|
+
|
|
65
|
+
clone2vec might be installed via `pip` (takes 1-2 minutes on Google Colab):
|
|
66
|
+
```bash
|
|
67
|
+
pip install clone2vec
|
|
68
|
+
```
|
|
69
|
+
or the latest development version can be installed from GitHub using:
|
|
70
|
+
```bash
|
|
71
|
+
pip install git+https://github.com/kharchenkolab/clone2vec
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## System requirements
|
|
75
|
+
|
|
76
|
+
`clone2vec` requires Python 3.8 or later with packages listed in [setup.cfg](setup.cfg) file. The package was successfully tested
|
|
77
|
+
on the following systems:
|
|
78
|
+
|
|
79
|
+
* macOS Sonoma 14.5 (Apple M1 Chip @ 3.20GHz × 8, 16GB RAM) — *MacBook Air M1*,
|
|
80
|
+
* Ubuntu 18.04.5 LTS, 64-bit (Intel Xeon @ 2.60GHz × 32, 256GB RAM) — *PowerEdge server*,
|
|
81
|
+
* Ubuntu 22.04.3 LTS, 64-bit (Intel Xeon @ 2.20GHz × 2, 13GB RAM) — *Google Colab*.
|
|
82
|
+
|
|
83
|
+
## Documentation and tutorials
|
|
84
|
+
|
|
85
|
+
Please visit [documentation web-site](https://clone2vec.readthedocs.io/en/latest/) to check out API description and a few
|
|
86
|
+
tutorials with analysis.
|