scCODE 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.
- CODE/__init__.py +28 -0
- CODE/agent.py +571 -0
- CODE/environment.py +149 -0
- CODE/mixin.py +317 -0
- CODE/model.py +624 -0
- CODE/module.py +499 -0
- CODE/utils.py +232 -0
- sccode-0.1.0.dist-info/METADATA +366 -0
- sccode-0.1.0.dist-info/RECORD +12 -0
- sccode-0.1.0.dist-info/WHEEL +5 -0
- sccode-0.1.0.dist-info/licenses/LICENSE +21 -0
- sccode-0.1.0.dist-info/top_level.txt +1 -0
CODE/__init__.py
ADDED
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
"""
|
|
2
|
+
CODE: Correlated Latent Space Learning and Continuum Modeling of Single Cell Data
|
|
3
|
+
|
|
4
|
+
A Python package for advanced single-cell RNA sequencing data analysis using
|
|
5
|
+
Variational Autoencoders (VAE) with optional Neural Ordinary Differential Equations (ODE)
|
|
6
|
+
for modeling cellular dynamics and developmental trajectories.
|
|
7
|
+
|
|
8
|
+
Main Components:
|
|
9
|
+
- Agent: High-level interface for model training and inference
|
|
10
|
+
- VAE: Variational autoencoder with multiple loss function options
|
|
11
|
+
- ODE: Neural ODE for continuous trajectory modeling
|
|
12
|
+
- MoCo: Momentum contrast for unsupervised contrastive learning
|
|
13
|
+
|
|
14
|
+
Example:
|
|
15
|
+
>>> from CODE import Agent
|
|
16
|
+
>>> import scanpy as sc
|
|
17
|
+
>>>
|
|
18
|
+
>>> adata = sc.read_h5ad("data.h5ad")
|
|
19
|
+
>>> agent = Agent(adata, layer="counts", use_ode=True)
|
|
20
|
+
>>> agent.fit(epochs=1000)
|
|
21
|
+
>>> latent = agent.get_latent()
|
|
22
|
+
"""
|
|
23
|
+
|
|
24
|
+
from .agent import Agent
|
|
25
|
+
|
|
26
|
+
__all__ = ['Agent']
|
|
27
|
+
|
|
28
|
+
__version__ = '0.1.0'
|
CODE/agent.py
ADDED
|
@@ -0,0 +1,571 @@
|
|
|
1
|
+
from .environment import Env
|
|
2
|
+
from .utils import quiver_autoscale, l2_norm
|
|
3
|
+
import scanpy as sc
|
|
4
|
+
from anndata import AnnData
|
|
5
|
+
import torch
|
|
6
|
+
import tqdm
|
|
7
|
+
from typing import Optional, Literal
|
|
8
|
+
import numpy as np
|
|
9
|
+
from scipy.sparse import csr_matrix, coo_matrix
|
|
10
|
+
from scipy.stats import norm
|
|
11
|
+
from sklearn.neighbors import NearestNeighbors
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
class Agent(Env):
|
|
15
|
+
"""
|
|
16
|
+
Main agent class for training and inference with single-cell data.
|
|
17
|
+
|
|
18
|
+
This class provides a high-level interface for training variational autoencoders
|
|
19
|
+
(VAE) with optional Neural ODE components on single-cell data. It handles data
|
|
20
|
+
loading, model training, and extraction of various representations including
|
|
21
|
+
latent embeddings, pseudotime, and velocity fields.
|
|
22
|
+
|
|
23
|
+
Inherits from Env which combines the model (CODEVAE) and environment functionality.
|
|
24
|
+
|
|
25
|
+
Attributes:
|
|
26
|
+
adata (AnnData): The annotated data object
|
|
27
|
+
X (np.ndarray): Preprocessed data matrix (log1p transformed)
|
|
28
|
+
n_obs (int): Number of observations (cells)
|
|
29
|
+
n_var (int): Number of variables (genes)
|
|
30
|
+
batch_size (int): Batch size for training
|
|
31
|
+
loss (list): Training loss history
|
|
32
|
+
score (list): Evaluation metrics history
|
|
33
|
+
"""
|
|
34
|
+
|
|
35
|
+
def __init__(
|
|
36
|
+
self,
|
|
37
|
+
adata: AnnData,
|
|
38
|
+
layer: str = "counts",
|
|
39
|
+
percent: float = 0.01,
|
|
40
|
+
recon: float = 1.0,
|
|
41
|
+
irecon: float = 0.0,
|
|
42
|
+
beta: float = 1.0,
|
|
43
|
+
dip: float = 0.0,
|
|
44
|
+
tc: float = 0.0,
|
|
45
|
+
info: float = 0.0,
|
|
46
|
+
hidden_dim: int = 128,
|
|
47
|
+
latent_dim: int = 10,
|
|
48
|
+
i_dim: int = 2,
|
|
49
|
+
use_ode: bool = False,
|
|
50
|
+
use_moco: bool = False,
|
|
51
|
+
loss_mode: Literal["mse", "nb", "zinb"] = "nb",
|
|
52
|
+
lr: float = 1e-4,
|
|
53
|
+
vae_reg: float = 0.5,
|
|
54
|
+
ode_reg: float = 0.5,
|
|
55
|
+
moco_weight: float = 1,
|
|
56
|
+
device: torch.device = torch.device("cuda")
|
|
57
|
+
if torch.cuda.is_available()
|
|
58
|
+
else torch.device("cpu"),
|
|
59
|
+
):
|
|
60
|
+
super().__init__(
|
|
61
|
+
adata=adata,
|
|
62
|
+
layer=layer,
|
|
63
|
+
percent=percent,
|
|
64
|
+
recon=recon,
|
|
65
|
+
irecon=irecon,
|
|
66
|
+
beta=beta,
|
|
67
|
+
dip=dip,
|
|
68
|
+
tc=tc,
|
|
69
|
+
info=info,
|
|
70
|
+
hidden_dim=hidden_dim,
|
|
71
|
+
latent_dim=latent_dim,
|
|
72
|
+
i_dim=i_dim,
|
|
73
|
+
use_ode=use_ode,
|
|
74
|
+
use_moco=use_moco,
|
|
75
|
+
loss_mode=loss_mode,
|
|
76
|
+
lr=lr,
|
|
77
|
+
vae_reg=vae_reg,
|
|
78
|
+
ode_reg=ode_reg,
|
|
79
|
+
moco_weight=moco_weight,
|
|
80
|
+
device=device,
|
|
81
|
+
)
|
|
82
|
+
|
|
83
|
+
def fit(self, epochs: int = 1000):
|
|
84
|
+
"""
|
|
85
|
+
Train the VAE model on the single-cell data.
|
|
86
|
+
|
|
87
|
+
Performs iterative training with mini-batch sampling. Progress is displayed
|
|
88
|
+
with a progress bar showing loss and evaluation metrics (updated every 10 epochs).
|
|
89
|
+
|
|
90
|
+
Args:
|
|
91
|
+
epochs (int): Number of training epochs. Default is 1000.
|
|
92
|
+
|
|
93
|
+
Returns:
|
|
94
|
+
Agent: Self reference for method chaining.
|
|
95
|
+
|
|
96
|
+
Metrics displayed:
|
|
97
|
+
- Loss: Total training loss
|
|
98
|
+
- ARI: Adjusted Rand Index (clustering similarity)
|
|
99
|
+
- NMI: Normalized Mutual Information (clustering similarity)
|
|
100
|
+
- ASW: Average Silhouette Width (cluster separation)
|
|
101
|
+
- C_H: Calinski-Harabasz score (cluster density)
|
|
102
|
+
- D_B: Davies-Bouldin score (cluster separation, lower is better)
|
|
103
|
+
- P_C: Pearson Correlation (latent dimension correlation)
|
|
104
|
+
"""
|
|
105
|
+
with tqdm.tqdm(total=int(epochs), desc="Fitting", ncols=150) as pbar:
|
|
106
|
+
for i in range(int(epochs)):
|
|
107
|
+
data = self.load_data()
|
|
108
|
+
self.step(data)
|
|
109
|
+
if (i + 1) % 10 == 0:
|
|
110
|
+
pbar.set_postfix(
|
|
111
|
+
{
|
|
112
|
+
"Loss": f"{self.loss[-1][0]:.2f}",
|
|
113
|
+
"ARI": f"{(self.score[-1][0]):.2f}",
|
|
114
|
+
"NMI": f"{(self.score[-1][1]):.2f}",
|
|
115
|
+
"ASW": f"{(self.score[-1][2]):.2f}",
|
|
116
|
+
"C_H": f"{(self.score[-1][3]):.2f}",
|
|
117
|
+
"D_B": f"{(self.score[-1][4]):.2f}",
|
|
118
|
+
"P_C": f"{(self.score[-1][5]):.2f}",
|
|
119
|
+
}
|
|
120
|
+
)
|
|
121
|
+
pbar.update(1)
|
|
122
|
+
return self
|
|
123
|
+
|
|
124
|
+
def get_iembed(
|
|
125
|
+
self,
|
|
126
|
+
):
|
|
127
|
+
"""
|
|
128
|
+
Extract information bottleneck embeddings from the trained model.
|
|
129
|
+
|
|
130
|
+
The information bottleneck is a lower-dimensional representation (i_dim)
|
|
131
|
+
that compresses the latent space further, encouraging more compact and
|
|
132
|
+
interpretable representations.
|
|
133
|
+
|
|
134
|
+
Returns:
|
|
135
|
+
np.ndarray: Information bottleneck embeddings of shape (n_obs, i_dim).
|
|
136
|
+
"""
|
|
137
|
+
iembed = self.take_iembed(self.X)
|
|
138
|
+
return iembed
|
|
139
|
+
|
|
140
|
+
def get_latent(
|
|
141
|
+
self,
|
|
142
|
+
):
|
|
143
|
+
"""
|
|
144
|
+
Extract latent space representations from the trained model.
|
|
145
|
+
|
|
146
|
+
For ODE models, this combines both VAE and ODE predictions weighted by
|
|
147
|
+
vae_reg and ode_reg parameters. For standard VAE, returns the encoder output.
|
|
148
|
+
|
|
149
|
+
Returns:
|
|
150
|
+
np.ndarray: Latent representations of shape (n_obs, latent_dim).
|
|
151
|
+
"""
|
|
152
|
+
latent = self.take_latent(self.X)
|
|
153
|
+
return latent
|
|
154
|
+
|
|
155
|
+
def get_time(
|
|
156
|
+
self,
|
|
157
|
+
):
|
|
158
|
+
"""
|
|
159
|
+
Extract predicted pseudotime for each cell.
|
|
160
|
+
|
|
161
|
+
Only available when use_ode=True. Pseudotime represents the inferred
|
|
162
|
+
developmental or temporal progression of cells, ranging from 0 to 1.
|
|
163
|
+
|
|
164
|
+
Returns:
|
|
165
|
+
np.ndarray: Pseudotime values of shape (n_obs,).
|
|
166
|
+
|
|
167
|
+
Raises:
|
|
168
|
+
RuntimeError: If model was not trained with use_ode=True.
|
|
169
|
+
"""
|
|
170
|
+
time = self.take_time(self.X)
|
|
171
|
+
return time
|
|
172
|
+
|
|
173
|
+
def get_impute(
|
|
174
|
+
self, top_k: int = 30, alpha: float = 0.9, steps: int = 3, decay: float = 0.99
|
|
175
|
+
):
|
|
176
|
+
"""
|
|
177
|
+
Impute gene expression values using learned cell-cell transition probabilities.
|
|
178
|
+
|
|
179
|
+
This method uses the ODE-derived velocity field to construct a transition matrix
|
|
180
|
+
between cells, then performs multi-step imputation by propagating information
|
|
181
|
+
through the cell neighborhood graph.
|
|
182
|
+
|
|
183
|
+
Args:
|
|
184
|
+
top_k (int): Number of nearest neighbors to consider for sparse transition
|
|
185
|
+
matrix. Default is 30.
|
|
186
|
+
alpha (float): Blending weight between original and imputed data.
|
|
187
|
+
0 = use original data, 1 = use fully imputed data. Default is 0.9.
|
|
188
|
+
steps (int): Number of diffusion steps for multi-step imputation.
|
|
189
|
+
Default is 3.
|
|
190
|
+
decay (float): Decay factor for multi-step imputation weighting.
|
|
191
|
+
Default is 0.99.
|
|
192
|
+
|
|
193
|
+
Returns:
|
|
194
|
+
np.ndarray: Imputed data matrix of same shape as input (n_obs, n_var).
|
|
195
|
+
|
|
196
|
+
Note:
|
|
197
|
+
Requires use_ode=True during model initialization.
|
|
198
|
+
"""
|
|
199
|
+
T = self.take_transition(self.X, top_k)
|
|
200
|
+
|
|
201
|
+
def multi_step_impute(T, X, steps, decay):
|
|
202
|
+
"""
|
|
203
|
+
Perform multi-step diffusion through transition matrix.
|
|
204
|
+
|
|
205
|
+
Args:
|
|
206
|
+
T (np.ndarray): Transition probability matrix
|
|
207
|
+
X (np.ndarray): Input data matrix
|
|
208
|
+
steps (int): Number of diffusion steps
|
|
209
|
+
decay (float): Decay factor for weighting
|
|
210
|
+
|
|
211
|
+
Returns:
|
|
212
|
+
np.ndarray: Imputed data after multi-step diffusion
|
|
213
|
+
"""
|
|
214
|
+
X_current = X.copy()
|
|
215
|
+
X_imputed = X.copy()
|
|
216
|
+
for i in range(steps):
|
|
217
|
+
X_current = T @ X_current
|
|
218
|
+
X_imputed = X_imputed + decay**i * X_current
|
|
219
|
+
X_imputed = X_imputed / (1 + sum(decay**i for i in range(steps)))
|
|
220
|
+
return X_imputed
|
|
221
|
+
|
|
222
|
+
def balanced_impute(T, X, alpha=0.5, steps=3, decay=0.9):
|
|
223
|
+
"""
|
|
224
|
+
Blend original and imputed data.
|
|
225
|
+
|
|
226
|
+
Args:
|
|
227
|
+
T (np.ndarray): Transition probability matrix
|
|
228
|
+
X (np.ndarray): Input data matrix
|
|
229
|
+
alpha (float): Blending weight
|
|
230
|
+
steps (int): Number of diffusion steps
|
|
231
|
+
decay (float): Decay factor
|
|
232
|
+
|
|
233
|
+
Returns:
|
|
234
|
+
np.ndarray: Balanced imputed data
|
|
235
|
+
"""
|
|
236
|
+
X_imputed = multi_step_impute(T, X, steps, decay)
|
|
237
|
+
X_balanced = (1 - alpha) * X + alpha * X_imputed
|
|
238
|
+
return X_balanced
|
|
239
|
+
|
|
240
|
+
return balanced_impute(T, self.X, alpha, steps, decay)
|
|
241
|
+
|
|
242
|
+
def get_vfres(
|
|
243
|
+
self,
|
|
244
|
+
adata: AnnData,
|
|
245
|
+
zs_key: str,
|
|
246
|
+
E_key: str,
|
|
247
|
+
vf_key: str = "X_vf",
|
|
248
|
+
T_key: str = "cosine_similarity",
|
|
249
|
+
dv_key: str = "X_dv",
|
|
250
|
+
reverse: bool = False,
|
|
251
|
+
run_neigh: bool = True,
|
|
252
|
+
use_rep_neigh: Optional[str] = None,
|
|
253
|
+
t_key: Optional[str] = None,
|
|
254
|
+
n_neigh: int = 20,
|
|
255
|
+
var_stabilize_transform: bool = False,
|
|
256
|
+
scale: int = 10,
|
|
257
|
+
self_transition: bool = False,
|
|
258
|
+
smooth: float = 0.5,
|
|
259
|
+
stream: bool = True,
|
|
260
|
+
density: float = 1.0,
|
|
261
|
+
):
|
|
262
|
+
"""
|
|
263
|
+
Compute velocity field results for visualization and analysis.
|
|
264
|
+
|
|
265
|
+
This method computes the velocity field (vector field) in a 2D embedding space
|
|
266
|
+
(e.g., UMAP, t-SNE) based on the ODE gradients in the latent space. It includes
|
|
267
|
+
computing similarity matrices, transition probabilities, and gridded vector fields.
|
|
268
|
+
|
|
269
|
+
Args:
|
|
270
|
+
adata (AnnData): Annotated data object to store results
|
|
271
|
+
zs_key (str): Key in adata.obsm for latent space coordinates
|
|
272
|
+
E_key (str): Key in adata.obsm for 2D embedding (e.g., 'X_umap')
|
|
273
|
+
vf_key (str): Key to store velocity field gradients. Default 'X_vf'
|
|
274
|
+
T_key (str): Key to store transition similarity matrix. Default 'cosine_similarity'
|
|
275
|
+
dv_key (str): Key to store displacement vectors. Default 'X_dv'
|
|
276
|
+
reverse (bool): Whether to reverse velocity direction. Default False
|
|
277
|
+
run_neigh (bool): Whether to recompute neighbors. Default True
|
|
278
|
+
use_rep_neigh (Optional[str]): Representation for neighbor computation. Default uses zs_key
|
|
279
|
+
t_key (Optional[str]): Key in adata.obs for pseudotime-based neighbors
|
|
280
|
+
n_neigh (int): Number of neighbors. Default 20
|
|
281
|
+
var_stabilize_transform (bool): Apply variance stabilization. Default False
|
|
282
|
+
scale (int): Scaling factor for transition probabilities. Default 10
|
|
283
|
+
self_transition (bool): Include self-transitions. Default False
|
|
284
|
+
smooth (float): Smoothing parameter for grid interpolation. Default 0.5
|
|
285
|
+
stream (bool): Format output for streamplot. Default True
|
|
286
|
+
density (float): Grid density for vector field. Default 1.0
|
|
287
|
+
|
|
288
|
+
Returns:
|
|
289
|
+
tuple: (E_grid, V_grid) containing:
|
|
290
|
+
- E_grid: Grid coordinates for embedding space
|
|
291
|
+
- V_grid: Velocity vectors at grid points
|
|
292
|
+
|
|
293
|
+
Note:
|
|
294
|
+
Requires use_ode=True during model initialization.
|
|
295
|
+
"""
|
|
296
|
+
# Compute gradients in latent space from ODE
|
|
297
|
+
grads = self.take_grad(self.X)
|
|
298
|
+
adata.obsm[vf_key] = grads
|
|
299
|
+
|
|
300
|
+
# Compute cosine similarity-based transition matrix
|
|
301
|
+
adata.obsp[T_key] = self.get_similarity(
|
|
302
|
+
adata,
|
|
303
|
+
zs_key=zs_key,
|
|
304
|
+
vf_key=vf_key,
|
|
305
|
+
reverse=reverse,
|
|
306
|
+
run_neigh=run_neigh,
|
|
307
|
+
use_rep_neigh=use_rep_neigh,
|
|
308
|
+
t_key=t_key,
|
|
309
|
+
n_neigh=n_neigh,
|
|
310
|
+
var_stabilize_transform=var_stabilize_transform,
|
|
311
|
+
)
|
|
312
|
+
|
|
313
|
+
# Project velocity field onto 2D embedding
|
|
314
|
+
adata.obsm[dv_key] = self.get_vf(
|
|
315
|
+
adata,
|
|
316
|
+
T_key=T_key,
|
|
317
|
+
E_key=E_key,
|
|
318
|
+
scale=scale,
|
|
319
|
+
self_transition=self_transition,
|
|
320
|
+
)
|
|
321
|
+
|
|
322
|
+
# Create gridded vector field for visualization
|
|
323
|
+
E = np.array(adata.obsm[E_key])
|
|
324
|
+
V = adata.obsm[dv_key]
|
|
325
|
+
E_grid, V_grid = self.get_vfgrid(
|
|
326
|
+
E=E,
|
|
327
|
+
V=V,
|
|
328
|
+
smooth=smooth,
|
|
329
|
+
stream=stream,
|
|
330
|
+
density=density,
|
|
331
|
+
)
|
|
332
|
+
return E_grid, V_grid
|
|
333
|
+
|
|
334
|
+
def get_similarity(
|
|
335
|
+
self,
|
|
336
|
+
adata: AnnData,
|
|
337
|
+
zs_key: str,
|
|
338
|
+
vf_key: str = "X_vf",
|
|
339
|
+
reverse: bool = False,
|
|
340
|
+
run_neigh: bool = True,
|
|
341
|
+
use_rep_neigh: Optional[str] = None,
|
|
342
|
+
t_key: Optional[str] = None,
|
|
343
|
+
n_neigh: int = 20,
|
|
344
|
+
var_stabilize_transform: bool = False,
|
|
345
|
+
):
|
|
346
|
+
"""
|
|
347
|
+
Compute cell-cell similarity matrix based on velocity field alignment.
|
|
348
|
+
|
|
349
|
+
This method calculates cosine similarity between the velocity field direction
|
|
350
|
+
and the displacement vectors between cells in latent space. High similarity
|
|
351
|
+
indicates that a cell is likely to transition toward another cell.
|
|
352
|
+
|
|
353
|
+
Args:
|
|
354
|
+
adata (AnnData): Annotated data object
|
|
355
|
+
zs_key (str): Key in adata.obsm for latent space coordinates
|
|
356
|
+
vf_key (str): Key in adata.obsm for velocity field. Default 'X_vf'
|
|
357
|
+
reverse (bool): Reverse velocity direction. Default False
|
|
358
|
+
run_neigh (bool): Whether to compute neighbors. Default True
|
|
359
|
+
use_rep_neigh (Optional[str]): Representation for neighbor computation
|
|
360
|
+
t_key (Optional[str]): Key for pseudotime-based neighbor selection
|
|
361
|
+
n_neigh (int): Number of neighbors. Default 20
|
|
362
|
+
var_stabilize_transform (bool): Apply sqrt variance stabilization. Default False
|
|
363
|
+
|
|
364
|
+
Returns:
|
|
365
|
+
scipy.sparse.csr_matrix: Similarity matrix of shape (n_obs, n_obs) with
|
|
366
|
+
values in range [-1, 1] representing cosine similarity.
|
|
367
|
+
"""
|
|
368
|
+
Z = np.array(adata.obsm[zs_key])
|
|
369
|
+
V = np.array(adata.obsm[vf_key])
|
|
370
|
+
if reverse:
|
|
371
|
+
V = -V
|
|
372
|
+
if var_stabilize_transform:
|
|
373
|
+
V = np.sqrt(np.abs(V)) * np.sign(V)
|
|
374
|
+
|
|
375
|
+
ncells = adata.n_obs
|
|
376
|
+
|
|
377
|
+
# Compute or use existing neighbor graph
|
|
378
|
+
if run_neigh or ("neighbors" not in adata.uns):
|
|
379
|
+
if use_rep_neigh is None:
|
|
380
|
+
use_rep_neigh = zs_key
|
|
381
|
+
else:
|
|
382
|
+
if use_rep_neigh not in adata.obsm:
|
|
383
|
+
raise KeyError(
|
|
384
|
+
f"`{use_rep_neigh}` not found in `.obsm` of the AnnData. Please provide valid `use_rep_neigh` for neighbor detection."
|
|
385
|
+
)
|
|
386
|
+
sc.pp.neighbors(adata, use_rep=use_rep_neigh, n_neighbors=n_neigh)
|
|
387
|
+
n_neigh = adata.uns["neighbors"]["params"]["n_neighbors"] - 1
|
|
388
|
+
|
|
389
|
+
# Compute pseudotime-based neighbors if provided
|
|
390
|
+
if t_key is not None:
|
|
391
|
+
if t_key not in adata.obs:
|
|
392
|
+
raise KeyError(
|
|
393
|
+
f"`{t_key}` not found in `.obs` of the AnnData. Please provide valid `t_key` for estimated pseudotime."
|
|
394
|
+
)
|
|
395
|
+
ts = adata.obs[t_key].values
|
|
396
|
+
indices_matrix2 = np.zeros((ncells, n_neigh), dtype=int)
|
|
397
|
+
for i in range(ncells):
|
|
398
|
+
idx = np.abs(ts - ts[i]).argsort()[: (n_neigh + 1)]
|
|
399
|
+
idx = np.setdiff1d(idx, i) if i in idx else idx[:-1]
|
|
400
|
+
indices_matrix2[i] = idx
|
|
401
|
+
|
|
402
|
+
# Compute cosine similarity for each cell with its neighbors
|
|
403
|
+
vals, rows, cols = [], [], []
|
|
404
|
+
for i in range(ncells):
|
|
405
|
+
# Get first and second-order neighbors
|
|
406
|
+
idx = adata.obsp["distances"][i].indices
|
|
407
|
+
idx2 = adata.obsp["distances"][idx].indices
|
|
408
|
+
idx2 = np.setdiff1d(idx2, i)
|
|
409
|
+
idx = (
|
|
410
|
+
np.unique(np.concatenate([idx, idx2]))
|
|
411
|
+
if t_key is None
|
|
412
|
+
else np.unique(np.concatenate([idx, idx2, indices_matrix2[i]]))
|
|
413
|
+
)
|
|
414
|
+
|
|
415
|
+
# Compute displacement vectors
|
|
416
|
+
dZ = Z[idx] - Z[i, None]
|
|
417
|
+
if var_stabilize_transform:
|
|
418
|
+
dZ = np.sqrt(np.abs(dZ)) * np.sign(dZ)
|
|
419
|
+
|
|
420
|
+
# Compute cosine similarity between displacement and velocity
|
|
421
|
+
cos_sim = np.einsum("ij, j", dZ, V[i]) / (
|
|
422
|
+
l2_norm(dZ, axis=1) * l2_norm(V[i])
|
|
423
|
+
)
|
|
424
|
+
cos_sim[np.isnan(cos_sim)] = 0
|
|
425
|
+
vals.extend(cos_sim)
|
|
426
|
+
rows.extend(np.repeat(i, len(idx)))
|
|
427
|
+
cols.extend(idx)
|
|
428
|
+
|
|
429
|
+
res = coo_matrix((vals, (rows, cols)), shape=(ncells, ncells))
|
|
430
|
+
res.data = np.clip(res.data, -1, 1)
|
|
431
|
+
return res.tocsr()
|
|
432
|
+
|
|
433
|
+
def get_vf(
|
|
434
|
+
self,
|
|
435
|
+
adata: AnnData,
|
|
436
|
+
T_key: str,
|
|
437
|
+
E_key: str,
|
|
438
|
+
scale: int = 10,
|
|
439
|
+
self_transition: bool = False,
|
|
440
|
+
):
|
|
441
|
+
"""
|
|
442
|
+
Project velocity field from latent space to 2D embedding space.
|
|
443
|
+
|
|
444
|
+
This method uses the transition probability matrix to compute expected
|
|
445
|
+
displacement vectors in the embedding space (e.g., UMAP, t-SNE).
|
|
446
|
+
|
|
447
|
+
Args:
|
|
448
|
+
adata (AnnData): Annotated data object
|
|
449
|
+
T_key (str): Key in adata.obsp for transition similarity matrix
|
|
450
|
+
E_key (str): Key in adata.obsm for 2D embedding coordinates
|
|
451
|
+
scale (int): Exponential scaling factor for transition probabilities.
|
|
452
|
+
Higher values emphasize strong transitions. Default 10
|
|
453
|
+
self_transition (bool): Include self-transition probabilities. Default False
|
|
454
|
+
|
|
455
|
+
Returns:
|
|
456
|
+
np.ndarray: Displacement vectors in embedding space of shape (n_obs, 2).
|
|
457
|
+
"""
|
|
458
|
+
T = adata.obsp[T_key].copy()
|
|
459
|
+
|
|
460
|
+
# Optionally add self-transitions for stability
|
|
461
|
+
if self_transition:
|
|
462
|
+
max_t = T.max(1).A.flatten()
|
|
463
|
+
ub = np.percentile(max_t, 98)
|
|
464
|
+
self_t = np.clip(ub - max_t, 0, 1)
|
|
465
|
+
T.setdiag(self_t)
|
|
466
|
+
|
|
467
|
+
# Apply exponential scaling and normalize to probabilities
|
|
468
|
+
T = T.sign().multiply(np.expm1(abs(T * scale)))
|
|
469
|
+
T = T.multiply(csr_matrix(1.0 / abs(T).sum(1)))
|
|
470
|
+
if self_transition:
|
|
471
|
+
T.setdiag(0)
|
|
472
|
+
T.eliminate_zeros()
|
|
473
|
+
|
|
474
|
+
E = np.array(adata.obsm[E_key])
|
|
475
|
+
V = np.zeros(E.shape)
|
|
476
|
+
|
|
477
|
+
# Compute expected displacement for each cell
|
|
478
|
+
for i in range(adata.n_obs):
|
|
479
|
+
idx = T[i].indices
|
|
480
|
+
dE = E[idx] - E[i, None]
|
|
481
|
+
dE /= l2_norm(dE)[:, None]
|
|
482
|
+
dE[np.isnan(dE)] = 0
|
|
483
|
+
prob = T[i].data
|
|
484
|
+
# Weighted average displacement minus mean to center
|
|
485
|
+
V[i] = prob.dot(dE) - prob.mean() * dE.sum(0)
|
|
486
|
+
|
|
487
|
+
# Normalize for visualization
|
|
488
|
+
V /= 3 * quiver_autoscale(E, V)
|
|
489
|
+
return V
|
|
490
|
+
|
|
491
|
+
def get_vfgrid(
|
|
492
|
+
self,
|
|
493
|
+
E: np.ndarray,
|
|
494
|
+
V: np.ndarray,
|
|
495
|
+
smooth: float = 0.5,
|
|
496
|
+
stream: bool = True,
|
|
497
|
+
density: float = 1.0,
|
|
498
|
+
):
|
|
499
|
+
"""
|
|
500
|
+
Interpolate velocity field onto a regular grid for visualization.
|
|
501
|
+
|
|
502
|
+
Creates a gridded representation of the velocity field suitable for
|
|
503
|
+
matplotlib's streamplot or quiver functions.
|
|
504
|
+
|
|
505
|
+
Args:
|
|
506
|
+
E (np.ndarray): Embedding coordinates of shape (n_obs, 2)
|
|
507
|
+
V (np.ndarray): Velocity vectors of shape (n_obs, 2)
|
|
508
|
+
smooth (float): Smoothing bandwidth for Gaussian kernel. Default 0.5
|
|
509
|
+
stream (bool): Format output for streamplot (True) or quiver (False). Default True
|
|
510
|
+
density (float): Grid density multiplier. Default 1.0
|
|
511
|
+
|
|
512
|
+
Returns:
|
|
513
|
+
tuple: (E_grid, V_grid)
|
|
514
|
+
- If stream=True: E_grid is (2, n, n) coordinate arrays, V_grid is (2, n, n) velocity
|
|
515
|
+
- If stream=False: E_grid is (m, 2) grid points, V_grid is (m, 2) velocities
|
|
516
|
+
"""
|
|
517
|
+
# Create grid along each dimension
|
|
518
|
+
grs = []
|
|
519
|
+
for i in range(E.shape[1]):
|
|
520
|
+
m, M = np.min(E[:, i]), np.max(E[:, i])
|
|
521
|
+
diff = M - m
|
|
522
|
+
m = m - 0.01 * diff
|
|
523
|
+
M = M + 0.01 * diff
|
|
524
|
+
gr = np.linspace(m, M, int(50 * density))
|
|
525
|
+
grs.append(gr)
|
|
526
|
+
|
|
527
|
+
meshes = np.meshgrid(*grs)
|
|
528
|
+
E_grid = np.vstack([i.flat for i in meshes]).T
|
|
529
|
+
|
|
530
|
+
# Find nearest neighbors for each grid point
|
|
531
|
+
n_neigh = int(E.shape[0] / 50)
|
|
532
|
+
nn = NearestNeighbors(n_neighbors=n_neigh, n_jobs=-1)
|
|
533
|
+
nn.fit(E)
|
|
534
|
+
dists, neighs = nn.kneighbors(E_grid)
|
|
535
|
+
|
|
536
|
+
# Gaussian kernel weighting based on distance
|
|
537
|
+
scale = np.mean([g[1] - g[0] for g in grs]) * smooth
|
|
538
|
+
weight = norm.pdf(x=dists, scale=scale)
|
|
539
|
+
weight_sum = weight.sum(1)
|
|
540
|
+
|
|
541
|
+
# Interpolate velocities with weighted average
|
|
542
|
+
V_grid = (V[neighs] * weight[:, :, None]).sum(1)
|
|
543
|
+
V_grid /= np.maximum(1, weight_sum)[:, None]
|
|
544
|
+
|
|
545
|
+
if stream:
|
|
546
|
+
# Format for streamplot
|
|
547
|
+
E_grid = np.stack(grs)
|
|
548
|
+
ns = E_grid.shape[1]
|
|
549
|
+
V_grid = V_grid.T.reshape(2, ns, ns)
|
|
550
|
+
|
|
551
|
+
# Filter out low-magnitude and low-confidence regions
|
|
552
|
+
mass = np.sqrt((V_grid * V_grid).sum(0))
|
|
553
|
+
min_mass = 1e-5
|
|
554
|
+
min_mass = np.clip(min_mass, None, np.percentile(mass, 99) * 0.01)
|
|
555
|
+
cutoff1 = mass < min_mass
|
|
556
|
+
|
|
557
|
+
length = np.sum(np.mean(np.abs(V[neighs]), axis=1), axis=1).reshape(ns, ns)
|
|
558
|
+
cutoff2 = length < np.percentile(length, 5)
|
|
559
|
+
|
|
560
|
+
cutoff = cutoff1 | cutoff2
|
|
561
|
+
V_grid[0][cutoff] = np.nan
|
|
562
|
+
else:
|
|
563
|
+
# Format for quiver plot - filter by weight
|
|
564
|
+
min_weight = np.percentile(weight_sum, 99) * 0.01
|
|
565
|
+
E_grid, V_grid = (
|
|
566
|
+
E_grid[weight_sum > min_weight],
|
|
567
|
+
V_grid[weight_sum > min_weight],
|
|
568
|
+
)
|
|
569
|
+
V_grid /= 3 * quiver_autoscale(E_grid, V_grid)
|
|
570
|
+
|
|
571
|
+
return E_grid, V_grid
|