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
|
@@ -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
|