scoubi 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.
- scoubi/__init__.py +5 -0
- scoubi/data/__init__.py +1 -0
- scoubi/data/pairs.pkl +0 -0
- scoubi/io/__init__.py +1 -0
- scoubi/io/_io.py +236 -0
- scoubi/model/__init__.py +1 -0
- scoubi/model/_annotate.py +254 -0
- scoubi/plotting/__init__.py +3 -0
- scoubi/plotting/_enrichment.py +399 -0
- scoubi/plotting/_radviz.py +257 -0
- scoubi/plotting/_sunburst.py +251 -0
- scoubi/preprocess/__init__.py +1 -0
- scoubi/preprocess/_preprocess.py +97 -0
- scoubi/tools/__init__.py +7 -0
- scoubi/tools/_communication.py +80 -0
- scoubi/tools/_distance.py +19 -0
- scoubi/tools/_empirical.py +141 -0
- scoubi/tools/_enrichment.py +187 -0
- scoubi/tools/_overview.py +237 -0
- scoubi/tools/_profile.py +130 -0
- scoubi/tools/_ptest.py +382 -0
- scoubi-1.0.dist-info/METADATA +143 -0
- scoubi-1.0.dist-info/RECORD +26 -0
- scoubi-1.0.dist-info/WHEEL +5 -0
- scoubi-1.0.dist-info/licenses/LICENSE +21 -0
- scoubi-1.0.dist-info/top_level.txt +1 -0
scoubi/__init__.py
ADDED
scoubi/data/__init__.py
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""Bundled SCOUBI resources."""
|
scoubi/data/pairs.pkl
ADDED
|
Binary file
|
scoubi/io/__init__.py
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
from ._io import load_data
|
scoubi/io/_io.py
ADDED
|
@@ -0,0 +1,236 @@
|
|
|
1
|
+
import os
|
|
2
|
+
import pandas as pd
|
|
3
|
+
import anndata as ad
|
|
4
|
+
import numpy as np
|
|
5
|
+
from scipy.sparse import coo_matrix
|
|
6
|
+
import types
|
|
7
|
+
|
|
8
|
+
class LazyTranscripts:
|
|
9
|
+
"""Lazy loader for transcripts parquet (cached after first load)."""
|
|
10
|
+
def __init__(self, path):
|
|
11
|
+
self.path = path
|
|
12
|
+
self._df = None
|
|
13
|
+
def load(self):
|
|
14
|
+
if self._df is None:
|
|
15
|
+
self._df = pd.read_parquet(self.path)
|
|
16
|
+
return self._df
|
|
17
|
+
def save(self):
|
|
18
|
+
if self._df is not None:
|
|
19
|
+
self._df.to_parquet(self.path)
|
|
20
|
+
else:
|
|
21
|
+
raise("DataFrame not loaded.")
|
|
22
|
+
def __call__(self):
|
|
23
|
+
return self.load()
|
|
24
|
+
def __getattr__(self, name):
|
|
25
|
+
raise AttributeError("Access only via .load()")
|
|
26
|
+
def __getitem__(self, key):
|
|
27
|
+
return self.load()[key]
|
|
28
|
+
|
|
29
|
+
def _attach_lazy_loader(adata):
|
|
30
|
+
"""Attach get_transcripts() method to adata in memory (not stored in .uns)."""
|
|
31
|
+
def _get_transcripts(self):
|
|
32
|
+
path = self.uns.get('transcripts_path', None)
|
|
33
|
+
if path is None:
|
|
34
|
+
raise KeyError("No 'transcripts_path' in adata.uns")
|
|
35
|
+
if not hasattr(self, '_transcripts') or self._transcripts.path != path:
|
|
36
|
+
self._transcripts = LazyTranscripts(path)
|
|
37
|
+
return self._transcripts
|
|
38
|
+
adata.get_transcripts = types.MethodType(_get_transcripts, adata)
|
|
39
|
+
|
|
40
|
+
def _summarize(self):
|
|
41
|
+
"""Structured summary of AnnData with grouped .uns fields.
|
|
42
|
+
|
|
43
|
+
Groups are: data, annotations, maps, enrichment, comparison, testing,
|
|
44
|
+
interface, communication, misc.
|
|
45
|
+
Any .uns keys not in a known group are printed under 'other'.
|
|
46
|
+
"""
|
|
47
|
+
print(f"AnnData object with n_obs × n_vars = {self.n_obs} × {self.n_vars}")
|
|
48
|
+
print("obs:", ", ".join(self.obs.columns.tolist()))
|
|
49
|
+
print("obsm:", ", ".join(self.obsm.keys()))
|
|
50
|
+
print("uns:")
|
|
51
|
+
|
|
52
|
+
# --- Predefined grouping map ---
|
|
53
|
+
group_map = {
|
|
54
|
+
'data': [
|
|
55
|
+
'transcripts_path', 'data_shape', 'binned_data_shape',
|
|
56
|
+
'mask_cell', 'mask_ecm', 'binned_data',
|
|
57
|
+
'axon_markers', 'dendrite_markers', 'genes', 'lr_pairs'
|
|
58
|
+
],
|
|
59
|
+
'annotations': ['bin_probabilities', 'bin_scores'],
|
|
60
|
+
'maps': [
|
|
61
|
+
'axon_map', 'dendrite_map', 'interface_map'
|
|
62
|
+
],
|
|
63
|
+
'enrichment': ['axon_enrichment_df', 'dendrite_enrichment_df'],
|
|
64
|
+
'comparison': ['ptest_a_vs_d'],
|
|
65
|
+
'testing': [
|
|
66
|
+
'empirical', 'regional_ptest',
|
|
67
|
+
'ptest_best_rank', 'ptest_best_rank_neuronal', 'ptest_best_rank_non_neuronal'
|
|
68
|
+
],
|
|
69
|
+
'interface': ['interface_cell_type_profile', 'interface_cell_type_region_profile', 'interface_region_profile'],
|
|
70
|
+
'communication': [
|
|
71
|
+
'cellwhisper', 'cellwhisper_unfiltered', 'cellwhisper_lr', 'cellwhisper_regionwise',
|
|
72
|
+
'communication_cell_type_profile', 'communication_cell_type_region_profile',
|
|
73
|
+
'communication_region_profile', 'lr_edges'
|
|
74
|
+
],
|
|
75
|
+
'misc': ['interface_knn_idx', 'interface_knn_dists', 'model_weights'],
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
# flatten group map for lookup
|
|
79
|
+
assigned = set(k for keys in group_map.values() for k in keys)
|
|
80
|
+
uns_keys = set(self.uns.keys())
|
|
81
|
+
ungrouped = sorted(uns_keys - assigned)
|
|
82
|
+
|
|
83
|
+
# print present keys per group
|
|
84
|
+
for group, keys in group_map.items():
|
|
85
|
+
present = [k for k in keys if k in self.uns]
|
|
86
|
+
if present:
|
|
87
|
+
print(f" {group:<22}: {', '.join(present)}")
|
|
88
|
+
|
|
89
|
+
if ungrouped:
|
|
90
|
+
print(f" {'other':<22}: {', '.join(ungrouped)}")
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
def _attach_summarize(adata):
|
|
94
|
+
"""Attach summarize() method to a single AnnData object in memory."""
|
|
95
|
+
adata.summarize = types.MethodType(_summarize, adata)
|
|
96
|
+
return adata
|
|
97
|
+
|
|
98
|
+
def load_data(
|
|
99
|
+
filename: str,
|
|
100
|
+
cell_type=None,
|
|
101
|
+
region=None,
|
|
102
|
+
qv_thresold=None,
|
|
103
|
+
filter_genes=('BLANK', 'NegControl', 'DeprecatedCodeword', 'UnassignedCodeword', 'Blank'),
|
|
104
|
+
usr_label="UNASSIGNED",
|
|
105
|
+
overwrite=False,
|
|
106
|
+
) -> ad.AnnData:
|
|
107
|
+
"""
|
|
108
|
+
Load spatial transcriptomics data and return an annotated AnnData object.
|
|
109
|
+
|
|
110
|
+
Reads transcript-level data from a CSV, Parquet, or pre-built H5AD file,
|
|
111
|
+
constructs a sparse cell × gene count matrix, stores spatial coordinates,
|
|
112
|
+
writes a sidecar Parquet for lazy transcript access, and attaches two
|
|
113
|
+
convenience methods to the returned object:
|
|
114
|
+
|
|
115
|
+
* ``adata.summarize()`` – prints a structured overview (see :func:`_summarize`)
|
|
116
|
+
* ``adata.get_transcripts()`` – lazily loads the transcript table (see :func:`_attach_lazy_loader`)
|
|
117
|
+
|
|
118
|
+
Parameters
|
|
119
|
+
----------
|
|
120
|
+
filename : str
|
|
121
|
+
Path to the input file. Accepted formats:
|
|
122
|
+
|
|
123
|
+
* ``.parquet`` / ``.csv`` – raw transcript table with columns
|
|
124
|
+
``cell_id``, ``gene`` (or ``feature_name``), and optionally
|
|
125
|
+
``x_location``, ``y_location``, ``z_location``, ``qv``.
|
|
126
|
+
* ``.h5ad`` – previously saved AnnData; loaded directly and
|
|
127
|
+
returned after re-attaching the lazy-loader and summarize methods.
|
|
128
|
+
cell_type : str, optional
|
|
129
|
+
Path to a CSV file (index = cell IDs) containing a single column
|
|
130
|
+
of cell-type labels. Stored in ``adata.obs['cell_type']``.
|
|
131
|
+
region : str, optional
|
|
132
|
+
Path to a CSV file (index = cell IDs) containing a single column
|
|
133
|
+
of region labels. Stored in ``adata.obs['region']``.
|
|
134
|
+
qv_thresold : float, optional
|
|
135
|
+
Minimum quality-value score. Transcripts with ``qv < qv_threshold``
|
|
136
|
+
are dropped before matrix construction. No filtering if ``None``.
|
|
137
|
+
filter_genes : tuple[str, ...], optional
|
|
138
|
+
Gene-name prefixes to exclude (e.g. blanks, negative controls).
|
|
139
|
+
Default: ``('BLANK', 'NegControl', 'DeprecatedCodeword',
|
|
140
|
+
'UnassignedCodeword', 'Blank')``.
|
|
141
|
+
usr_label : str, optional
|
|
142
|
+
Cell-ID value used to mark unassigned transcripts. Rows with this
|
|
143
|
+
label are excluded from the count matrix but retained in the saved
|
|
144
|
+
transcript Parquet. Default: ``'UNASSIGNED'``.
|
|
145
|
+
overwrite : bool, optional
|
|
146
|
+
If ``True``, the sidecar Parquet is written to `filename` directly
|
|
147
|
+
instead of ``<stem>_scoubi.parquet``. Default: ``False``.
|
|
148
|
+
|
|
149
|
+
Returns
|
|
150
|
+
-------
|
|
151
|
+
ad.AnnData
|
|
152
|
+
AnnData object with:
|
|
153
|
+
|
|
154
|
+
* ``X`` – sparse (CSR) cell × gene count matrix
|
|
155
|
+
* ``obsm['spatial']`` – mean (x, y[, z]) coordinates per cell
|
|
156
|
+
* ``uns['transcripts_path']`` – path to the sidecar Parquet
|
|
157
|
+
* ``adata.summarize()`` – bound summary method
|
|
158
|
+
* ``adata.get_transcripts()`` – bound lazy transcript accessor
|
|
159
|
+
|
|
160
|
+
Raises
|
|
161
|
+
------
|
|
162
|
+
ValueError
|
|
163
|
+
If ``filename`` does not end with ``.csv``, ``.parquet``, or ``.h5ad``.
|
|
164
|
+
|
|
165
|
+
See Also
|
|
166
|
+
--------
|
|
167
|
+
_summarize : Prints a grouped overview of all AnnData fields.
|
|
168
|
+
_attach_lazy_loader : Attaches the ``get_transcripts()`` method.
|
|
169
|
+
"""
|
|
170
|
+
# --- read input ---
|
|
171
|
+
if filename.endswith('.parquet'):
|
|
172
|
+
df = pd.read_parquet(filename)
|
|
173
|
+
elif filename.endswith('.csv'):
|
|
174
|
+
df = pd.read_csv(filename)
|
|
175
|
+
elif filename.endswith('.h5ad'):
|
|
176
|
+
adata = ad.read_h5ad(filename)
|
|
177
|
+
if 'transcripts_path' in adata.uns:
|
|
178
|
+
_attach_lazy_loader(adata)
|
|
179
|
+
_attach_summarize(adata)
|
|
180
|
+
return adata
|
|
181
|
+
else:
|
|
182
|
+
raise ValueError("Unsupported file format. Use .csv, .parquet, or .h5ad.")
|
|
183
|
+
|
|
184
|
+
# --- filter ---
|
|
185
|
+
if 'qv' in df.columns and qv_thresold is not None:
|
|
186
|
+
df = df[df.qv >= qv_thresold]
|
|
187
|
+
if 'feature_name' in df.columns:
|
|
188
|
+
df = df.rename(columns={'feature_name':'gene'})
|
|
189
|
+
df = df[~df['gene'].str.startswith(tuple(filter_genes), na=False)]
|
|
190
|
+
df.sort_values(by=['cell_id'], inplace=True, ascending=True)
|
|
191
|
+
df_cell = df[df.cell_id != usr_label].copy()
|
|
192
|
+
|
|
193
|
+
# --- build sparse counts from df_cell ---
|
|
194
|
+
cell_codes, cell_uniques = pd.factorize(df_cell['cell_id'].astype(str))
|
|
195
|
+
gene_codes, gene_uniques = pd.factorize(df_cell['gene'].astype(str))
|
|
196
|
+
data = np.ones(len(df_cell), dtype=np.int32)
|
|
197
|
+
X = coo_matrix((data, (cell_codes, gene_codes)),
|
|
198
|
+
shape=(len(cell_uniques), len(gene_uniques))).tocsr()
|
|
199
|
+
|
|
200
|
+
obs = pd.DataFrame(index=cell_uniques.astype(str))
|
|
201
|
+
var = pd.DataFrame(index=gene_uniques.astype(str))
|
|
202
|
+
adata = ad.AnnData(X=X, obs=obs, var=var)
|
|
203
|
+
|
|
204
|
+
# --- spatial coordinates ---
|
|
205
|
+
loc_cols = ['x_location','y_location']
|
|
206
|
+
if 'z_location' in df_cell.columns:
|
|
207
|
+
loc_cols.append('z_location')
|
|
208
|
+
if loc_cols:
|
|
209
|
+
spatial = df_cell.groupby(df_cell['cell_id'].astype(str))[loc_cols].mean()
|
|
210
|
+
spatial = spatial.reindex(obs.index)
|
|
211
|
+
adata.obsm['spatial'] = spatial.values
|
|
212
|
+
|
|
213
|
+
# --- save transcripts parquet (full df) ---
|
|
214
|
+
if not overwrite:
|
|
215
|
+
parquet_path = os.path.abspath(os.path.splitext(filename)[0] + "_scoubi.parquet")
|
|
216
|
+
else:
|
|
217
|
+
parquet_path = os.path.abspath(filename)
|
|
218
|
+
df.to_parquet(parquet_path, index=False)
|
|
219
|
+
adata.uns['transcripts_path'] = parquet_path
|
|
220
|
+
_attach_lazy_loader(adata)
|
|
221
|
+
_attach_summarize(adata)
|
|
222
|
+
ad.AnnData.summarize = _summarize
|
|
223
|
+
adata._transcripts = LazyTranscripts(parquet_path) # optional pre-cache
|
|
224
|
+
|
|
225
|
+
# --- cell type annotations ---
|
|
226
|
+
if cell_type is not None:
|
|
227
|
+
df_ct = pd.read_csv(cell_type, index_col=0)
|
|
228
|
+
df_ct.index = df_ct.index.astype(str)
|
|
229
|
+
adata.obs['cell_type'] = df_ct.reindex(obs.index)
|
|
230
|
+
if region is not None:
|
|
231
|
+
df_rg = pd.read_csv(region, index_col=0)
|
|
232
|
+
df_rg.index = df_rg.index.astype(str)
|
|
233
|
+
adata.obs['region'] = df_rg.reindex(obs.index)
|
|
234
|
+
|
|
235
|
+
del df, X, data
|
|
236
|
+
return adata
|
scoubi/model/__init__.py
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
from ._annotate import train, get_zscore, do_conv, _prep_dict, kernel
|
|
@@ -0,0 +1,254 @@
|
|
|
1
|
+
import pandas as pd
|
|
2
|
+
import numpy as np
|
|
3
|
+
import torch
|
|
4
|
+
import torch.nn.functional as F
|
|
5
|
+
import torch.nn as nn
|
|
6
|
+
import torch.optim as optim
|
|
7
|
+
import pickle
|
|
8
|
+
import random
|
|
9
|
+
from importlib import resources
|
|
10
|
+
from tqdm import trange, tqdm
|
|
11
|
+
|
|
12
|
+
def set_seed(seed_value):
|
|
13
|
+
"""Sets the seed for reproducibility."""
|
|
14
|
+
random.seed(seed_value)
|
|
15
|
+
np.random.seed(seed_value)
|
|
16
|
+
torch.manual_seed(seed_value)
|
|
17
|
+
if torch.cuda.is_available():
|
|
18
|
+
torch.cuda.manual_seed(seed_value)
|
|
19
|
+
torch.cuda.manual_seed_all(seed_value)
|
|
20
|
+
# Configure PyTorch for deterministic operations
|
|
21
|
+
torch.backends.cudnn.deterministic = True
|
|
22
|
+
torch.backends.cudnn.benchmark = False
|
|
23
|
+
|
|
24
|
+
kernel = torch.tensor([[1., 1., 1.],[1., 0., 1.],[1., 1., 1.]]).unsqueeze(0).unsqueeze(0)
|
|
25
|
+
|
|
26
|
+
class BinAnnotator(nn.Module):
|
|
27
|
+
def __init__(self, input_dims):
|
|
28
|
+
super().__init__()
|
|
29
|
+
self.fcs = nn.ModuleList([nn.Linear(d, 1, bias=False) for d in input_dims])
|
|
30
|
+
# for fc in self.fcs:
|
|
31
|
+
# fc.weight.data.fill_(0.2)
|
|
32
|
+
|
|
33
|
+
def forward(self, x, temperature=1e-3):
|
|
34
|
+
splits = torch.split(x, [fc.in_features for fc in self.fcs], dim=1)
|
|
35
|
+
out = torch.cat([F.relu(fc(split) / (fc.in_features ** 0.5)) for fc, split in zip(self.fcs, splits)], dim=1)
|
|
36
|
+
return F.softmax(out / temperature, dim=1)
|
|
37
|
+
|
|
38
|
+
def score(self, x):
|
|
39
|
+
splits = torch.split(x, [fc.in_features for fc in self.fcs], dim=1)
|
|
40
|
+
out = torch.cat([F.relu(fc(split) / (fc.in_features ** 0.5)) for fc, split in zip(self.fcs, splits)], dim=1)
|
|
41
|
+
return out
|
|
42
|
+
|
|
43
|
+
def tstat_loss(X, P, eps=1e-8):
|
|
44
|
+
p1 = P.unsqueeze(1)
|
|
45
|
+
p2 = 1 - P.unsqueeze(1)
|
|
46
|
+
n1 = p1.sum()
|
|
47
|
+
n2 = p2.sum()
|
|
48
|
+
mu1 = torch.sum(p1 * X, dim=0) / (n1 + eps)
|
|
49
|
+
mu2 = torch.sum(p2 * X, dim=0) / (n2 + eps)
|
|
50
|
+
var1 = torch.sum(p1 * (X - mu1)**2, dim=0) / (n1 + eps)
|
|
51
|
+
var2 = torch.sum(p2 * (X - mu2)**2, dim=0) / (n2 + eps)
|
|
52
|
+
t_stat = (mu1 - mu2) / torch.sqrt(var1 / n1 + var2 / n2 + eps)
|
|
53
|
+
return -t_stat.mean()
|
|
54
|
+
|
|
55
|
+
def do_conv(matrix, kernel=None):
|
|
56
|
+
return F.conv2d(matrix[None, None, :, :], kernel, padding='same')[0, 0]
|
|
57
|
+
|
|
58
|
+
def precompute_zscore_shared(Z_1, Z_2, kernel, eps=1e-30):
|
|
59
|
+
"""Compute epoch-level invariants shared across all pairs."""
|
|
60
|
+
agg_Z_2 = do_conv(Z_2, kernel)
|
|
61
|
+
Z_prod = Z_1 * agg_Z_2
|
|
62
|
+
N = torch.sum(Z_prod)
|
|
63
|
+
Z_prod_sq_sum = torch.sum(Z_prod ** 2)
|
|
64
|
+
Z_1_sum = torch.sum(Z_1)
|
|
65
|
+
Z_2_sum = torch.sum(Z_2)
|
|
66
|
+
return agg_Z_2, Z_prod, N, Z_prod_sq_sum, Z_1_sum, Z_2_sum
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def get_zscore_pair(Z_1, Z_2, x_a, x_b, kernel,
|
|
70
|
+
agg_Z_2, Z_prod, N, Z_prod_sq_sum,
|
|
71
|
+
Z_1_sum, Z_2_sum, eps=1e-30, iid=True):
|
|
72
|
+
"""Compute z-score for a single pair using pre-computed shared tensors."""
|
|
73
|
+
agg_Z_2_x_b = do_conv(Z_2 * x_b, kernel)
|
|
74
|
+
X = torch.sum((Z_1 * x_a) * agg_Z_2_x_b)
|
|
75
|
+
p_a = torch.sum(x_a * Z_1) / (Z_1_sum + eps)
|
|
76
|
+
p_d = torch.sum(x_b * Z_2) / (Z_2_sum + eps)
|
|
77
|
+
E_x = N * p_a * p_d
|
|
78
|
+
if iid:
|
|
79
|
+
var_X = torch.clamp(E_x * (1 - p_a * p_d), min=eps)
|
|
80
|
+
else:
|
|
81
|
+
E_x_2 = Z_prod_sq_sum * (p_a * p_d) ** 2 + (N ** 2 - Z_prod_sq_sum) * (p_a * p_d) ** 2
|
|
82
|
+
var_X = torch.clamp(E_x + E_x_2 - E_x ** 2, min=eps)
|
|
83
|
+
return (X - E_x) / torch.sqrt(var_X)
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
def get_zscore(Z_1, Z_2, x_a, x_b, kernel, eps=1e-30, iid=True):
|
|
87
|
+
shared = precompute_zscore_shared(Z_1, Z_2, kernel, eps)
|
|
88
|
+
return get_zscore_pair(Z_1, Z_2, x_a, x_b, kernel, *shared, eps=eps, iid=iid)
|
|
89
|
+
|
|
90
|
+
def _prep_dict(array_usr, pairs, genes, device):
|
|
91
|
+
x_bin = {}
|
|
92
|
+
x_shape = (array_usr.shape[0], array_usr.shape[1])
|
|
93
|
+
gene_to_idx = {gene: i for i, gene in enumerate(genes)}
|
|
94
|
+
for gp in pairs:
|
|
95
|
+
for gene_name in gp:
|
|
96
|
+
g_idx = gene_to_idx.get(gene_name)
|
|
97
|
+
if g_idx is not None and g_idx not in x_bin:
|
|
98
|
+
x_bin[g_idx] = torch.from_numpy(array_usr[:, :, g_idx]).float().to(device)
|
|
99
|
+
return x_bin, x_shape, gene_to_idx
|
|
100
|
+
|
|
101
|
+
def train(adata, axon_markers, dendrite_markers, pairs = None, epochs = 500, lambda_gex = 1e-1, lambda_comm = 1, ftemp = 1e-1, patience = 50, lr = 1e-3, device='cpu', weight_decay=1e-4, seed = 42, tol = 1e-2, do_comm = True, iid=True):
|
|
102
|
+
"""Train the BinAnnotator model to assign spatial bins to axon or dendrite identity.
|
|
103
|
+
|
|
104
|
+
Optimizes a joint loss combining a GEX alignment term (t-statistic between
|
|
105
|
+
annotated compartments) and a communication term (z-score enrichment of
|
|
106
|
+
ligand-receptor co-localisation across neighbouring bins).
|
|
107
|
+
|
|
108
|
+
Parameters
|
|
109
|
+
----------
|
|
110
|
+
adata : AnnData
|
|
111
|
+
Spatial transcriptomics object. Must contain ``adata.uns['binned_data']``,
|
|
112
|
+
``adata.uns['binned_data_shape']``, ``adata.uns['mask_ecm']``, and
|
|
113
|
+
``adata.uns['genes']``.
|
|
114
|
+
axon_markers : list of str
|
|
115
|
+
Gene names used as axon compartment markers.
|
|
116
|
+
dendrite_markers : list of str
|
|
117
|
+
Gene names used as dendrite compartment markers.
|
|
118
|
+
pairs : list of (str, str) or None, optional
|
|
119
|
+
Ligand-receptor gene pairs for the communication loss. Defaults to the
|
|
120
|
+
bundled ``pairs.pkl`` resource.
|
|
121
|
+
epochs : int, optional
|
|
122
|
+
Maximum number of training epochs (default 500).
|
|
123
|
+
lambda_gex : float, optional
|
|
124
|
+
Weight for the GEX alignment loss term (default 0.1).
|
|
125
|
+
lambda_comm : float, optional
|
|
126
|
+
Weight for the communication loss term (default 1).
|
|
127
|
+
ftemp : float, optional
|
|
128
|
+
Softmax temperature used when computing final bin probabilities after
|
|
129
|
+
training (default 0.1).
|
|
130
|
+
patience : int, optional
|
|
131
|
+
Early-stopping patience in epochs (default 50).
|
|
132
|
+
lr : float, optional
|
|
133
|
+
AdamW learning rate (default 1e-3).
|
|
134
|
+
device : str, optional
|
|
135
|
+
Torch device string, e.g. ``'cpu'`` or ``'cuda'`` (default ``'cpu'``).
|
|
136
|
+
weight_decay : float, optional
|
|
137
|
+
AdamW weight decay (default 1e-4).
|
|
138
|
+
seed : int, optional
|
|
139
|
+
Random seed for reproducibility (default 42).
|
|
140
|
+
tol : float, optional
|
|
141
|
+
Minimum loss improvement required to reset the patience counter
|
|
142
|
+
(default 1e-2).
|
|
143
|
+
do_comm : bool, optional
|
|
144
|
+
Whether to include the communication loss (default True).
|
|
145
|
+
iid : bool, optional
|
|
146
|
+
Variance model for the communication z-score. ``True`` (default) uses
|
|
147
|
+
the fast closed-form ``var = E[X] * (1 - p_a * p_d)``; ``False`` uses
|
|
148
|
+
the full spatial covariance formula.
|
|
149
|
+
|
|
150
|
+
Returns
|
|
151
|
+
-------
|
|
152
|
+
AnnData
|
|
153
|
+
The input ``adata`` updated in-place with the following keys in
|
|
154
|
+
``adata.uns``: ``'model_weights'``, ``'bin_probabilities'``,
|
|
155
|
+
``'bin_scores'``, ``'lr_pairs'``, ``'axon_markers'``,
|
|
156
|
+
``'dendrite_markers'``.
|
|
157
|
+
"""
|
|
158
|
+
set_seed(seed)
|
|
159
|
+
if pairs is None:
|
|
160
|
+
with resources.open_binary("scoubi.data", "pairs.pkl") as fp:
|
|
161
|
+
pairs = pickle.load(fp)
|
|
162
|
+
genes = list(adata.uns['genes'])
|
|
163
|
+
pairs = [pair for pair in pairs if pair[0] in genes and pair[1] in genes]
|
|
164
|
+
array_usr = (adata.uns['binned_data'].toarray().reshape(adata.uns['binned_data_shape']) * adata.uns["mask_ecm"][:, :, None]).copy()
|
|
165
|
+
axon_markers = [gene for gene in axon_markers if gene in genes]
|
|
166
|
+
dendrite_markers = [gene for gene in dendrite_markers if gene in genes]
|
|
167
|
+
axon_idx = [genes.index(gene) for gene in axon_markers]
|
|
168
|
+
dendrite_idx = [genes.index(gene) for gene in dendrite_markers]
|
|
169
|
+
|
|
170
|
+
taxon_markers = {"Axon": axon_markers, "Dendrite": dendrite_markers}
|
|
171
|
+
num_cts = len(taxon_markers)
|
|
172
|
+
selected_cts = list(taxon_markers.keys())
|
|
173
|
+
ct_genes, len_idx, ct_genes_idx = [], [], []
|
|
174
|
+
for ct in selected_cts:
|
|
175
|
+
ct_genes.extend(taxon_markers[ct])
|
|
176
|
+
len_idx.append(len(taxon_markers[ct]))
|
|
177
|
+
for gene in taxon_markers[ct]:
|
|
178
|
+
ct_genes_idx.append(genes.index(gene))
|
|
179
|
+
|
|
180
|
+
x_all = torch.from_numpy(array_usr[:, :, ct_genes_idx]).float().flatten(0, 1).to(device)
|
|
181
|
+
x_mask = (x_all.sum(axis = 1) != 0).unsqueeze(1).float().clone()
|
|
182
|
+
ct_markers_gex = {ct: torch.from_numpy(array_usr[:, :, [genes.index(x) for x in taxon_markers[ct]]]).float().flatten(0, 1).to(device) for ct in selected_cts}
|
|
183
|
+
|
|
184
|
+
x_bin, x_shape, gene_to_idx = _prep_dict(array_usr, pairs, genes, device)
|
|
185
|
+
|
|
186
|
+
model = BinAnnotator(input_dims=len_idx).to(device)
|
|
187
|
+
optimizer = optim.AdamW(model.parameters(), lr=lr, weight_decay=weight_decay)
|
|
188
|
+
model.train()
|
|
189
|
+
patience_counter = 0
|
|
190
|
+
best_loss = float('inf')
|
|
191
|
+
best_model_weights = None
|
|
192
|
+
|
|
193
|
+
kernel_dev = kernel.to(device)
|
|
194
|
+
pbar = trange(epochs, desc="Training", unit="epoch")
|
|
195
|
+
for epoch in pbar:
|
|
196
|
+
optimizer.zero_grad()
|
|
197
|
+
temperature = 1e-3
|
|
198
|
+
Z = model(x_all, temperature)
|
|
199
|
+
Z = Z * x_mask
|
|
200
|
+
|
|
201
|
+
# GEX loss
|
|
202
|
+
gex_loss = 0.0
|
|
203
|
+
for n, ct_name in enumerate(selected_cts):
|
|
204
|
+
gex_loss += tstat_loss(ct_markers_gex[ct_name], Z[:, n])
|
|
205
|
+
gex_loss_term = (lambda_gex * gex_loss) / num_cts
|
|
206
|
+
|
|
207
|
+
# Communication loss
|
|
208
|
+
Z_a = Z[:, 0].reshape(x_shape)
|
|
209
|
+
Z_d = Z[:, 1].reshape(x_shape)
|
|
210
|
+
ct_loss_for_n1 = 0.0
|
|
211
|
+
if do_comm:
|
|
212
|
+
shared = precompute_zscore_shared(Z_a, Z_d, kernel_dev)
|
|
213
|
+
for gp in pairs:
|
|
214
|
+
a_idx, b_idx = gene_to_idx.get(gp[0]), gene_to_idx.get(gp[1])
|
|
215
|
+
if a_idx is None or b_idx is None or a_idx not in x_bin or b_idx not in x_bin:
|
|
216
|
+
continue
|
|
217
|
+
x_a, x_b = x_bin[a_idx], x_bin[b_idx]
|
|
218
|
+
ct_loss_for_n1 -= get_zscore_pair(Z_a, Z_d, x_a, x_b, kernel_dev, *shared, iid=iid)
|
|
219
|
+
|
|
220
|
+
total_loss = gex_loss_term + (lambda_comm * ct_loss_for_n1 / len(pairs))
|
|
221
|
+
total_loss.backward()
|
|
222
|
+
optimizer.step()
|
|
223
|
+
|
|
224
|
+
comm_term = (ct_loss_for_n1 / len(pairs)).item() if do_comm else ct_loss_for_n1
|
|
225
|
+
pbar.set_description(
|
|
226
|
+
f"Epoch {epoch+1}/{epochs} | Total: {total_loss.item():.6f} | GEX: {gex_loss_term.item():.6f} | Comm: {comm_term:.6f} | Patience: {patience_counter}/{patience}"
|
|
227
|
+
)
|
|
228
|
+
|
|
229
|
+
# Early stopping logic
|
|
230
|
+
current_loss = total_loss.item()
|
|
231
|
+
if current_loss < best_loss - tol:
|
|
232
|
+
best_loss = current_loss
|
|
233
|
+
patience_counter = 0
|
|
234
|
+
best_model_weights = model.state_dict()
|
|
235
|
+
else:
|
|
236
|
+
patience_counter += 1
|
|
237
|
+
if patience_counter >= patience:
|
|
238
|
+
print(f"\nEarly stopping at epoch {epoch}. Loss did not improve for {patience} epochs.")
|
|
239
|
+
break
|
|
240
|
+
|
|
241
|
+
if best_model_weights:
|
|
242
|
+
model.load_state_dict(best_model_weights)
|
|
243
|
+
adata.uns["model_weights"] = {k: v.cpu().numpy() for k, v in best_model_weights.items()}
|
|
244
|
+
model.eval()
|
|
245
|
+
with torch.no_grad():
|
|
246
|
+
Z = model(x_all, temperature=ftemp).cpu().numpy()
|
|
247
|
+
Z_score = model.score(x_all).cpu().numpy()
|
|
248
|
+
adata.uns["bin_probabilities"] = Z
|
|
249
|
+
adata.uns['lr_pairs'] = pairs
|
|
250
|
+
adata.uns['axon_markers'] = axon_markers
|
|
251
|
+
adata.uns['dendrite_markers'] = dendrite_markers
|
|
252
|
+
adata.uns['bin_scores'] = Z_score
|
|
253
|
+
return adata
|
|
254
|
+
|