laior 0.6.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.
Files changed (60) hide show
  1. laior/__init__.py +7 -0
  2. laior/agent.py +452 -0
  3. laior/benchmarking.py +338 -0
  4. laior/distributions/EuclideanNormal/__init__.py +15 -0
  5. laior/distributions/EuclideanNormal/arguments.py +3 -0
  6. laior/distributions/EuclideanNormal/distribution.py +26 -0
  7. laior/distributions/EuclideanNormal/layers.py +35 -0
  8. laior/distributions/EuclideanNormal/prior.py +18 -0
  9. laior/distributions/HWNormal/__init__.py +15 -0
  10. laior/distributions/HWNormal/arguments.py +3 -0
  11. laior/distributions/HWNormal/distribution.py +56 -0
  12. laior/distributions/HWNormal/layers.py +44 -0
  13. laior/distributions/HWNormal/prior.py +24 -0
  14. laior/distributions/LearnablePGMNormal/__init__.py +24 -0
  15. laior/distributions/LearnablePGMNormal/arguments.py +4 -0
  16. laior/distributions/LearnablePGMNormal/distribution.py +81 -0
  17. laior/distributions/LearnablePGMNormal/layers.py +218 -0
  18. laior/distributions/LearnablePGMNormal/prior.py +18 -0
  19. laior/distributions/PGMNormal/__init__.py +24 -0
  20. laior/distributions/PGMNormal/arguments.py +4 -0
  21. laior/distributions/PGMNormal/distribution.py +71 -0
  22. laior/distributions/PGMNormal/layers.py +82 -0
  23. laior/distributions/PGMNormal/prior.py +18 -0
  24. laior/distributions/PoincareNormal/__init__.py +16 -0
  25. laior/distributions/PoincareNormal/arguments.py +4 -0
  26. laior/distributions/PoincareNormal/ars.py +133 -0
  27. laior/distributions/PoincareNormal/distribution.py +56 -0
  28. laior/distributions/PoincareNormal/hyperbolic_radius.py +360 -0
  29. laior/distributions/PoincareNormal/hyperbolic_uniform.py +43 -0
  30. laior/distributions/PoincareNormal/layers.py +45 -0
  31. laior/distributions/PoincareNormal/prior.py +18 -0
  32. laior/distributions/__init__.py +0 -0
  33. laior/distributions/utils.py +21 -0
  34. laior/environment.py +548 -0
  35. laior/examples/encoder_example.py +58 -0
  36. laior/interpretation.py +1205 -0
  37. laior/mixin.py +829 -0
  38. laior/model.py +412 -0
  39. laior/module.py +463 -0
  40. laior/ode_functions.py +313 -0
  41. laior/unified_models/__init__.py +53 -0
  42. laior/unified_models/base_model.py +361 -0
  43. laior/unified_models/cellblast_model.py +349 -0
  44. laior/unified_models/clear_model.py +258 -0
  45. laior/unified_models/gmvae_model.py +560 -0
  46. laior/unified_models/scalex_model.py +352 -0
  47. laior/unified_models/scdac_model.py +269 -0
  48. laior/unified_models/scdeepcluster_model.py +300 -0
  49. laior/unified_models/scdhmap_model.py +454 -0
  50. laior/unified_models/scdiffusion_model.py +479 -0
  51. laior/unified_models/scgcc_model.py +374 -0
  52. laior/unified_models/scgnn_model.py +210 -0
  53. laior/unified_models/scsmd_model.py +387 -0
  54. laior/unified_models/sivae_model.py +460 -0
  55. laior/utils.py +481 -0
  56. laior-0.6.0.dist-info/METADATA +264 -0
  57. laior-0.6.0.dist-info/RECORD +60 -0
  58. laior-0.6.0.dist-info/WHEEL +5 -0
  59. laior-0.6.0.dist-info/licenses/LICENSE +21 -0
  60. laior-0.6.0.dist-info/top_level.txt +1 -0
laior/__init__.py ADDED
@@ -0,0 +1,7 @@
1
+ from .agent import LAIOR
2
+
3
+ # Backward compatibility alias
4
+ Liora = LAIOR
5
+
6
+ __all__ = ['LAIOR', 'Liora']
7
+ __version__ = '0.6.0'
laior/agent.py ADDED
@@ -0,0 +1,452 @@
1
+ """
2
+ LAIOR: Lorentz Attentive Interpretable ODE Regularized VAE
3
+ ===========================================================
4
+
5
+ A unified deep learning framework for single-cell omics analysis combining:
6
+ - Variational Autoencoder (VAE) for dimensionality reduction
7
+ - Lorentz geometric regularization for hierarchical structure
8
+ - Dual-path information bottleneck for coordinated biological programs
9
+ - Neural ODE regularization for trajectory stability
10
+ - Transformer-based attention mechanisms for long-range dependencies
11
+ - Multiple count-based likelihood functions (NB, ZINB, Poisson, ZIP)
12
+
13
+ Supports both scRNA-seq and scATAC-seq modalities without architectural modification.
14
+ """
15
+
16
+ # ============================================================================
17
+ # agent.py - Main User Interface
18
+ # ============================================================================
19
+ from .mixin import VectorFieldMixin
20
+ from .environment import Env
21
+ from anndata import AnnData
22
+ from typing import Optional
23
+ import torch
24
+ import tqdm
25
+ import time
26
+
27
+ class LAIOR(Env, VectorFieldMixin):
28
+ """
29
+ LAIOR: Lorentz Attentive Interpretable ODE Regularized VAE
30
+
31
+ A unified framework for single-cell omics analysis (scRNA-seq and scATAC-seq) that
32
+ learns low-dimensional representations while preserving both local cell-state structure
33
+ and global hierarchical organization through Lorentz geometric regularization,
34
+ information bottleneck architecture, and neural ODE-based trajectory stabilization.
35
+
36
+ Architecture Overview
37
+ ---------------------
38
+ 1. **Encoder**: Maps high-dimensional gene expression to latent space
39
+ 2. **Information Bottleneck**: Optional compression layer for hierarchical features
40
+ 3. **Manifold Regularization**: Lorentz or Euclidean distance constraints
41
+ 4. **Decoder**: Reconstructs gene expression with count-appropriate likelihoods
42
+ 5. **ODE Solver** (optional): Models continuous cell state trajectories
43
+
44
+ Parameters
45
+ ----------
46
+ adata : AnnData
47
+ Annotated data matrix with raw count data in `adata.layers[layer]`
48
+ layer : str, default='counts'
49
+ Layer name containing raw unnormalized count data
50
+ recon : float, default=1.0
51
+ Weight for reconstruction loss (primary objective)
52
+ irecon : float, default=0.0
53
+ Weight for information bottleneck reconstruction loss
54
+ lorentz : float, default=0.0
55
+ Weight for geometric manifold regularization
56
+ beta : float, default=1.0
57
+ Weight for KL divergence (β-VAE); >1 encourages disentanglement
58
+ dip : float, default=0.0
59
+ Weight for Disentangled Inferred Prior (DIP-VAE) loss
60
+ tc : float, default=0.0
61
+ Weight for Total Correlation (β-TC-VAE) loss
62
+ info : float, default=0.0
63
+ Weight for Maximum Mean Discrepancy (InfoVAE) loss
64
+ hidden_dim : int, default=128
65
+ Hidden layer dimension in encoder/decoder
66
+ latent_dim : int, default=10
67
+ Primary latent space dimensionality
68
+ i_dim : int, default=2
69
+ Information bottleneck dimension (should be < latent_dim)
70
+ lr : float, default=1e-4
71
+ Learning rate for Adam optimizer
72
+ use_bottleneck_lorentz : bool, default=True
73
+ If True, compute manifold distance on bottleneck; else on resampled latents
74
+ loss_type : str, default='nb'
75
+ Count likelihood model:
76
+ - 'nb': Negative Binomial (recommended for UMI data)
77
+ - 'zinb': Zero-Inflated Negative Binomial (high dropout)
78
+ - 'poisson': Poisson (simple baseline)
79
+ - 'zip': Zero-Inflated Poisson
80
+ grad_clip : float, default=1.0
81
+ Gradient clipping threshold for training stability
82
+ adaptive_norm : bool, default=True
83
+ Use dataset-specific normalization heuristics
84
+ use_layer_norm : bool, default=True
85
+ Apply layer normalization in encoder/decoder
86
+ use_euclidean_manifold : bool, default=False
87
+ Use Euclidean distance instead of Lorentz (hyperbolic) distance
88
+ use_ode : bool, default=False
89
+ Enable Neural ODE regularization for trajectory inference
90
+ vae_reg : float, default=0.5
91
+ Weight for VAE path in ODE mode (should sum to 1.0 with ode_reg)
92
+ ode_reg : float, default=0.5
93
+ Weight for ODE path in ODE mode
94
+ train_size : float, default=0.7
95
+ Proportion of cells for training set
96
+ val_size : float, default=0.15
97
+ Proportion of cells for validation set
98
+ test_size : float, default=0.15
99
+ Proportion of cells for test set (should sum to 1.0)
100
+ batch_size : int, default=128
101
+ Mini-batch size for stochastic gradient descent
102
+ random_seed : int, default=42
103
+ Random seed for reproducibility
104
+ device : torch.device, optional
105
+ Computation device (auto-detects CUDA if available)
106
+ encoder_type : str, default='mlp'
107
+ Encoder backbone: 'mlp' (default) or 'transformer'
108
+ attn_embed_dim : int, default=64
109
+ Embedding dimension for transformer-based encoder
110
+ attn_num_heads : int, default=4
111
+ Number of attention heads for transformer encoder
112
+ attn_num_layers : int, default=2
113
+ Number of transformer encoder layers
114
+ attn_seq_len : int, default=32
115
+ Pseudo-sequence length used in transformer encoder
116
+ ode_type : str, default='time_mlp'
117
+ ODE function type: 'legacy', 'time_mlp', or 'gru'
118
+ ode_time_cond : str, default='concat'
119
+ Time conditioning strategy for 'time_mlp' ODE: 'concat', 'film', or 'add'
120
+ ode_hidden_dim : int, optional
121
+ Hidden dimension for ODE function (defaults to hidden_dim when None)
122
+ ode_solver_method : str, default='rk4'
123
+ ODE solver method: 'rk4' (fixed step) or 'dopri5' (adaptive)
124
+ ode_step_size : float, optional
125
+ Step size for fixed-step solvers (e.g., 'rk4'); use 'auto' to infer
126
+ ode_rtol : float, optional
127
+ Relative tolerance for adaptive solvers (e.g., 'dopri5')
128
+ ode_atol : float, optional
129
+ Absolute tolerance for adaptive solvers (e.g., 'dopri5')
130
+
131
+ Attributes
132
+ ----------
133
+ nn : VAE
134
+ The neural network model
135
+ train_losses : list
136
+ Training loss history
137
+ val_losses : list
138
+ Validation loss history
139
+ best_val_loss : float
140
+ Best validation loss achieved (for early stopping)
141
+
142
+ Examples
143
+ --------
144
+ >>> import scanpy as sc
145
+ >>> from laior import LAIOR
146
+ >>>
147
+ >>> # Load data
148
+ >>> adata = sc.read_h5ad('data.h5ad')
149
+ >>>
150
+ >>> # Basic usage with default parameters
151
+ >>> model = LAIOR(adata, layer='counts')
152
+ >>> model.fit(epochs=100)
153
+ >>> latent = model.get_latent()
154
+ >>>
155
+ >>> # Advanced: with manifold regularization and ODE
156
+ >>> model = LAIOR(
157
+ ... adata,
158
+ ... lorentz=5.0, # Enable Lorentz regularization
159
+ ... use_ode=True, # Enable trajectory inference
160
+ ... latent_dim=10,
161
+ ... i_dim=2
162
+ ... )
163
+ >>> model.fit(epochs=400, patience=25)
164
+ >>>
165
+ >>> # Get embeddings and trajectories
166
+ >>> latent = model.get_latent()
167
+ >>> bottleneck = model.get_bottleneck()
168
+ >>> pseudotime = model.get_time() # ODE mode only
169
+ >>> transitions = model.get_transition() # ODE mode only
170
+ """
171
+
172
+ def __init__(
173
+ self,
174
+ adata: AnnData,
175
+ layer: str = 'counts',
176
+ recon: float = 1.0,
177
+ irecon: float = 0.0,
178
+ lorentz: float = 0.0,
179
+ beta: float = 1.0,
180
+ dip: float = 0.0,
181
+ tc: float = 0.0,
182
+ info: float = 0.0,
183
+ hidden_dim: int = 128,
184
+ latent_dim: int = 10,
185
+ i_dim: int = 2,
186
+ lr: float = 1e-4,
187
+ use_bottleneck_lorentz: bool = True,
188
+ loss_type: str = 'nb',
189
+ grad_clip: float = 1.0,
190
+ adaptive_norm: bool = True,
191
+ use_layer_norm: bool = True,
192
+ use_euclidean_manifold: bool = False,
193
+ use_ode: bool = False,
194
+ vae_reg: float = 0.5,
195
+ ode_reg: float = 0.5,
196
+ train_size: float = 0.7,
197
+ val_size: float = 0.15,
198
+ test_size: float = 0.15,
199
+ batch_size: int = 128,
200
+ random_seed: int = 42,
201
+ device : torch.device = None,
202
+ # Encoder selection and attention hyperparameters
203
+ encoder_type: str = 'mlp',
204
+ attn_embed_dim: int = 64,
205
+ attn_num_heads: int = 4,
206
+ attn_num_layers: int = 2,
207
+ attn_seq_len: int = 32,
208
+ # ODE function and solver parameters
209
+ ode_type: str = 'time_mlp',
210
+ ode_time_cond: str = 'concat',
211
+ ode_hidden_dim: Optional[int] = None,
212
+ ode_solver_method: str = 'rk4',
213
+ ode_step_size: Optional[float] = None,
214
+ ode_rtol: Optional[float] = None,
215
+ ode_atol: Optional[float] = None,
216
+ ):
217
+ # Auto-detect device
218
+ if device is None:
219
+ device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
220
+
221
+ # Validate parameters
222
+ if not (0.99 <= train_size + val_size + test_size <= 1.01):
223
+ raise ValueError(f"Split sizes must sum to 1.0, got {train_size + val_size + test_size}")
224
+
225
+ if use_ode and not (0.99 <= vae_reg + ode_reg <= 1.01):
226
+ raise ValueError(f"ODE weights must sum to 1.0, got {vae_reg + ode_reg}")
227
+
228
+ if i_dim >= latent_dim:
229
+ raise ValueError(f"Information bottleneck dimension ({i_dim}) must be < latent dimension ({latent_dim})")
230
+
231
+ # Initialize parent environment
232
+ super().__init__(
233
+ adata=adata,
234
+ layer=layer,
235
+ recon=recon,
236
+ irecon=irecon,
237
+ lorentz=lorentz,
238
+ beta=beta,
239
+ dip=dip,
240
+ tc=tc,
241
+ info=info,
242
+ hidden_dim=hidden_dim,
243
+ latent_dim=latent_dim,
244
+ i_dim=i_dim,
245
+ lr=lr,
246
+ use_bottleneck_lorentz=use_bottleneck_lorentz,
247
+ loss_type=loss_type,
248
+ grad_clip=grad_clip,
249
+ adaptive_norm=adaptive_norm,
250
+ use_layer_norm=use_layer_norm,
251
+ use_euclidean_manifold=use_euclidean_manifold,
252
+ use_ode=use_ode,
253
+ vae_reg=vae_reg,
254
+ ode_reg=ode_reg,
255
+ train_size=train_size,
256
+ val_size=val_size,
257
+ test_size=test_size,
258
+ batch_size=batch_size,
259
+ random_seed=random_seed,
260
+ device=device,
261
+ ode_type=ode_type,
262
+ ode_time_cond=ode_time_cond,
263
+ ode_hidden_dim=ode_hidden_dim,
264
+ ode_solver_method=ode_solver_method,
265
+ ode_step_size=ode_step_size,
266
+ ode_rtol=ode_rtol,
267
+ ode_atol=ode_atol,
268
+ encoder_type=encoder_type,
269
+ attn_embed_dim=attn_embed_dim,
270
+ attn_num_heads=attn_num_heads,
271
+ attn_num_layers=attn_num_layers,
272
+ attn_seq_len=attn_seq_len
273
+ )
274
+
275
+ # Resource tracking
276
+ self.train_time = 0.0
277
+ self.peak_memory_gb = 0.0
278
+ self.actual_epochs = 0
279
+
280
+ def fit(
281
+ self,
282
+ epochs: int = 400,
283
+ patience: int = 25,
284
+ val_every: int = 5,
285
+ early_stop: bool = True,
286
+ ):
287
+ """
288
+ Train the LAIOR model with mini-batch gradient descent.
289
+
290
+ Training uses:
291
+ - Adam optimizer with configurable learning rate
292
+ - Early stopping based on validation loss
293
+ - Gradient clipping for stability
294
+ - Periodic validation every `val_every` epochs
295
+
296
+ Parameters
297
+ ----------
298
+ epochs : int, default=400
299
+ Maximum number of training epochs
300
+ patience : int, default=25
301
+ Early stopping patience (epochs without validation improvement)
302
+ val_every : int, default=5
303
+ Validation frequency (every N epochs)
304
+ early_stop : bool, default=True
305
+ Enable early stopping mechanism
306
+
307
+ Returns
308
+ -------
309
+ self : LAIOR
310
+ Returns self for method chaining
311
+
312
+ Notes
313
+ -----
314
+ Progress bar displays:
315
+ - Train: Training loss
316
+ - Val: Validation loss
317
+ - ARI: Adjusted Rand Index
318
+ - NMI: Normalized Mutual Information
319
+ - ASW: Average Silhouette Width
320
+ - CAL: Calinski-Harabasz score
321
+ - DAV: Davies-Bouldin score
322
+ - COR: Average correlation per dimension
323
+ - Best: Best validation loss seen
324
+ - Pat: Patience counter
325
+ """
326
+ use_cuda = torch.cuda.is_available()
327
+ if use_cuda:
328
+ torch.cuda.reset_peak_memory_stats()
329
+ start_time = time.time()
330
+
331
+ with tqdm.tqdm(total=epochs, desc="Training", ncols=200) as pbar:
332
+ for epoch in range(epochs):
333
+ # Train for one complete epoch
334
+ train_loss = self.train_epoch()
335
+
336
+ # Periodic validation
337
+ if (epoch + 1) % val_every == 0 or epoch == 0:
338
+ val_loss, val_score = self.validate()
339
+
340
+ if early_stop:
341
+ # Check if we should stop early
342
+ should_stop, improved = self.check_early_stopping(
343
+ val_loss, patience
344
+ )
345
+
346
+ # Update progress bar
347
+ pbar.set_postfix({
348
+ "Train": f"{train_loss:.2f}",
349
+ "Val": f"{val_loss:.2f}",
350
+ "ARI": f"{val_score[0]:.2f}",
351
+ "NMI": f"{val_score[1]:.2f}",
352
+ "ASW": f"{val_score[2]:.2f}",
353
+ "CAL": f"{val_score[3]:.2f}",
354
+ "DAV": f"{val_score[4]:.2f}",
355
+ "COR": f"{val_score[5]:.2f}",
356
+ "Best": f"{self.best_val_loss:.2f}",
357
+ "Pat": f"{self.patience_counter}/{patience}",
358
+ "Imp": "✓" if improved else "✗"
359
+ })
360
+
361
+ if should_stop:
362
+ self.actual_epochs = epoch + 1
363
+ print(f"\n\nEarly stopping at epoch {epoch + 1}")
364
+ print(f"Best validation loss: {self.best_val_loss:.4f}")
365
+ self.load_best_model()
366
+ break
367
+ else:
368
+ # No early stopping - just display metrics
369
+ pbar.set_postfix({
370
+ "Train": f"{train_loss:.2f}",
371
+ "Val": f"{val_loss:.2f}",
372
+ "ARI": f"{val_score[0]:.2f}",
373
+ "NMI": f"{val_score[1]:.2f}",
374
+ "ASW": f"{val_score[2]:.2f}",
375
+ "CAL": f"{val_score[3]:.2f}",
376
+ "DAV": f"{val_score[4]:.2f}",
377
+ "COR": f"{val_score[5]:.2f}",
378
+ })
379
+
380
+ pbar.update(1)
381
+ else:
382
+ self.actual_epochs = epochs
383
+
384
+ # Record resource usage
385
+ self.train_time = time.time() - start_time
386
+ self.peak_memory_gb = torch.cuda.max_memory_allocated() / 1e9 if use_cuda else 0.0
387
+ return self
388
+
389
+ def get_latent(self):
390
+ """
391
+ Extract latent representations for all cells.
392
+
393
+ In standard mode, returns encoder output.
394
+ In ODE mode, returns weighted combination of VAE and ODE paths.
395
+
396
+ Returns
397
+ -------
398
+ latent : ndarray of shape (n_cells, latent_dim)
399
+ Low-dimensional cell embeddings
400
+ """
401
+ return self.take_latent(self.X_norm)
402
+
403
+ def get_time(self):
404
+ """
405
+ Extract pseudotime for all cells.
406
+ """
407
+ return self.take_time(self.X_norm)
408
+
409
+ def get_transition(self):
410
+ """
411
+ Extract transition probabilities for all cells.
412
+ """
413
+ return self.take_transition(self.X_norm)
414
+
415
+ def get_test_latent(self):
416
+ """
417
+ Extract latent representations for test set only.
418
+ """
419
+ return self.take_latent(self.X_test_norm)
420
+
421
+ def get_bottleneck(self):
422
+ """
423
+ Extract information bottleneck representations.
424
+
425
+ The bottleneck layer compresses latent features to a lower-dimensional
426
+ space (i_dim), capturing the most essential information for reconstruction.
427
+
428
+ Returns
429
+ -------
430
+ bottleneck : ndarray of shape (n_cells, i_dim)
431
+ Compressed hierarchical representations
432
+ """
433
+ x = torch.tensor(self.X_norm, dtype=torch.float32).to(self.device)
434
+ with torch.no_grad():
435
+ outputs = self.nn(x)
436
+ le = outputs[4] # Information bottleneck encoding
437
+ return le.cpu().numpy()
438
+
439
+ def get_resource_metrics(self):
440
+ """
441
+ Get training resource usage metrics.
442
+
443
+ Returns
444
+ -------
445
+ metrics : dict
446
+ Dictionary with 'train_time', 'peak_memory_gb', 'actual_epochs'
447
+ """
448
+ return {
449
+ 'train_time': self.train_time,
450
+ 'peak_memory_gb': self.peak_memory_gb,
451
+ 'actual_epochs': self.actual_epochs
452
+ }