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/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
+ ![Tests](https://github.com/kharchenkolab/clone2vec/actions/workflows/tests.yml/badge.svg)
43
+ ![PyPI](https://img.shields.io/pypi/v/clone2vec)
44
+ ![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
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.