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.
@@ -0,0 +1,660 @@
1
+ from __future__ import annotations
2
+ from typing import Literal
3
+ from scanpy import AnnData
4
+
5
+ import scanpy as sc
6
+ import numpy as np
7
+ import pandas as pd
8
+ import scipy.sparse as sp
9
+
10
+ logg = sc.logging
11
+
12
+ __all__ = [
13
+ "clones_adata",
14
+ "make_unique_clones",
15
+ "recalc_composition",
16
+ "transfer_annotation",
17
+ "transfer_expression",
18
+ ]
19
+
20
+ def __dir__():
21
+ return sorted(__all__)
22
+
23
+
24
+ def clones_adata(
25
+ adata: AnnData,
26
+ obs_name: str = "clone",
27
+ min_size: int = 3,
28
+ na_value: str = "NA",
29
+ fill_obs: str | None = None,
30
+ ) -> AnnData:
31
+ """
32
+ Creates a clone-level AnnData object from a cell-level AnnData object.
33
+
34
+ This function identifies clones meeting a minimum size requirement and, if specified,
35
+ calculates their cellular composition (e.g., by cell type).
36
+
37
+ Parameters
38
+ ----------
39
+ adata : AnnData
40
+ The cell-level annotated data matrix.
41
+ obs_name : str, optional
42
+ Column in `adata.obs` containing clonal information, by default "clone".
43
+ min_size : int, optional
44
+ Minimum clone size to be considered, by default 3.
45
+ na_value : str, optional
46
+ Value indicating the absence of clonal information, by default "NA".
47
+ fill_obs : str | None, optional
48
+ Column in `adata.obs` (e.g., 'cell_type') to calculate clone composition, by default None.
49
+
50
+ Returns
51
+ -------
52
+ AnnData
53
+ A new AnnData object where each observation is a clone. The `.X` matrix and
54
+ `.layers['proportions']` store composition proportions, and `.layers['counts']`
55
+ stores raw counts. The `.obs['n_cells']` column contains the number of
56
+ cells per clone.
57
+ """
58
+ # Scanpy-style logging
59
+ start = logg.info("creating clone-level AnnData")
60
+
61
+ # 1. Identify valid clones based on min_size
62
+ clonal_obs = adata.obs[obs_name]
63
+ clones_counts = clonal_obs.value_counts()
64
+
65
+ valid_clone_names = clones_counts[clones_counts >= min_size].index
66
+ valid_clone_names = valid_clone_names.drop(na_value, errors="ignore")
67
+
68
+ n_all = len(clones_counts.drop(na_value, errors="ignore"))
69
+ n_valid = len(valid_clone_names)
70
+ logg.info(f" selected {n_valid} clones (>= {min_size})")
71
+
72
+ if valid_clone_names.empty:
73
+ raise ValueError(f"No clones with min_size={min_size} found in the dataset.")
74
+
75
+ train_adata = adata[adata.obs[obs_name].isin(valid_clone_names)].copy()
76
+ n_clones = len(valid_clone_names)
77
+
78
+ # 2. Calculate cellular composition if fill_obs is provided
79
+ if fill_obs and fill_obs not in adata.obs.columns:
80
+ logg.warning(f"'{fill_obs}' not found in adata.obs. Skipping composition analysis.")
81
+ fill_obs = None
82
+
83
+ if fill_obs:
84
+ cell_counts_df = pd.crosstab(train_adata.obs[fill_obs], train_adata.obs[obs_name])
85
+ cell_counts_df = cell_counts_df.reindex(columns=valid_clone_names, fill_value=0)
86
+
87
+ var_names = list(cell_counts_df.index)
88
+ cell_counts = cell_counts_df.values
89
+ col_sums = cell_counts.sum(axis=0, keepdims=True)
90
+ freqs = np.divide(cell_counts, col_sums, out=np.zeros_like(cell_counts, dtype=float), where=col_sums!=0)
91
+ else:
92
+ var_names = ["None"]
93
+ cell_counts = np.zeros((1, n_clones), dtype=np.int32)
94
+ freqs = np.zeros((1, n_clones), dtype=np.float32)
95
+
96
+ # 3. Create the new AnnData object at the clone level
97
+ clones = AnnData(
98
+ X=freqs.T,
99
+ obs=pd.DataFrame(index=list(valid_clone_names)),
100
+ var=pd.DataFrame(index=var_names),
101
+ layers={"proportions": freqs.T, "counts": cell_counts.T},
102
+ uns={"fill_obs": fill_obs, "min_size": min_size, "obs_name": obs_name},
103
+ )
104
+
105
+ # 4. Add n_cells information from the filtered data
106
+ clones.obs["n_cells"] = train_adata.obs[obs_name].value_counts().loc[clones.obs_names].values
107
+ clones.obs["n_fates"] = (clones.layers["proportions"] > 0).sum(axis=1)
108
+ clones.var["n_clones"] = (clones.X > 0).sum(axis=0)
109
+
110
+ clones.obs["n_cells"] = clones.obs["n_cells"].astype(int)
111
+ clones.obs["n_fates"] = clones.obs["n_fates"].astype(int)
112
+ clones.var["n_clones"] = clones.var["n_clones"].astype(int)
113
+
114
+ # Final logging of added fields and summary (Scanpy style)
115
+ lines = [
116
+ "created clones AnnData with",
117
+ " .X float matrix of proportions (clones × categories)",
118
+ " .layers['proportions'] float matrix with fate proportions",
119
+ " .layers['counts'] integer matrix with fate counts",
120
+ " .obs['n_cells'] integer vector with number of cells per clone",
121
+ " .obs['n_fates'] integer vector with number of fates per clone",
122
+ " .var['n_clones'] integer vector with number of clones per fate",
123
+ " .uns['fill_obs'] string label",
124
+ ]
125
+ logg.info(" finished ({time_passed})", deep="\n".join(lines), time=start)
126
+
127
+ return clones
128
+
129
+ def make_unique_clones(
130
+ adata: AnnData,
131
+ injection_cols: list[str],
132
+ na_value: str = "NA",
133
+ final_obs_name: str = "clone",
134
+ ) -> AnnData:
135
+ """
136
+ Prepares a clone2vec-friendly AnnData object by handling multiple clonal labels per cell.
137
+ Duplicates cells with multiple clonal labels into separate rows for each unique clone label.
138
+
139
+ Parameters
140
+ ----------
141
+ adata : AnnData
142
+ Annotated data matrix containing the clonal labels across multiple columns.
143
+ injection_cols : list[str]
144
+ List of column names in `adata.obs` that contain the clonal labels.
145
+ na_value : str, optional
146
+ The value used to indicate missing or absent clonal information. Default is "NA".
147
+ final_obs_name : str, optional
148
+ The name of the new column in `adata.obs` to store the merged clone labels. Default is "clone".
149
+
150
+ Returns
151
+ -------
152
+ AnnData
153
+ A new AnnData object with cells duplicated where necessary, with updated clonal labeling in the `final_obs_name` column.
154
+ """
155
+ start = logg.info("creating unique per-cell clone labels")
156
+
157
+ bc_list = []
158
+ clone_obs = []
159
+
160
+ for bc, clonal_labels in adata.obs[injection_cols].iterrows():
161
+ labeled_cells = clonal_labels[clonal_labels != na_value]
162
+ if len(labeled_cells) == 0:
163
+ bc_list.append(bc)
164
+ clone_obs.append(na_value)
165
+ else:
166
+ for label, clone in clonal_labels[clonal_labels != na_value].items():
167
+ bc_list.append(bc)
168
+ clone_obs.append(label + "_" + clone)
169
+
170
+ adata_demult = adata[bc_list]
171
+ adata_demult.obs[final_obs_name] = clone_obs
172
+ adata_demult.obs_names_make_unique()
173
+ lines = [
174
+ "created AnnData with",
175
+ f" .obs['{final_obs_name}'] categorical labels.",
176
+ ]
177
+ logg.info(" finished ({time_passed})", deep="\n".join(lines), time=start)
178
+
179
+ return adata_demult
180
+
181
+ def recalc_composition(
182
+ adata: AnnData,
183
+ clones: AnnData,
184
+ fill_obs: str,
185
+ obs_name: str | None = None,
186
+ ) -> AnnData:
187
+ """
188
+ Create a new annotated data matrix at the clone level with updated cell type proportions.
189
+
190
+ Parameters
191
+ ----------
192
+ adata : AnnData
193
+ Annotated data matrix at the cell level.
194
+ clones : AnnData
195
+ Annotated data matrix at the clone level.
196
+ fill_obs : str
197
+ Column in `adata.obs` containing updated cell type / cluster labels.
198
+ obs_name : str | None, optional
199
+ Column in `adata.obs` containing clonal information, if None, try to get from `clones.uns['obs_name']`,
200
+ by default None.
201
+
202
+ Returns
203
+ -------
204
+ AnnData
205
+ New annotated data matrix at the clone level with updated cell type proportions.
206
+ """
207
+ # Scanpy-style logging
208
+ start = logg.info("recalculating clone composition")
209
+
210
+ if obs_name is None:
211
+ try:
212
+ obs_name = clones.uns["obs_name"]
213
+ except KeyError:
214
+ raise KeyError("obs_name not found in clones.uns. Please provide obs_name.")
215
+
216
+ if obs_name not in adata.obs.columns:
217
+ raise KeyError(f"obs_name '{obs_name}' not found in adata.obs. Please provide a valid obs_name.")
218
+
219
+ if fill_obs not in adata.obs.columns:
220
+ raise KeyError(f"fill_obs '{fill_obs}' not found in adata.obs. Please provide a valid fill_obs.")
221
+
222
+ clones_new = adata.obs.groupby(
223
+ [fill_obs, obs_name], observed=False
224
+ ).size().unstack().T.loc[clones.obs_names].fillna(0)
225
+ clones_new.index = list(clones_new.index)
226
+ clones_new = sc.AnnData(clones_new)
227
+
228
+ clones_new.uns = clones.uns.copy()
229
+ clones_new.uns["fill_obs"] = fill_obs
230
+ # concise logging
231
+
232
+ clones_new.obs = clones.obs.copy()
233
+ clones_new.obsm = clones.obsm.copy()
234
+ clones_new.obsp = clones.obsp.copy()
235
+ # concise logging
236
+
237
+ clones_new.layers["counts"] = clones_new.X.copy()
238
+ clones_new.layers["proportions"] = (clones_new.X.T / clones_new.X.sum(axis=1)).T
239
+ clones_new.X = clones_new.layers["proportions"].copy()
240
+ # concise logging
241
+
242
+ clones_new.obs["n_fates"] = (clones_new.layers["proportions"] > 0).sum(axis=1)
243
+ clones_new.obs["n_fates"] = clones_new.obs["n_fates"].astype(int)
244
+ clones_new.var["n_clones"] = (clones_new.X > 0).sum(axis=0)
245
+ lines = [
246
+ "created clones AnnData with",
247
+ " .X float matrix of proportions (clones × categories)",
248
+ " .layers['proportions'] float matrix with fate proportions",
249
+ " .layers['counts'] integer matrix with fate counts",
250
+ " .obs['n_fates'] integer vector with number of fates per clone",
251
+ " .var['n_clones'] integer vector with number of cells per clone",
252
+ " .uns['fill_obs'] string label",
253
+ " .obs and .obsm are copied from the original AnnData",
254
+ ]
255
+ logg.info(" finished ({time_passed})", deep="\n".join(lines), time=start)
256
+ return clones_new
257
+
258
+ def transfer_annotation(
259
+ adata: AnnData,
260
+ clones: AnnData,
261
+ annotation_obs_clones: str | list[str] | None = None,
262
+ annotation_obs_adata: str | list[str] | None = None,
263
+ created_obs_name: str | list[str] | None = None,
264
+ obs_name: str | None = None,
265
+ na_value: str | None = "NA",
266
+ ) -> None:
267
+ """
268
+ Transfer clonal labels from a `clones` AnnData object to a `adata` AnnData object, or otherwise.
269
+ The direction of the transfer is from `clones` to `adata` if `annotation_obs_clones` is provided,
270
+ or from `adata` to `clones` if `annotation_obs_adata` is provided.
271
+
272
+ Parameters
273
+ ----------
274
+ adata : AnnData
275
+ Annotated data matrix at the cell level.
276
+ clones : AnnData
277
+ Annotated data matrix at the clone level.
278
+ annotation_obs_clones : str | list[str] | None, optional
279
+ Column(s) in `clones.obs` containing clonal labels, by default None.
280
+ annotation_obs_adata : str | list[str] | None, optional
281
+ Name of the new column(s) in `adata.obs` to store transferred clonal labels, by default None.
282
+ obs_name : str | None, optional
283
+ Column in `adata.obs` with the original clonal information, by default None.
284
+ na_value : str | None, optional
285
+ Value to assign to cells with no matching clone in the `clones` object, by default "NA".
286
+
287
+ Returns
288
+ -------
289
+ None
290
+ The `adata` or `clones` object is modified in place with the new labels stored in `.obs[created_obs_name]`.
291
+ """
292
+ # Scanpy-style logging
293
+ start = logg.info("transferring annotations between cell and clone objects")
294
+
295
+ if obs_name is None:
296
+ try:
297
+ obs_name = clones.uns["obs_name"]
298
+ except KeyError:
299
+ raise KeyError("obs_name not found in clones.uns. Please provide obs_name.")
300
+ if obs_name not in adata.obs:
301
+ raise KeyError(f"obs_name '{obs_name}' not found in adata.obs. Please provide a valid obs_name.")
302
+
303
+ if (annotation_obs_clones is None) and (annotation_obs_adata is None):
304
+ raise ValueError("Either annotation_obs_clones or annotation_obs_adata must be provided.")
305
+
306
+ if annotation_obs_clones and annotation_obs_adata:
307
+ raise ValueError("Only one of annotation_obs_clones or annotation_obs_adata must be provided.")
308
+
309
+ if annotation_obs_clones:
310
+ if isinstance(annotation_obs_clones, str):
311
+ annotation_obs_clones = [annotation_obs_clones]
312
+ if isinstance(created_obs_name, str):
313
+ created_obs_name = [created_obs_name]
314
+ if isinstance(created_obs_name, list) and len(annotation_obs_clones) != len(created_obs_name):
315
+ logg.warning("annotation_obs_clones and created_obs_name must have the same length. Keeping default naming.")
316
+ created_obs_name = None
317
+ if created_obs_name is None:
318
+ created_obs_name = [f"c2v_{col}" for col in annotation_obs_clones]
319
+ else:
320
+ if isinstance(annotation_obs_adata, str):
321
+ annotation_obs_adata = [annotation_obs_adata]
322
+ if isinstance(created_obs_name, str):
323
+ created_obs_name = [created_obs_name]
324
+ if isinstance(created_obs_name, list) and len(annotation_obs_adata) != len(created_obs_name):
325
+ logg.warning("annotation_obs_adata and created_obs_name must have the same length. Keeping default naming.")
326
+ created_obs_name = None
327
+ if created_obs_name is None:
328
+ created_obs_name = ["gex_" + col for col in annotation_obs_adata]
329
+
330
+ if annotation_obs_clones:
331
+ for col, obs_col in zip(annotation_obs_clones, created_obs_name):
332
+ clone_mapping = dict(clones.obs[col])
333
+ adata.obs[obs_col] = [
334
+ clone_mapping[clone] if clone in clone_mapping else na_value
335
+ for clone in adata.obs[obs_name]
336
+ ]
337
+ adata.obs[obs_col] = adata.obs[obs_col].astype("category")
338
+ added_target = "adata"
339
+ added_obs_cols = created_obs_name
340
+ else:
341
+ for col, obs_col in zip(annotation_obs_adata, created_obs_name):
342
+ mapping_df = adata.obs[[obs_name, col]].copy()
343
+ mapping_df = mapping_df[mapping_df[obs_name].isin(clones.obs_names)]
344
+ nunique_per_obs = mapping_df.groupby(obs_name, observed=False)[col].nunique()
345
+ problematic = nunique_per_obs[nunique_per_obs > 1]
346
+ if len(problematic) > 0:
347
+ raise ValueError(
348
+ (
349
+ f"Non-unique mapping from '{obs_name}' to '{col}'. "
350
+ f"{len(problematic)} values map to multiple annotations."
351
+ )
352
+ )
353
+
354
+ clone_to_annot = mapping_df.groupby(obs_name, observed=False)[col].first()
355
+ clones.obs[obs_col] = [
356
+ clone_to_annot[clone] if clone in clone_to_annot.index else na_value
357
+ for clone in clones.obs_names
358
+ ]
359
+ clones.obs[obs_col] = clones.obs[obs_col].astype("category")
360
+ added_target = "clones"
361
+ added_obs_cols = created_obs_name
362
+ lines = ["added to clonal AnnData"]
363
+ for obs_col in added_obs_cols:
364
+ if added_target == "adata":
365
+ lines.append(f" .obs['{obs_col}'] categorical labels")
366
+ else:
367
+ lines.append(f" .obs['{obs_col}'] categorical labels")
368
+ logg.info(" finished ({time_passed})", deep="\n".join(lines), time=start)
369
+
370
+ def transfer_expression(
371
+ adata: AnnData,
372
+ clones: AnnData,
373
+ obs_name: str | None = None,
374
+ split_obs: str | None = None,
375
+ use_col: str | None = None,
376
+ strategy: Literal["sum", "average"] = "average",
377
+ layer: str | None = None,
378
+ use_raw: bool | None = None,
379
+ layers_to_obsm: list[str] | str | None = None,
380
+ mask_key: str = "mask",
381
+ ) -> AnnData:
382
+ """
383
+ Summarize gene expression at the clone level using a specified strategy (sum or average).
384
+
385
+ Parameters
386
+ ----------
387
+ adata : AnnData
388
+ Annotated data matrix at the cell level with gene expression data.
389
+ clones : AnnData
390
+ Annotated data matrix at the clone level.
391
+ obs_name : str, optional
392
+ Column name in `adata.obs` containing clonal information. If not provided,
393
+ the value from `clones.uns["obs_name"]` is used.
394
+ split_obs : str | None, optional
395
+ Column name in `adata.obs` to split the data for aggregation. If None,
396
+ the entire dataset is used for aggregation, default None.
397
+ strategy : Literal["sum", "average"], optional
398
+ Strategy for aggregating gene expression ("sum" or "average"), by default "average".
399
+ layer : str | None, optional
400
+ If specified, summarizes expression from `adata.layers[layer]`, by default None.
401
+ use_raw : bool | None, optional
402
+ If specified, uses `adata.raw.X` for summarization, by default None.
403
+ layers_to_obsm : list[str] | str | None, optional
404
+ List of layers in `clones.layers` to transfer to `clones_expr.obsm`.
405
+ If None, all layers with `adata.X` are transferred, by default None.
406
+
407
+ Returns
408
+ -------
409
+ AnnData
410
+ Annotated data matrix at the clone level with summarized gene expression.
411
+ The strategy used for aggregation is stored in `clones.uns["transfer_expression"]["strategy"]`.
412
+ If `split_obs` is provided, the aggregation is performed within each group defined by `split_obs` and stored
413
+ in `clones.layers[g]` where `g` is the group name. Clones without a matching group in `split_obs` contain
414
+ NaN values in this layer if `absent_expression` is "nan", otherwise they contain zero expression.
415
+ """
416
+ if obs_name is None:
417
+ try:
418
+ obs_name = clones.uns["obs_name"]
419
+ except KeyError:
420
+ raise KeyError("obs_name not found in clones.uns. Please provide obs_name.")
421
+
422
+ if obs_name not in adata.obs:
423
+ raise KeyError(f"obs_name '{obs_name}' not found in adata.obs. Please provide a valid obs_name.")
424
+
425
+ if use_col:
426
+ if use_col not in clones.obs.columns:
427
+ raise KeyError(f"use_col '{use_col}' not found in clones.obs. Please provide a valid use_col or set use_col to None.")
428
+
429
+ if use_raw is None and layer is None:
430
+ if adata.raw is None:
431
+ use_raw = False
432
+ else:
433
+ use_raw = True
434
+ elif use_raw and not (layer is None):
435
+ logg.warning(f"Can't use both `adata.raw` and `adata.layers['{layer}']`. Using `adata.raw.X` as expression source.")
436
+ use_raw = True
437
+
438
+ if strategy not in ("average", "sum"):
439
+ logg.warning(f"Only average and sum methods of expression aggregation are supported, got '{strategy}'")
440
+ strategy = "average"
441
+
442
+ if split_obs and (split_obs not in adata.obs.columns):
443
+ raise KeyError(f"split_obs '{split_obs}' not found in adata.obs. Please provide a valid split_obs or set split_obs to None.")
444
+
445
+ if not (layer is None):
446
+ X = adata.layers[layer]
447
+ var_names = adata.var_names
448
+ line_before = f"\n using `adata.layers['{layer}']` as expression source"
449
+ elif use_raw:
450
+ X = adata.raw.X
451
+ var_names = adata.raw.var_names
452
+ line_before = "\n using `adata.raw.X` as expression source"
453
+ else:
454
+ X = adata.X
455
+ var_names = adata.var_names
456
+ line_before = "\n using `adata.X` as expression source"
457
+
458
+ start = logg.info("summarizing expression at clone level", deep=line_before)
459
+
460
+ n_cells = adata.n_obs
461
+ n_clones = clones.n_obs
462
+ if use_col:
463
+ categories = list(pd.unique(clones.obs[use_col]))
464
+ cat_to_idx = {c: i for i, c in enumerate(categories)}
465
+ clone_cat_idx = np.array([cat_to_idx.get(v, -1) for v in clones.obs[use_col].values], dtype=np.int64)
466
+ clone_to_cat_idx = dict(zip(clones.obs_names, clone_cat_idx))
467
+ adata_vals = adata.obs[obs_name].values
468
+ codes_direct = np.array([cat_to_idx.get(v, -1) for v in adata_vals], dtype=np.int64)
469
+ if np.any(codes_direct != -1):
470
+ codes_fallback = np.array([clone_to_cat_idx.get(v, -1) for v in adata_vals], dtype=np.int64)
471
+ use_direct_mask = codes_direct != -1
472
+ codes = np.where(use_direct_mask, codes_direct, codes_fallback)
473
+ else:
474
+ codes = np.array([clone_to_cat_idx.get(v, -1) for v in adata_vals], dtype=np.int64)
475
+ else:
476
+ categories = list(clones.obs_names)
477
+ labels = pd.Categorical(adata.obs[obs_name].values, categories=categories)
478
+ codes = labels.codes
479
+ valid_mask = codes != -1
480
+ rows = np.where(valid_mask)[0]
481
+ cols = codes[valid_mask]
482
+
483
+ if use_col:
484
+ n_categories = len(categories)
485
+ if sp.issparse(X):
486
+ data = np.ones(rows.shape[0], dtype=np.uint8)
487
+ Bc = sp.csr_matrix((data, (rows, cols)), shape=(n_cells, n_categories))
488
+ X_sum_cat = Bc.T @ X
489
+ counts_cat = np.asarray(Bc.sum(axis=0)).ravel().astype(np.float32)
490
+ else:
491
+ counts_cat = np.bincount(cols, minlength=n_categories).astype(np.float32)
492
+ X_sum_cat = np.zeros((n_categories, X.shape[1]), dtype=X.dtype)
493
+ np.add.at(X_sum_cat, cols, X[rows, :])
494
+
495
+ if strategy == "average":
496
+ inv_counts_cat = np.divide(1.0, counts_cat, out=np.zeros_like(counts_cat), where=counts_cat != 0)
497
+ if sp.issparse(X_sum_cat):
498
+ X_agg_cat = sp.diags(inv_counts_cat) @ X_sum_cat
499
+ else:
500
+ X_agg_cat = inv_counts_cat[:, None] * X_sum_cat
501
+ else:
502
+ X_agg_cat = X_sum_cat
503
+
504
+ valid_clone_mask = clone_cat_idx != -1
505
+ if sp.issparse(X_agg_cat):
506
+ rows_list = [X_agg_cat.getrow(clone_cat_idx[i]) if valid_clone_mask[i] else sp.csr_matrix((1, X_agg_cat.shape[1]), dtype=X_agg_cat.dtype) for i in range(n_clones)]
507
+ X_agg = sp.vstack(rows_list)
508
+ else:
509
+ X_agg = np.zeros((n_clones, X_agg_cat.shape[1]), dtype=X_agg_cat.dtype)
510
+ X_agg[valid_clone_mask, :] = X_agg_cat[clone_cat_idx[valid_clone_mask], :]
511
+ counts = np.zeros(n_clones, dtype=np.float32)
512
+ counts[valid_clone_mask] = counts_cat[clone_cat_idx[valid_clone_mask]]
513
+ else:
514
+ if sp.issparse(X):
515
+ data = np.ones(rows.shape[0], dtype=np.uint8)
516
+ B = sp.csr_matrix((data, (rows, cols)), shape=(n_cells, n_clones))
517
+ X_sum = B.T @ X
518
+ counts = np.asarray(B.sum(axis=0)).ravel().astype(np.float32)
519
+ else:
520
+ counts = np.bincount(cols, minlength=n_clones).astype(np.float32)
521
+ X_sum = np.zeros((n_clones, X.shape[1]), dtype=X.dtype)
522
+ np.add.at(X_sum, cols, X[rows, :])
523
+
524
+ if strategy == "average":
525
+ inv_counts = np.divide(1.0, counts, out=np.zeros_like(counts), where=counts != 0)
526
+ if sp.issparse(X_sum):
527
+ X_agg = sp.diags(inv_counts) @ X_sum
528
+ else:
529
+ X_agg = inv_counts[:, None] * X_sum
530
+ else:
531
+ X_agg = X_sum
532
+
533
+ clones_expr = AnnData(
534
+ X=X_agg,
535
+ obs=clones.obs.copy(),
536
+ var=pd.DataFrame(index=var_names),
537
+ obsm=clones.obsm.copy(),
538
+ obsp=clones.obsp.copy(),
539
+ uns=clones.uns.copy(),
540
+ )
541
+ clones_expr.uns["transfer_expression"] = {"strategy": strategy}
542
+
543
+ if layers_to_obsm is None:
544
+ layers_to_obsm = ["X"] + list(clones.layers.keys())
545
+ elif isinstance(layers_to_obsm, str):
546
+ layers_to_obsm = [layers_to_obsm]
547
+ layers_to_obsm = np.array(layers_to_obsm)
548
+ if "X" in layers_to_obsm:
549
+ clones_expr.obsm["X"] = clones.to_df()
550
+ clones_expr.obsm["X"].index = list(clones_expr.obs_names)
551
+ clones_expr.obsm["X"].columns = clones.var_names
552
+ layers_to_obsm = layers_to_obsm[layers_to_obsm != "X"]
553
+ for layer in layers_to_obsm:
554
+ layer = str(layer)
555
+ try:
556
+ clones_expr.obsm[layer] = clones.to_df(layer=layer)
557
+ clones_expr.obsm[layer].index = list(clones_expr.obs_names)
558
+ clones_expr.obsm[layer].columns = clones.var_names
559
+ except ValueError:
560
+ logg.warning(f"Layer '{layer}' not found in clones.obs. Skipping.")
561
+ if isinstance(layers_to_obsm, np.ndarray):
562
+ lt = list(layers_to_obsm)
563
+ else:
564
+ lt = layers_to_obsm
565
+
566
+ if split_obs is not None:
567
+ groups = pd.unique(adata.obs[split_obs])
568
+ groups = [g for g in groups if pd.notna(g)]
569
+ zero_df = {}
570
+
571
+ for g in groups:
572
+ group_mask = (adata.obs[split_obs].values == g) & valid_mask
573
+ g_rows = np.where(group_mask)[0]
574
+ codes_g = codes[g_rows]
575
+
576
+ if use_col:
577
+ n_categories = len(categories)
578
+ if sp.issparse(X):
579
+ data_g = np.ones(g_rows.shape[0], dtype=np.uint8)
580
+ B_gc = sp.csr_matrix((data_g, (np.arange(g_rows.size), codes_g)), shape=(g_rows.size, n_categories))
581
+ X_g = X[g_rows, :] if hasattr(X, "__getitem__") else X
582
+ X_sum_g_cat = B_gc.T @ X_g
583
+ counts_g_cat = np.asarray(B_gc.sum(axis=0)).ravel().astype(np.float32)
584
+ else:
585
+ X_g = X[g_rows, :]
586
+ counts_g_cat = np.bincount(codes_g, minlength=n_categories).astype(np.float32)
587
+ X_sum_g_cat = np.zeros((n_categories, X.shape[1]), dtype=X.dtype)
588
+ np.add.at(X_sum_g_cat, codes_g, X_g)
589
+ if strategy == "average":
590
+ inv_counts_g_cat = np.divide(1.0, counts_g_cat, out=np.zeros_like(counts_g_cat), where=counts_g_cat != 0)
591
+ if sp.issparse(X_sum_g_cat):
592
+ X_agg_g_cat = sp.diags(inv_counts_g_cat) @ X_sum_g_cat
593
+ else:
594
+ X_agg_g_cat = inv_counts_g_cat[:, None] * X_sum_g_cat
595
+ else:
596
+ X_agg_g_cat = X_sum_g_cat
597
+ valid_clone_mask = clone_cat_idx != -1
598
+ if sp.issparse(X_agg_g_cat):
599
+ rows_list_g = [X_agg_g_cat.getrow(clone_cat_idx[i]) if valid_clone_mask[i] else sp.csr_matrix((1, X_agg_g_cat.shape[1]), dtype=X_agg_g_cat.dtype) for i in range(n_clones)]
600
+ X_agg_g = sp.vstack(rows_list_g)
601
+ else:
602
+ X_agg_g = np.zeros((n_clones, X_agg_g_cat.shape[1]), dtype=X_agg_g_cat.dtype)
603
+ X_agg_g[valid_clone_mask, :] = X_agg_g_cat[clone_cat_idx[valid_clone_mask], :]
604
+ counts_g = np.zeros(n_clones, dtype=np.float32)
605
+ counts_g[valid_clone_mask] = counts_g_cat[clone_cat_idx[valid_clone_mask]]
606
+ else:
607
+ if sp.issparse(X):
608
+ data_g = np.ones(g_rows.shape[0], dtype=np.uint8)
609
+ B_g = sp.csr_matrix((data_g, (np.arange(g_rows.size), codes_g)), shape=(g_rows.size, n_clones))
610
+ X_g = X[g_rows, :] if hasattr(X, "__getitem__") else X
611
+ X_sum_g = B_g.T @ X_g
612
+ counts_g = np.asarray(B_g.sum(axis=0)).ravel().astype(np.float32)
613
+ else:
614
+ X_g = X[g_rows, :]
615
+ counts_g = np.bincount(codes_g, minlength=n_clones).astype(np.float32)
616
+ X_sum_g = np.zeros((n_clones, X.shape[1]), dtype=X.dtype)
617
+ np.add.at(X_sum_g, codes_g, X_g)
618
+ if strategy == "average":
619
+ inv_counts_g = np.divide(1.0, counts_g, out=np.zeros_like(counts_g), where=counts_g != 0)
620
+ if sp.issparse(X_sum_g):
621
+ X_agg_g = sp.diags(inv_counts_g) @ X_sum_g
622
+ else:
623
+ X_agg_g = inv_counts_g[:, None] * X_sum_g
624
+ else:
625
+ X_agg_g = X_sum_g
626
+
627
+ mask_nonzero = (counts_g > 0)
628
+ if sp.issparse(X_agg_g):
629
+ clones_expr.layers[g] = X_agg_g.tocsr()
630
+ else:
631
+ X_agg_g[~mask_nonzero, :] = np.nan
632
+ clones_expr.layers[g] = X_agg_g
633
+ zero_df[g] = mask_nonzero
634
+
635
+ clones_expr.obsm[mask_key] = pd.DataFrame(zero_df, index=clones_expr.obs_names)
636
+ clones_expr.uns["mask_key"] = mask_key
637
+ clones_expr.uns["transfer_expression"]["split_obs"] = split_obs
638
+
639
+ nonzero_clones = np.asarray(clones_expr.X.sum(axis=1)).ravel() > 0
640
+ if sum(~nonzero_clones) > 0:
641
+ logg.warning(f"Removing {sum(~nonzero_clones)} clones with no overall expression")
642
+ clones_expr = clones_expr[nonzero_clones].copy()
643
+
644
+ lines = [
645
+ "created clone-level AnnData with",
646
+ " .X aggregated expression matrix (clones × genes)",
647
+ " .uns['transfer_expression'] dict with 'strategy'",
648
+ f" .uns['mask_key'] string with obsm key for boolean mask of clones with non-zero cells",
649
+ ]
650
+ if 'lt' in locals() and lt is not None:
651
+ if "X" in lt:
652
+ lines.append(" .obsm['X'] dataframe of features")
653
+ for layer_name in [l for l in lt if l != "X"]:
654
+ lines.append(f" .obsm['{layer_name}'] dataframe of features")
655
+ if split_obs is not None:
656
+ lines.append(f" .layers['<groups>'] aggregated matrices per '{split_obs}' group")
657
+ lines.append(f" .obsm['{mask_key}'] boolean mask of clones with zero cells")
658
+ logg.info(" finished ({time_passed})", deep="\n".join(lines), time=start)
659
+
660
+ return clones_expr