iaode 0.2.2__tar.gz → 0.2.3__tar.gz

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.
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2024 Zeyu Fu
3
+ Copyright (c) 2025 Zeyu Fu
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: iaode
3
- Version: 0.2.2
3
+ Version: 0.2.3
4
4
  Summary: Interpretable Autoencoder with Ordinary Differential Equations for single-cell omics analysis
5
5
  Author-email: Zeyu Fu <fuzeyu99@126.com>
6
6
  License: MIT
@@ -64,7 +64,7 @@ The design targets the unique characteristics of scATAC data: extreme sparsity,
64
64
 
65
65
  ## Core Architecture
66
66
 
67
- ```
67
+ ```text
68
68
  Raw Peak Counts --(TF-IDF)--> Normalized Matrix --(HVP Selection)--> Peak Subset
69
69
  |
70
70
  v
@@ -80,6 +80,7 @@ Encoder (MLP / Residual / Transformer) --> q(z|x)
80
80
  ```
81
81
 
82
82
  **Key Components**:
83
+
83
84
  - **TF‑IDF Normalization**: Stabilizes cell‑wise peak depth, emphasizes specific accessibility
84
85
  - **Highly Variable Peaks (HVP)**: Variance / VMR / deviance‑based selection
85
86
  - **NB/ZINB Likelihoods**: Models over‑dispersion & zero inflation
@@ -88,7 +89,8 @@ Encoder (MLP / Residual / Transformer) --> q(z|x)
88
89
  - **Multi‑Objective Regularization**: β‑VAE KL, β‑TC, DIP, InfoVAE MMD, ODE consistency
89
90
 
90
91
  **Loss Function**:
91
- ```
92
+
93
+ ```python
92
94
  Loss = recon + i_recon + ODE_consistency + β·KL + dip·DIP + tc·TC + info·MMD
93
95
  ```
94
96
 
@@ -434,6 +436,7 @@ adata = iaode.annotation_pipeline(
434
436
  ```
435
437
 
436
438
  **Returns AnnData with:**
439
+
437
440
  - `adata.var['peak_type']`: Peak annotation (promoter/exonic/intronic/intergenic)
438
441
  - `adata.var['gene_name']`: Associated gene names
439
442
  - `adata.var['distance_to_tss']`: Distance to nearest TSS
@@ -631,6 +634,7 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
631
634
  ## Acknowledgments
632
635
 
633
636
  Built upon ideas from:
637
+
634
638
  - **scVI-tools**: scVI, PEAKVI, POISSONVI architectures
635
639
  - **Signac** and **SnapATAC2**: scATAC-seq best practices
636
640
  - **Neural ODE** literature: Continuous latent dynamics
@@ -642,53 +646,10 @@ PyTorch, AnnData, and Scanpy ecosystems provide the foundation.
642
646
  ## Contact
643
647
 
644
648
  - **GitHub Issues**: [https://github.com/PeterPonyu/iAODE/issues](https://github.com/PeterPonyu/iAODE/issues)
645
- - **Email**: fuzeyu99@126.com
649
+ - **Email**: <fuzeyu99@126.com>
646
650
 
647
651
  ---
648
652
 
649
653
  ## Changelog
650
654
 
651
- ### v0.2.0 (2025-11-20)
652
-
653
- **Documentation & Usability**
654
- - Comprehensive documentation overhaul (README, examples/README, QUICKSTART)
655
- - Separated scRNA-seq and scATAC-seq workflows with clear examples
656
- - Added automatic dataset download and caching system
657
- - Created `examples/data/download_data.sh` helper script
658
- - Verified all API usage examples against actual implementation
659
-
660
- **Code Quality**
661
- - Cleaned example scripts: removed unused imports, improved error handling
662
- - Fixed all cross-references between examples and core modules
663
- - Enhanced inline documentation and error messages
664
- - Verified method signatures: `get_velocity()`, `get_vfres()`, `get_pseudotime()`, etc.
665
-
666
- **Package Improvements**
667
- - Complete scATAC-seq preprocessing pipeline with TF-IDF and HVP selection
668
- - Improved peak annotation with distance-to-TSS computation
669
- - Enhanced evaluation metrics (DRE + LSE frameworks)
670
- - Better handling of sparse data and zero inflation
671
-
672
- ### v0.1.2 (2025-11-19)
673
-
674
- **Metadata & Contact**
675
- - Updated author name to "Zeyu Fu"
676
- - Set primary contact email to fuzeyu99@126.com
677
- - Fixed BibTeX citation formatting
678
-
679
- ### v0.1.1 (2025-11-19)
680
-
681
- **Bug Fixes**
682
- - Added missing `requests` dependency for scvi-tools compatibility
683
- - Dropped Python 3.8 support (requires Python ≥3.9)
684
- - Fixed CI test imports and matrix configuration
685
-
686
- ### v0.1.0 (2025-11-19)
687
-
688
- **Initial Release**
689
- - VAE with Neural ODE support for trajectory inference
690
- - Complete scATAC-seq peak annotation pipeline
691
- - Comprehensive evaluation metrics
692
- - Benchmark framework vs scVI models
693
- - Multiple encoder types (MLP, Residual, Transformer, Linear)
694
- - Multiple loss modes (MSE, NB, ZINB)
655
+ See [CHANGELOG.md](CHANGELOG.md) for detailed release notes and version history.
@@ -15,7 +15,7 @@ The design targets the unique characteristics of scATAC data: extreme sparsity,
15
15
 
16
16
  ## Core Architecture
17
17
 
18
- ```
18
+ ```text
19
19
  Raw Peak Counts --(TF-IDF)--> Normalized Matrix --(HVP Selection)--> Peak Subset
20
20
  |
21
21
  v
@@ -31,6 +31,7 @@ Encoder (MLP / Residual / Transformer) --> q(z|x)
31
31
  ```
32
32
 
33
33
  **Key Components**:
34
+
34
35
  - **TF‑IDF Normalization**: Stabilizes cell‑wise peak depth, emphasizes specific accessibility
35
36
  - **Highly Variable Peaks (HVP)**: Variance / VMR / deviance‑based selection
36
37
  - **NB/ZINB Likelihoods**: Models over‑dispersion & zero inflation
@@ -39,7 +40,8 @@ Encoder (MLP / Residual / Transformer) --> q(z|x)
39
40
  - **Multi‑Objective Regularization**: β‑VAE KL, β‑TC, DIP, InfoVAE MMD, ODE consistency
40
41
 
41
42
  **Loss Function**:
42
- ```
43
+
44
+ ```python
43
45
  Loss = recon + i_recon + ODE_consistency + β·KL + dip·DIP + tc·TC + info·MMD
44
46
  ```
45
47
 
@@ -385,6 +387,7 @@ adata = iaode.annotation_pipeline(
385
387
  ```
386
388
 
387
389
  **Returns AnnData with:**
390
+
388
391
  - `adata.var['peak_type']`: Peak annotation (promoter/exonic/intronic/intergenic)
389
392
  - `adata.var['gene_name']`: Associated gene names
390
393
  - `adata.var['distance_to_tss']`: Distance to nearest TSS
@@ -582,6 +585,7 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
582
585
  ## Acknowledgments
583
586
 
584
587
  Built upon ideas from:
588
+
585
589
  - **scVI-tools**: scVI, PEAKVI, POISSONVI architectures
586
590
  - **Signac** and **SnapATAC2**: scATAC-seq best practices
587
591
  - **Neural ODE** literature: Continuous latent dynamics
@@ -593,53 +597,10 @@ PyTorch, AnnData, and Scanpy ecosystems provide the foundation.
593
597
  ## Contact
594
598
 
595
599
  - **GitHub Issues**: [https://github.com/PeterPonyu/iAODE/issues](https://github.com/PeterPonyu/iAODE/issues)
596
- - **Email**: fuzeyu99@126.com
600
+ - **Email**: <fuzeyu99@126.com>
597
601
 
598
602
  ---
599
603
 
600
604
  ## Changelog
601
605
 
602
- ### v0.2.0 (2025-11-20)
603
-
604
- **Documentation & Usability**
605
- - Comprehensive documentation overhaul (README, examples/README, QUICKSTART)
606
- - Separated scRNA-seq and scATAC-seq workflows with clear examples
607
- - Added automatic dataset download and caching system
608
- - Created `examples/data/download_data.sh` helper script
609
- - Verified all API usage examples against actual implementation
610
-
611
- **Code Quality**
612
- - Cleaned example scripts: removed unused imports, improved error handling
613
- - Fixed all cross-references between examples and core modules
614
- - Enhanced inline documentation and error messages
615
- - Verified method signatures: `get_velocity()`, `get_vfres()`, `get_pseudotime()`, etc.
616
-
617
- **Package Improvements**
618
- - Complete scATAC-seq preprocessing pipeline with TF-IDF and HVP selection
619
- - Improved peak annotation with distance-to-TSS computation
620
- - Enhanced evaluation metrics (DRE + LSE frameworks)
621
- - Better handling of sparse data and zero inflation
622
-
623
- ### v0.1.2 (2025-11-19)
624
-
625
- **Metadata & Contact**
626
- - Updated author name to "Zeyu Fu"
627
- - Set primary contact email to fuzeyu99@126.com
628
- - Fixed BibTeX citation formatting
629
-
630
- ### v0.1.1 (2025-11-19)
631
-
632
- **Bug Fixes**
633
- - Added missing `requests` dependency for scvi-tools compatibility
634
- - Dropped Python 3.8 support (requires Python ≥3.9)
635
- - Fixed CI test imports and matrix configuration
636
-
637
- ### v0.1.0 (2025-11-19)
638
-
639
- **Initial Release**
640
- - VAE with Neural ODE support for trajectory inference
641
- - Complete scATAC-seq peak annotation pipeline
642
- - Comprehensive evaluation metrics
643
- - Benchmark framework vs scVI models
644
- - Multiple encoder types (MLP, Residual, Transformer, Linear)
645
- - Multiple loss modes (MSE, NB, ZINB)
606
+ See [CHANGELOG.md](CHANGELOG.md) for detailed release notes and version history.
@@ -2,23 +2,23 @@ import gc
2
2
  import os
3
3
  import time
4
4
  import numpy as np
5
- import pandas as pd
6
- import scanpy as sc
7
- import scipy.sparse as sp
5
+ import pandas as pd # type: ignore
6
+ import scanpy as sc # type: ignore
7
+ import scipy.sparse as sp # type: ignore
8
8
  import torch
9
- from sklearn.cluster import KMeans
10
- from sklearn.metrics import (
9
+ from sklearn.cluster import KMeans # type: ignore
10
+ from sklearn.metrics import ( # type: ignore
11
11
  normalized_mutual_info_score,
12
12
  adjusted_mutual_info_score,
13
13
  silhouette_score,
14
14
  davies_bouldin_score,
15
15
  calinski_harabasz_score
16
16
  )
17
- from sklearn.model_selection import train_test_split
17
+ from sklearn.model_selection import train_test_split # type: ignore
18
18
 
19
19
  # scVI imports
20
- from scvi.model import SCVI, PEAKVI
21
- from scvi.external import POISSONVI
20
+ from scvi.model import SCVI, PEAKVI # type: ignore
21
+ from scvi.external import POISSONVI # type: ignore
22
22
  from .DRE import evaluate_dimensionality_reduction
23
23
  from .LSE import evaluate_single_cell_latent_space
24
24
 
@@ -1,8 +1,7 @@
1
1
  import numpy as np
2
- import pandas as pd
3
- from sklearn.metrics import pairwise_distances
4
- from scipy.stats import spearmanr
5
- import time
2
+ import pandas as pd # type: ignore
3
+ from sklearn.metrics import pairwise_distances # type: ignore
4
+ from scipy.stats import spearmanr # type: ignore
6
5
  import warnings
7
6
  from typing import Dict, Tuple
8
7
 
@@ -348,8 +347,8 @@ class DimensionalityReductionEvaluator:
348
347
 
349
348
  overall_quality = float(np.mean([
350
349
  results['distance_correlation'],
351
- results['Q_Local'],
352
- results['Q_Global'],
350
+ results['Q_local'],
351
+ results['Q_global'],
353
352
  ]))
354
353
 
355
354
  comparison_results.append({
@@ -1,8 +1,8 @@
1
1
  import numpy as np
2
- import pandas as pd
3
- from sklearn.decomposition import PCA
4
- from scipy.stats import entropy, skew, kurtosis
5
- from scipy.linalg import svd, norm
2
+ import pandas as pd # type: ignore
3
+ from sklearn.decomposition import PCA # type: ignore
4
+ from scipy.stats import entropy # type: ignore
5
+ from scipy.linalg import svd # type: ignore
6
6
  import warnings
7
7
 
8
8
 
@@ -493,7 +493,7 @@ class SingleCellLatentSpaceEvaluator:
493
493
  print("=" * 80)
494
494
 
495
495
  # Core metrics
496
- print(f"\n[Core Manifold Metrics]")
496
+ print("\n[Core Manifold Metrics]")
497
497
  print(f" Manifold dimensionality consistency: {results['manifold_dimensionality']:.4f} ★")
498
498
  print(f" Spectral decay rate: {results['spectral_decay_rate']:.4f} (higher is better)")
499
499
  print(
@@ -506,21 +506,21 @@ class SingleCellLatentSpaceEvaluator:
506
506
  )
507
507
 
508
508
  # Single-cell–specific
509
- print(f"\n[Single-cell Specific Metrics]")
509
+ print("\n[Single-cell Specific Metrics]")
510
510
  print(f" Trajectory directionality: {results['trajectory_directionality']:.4f} (higher is better)")
511
511
 
512
512
  # Technical quality
513
- print(f"\n[Technical Quality Metrics]")
513
+ print("\n[Technical Quality Metrics]")
514
514
  print(f" Noise resilience: {results['noise_resilience']:.4f} (higher is better)")
515
515
 
516
516
  # Aggregate
517
- print(f"\n[Aggregate Scores]")
517
+ print("\n[Aggregate Scores]")
518
518
  print(f" Core quality score: {results['core_quality']:.4f}")
519
519
  print(f" Overall quality score: {results['overall_quality']:.4f} ★★★")
520
520
 
521
521
  # Interpretation
522
522
  interp = results['interpretation']
523
- print(f"\n[Interpretation]")
523
+ print("\n[Interpretation]")
524
524
  print(f" Quality level: {interp['quality_level']}")
525
525
 
526
526
  if interp['strengths']:
@@ -8,7 +8,8 @@ dimensionality reduction.
8
8
  Main Components:
9
9
  - agent: High-level interface for model training and evaluation
10
10
  - annotation: Peak-to-gene annotation pipeline for scATAC-seq data
11
- - BEN: Benchmark evaluation framework for comparing dimensionality reduction methods
11
+ - BEN: Benchmark evaluation framework for comparing dimensionality
12
+ reduction methods
12
13
  - environment: Data handling and train/validation/test splitting
13
14
  - model: Core VAE model with ODE integration
14
15
  - module: Neural network building blocks (encoders, decoders, ODE functions)
@@ -19,10 +20,10 @@ Main Components:
19
20
  Usage Example:
20
21
  >>> import anndata as ad
21
22
  >>> import iaode
22
- >>>
23
+ >>>
23
24
  >>> # Load your data
24
25
  >>> adata = ad.read_h5ad('your_data.h5ad')
25
- >>>
26
+ >>>
26
27
  >>> # Create and train model
27
28
  >>> model = iaode.agent(
28
29
  ... adata,
@@ -31,12 +32,12 @@ Usage Example:
31
32
  ... use_ode=True
32
33
  ... )
33
34
  >>> model.fit(epochs=100)
34
- >>>
35
+ >>>
35
36
  >>> # Get latent representation
36
37
  >>> latent = model.get_latent()
37
38
  """
38
39
 
39
- __version__ = "0.2.2"
40
+ __version__ = "0.2.3"
40
41
  __author__ = "Zeyu Fu"
41
42
 
42
43
  # Import main classes and functions
@@ -1,16 +1,16 @@
1
1
  # agent.py
2
2
 
3
3
  from .environment import Env
4
- import scanpy as sc
5
- from anndata import AnnData
4
+ import scanpy as sc # type: ignore
5
+ from anndata import AnnData # type: ignore
6
6
  import numpy as np
7
7
  import torch
8
- import tqdm
8
+ import tqdm # type: ignore
9
9
  import time
10
10
  from typing import Literal, Optional
11
- from scipy.stats import norm
12
- from scipy.sparse import issparse, csr_matrix, coo_matrix
13
- from sklearn.neighbors import NearestNeighbors
11
+ from scipy.stats import norm # type: ignore
12
+ from scipy.sparse import issparse, csr_matrix, coo_matrix # type: ignore
13
+ from sklearn.neighbors import NearestNeighbors # type: ignore
14
14
 
15
15
 
16
16
  class agent(Env):
@@ -183,25 +183,7 @@ class agent(Env):
183
183
  val_every: int = 5,
184
184
  early_stop: bool = True,
185
185
  ):
186
- """
187
- Train model with early stopping.
188
-
189
- Parameters
190
- ----------
191
- epochs : int, default=100
192
- Maximum number of training epochs
193
- patience : int, default=20
194
- Early stopping patience (epochs without improvement)
195
- val_every : int, default=5
196
- Validate every N epochs
197
- early_stop : bool, default=True
198
- Whether to use early stopping
199
-
200
- Returns
201
- -------
202
- self : agent
203
- Trained model instance
204
- """
186
+ """Train model with early stopping."""
205
187
 
206
188
  # Initialize resource tracking
207
189
  use_cuda = torch.cuda.is_available()
@@ -209,68 +191,72 @@ class agent(Env):
209
191
  torch.cuda.reset_peak_memory_stats()
210
192
  start_time = time.time()
211
193
 
212
- with tqdm.tqdm(total=epochs, desc="Training", ncols=225) as pbar:
213
- for epoch in range(epochs):
194
+ # Main progress bar (compact)
195
+ with tqdm.tqdm(total=epochs, desc="Training", position=0) as pbar:
196
+ # Secondary info bar (detailed metrics)
197
+ with tqdm.tqdm(total=0, position=1, bar_format='{desc}') as pbar_info:
214
198
 
215
- train_loss = self.train_epoch()
216
-
217
- if (epoch + 1) % val_every == 0 or epoch == 0:
218
- val_loss, val_score = self.validate()
219
- # Ensure native float for type checkers
220
- val_loss = float(val_loss)
199
+ for epoch in range(epochs):
221
200
 
222
- if early_stop:
223
- should_stop, improved = self.check_early_stopping(val_loss, patience)
224
-
225
- pbar.set_postfix({
226
- "Train": f"{train_loss:.2f}",
227
- "Val": f"{val_loss:.2f}",
228
- "ARI": f"{val_score[0]:.2f}",
229
- "NMI": f"{val_score[1]:.2f}",
230
- "ASW": f"{val_score[2]:.2f}",
231
- "CAL": f"{val_score[3]:.2f}",
232
- "DAV": f"{val_score[4]:.2f}",
233
- "COR": f"{val_score[5]:.2f}",
234
- "Best": f"{self.best_val_loss:.2f}",
235
- "Pat": f"{self.patience_counter}/{patience}",
236
- "Imp": "✓" if improved else "✗"
237
- })
238
-
239
- if should_stop:
240
- self.actual_epochs = epoch + 1
241
- print(f"\n\nEarly stopping at epoch {epoch + 1}")
242
- print(f"Best validation loss: {self.best_val_loss:.4f}")
243
- break
244
- else:
245
- pbar.set_postfix({
246
- "Train": f"{train_loss:.2f}",
247
- "Val": f"{val_loss:.2f}",
248
- "ARI": f"{val_score[0]:.2f}",
249
- "NMI": f"{val_score[1]:.2f}",
250
- "ASW": f"{val_score[2]:.2f}",
251
- "CAL": f"{val_score[3]:.2f}",
252
- "DAV": f"{val_score[4]:.2f}",
253
- "COR": f"{val_score[5]:.2f}",
254
- })
255
-
256
- pbar.update(1)
257
- else:
258
- self.actual_epochs = epochs
201
+ train_loss = self.train_epoch()
202
+
203
+ if (epoch + 1) % val_every == 0 or epoch == 0:
204
+ val_loss, val_score = self.validate()
205
+ val_loss = float(val_loss)
206
+
207
+ if early_stop:
208
+ should_stop, improved = self.check_early_stopping(val_loss, patience)
209
+
210
+ # Main bar: key metrics only
211
+ pbar.set_postfix({
212
+ "trn": f"{train_loss:.2f}",
213
+ "val": f"{val_loss:.2f}",
214
+ "pat": f"{self.patience_counter}/{patience}",
215
+ "↑" if improved else "↓": ""
216
+ })
217
+
218
+ # Info bar: all metrics
219
+ pbar_info.set_description_str(
220
+ f"Metrics | ARI:{val_score[0]:.3f} NMI:{val_score[1]:.3f} "
221
+ f"ASW:{val_score[2]:.3f} CAL:{val_score[3]:.3f} "
222
+ f"DAV:{val_score[4]:.3f} COR:{val_score[5]:.3f} | "
223
+ f"Best:{self.best_val_loss:.3f}"
224
+ )
225
+
226
+ if should_stop:
227
+ self.actual_epochs = epoch + 1
228
+ pbar.write(f"\nEarly stopping at epoch {epoch + 1}")
229
+ break
230
+ else:
231
+ pbar.set_postfix({
232
+ "trn": f"{train_loss:.2f}",
233
+ "val": f"{val_loss:.2f}",
234
+ })
235
+ pbar_info.set_description_str(
236
+ f"Metrics | ARI:{val_score[0]:.3f} NMI:{val_score[1]:.3f} "
237
+ f"ASW:{val_score[2]:.3f} CAL:{val_score[3]:.3f} "
238
+ f"DAV:{val_score[4]:.3f} COR:{val_score[5]:.3f}"
239
+ )
240
+
241
+ pbar.update(1)
242
+ else:
243
+ self.actual_epochs = epochs
259
244
 
260
245
  # Record resource usage
261
246
  self.train_time = time.time() - start_time
262
247
  self.peak_memory_gb = torch.cuda.max_memory_allocated() / 1e9 if use_cuda else 0.0
263
248
 
264
249
  print(f"\n{'='*70}")
265
- print(f"Training Complete")
250
+ print("Training Complete")
266
251
  print(f"{'='*70}")
267
252
  print(f" Epochs: {self.actual_epochs}/{epochs}")
268
- print(f" Time: {self.train_time:.2f}s")
253
+ print(f" Time: {self.train_time:.2f}s ({self.train_time/self.actual_epochs:.2f}s/epoch)")
269
254
  print(f" Peak GPU Memory: {self.peak_memory_gb:.3f} GB")
255
+ if early_stop:
256
+ print(f" Best Val Loss: {self.best_val_loss:.4f}")
270
257
  print(f"{'='*70}\n")
271
258
 
272
259
  return self
273
-
274
260
  # ========================================================================
275
261
  # Representation Extraction
276
262
  # ========================================================================
@@ -567,7 +553,9 @@ class agent(Env):
567
553
  indices_matrix2[i] = idx
568
554
 
569
555
  # Compute cosine similarities
570
- vals, rows, cols = [], [], []
556
+ vals: list = []
557
+ rows: list = []
558
+ cols: list = []
571
559
  for i in range(ncells):
572
560
  # Get neighbors (first-order + second-order)
573
561
  dist_mat = adata.obsp["distances"]
@@ -811,6 +799,10 @@ def quiver_autoscale(E: np.ndarray, V: np.ndarray) -> float:
811
799
 
812
800
  fig, ax = plt.subplots()
813
801
  scale_factor = np.abs(E).max()
802
+
803
+ # Avoid division by zero
804
+ if scale_factor == 0:
805
+ scale_factor = 1.0
814
806
 
815
807
  Q = ax.quiver(
816
808
  E[:, 0] / scale_factor,
@@ -821,11 +813,18 @@ def quiver_autoscale(E: np.ndarray, V: np.ndarray) -> float:
821
813
  scale=None,
822
814
  scale_units="xy",
823
815
  )
824
- # Avoid calling private matplotlib internals (_init) for stability
825
- fig.clf()
826
- plt.close(fig)
827
-
828
- return Q.scale / scale_factor
816
+
817
+ # Render the figure to compute Q.scale
818
+ try:
819
+ fig.canvas.draw()
820
+ quiver_scale = Q.scale if Q.scale is not None else 1.0
821
+ except Exception:
822
+ # Fallback if rendering fails
823
+ quiver_scale = 1.0
824
+ finally:
825
+ plt.close(fig)
826
+
827
+ return quiver_scale / scale_factor
829
828
 
830
829
 
831
830
  def l2_norm(x: np.ndarray, axis: int = -1) -> np.ndarray:
@@ -5,9 +5,9 @@ Best practices from Signac, SnapATAC2, and scvi-tools (2024)
5
5
  """
6
6
 
7
7
  import numpy as np
8
- import pandas as pd
9
- import scanpy as sc
10
- import anndata as ad
8
+ import pandas as pd # type: ignore
9
+ import scanpy as sc # type: ignore
10
+ import anndata as ad # type: ignore
11
11
  from pathlib import Path
12
12
  from typing import Literal, Optional, Dict
13
13
  import re
@@ -148,7 +148,7 @@ class GTFParser:
148
148
 
149
149
  def __init__(self, gtf_file: str):
150
150
  self.gtf_file = Path(gtf_file)
151
- self.genes = defaultdict(list) # chr -> [(start, end, gene_name, gene_id, strand)]
151
+ self.genes: Dict[str, list] = defaultdict(list) # chr -> [(start, end, gene_name, gene_id, strand)]
152
152
 
153
153
  def parse(self, feature_type: str = 'gene',
154
154
  gene_type: Optional[str] = 'protein_coding') -> Dict:
@@ -412,7 +412,7 @@ def annotate_peaks_to_genes(
412
412
  adata.var['distance_to_tss'] = distances_to_tss
413
413
 
414
414
  # Statistics
415
- print(f"\n 📊 Annotation Summary:")
415
+ print("\n 📊 Annotation Summary:")
416
416
  type_counts = pd.Series(annotation_types).value_counts()
417
417
  for anno_type in ['promoter', 'gene_body', 'distal', 'intergenic']:
418
418
  if anno_type in type_counts.index:
@@ -426,7 +426,7 @@ def annotate_peaks_to_genes(
426
426
  # Top genes
427
427
  gene_counts = pd.Series([g for g in annotations if g not in ['intergenic', 'parse_failed']]).value_counts()
428
428
  if len(gene_counts) > 0:
429
- print(f"\n 🔝 Top 5 annotated genes:")
429
+ print("\n 🔝 Top 5 annotated genes:")
430
430
  for gene, count in gene_counts.head(5).items():
431
431
  print(f" • {gene}: {count} peaks")
432
432
 
@@ -570,7 +570,7 @@ def annotation_pipeline(
570
570
 
571
571
  # Step 6: Save output
572
572
  if output_h5ad:
573
- print(f"\n💾 Saving results")
573
+ print("\n💾 Saving results")
574
574
  output_path = Path(output_h5ad)
575
575
  output_path.parent.mkdir(parents=True, exist_ok=True)
576
576
  adata.write_h5ad(output_h5ad)
@@ -580,7 +580,7 @@ def annotation_pipeline(
580
580
  print("\n" + "="*70)
581
581
  print("✅ Pipeline complete!")
582
582
  print("="*70)
583
- print(f"\n📋 Final dataset:")
583
+ print("\n📋 Final dataset:")
584
584
  print(f" • Cells: {adata.n_obs:,}")
585
585
  print(f" • Peaks: {adata.n_vars:,}")
586
586
  if select_hvp:
@@ -11,7 +11,7 @@ import gzip
11
11
  import shutil
12
12
  from pathlib import Path
13
13
  from typing import Optional, Tuple
14
- import anndata as ad
14
+ import anndata as ad # type: ignore
15
15
 
16
16
 
17
17
  def get_data_dir() -> Path:
@@ -309,7 +309,7 @@ def list_cached_files() -> None:
309
309
  print(f"Location: {data_dir}")
310
310
  print()
311
311
 
312
- total_size = 0
312
+ total_size: float = 0.0
313
313
  file_count = 0
314
314
 
315
315
  for root, dirs, files in os.walk(data_dir):
@@ -3,8 +3,8 @@
3
3
  from .model import iaodeModel
4
4
  from .mixin import envMixin
5
5
  import numpy as np
6
- from sklearn.cluster import KMeans
7
- from sklearn.preprocessing import LabelEncoder
6
+ from sklearn.cluster import KMeans # type: ignore
7
+ from sklearn.preprocessing import LabelEncoder # type: ignore
8
8
  import torch
9
9
  from torch.utils.data import DataLoader, TensorDataset
10
10
 
@@ -2,11 +2,11 @@
2
2
 
3
3
  import torch
4
4
  import torch.nn.functional as F
5
- from torchdiffeq import odeint
5
+ from torchdiffeq import odeint # type: ignore
6
6
  import numpy as np
7
7
  import math
8
- from sklearn.cluster import KMeans
9
- from sklearn.metrics import (
8
+ from sklearn.cluster import KMeans # type: ignore
9
+ from sklearn.metrics import ( # type: ignore
10
10
  adjusted_mutual_info_score,
11
11
  normalized_mutual_info_score,
12
12
  silhouette_score,
@@ -5,7 +5,7 @@ import torch.nn as nn
5
5
  import torch.optim as optim
6
6
  import torch.nn.functional as F
7
7
  import numpy as np
8
- from sklearn.metrics.pairwise import pairwise_distances
8
+ from sklearn.metrics.pairwise import pairwise_distances # type: ignore
9
9
 
10
10
  from .mixin import scviMixin, dipMixin, betatcMixin, infoMixin
11
11
  from .module import iVAE
@@ -141,17 +141,17 @@ class iaodeModel(nn.Module, scviMixin, dipMixin, betatcMixin, infoMixin):
141
141
  pred_xl_ode, dropout_logitsl_ode,
142
142
  ) = self.nn(states)
143
143
 
144
- l = x.sum(-1).view(-1, 1)
145
- pred_x = pred_x * l
146
- pred_x_ode = pred_x_ode * l
144
+ L = x.sum(-1).view(-1, 1)
145
+ pred_x = pred_x * L
146
+ pred_x_ode = pred_x_ode * L
147
147
  disp = torch.exp(self.nn.decoder.disp)
148
148
 
149
149
  recon_loss = -self._log_zinb(x, pred_x, disp, dropout_logits).sum(-1).mean()
150
150
  recon_loss += -self._log_zinb(x, pred_x_ode, disp, dropout_logits_ode).sum(-1).mean()
151
151
 
152
152
  if self.irecon:
153
- pred_xl = pred_xl * l
154
- pred_xl_ode = pred_xl_ode * l
153
+ pred_xl = pred_xl * L
154
+ pred_xl_ode = pred_xl_ode * L
155
155
  irecon_loss = -self.irecon * self._log_zinb(x, pred_xl, disp, dropout_logitsl).sum(-1).mean()
156
156
  irecon_loss += -self.irecon * self._log_zinb(x, pred_xl_ode, disp, dropout_logitsl_ode).sum(-1).mean()
157
157
  else:
@@ -169,17 +169,17 @@ class iaodeModel(nn.Module, scviMixin, dipMixin, betatcMixin, infoMixin):
169
169
  ) = self.nn(states)
170
170
 
171
171
  if self.loss_mode == "nb":
172
- l = x.sum(-1).view(-1, 1)
173
- pred_x = pred_x * l
174
- pred_x_ode = pred_x_ode * l
172
+ L = x.sum(-1).view(-1, 1)
173
+ pred_x = pred_x * L
174
+ pred_x_ode = pred_x_ode * L
175
175
  disp = torch.exp(self.nn.decoder.disp)
176
176
 
177
177
  recon_loss = -self._log_nb(x, pred_x, disp).sum(-1).mean()
178
178
  recon_loss += -self._log_nb(x, pred_x_ode, disp).sum(-1).mean()
179
179
 
180
180
  if self.irecon:
181
- pred_xl = pred_xl * l
182
- pred_xl_ode = pred_xl_ode * l
181
+ pred_xl = pred_xl * L
182
+ pred_xl_ode = pred_xl_ode * L
183
183
  irecon_loss = -self.irecon * self._log_nb(x, pred_xl, disp).sum(-1).mean()
184
184
  irecon_loss += -self.irecon * self._log_nb(x, pred_xl_ode, disp).sum(-1).mean()
185
185
  else:
@@ -196,14 +196,14 @@ class iaodeModel(nn.Module, scviMixin, dipMixin, betatcMixin, infoMixin):
196
196
  if self.loss_mode == "zinb":
197
197
  q_z, q_m, q_s, pred_x, dropout_logits, le, pred_xl, dropout_logitsl = self.nn(states)
198
198
 
199
- l = states.sum(-1).view(-1, 1)
200
- pred_x = pred_x * l
199
+ L = states.sum(-1).view(-1, 1)
200
+ pred_x = pred_x * L
201
201
  disp = torch.exp(self.nn.decoder.disp)
202
202
  recon_loss = -self._log_zinb(states, pred_x, disp, dropout_logits).sum(-1).mean()
203
203
 
204
204
  if self.irecon:
205
- pred_xl = pred_xl * l
206
- irecon_loss = -self.irecon * self._log_zinb(states, pred_xl, disp, dropout_logitsl).sum(-1).mean()
205
+ pred_xl = pred_xl * L
206
+ irecon_loss = -self.irecon * self._log_zinb(x, pred_xl, disp, dropout_logitsl).sum(-1).mean()
207
207
  else:
208
208
  irecon_loss = torch.zeros(1).to(self.device)
209
209
 
@@ -211,13 +211,13 @@ class iaodeModel(nn.Module, scviMixin, dipMixin, betatcMixin, infoMixin):
211
211
  q_z, q_m, q_s, pred_x, le, pred_xl = self.nn(states)
212
212
 
213
213
  if self.loss_mode == "nb":
214
- l = states.sum(-1).view(-1, 1)
215
- pred_x = pred_x * l
214
+ L = states.sum(-1).view(-1, 1)
215
+ pred_x = pred_x * L
216
216
  disp = torch.exp(self.nn.decoder.disp)
217
217
  recon_loss = -self._log_nb(states, pred_x, disp).sum(-1).mean()
218
218
 
219
219
  if self.irecon:
220
- pred_xl = pred_xl * l
220
+ pred_xl = pred_xl * L
221
221
  irecon_loss = -self.irecon * self._log_nb(states, pred_xl, disp).sum(-1).mean()
222
222
  else:
223
223
  irecon_loss = torch.zeros(1).to(self.device)
@@ -365,16 +365,16 @@ class iaodeModel(nn.Module, scviMixin, dipMixin, betatcMixin, infoMixin):
365
365
 
366
366
  qz_div = F.mse_loss(q_z, q_z_ode, reduction="none").sum(-1).mean()
367
367
 
368
- l = x.sum(-1).view(-1, 1)
369
- pred_x = pred_x * l
370
- pred_x_ode = pred_x_ode * l
368
+ L = x.sum(-1).view(-1, 1)
369
+ pred_x = pred_x * L
370
+ pred_x_ode = pred_x_ode * L
371
371
  disp = torch.exp(self.nn.decoder.disp)
372
372
  recon_loss = -self._log_zinb(x, pred_x, disp, dropout_logits).sum(-1).mean()
373
373
  recon_loss += -self._log_zinb(x, pred_x_ode, disp, dropout_logits_ode).sum(-1).mean()
374
374
 
375
375
  if self.irecon:
376
- pred_xl = pred_xl * l
377
- pred_xl_ode = pred_xl_ode * l
376
+ pred_xl = pred_xl * L
377
+ pred_xl_ode = pred_xl_ode * L
378
378
  irecon_loss = -self.irecon * self._log_zinb(x, pred_xl, disp, dropout_logitsl).sum(-1).mean()
379
379
  irecon_loss += -self.irecon * self._log_zinb(x, pred_xl_ode, disp, dropout_logitsl_ode).sum(-1).mean()
380
380
  else:
@@ -394,16 +394,16 @@ class iaodeModel(nn.Module, scviMixin, dipMixin, betatcMixin, infoMixin):
394
394
  qz_div = F.mse_loss(q_z, q_z_ode, reduction="none").sum(-1).mean()
395
395
 
396
396
  if self.loss_mode == "nb":
397
- l = x.sum(-1).view(-1, 1)
398
- pred_x = pred_x * l
399
- pred_x_ode = pred_x_ode * l
397
+ L = x.sum(-1).view(-1, 1)
398
+ pred_x = pred_x * L
399
+ pred_x_ode = pred_x_ode * L
400
400
  disp = torch.exp(self.nn.decoder.disp)
401
401
  recon_loss = -self._log_nb(x, pred_x, disp).sum(-1).mean()
402
402
  recon_loss += -self._log_nb(x, pred_x_ode, disp).sum(-1).mean()
403
403
 
404
404
  if self.irecon:
405
- pred_xl = pred_xl * l
406
- pred_xl_ode = pred_xl_ode * l
405
+ pred_xl = pred_xl * L
406
+ pred_xl_ode = pred_xl_ode * L
407
407
  irecon_loss = -self.irecon * self._log_nb(x, pred_xl, disp).sum(-1).mean()
408
408
  irecon_loss += -self.irecon * self._log_nb(x, pred_xl_ode, disp).sum(-1).mean()
409
409
  else:
@@ -418,13 +418,13 @@ class iaodeModel(nn.Module, scviMixin, dipMixin, betatcMixin, infoMixin):
418
418
  if self.loss_mode == "zinb":
419
419
  q_z, q_m, q_s, pred_x, dropout_logits, le, pred_xl, dropout_logitsl = self.nn(states)
420
420
 
421
- l = states.sum(-1).view(-1, 1)
422
- pred_x = pred_x * l
421
+ L = states.sum(-1).view(-1, 1)
422
+ pred_x = pred_x * L
423
423
  disp = torch.exp(self.nn.decoder.disp)
424
424
  recon_loss = -self._log_zinb(states, pred_x, disp, dropout_logits).sum(-1).mean()
425
425
 
426
426
  if self.irecon:
427
- pred_xl = pred_xl * l
427
+ pred_xl = pred_xl * L
428
428
  irecon_loss = -self.irecon * self._log_zinb(states, pred_xl, disp, dropout_logitsl).sum(-1).mean()
429
429
  else:
430
430
  irecon_loss = torch.zeros(1).to(self.device)
@@ -433,13 +433,13 @@ class iaodeModel(nn.Module, scviMixin, dipMixin, betatcMixin, infoMixin):
433
433
  q_z, q_m, q_s, pred_x, le, pred_xl = self.nn(states)
434
434
 
435
435
  if self.loss_mode == "nb":
436
- l = states.sum(-1).view(-1, 1)
437
- pred_x = pred_x * l
436
+ L = states.sum(-1).view(-1, 1)
437
+ pred_x = pred_x * L
438
438
  disp = torch.exp(self.nn.decoder.disp)
439
439
  recon_loss = -self._log_nb(states, pred_x, disp).sum(-1).mean()
440
440
 
441
441
  if self.irecon:
442
- pred_xl = pred_xl * l
442
+ pred_xl = pred_xl * L
443
443
  irecon_loss = -self.irecon * self._log_nb(states, pred_xl, disp).sum(-1).mean()
444
444
  else:
445
445
  irecon_loss = torch.zeros(1).to(self.device)
@@ -72,7 +72,7 @@ class Encoder(nn.Module):
72
72
 
73
73
  # Build encoder backbone
74
74
  if encoder_type == "mlp":
75
- layers = []
75
+ layers: list[nn.Module] = []
76
76
  in_dim = state_dim
77
77
  for _ in range(encoder_num_layers):
78
78
  layers.append(nn.Linear(in_dim, hidden_dim))
@@ -272,10 +272,11 @@ class Decoder(nn.Module):
272
272
  # Negative binomial: dispersion parameter
273
273
  self.disp = nn.Parameter(torch.randn(state_dim))
274
274
  # Mean parameter with Softmax normalization
275
- self.mean_decoder = nn.Sequential(
275
+ mean_decoder_seq: nn.Module = nn.Sequential(
276
276
  nn.Linear(hidden_dim, state_dim),
277
277
  nn.Softmax(dim=-1)
278
278
  )
279
+ self.mean_decoder = mean_decoder_seq
279
280
  else: # 'mse' mode
280
281
  self.mean_decoder = nn.Linear(hidden_dim, state_dim)
281
282
 
@@ -1,5 +1,5 @@
1
1
  import numpy as np
2
- from scipy.sparse import issparse, csr_matrix
2
+ from scipy.sparse import issparse, csr_matrix # type: ignore
3
3
  from typing import Literal, Tuple, Optional
4
4
  import warnings
5
5
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: iaode
3
- Version: 0.2.2
3
+ Version: 0.2.3
4
4
  Summary: Interpretable Autoencoder with Ordinary Differential Equations for single-cell omics analysis
5
5
  Author-email: Zeyu Fu <fuzeyu99@126.com>
6
6
  License: MIT
@@ -64,7 +64,7 @@ The design targets the unique characteristics of scATAC data: extreme sparsity,
64
64
 
65
65
  ## Core Architecture
66
66
 
67
- ```
67
+ ```text
68
68
  Raw Peak Counts --(TF-IDF)--> Normalized Matrix --(HVP Selection)--> Peak Subset
69
69
  |
70
70
  v
@@ -80,6 +80,7 @@ Encoder (MLP / Residual / Transformer) --> q(z|x)
80
80
  ```
81
81
 
82
82
  **Key Components**:
83
+
83
84
  - **TF‑IDF Normalization**: Stabilizes cell‑wise peak depth, emphasizes specific accessibility
84
85
  - **Highly Variable Peaks (HVP)**: Variance / VMR / deviance‑based selection
85
86
  - **NB/ZINB Likelihoods**: Models over‑dispersion & zero inflation
@@ -88,7 +89,8 @@ Encoder (MLP / Residual / Transformer) --> q(z|x)
88
89
  - **Multi‑Objective Regularization**: β‑VAE KL, β‑TC, DIP, InfoVAE MMD, ODE consistency
89
90
 
90
91
  **Loss Function**:
91
- ```
92
+
93
+ ```python
92
94
  Loss = recon + i_recon + ODE_consistency + β·KL + dip·DIP + tc·TC + info·MMD
93
95
  ```
94
96
 
@@ -434,6 +436,7 @@ adata = iaode.annotation_pipeline(
434
436
  ```
435
437
 
436
438
  **Returns AnnData with:**
439
+
437
440
  - `adata.var['peak_type']`: Peak annotation (promoter/exonic/intronic/intergenic)
438
441
  - `adata.var['gene_name']`: Associated gene names
439
442
  - `adata.var['distance_to_tss']`: Distance to nearest TSS
@@ -631,6 +634,7 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
631
634
  ## Acknowledgments
632
635
 
633
636
  Built upon ideas from:
637
+
634
638
  - **scVI-tools**: scVI, PEAKVI, POISSONVI architectures
635
639
  - **Signac** and **SnapATAC2**: scATAC-seq best practices
636
640
  - **Neural ODE** literature: Continuous latent dynamics
@@ -642,53 +646,10 @@ PyTorch, AnnData, and Scanpy ecosystems provide the foundation.
642
646
  ## Contact
643
647
 
644
648
  - **GitHub Issues**: [https://github.com/PeterPonyu/iAODE/issues](https://github.com/PeterPonyu/iAODE/issues)
645
- - **Email**: fuzeyu99@126.com
649
+ - **Email**: <fuzeyu99@126.com>
646
650
 
647
651
  ---
648
652
 
649
653
  ## Changelog
650
654
 
651
- ### v0.2.0 (2025-11-20)
652
-
653
- **Documentation & Usability**
654
- - Comprehensive documentation overhaul (README, examples/README, QUICKSTART)
655
- - Separated scRNA-seq and scATAC-seq workflows with clear examples
656
- - Added automatic dataset download and caching system
657
- - Created `examples/data/download_data.sh` helper script
658
- - Verified all API usage examples against actual implementation
659
-
660
- **Code Quality**
661
- - Cleaned example scripts: removed unused imports, improved error handling
662
- - Fixed all cross-references between examples and core modules
663
- - Enhanced inline documentation and error messages
664
- - Verified method signatures: `get_velocity()`, `get_vfres()`, `get_pseudotime()`, etc.
665
-
666
- **Package Improvements**
667
- - Complete scATAC-seq preprocessing pipeline with TF-IDF and HVP selection
668
- - Improved peak annotation with distance-to-TSS computation
669
- - Enhanced evaluation metrics (DRE + LSE frameworks)
670
- - Better handling of sparse data and zero inflation
671
-
672
- ### v0.1.2 (2025-11-19)
673
-
674
- **Metadata & Contact**
675
- - Updated author name to "Zeyu Fu"
676
- - Set primary contact email to fuzeyu99@126.com
677
- - Fixed BibTeX citation formatting
678
-
679
- ### v0.1.1 (2025-11-19)
680
-
681
- **Bug Fixes**
682
- - Added missing `requests` dependency for scvi-tools compatibility
683
- - Dropped Python 3.8 support (requires Python ≥3.9)
684
- - Fixed CI test imports and matrix configuration
685
-
686
- ### v0.1.0 (2025-11-19)
687
-
688
- **Initial Release**
689
- - VAE with Neural ODE support for trajectory inference
690
- - Complete scATAC-seq peak annotation pipeline
691
- - Comprehensive evaluation metrics
692
- - Benchmark framework vs scVI models
693
- - Multiple encoder types (MLP, Residual, Transformer, Linear)
694
- - Multiple loss modes (MSE, NB, ZINB)
655
+ See [CHANGELOG.md](CHANGELOG.md) for detailed release notes and version history.
@@ -20,4 +20,5 @@ iaode.egg-info/PKG-INFO
20
20
  iaode.egg-info/SOURCES.txt
21
21
  iaode.egg-info/dependency_links.txt
22
22
  iaode.egg-info/requires.txt
23
- iaode.egg-info/top_level.txt
23
+ iaode.egg-info/top_level.txt
24
+ tests/test_smoke.py
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "iaode"
7
- version = "0.2.2"
7
+ version = "0.2.3"
8
8
  description = "Interpretable Autoencoder with Ordinary Differential Equations for single-cell omics analysis"
9
9
  readme = "README.md"
10
10
  authors = [
@@ -4,7 +4,7 @@ Setup configuration for iaode package.
4
4
  This file is kept for backward compatibility. Modern build uses pyproject.toml.
5
5
  """
6
6
 
7
- from setuptools import setup
7
+ from setuptools import setup # type: ignore
8
8
 
9
9
  # Read long description from README
10
10
  with open("README.md", "r", encoding="utf-8") as fh:
@@ -0,0 +1,21 @@
1
+ import iaode
2
+
3
+
4
+ def test_package_metadata() -> None:
5
+ assert isinstance(iaode.__version__, str)
6
+ assert iaode.__version__.startswith("0."), "Expected release-style version"
7
+ assert "agent" in iaode.__all__
8
+
9
+
10
+ def test_get_data_dir_idempotent() -> None:
11
+ cache_dir = iaode.datasets.get_data_dir()
12
+ assert cache_dir.exists()
13
+ assert cache_dir.is_dir()
14
+ assert (cache_dir / "atacseq").is_dir()
15
+ assert (cache_dir / "annotations").is_dir()
16
+
17
+ # Ensure calling twice is safe and does not raise
18
+ second = iaode.datasets.get_data_dir()
19
+ assert second.samefile(cache_dir)
20
+ assert (second / "atacseq").exists()
21
+ assert (second / "annotations").exists()
File without changes
File without changes
File without changes
File without changes