iaode 0.2.1__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.1
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
 
@@ -314,38 +316,35 @@ Comprehensive examples are available in the `examples/` directory. See **[exampl
314
316
 
315
317
  ### Example Scripts
316
318
 
317
- | Script | Purpose | Best For |
318
- |--------|---------|----------|
319
- | **`scATAC_quickstart.py`** | Complete scATAC pipeline (TF‑IDF → HVP → iAODE) | Real scATAC-seq analysis |
320
- | **`atacseq_annotation.py`** | Peak-to-gene annotation + QC plots | Understanding peak annotation |
321
- | **`trajectory_ode.py`** | Neural ODE pseudotime & velocity | Trajectory inference |
322
- | **`evaluation_metrics.py`** | DR quality + clustering metrics | Model evaluation |
323
- | **`model_evaluation.py`** | Benchmark vs scVI models | Comparative analysis |
324
- | **`basic_usage.py`** | Simple scRNA-seq workflow | Getting started |
325
- | **`trajectory_inference.py`** | Trajectory with vector field | Velocity visualization |
319
+ | Script | Purpose | Modality | Best For |
320
+ |--------|---------|----------|----------|
321
+ | **`basic_usage.py`** | scATAC-seq with 2D/histogram visualizations | scATAC | Getting started with scATAC-seq |
322
+ | **`atacseq_annotation.py`** | Peak-to-gene annotation + QC plots | scATAC | Understanding peak annotation |
323
+ | **`model_evaluation_atac.py`** | Benchmark iAODE vs scVI on scATAC-seq | scATAC | Comparative analysis (chromatin) |
324
+ | **`model_evaluation_rna.py`** | Benchmark iAODE vs scVI on scRNA-seq | scRNA | Comparative analysis (transcriptome) |
325
+ | **`trajectory_inference_atac.py`** | Neural ODE trajectory with scATAC-seq | scATAC | Chromatin accessibility dynamics |
326
+ | **`trajectory_inference_rna.py`** | Neural ODE trajectory with scRNA-seq | scRNA | Transcriptional trajectory |
327
+
326
328
 
327
329
  ### Running Examples
328
330
 
329
331
  ```bash
330
332
  cd examples
331
333
 
332
- # Complete scATAC-seq workflow with auto-download
333
- python atacseq_annotation.py
334
+ # Getting started with scATAC-seq
335
+ python basic_usage.py
334
336
 
335
- # Or use your own data
336
- python scATAC_quickstart.py \
337
- --h5 filtered_peak_bc_matrix.h5 \
338
- --gtf gencode.vM25.annotation.gtf.gz \
339
- --use-ode --latent-dim 32 --i-dim 16
337
+ # Peak-to-gene annotation with auto-download
338
+ python atacseq_annotation.py
340
339
 
341
- # Trajectory inference with synthetic data
342
- python trajectory_ode.py
340
+ # Benchmark models on scATAC-seq data
341
+ python model_evaluation_atac.py
343
342
 
344
- # Comprehensive benchmarking
345
- python model_evaluation.py
343
+ # Trajectory inference with Neural ODE (scRNA-seq)
344
+ python trajectory_inference_rna.py
346
345
  ```
347
346
 
348
- All examples save outputs to `examples/outputs/` with visualizations and processed data. See **[examples/README.md](examples/README.md)** for detailed usage instructions and output descriptions.
347
+ All examples save outputs to `examples/outputs/<example_name>/` by default. See **[examples/README.md](examples/README.md)** for detailed usage instructions and customization options.
349
348
 
350
349
  ---
351
350
 
@@ -437,6 +436,7 @@ adata = iaode.annotation_pipeline(
437
436
  ```
438
437
 
439
438
  **Returns AnnData with:**
439
+
440
440
  - `adata.var['peak_type']`: Peak annotation (promoter/exonic/intronic/intergenic)
441
441
  - `adata.var['gene_name']`: Associated gene names
442
442
  - `adata.var['distance_to_tss']`: Distance to nearest TSS
@@ -634,6 +634,7 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
634
634
  ## Acknowledgments
635
635
 
636
636
  Built upon ideas from:
637
+
637
638
  - **scVI-tools**: scVI, PEAKVI, POISSONVI architectures
638
639
  - **Signac** and **SnapATAC2**: scATAC-seq best practices
639
640
  - **Neural ODE** literature: Continuous latent dynamics
@@ -645,53 +646,10 @@ PyTorch, AnnData, and Scanpy ecosystems provide the foundation.
645
646
  ## Contact
646
647
 
647
648
  - **GitHub Issues**: [https://github.com/PeterPonyu/iAODE/issues](https://github.com/PeterPonyu/iAODE/issues)
648
- - **Email**: fuzeyu99@126.com
649
+ - **Email**: <fuzeyu99@126.com>
649
650
 
650
651
  ---
651
652
 
652
653
  ## Changelog
653
654
 
654
- ### v0.2.0 (2025-11-20)
655
-
656
- **Documentation & Usability**
657
- - Comprehensive documentation overhaul (README, examples/README, QUICKSTART)
658
- - Separated scRNA-seq and scATAC-seq workflows with clear examples
659
- - Added automatic dataset download and caching system
660
- - Created `examples/data/download_data.sh` helper script
661
- - Verified all API usage examples against actual implementation
662
-
663
- **Code Quality**
664
- - Cleaned example scripts: removed unused imports, improved error handling
665
- - Fixed all cross-references between examples and core modules
666
- - Enhanced inline documentation and error messages
667
- - Verified method signatures: `get_velocity()`, `get_vfres()`, `get_pseudotime()`, etc.
668
-
669
- **Package Improvements**
670
- - Complete scATAC-seq preprocessing pipeline with TF-IDF and HVP selection
671
- - Improved peak annotation with distance-to-TSS computation
672
- - Enhanced evaluation metrics (DRE + LSE frameworks)
673
- - Better handling of sparse data and zero inflation
674
-
675
- ### v0.1.2 (2025-11-19)
676
-
677
- **Metadata & Contact**
678
- - Updated author name to "Zeyu Fu"
679
- - Set primary contact email to fuzeyu99@126.com
680
- - Fixed BibTeX citation formatting
681
-
682
- ### v0.1.1 (2025-11-19)
683
-
684
- **Bug Fixes**
685
- - Added missing `requests` dependency for scvi-tools compatibility
686
- - Dropped Python 3.8 support (requires Python ≥3.9)
687
- - Fixed CI test imports and matrix configuration
688
-
689
- ### v0.1.0 (2025-11-19)
690
-
691
- **Initial Release**
692
- - VAE with Neural ODE support for trajectory inference
693
- - Complete scATAC-seq peak annotation pipeline
694
- - Comprehensive evaluation metrics
695
- - Benchmark framework vs scVI models
696
- - Multiple encoder types (MLP, Residual, Transformer, Linear)
697
- - 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
 
@@ -265,38 +267,35 @@ Comprehensive examples are available in the `examples/` directory. See **[exampl
265
267
 
266
268
  ### Example Scripts
267
269
 
268
- | Script | Purpose | Best For |
269
- |--------|---------|----------|
270
- | **`scATAC_quickstart.py`** | Complete scATAC pipeline (TF‑IDF → HVP → iAODE) | Real scATAC-seq analysis |
271
- | **`atacseq_annotation.py`** | Peak-to-gene annotation + QC plots | Understanding peak annotation |
272
- | **`trajectory_ode.py`** | Neural ODE pseudotime & velocity | Trajectory inference |
273
- | **`evaluation_metrics.py`** | DR quality + clustering metrics | Model evaluation |
274
- | **`model_evaluation.py`** | Benchmark vs scVI models | Comparative analysis |
275
- | **`basic_usage.py`** | Simple scRNA-seq workflow | Getting started |
276
- | **`trajectory_inference.py`** | Trajectory with vector field | Velocity visualization |
270
+ | Script | Purpose | Modality | Best For |
271
+ |--------|---------|----------|----------|
272
+ | **`basic_usage.py`** | scATAC-seq with 2D/histogram visualizations | scATAC | Getting started with scATAC-seq |
273
+ | **`atacseq_annotation.py`** | Peak-to-gene annotation + QC plots | scATAC | Understanding peak annotation |
274
+ | **`model_evaluation_atac.py`** | Benchmark iAODE vs scVI on scATAC-seq | scATAC | Comparative analysis (chromatin) |
275
+ | **`model_evaluation_rna.py`** | Benchmark iAODE vs scVI on scRNA-seq | scRNA | Comparative analysis (transcriptome) |
276
+ | **`trajectory_inference_atac.py`** | Neural ODE trajectory with scATAC-seq | scATAC | Chromatin accessibility dynamics |
277
+ | **`trajectory_inference_rna.py`** | Neural ODE trajectory with scRNA-seq | scRNA | Transcriptional trajectory |
278
+
277
279
 
278
280
  ### Running Examples
279
281
 
280
282
  ```bash
281
283
  cd examples
282
284
 
283
- # Complete scATAC-seq workflow with auto-download
284
- python atacseq_annotation.py
285
+ # Getting started with scATAC-seq
286
+ python basic_usage.py
285
287
 
286
- # Or use your own data
287
- python scATAC_quickstart.py \
288
- --h5 filtered_peak_bc_matrix.h5 \
289
- --gtf gencode.vM25.annotation.gtf.gz \
290
- --use-ode --latent-dim 32 --i-dim 16
288
+ # Peak-to-gene annotation with auto-download
289
+ python atacseq_annotation.py
291
290
 
292
- # Trajectory inference with synthetic data
293
- python trajectory_ode.py
291
+ # Benchmark models on scATAC-seq data
292
+ python model_evaluation_atac.py
294
293
 
295
- # Comprehensive benchmarking
296
- python model_evaluation.py
294
+ # Trajectory inference with Neural ODE (scRNA-seq)
295
+ python trajectory_inference_rna.py
297
296
  ```
298
297
 
299
- All examples save outputs to `examples/outputs/` with visualizations and processed data. See **[examples/README.md](examples/README.md)** for detailed usage instructions and output descriptions.
298
+ All examples save outputs to `examples/outputs/<example_name>/` by default. See **[examples/README.md](examples/README.md)** for detailed usage instructions and customization options.
300
299
 
301
300
  ---
302
301
 
@@ -388,6 +387,7 @@ adata = iaode.annotation_pipeline(
388
387
  ```
389
388
 
390
389
  **Returns AnnData with:**
390
+
391
391
  - `adata.var['peak_type']`: Peak annotation (promoter/exonic/intronic/intergenic)
392
392
  - `adata.var['gene_name']`: Associated gene names
393
393
  - `adata.var['distance_to_tss']`: Distance to nearest TSS
@@ -585,6 +585,7 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
585
585
  ## Acknowledgments
586
586
 
587
587
  Built upon ideas from:
588
+
588
589
  - **scVI-tools**: scVI, PEAKVI, POISSONVI architectures
589
590
  - **Signac** and **SnapATAC2**: scATAC-seq best practices
590
591
  - **Neural ODE** literature: Continuous latent dynamics
@@ -596,53 +597,10 @@ PyTorch, AnnData, and Scanpy ecosystems provide the foundation.
596
597
  ## Contact
597
598
 
598
599
  - **GitHub Issues**: [https://github.com/PeterPonyu/iAODE/issues](https://github.com/PeterPonyu/iAODE/issues)
599
- - **Email**: fuzeyu99@126.com
600
+ - **Email**: <fuzeyu99@126.com>
600
601
 
601
602
  ---
602
603
 
603
604
  ## Changelog
604
605
 
605
- ### v0.2.0 (2025-11-20)
606
-
607
- **Documentation & Usability**
608
- - Comprehensive documentation overhaul (README, examples/README, QUICKSTART)
609
- - Separated scRNA-seq and scATAC-seq workflows with clear examples
610
- - Added automatic dataset download and caching system
611
- - Created `examples/data/download_data.sh` helper script
612
- - Verified all API usage examples against actual implementation
613
-
614
- **Code Quality**
615
- - Cleaned example scripts: removed unused imports, improved error handling
616
- - Fixed all cross-references between examples and core modules
617
- - Enhanced inline documentation and error messages
618
- - Verified method signatures: `get_velocity()`, `get_vfres()`, `get_pseudotime()`, etc.
619
-
620
- **Package Improvements**
621
- - Complete scATAC-seq preprocessing pipeline with TF-IDF and HVP selection
622
- - Improved peak annotation with distance-to-TSS computation
623
- - Enhanced evaluation metrics (DRE + LSE frameworks)
624
- - Better handling of sparse data and zero inflation
625
-
626
- ### v0.1.2 (2025-11-19)
627
-
628
- **Metadata & Contact**
629
- - Updated author name to "Zeyu Fu"
630
- - Set primary contact email to fuzeyu99@126.com
631
- - Fixed BibTeX citation formatting
632
-
633
- ### v0.1.1 (2025-11-19)
634
-
635
- **Bug Fixes**
636
- - Added missing `requests` dependency for scvi-tools compatibility
637
- - Dropped Python 3.8 support (requires Python ≥3.9)
638
- - Fixed CI test imports and matrix configuration
639
-
640
- ### v0.1.0 (2025-11-19)
641
-
642
- **Initial Release**
643
- - VAE with Neural ODE support for trajectory inference
644
- - Complete scATAC-seq peak annotation pipeline
645
- - Comprehensive evaluation metrics
646
- - Benchmark framework vs scVI models
647
- - Multiple encoder types (MLP, Residual, Transformer, Linear)
648
- - 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.0"
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.1
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
 
@@ -314,38 +316,35 @@ Comprehensive examples are available in the `examples/` directory. See **[exampl
314
316
 
315
317
  ### Example Scripts
316
318
 
317
- | Script | Purpose | Best For |
318
- |--------|---------|----------|
319
- | **`scATAC_quickstart.py`** | Complete scATAC pipeline (TF‑IDF → HVP → iAODE) | Real scATAC-seq analysis |
320
- | **`atacseq_annotation.py`** | Peak-to-gene annotation + QC plots | Understanding peak annotation |
321
- | **`trajectory_ode.py`** | Neural ODE pseudotime & velocity | Trajectory inference |
322
- | **`evaluation_metrics.py`** | DR quality + clustering metrics | Model evaluation |
323
- | **`model_evaluation.py`** | Benchmark vs scVI models | Comparative analysis |
324
- | **`basic_usage.py`** | Simple scRNA-seq workflow | Getting started |
325
- | **`trajectory_inference.py`** | Trajectory with vector field | Velocity visualization |
319
+ | Script | Purpose | Modality | Best For |
320
+ |--------|---------|----------|----------|
321
+ | **`basic_usage.py`** | scATAC-seq with 2D/histogram visualizations | scATAC | Getting started with scATAC-seq |
322
+ | **`atacseq_annotation.py`** | Peak-to-gene annotation + QC plots | scATAC | Understanding peak annotation |
323
+ | **`model_evaluation_atac.py`** | Benchmark iAODE vs scVI on scATAC-seq | scATAC | Comparative analysis (chromatin) |
324
+ | **`model_evaluation_rna.py`** | Benchmark iAODE vs scVI on scRNA-seq | scRNA | Comparative analysis (transcriptome) |
325
+ | **`trajectory_inference_atac.py`** | Neural ODE trajectory with scATAC-seq | scATAC | Chromatin accessibility dynamics |
326
+ | **`trajectory_inference_rna.py`** | Neural ODE trajectory with scRNA-seq | scRNA | Transcriptional trajectory |
327
+
326
328
 
327
329
  ### Running Examples
328
330
 
329
331
  ```bash
330
332
  cd examples
331
333
 
332
- # Complete scATAC-seq workflow with auto-download
333
- python atacseq_annotation.py
334
+ # Getting started with scATAC-seq
335
+ python basic_usage.py
334
336
 
335
- # Or use your own data
336
- python scATAC_quickstart.py \
337
- --h5 filtered_peak_bc_matrix.h5 \
338
- --gtf gencode.vM25.annotation.gtf.gz \
339
- --use-ode --latent-dim 32 --i-dim 16
337
+ # Peak-to-gene annotation with auto-download
338
+ python atacseq_annotation.py
340
339
 
341
- # Trajectory inference with synthetic data
342
- python trajectory_ode.py
340
+ # Benchmark models on scATAC-seq data
341
+ python model_evaluation_atac.py
343
342
 
344
- # Comprehensive benchmarking
345
- python model_evaluation.py
343
+ # Trajectory inference with Neural ODE (scRNA-seq)
344
+ python trajectory_inference_rna.py
346
345
  ```
347
346
 
348
- All examples save outputs to `examples/outputs/` with visualizations and processed data. See **[examples/README.md](examples/README.md)** for detailed usage instructions and output descriptions.
347
+ All examples save outputs to `examples/outputs/<example_name>/` by default. See **[examples/README.md](examples/README.md)** for detailed usage instructions and customization options.
349
348
 
350
349
  ---
351
350
 
@@ -437,6 +436,7 @@ adata = iaode.annotation_pipeline(
437
436
  ```
438
437
 
439
438
  **Returns AnnData with:**
439
+
440
440
  - `adata.var['peak_type']`: Peak annotation (promoter/exonic/intronic/intergenic)
441
441
  - `adata.var['gene_name']`: Associated gene names
442
442
  - `adata.var['distance_to_tss']`: Distance to nearest TSS
@@ -634,6 +634,7 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
634
634
  ## Acknowledgments
635
635
 
636
636
  Built upon ideas from:
637
+
637
638
  - **scVI-tools**: scVI, PEAKVI, POISSONVI architectures
638
639
  - **Signac** and **SnapATAC2**: scATAC-seq best practices
639
640
  - **Neural ODE** literature: Continuous latent dynamics
@@ -645,53 +646,10 @@ PyTorch, AnnData, and Scanpy ecosystems provide the foundation.
645
646
  ## Contact
646
647
 
647
648
  - **GitHub Issues**: [https://github.com/PeterPonyu/iAODE/issues](https://github.com/PeterPonyu/iAODE/issues)
648
- - **Email**: fuzeyu99@126.com
649
+ - **Email**: <fuzeyu99@126.com>
649
650
 
650
651
  ---
651
652
 
652
653
  ## Changelog
653
654
 
654
- ### v0.2.0 (2025-11-20)
655
-
656
- **Documentation & Usability**
657
- - Comprehensive documentation overhaul (README, examples/README, QUICKSTART)
658
- - Separated scRNA-seq and scATAC-seq workflows with clear examples
659
- - Added automatic dataset download and caching system
660
- - Created `examples/data/download_data.sh` helper script
661
- - Verified all API usage examples against actual implementation
662
-
663
- **Code Quality**
664
- - Cleaned example scripts: removed unused imports, improved error handling
665
- - Fixed all cross-references between examples and core modules
666
- - Enhanced inline documentation and error messages
667
- - Verified method signatures: `get_velocity()`, `get_vfres()`, `get_pseudotime()`, etc.
668
-
669
- **Package Improvements**
670
- - Complete scATAC-seq preprocessing pipeline with TF-IDF and HVP selection
671
- - Improved peak annotation with distance-to-TSS computation
672
- - Enhanced evaluation metrics (DRE + LSE frameworks)
673
- - Better handling of sparse data and zero inflation
674
-
675
- ### v0.1.2 (2025-11-19)
676
-
677
- **Metadata & Contact**
678
- - Updated author name to "Zeyu Fu"
679
- - Set primary contact email to fuzeyu99@126.com
680
- - Fixed BibTeX citation formatting
681
-
682
- ### v0.1.1 (2025-11-19)
683
-
684
- **Bug Fixes**
685
- - Added missing `requests` dependency for scvi-tools compatibility
686
- - Dropped Python 3.8 support (requires Python ≥3.9)
687
- - Fixed CI test imports and matrix configuration
688
-
689
- ### v0.1.0 (2025-11-19)
690
-
691
- **Initial Release**
692
- - VAE with Neural ODE support for trajectory inference
693
- - Complete scATAC-seq peak annotation pipeline
694
- - Comprehensive evaluation metrics
695
- - Benchmark framework vs scVI models
696
- - Multiple encoder types (MLP, Residual, Transformer, Linear)
697
- - 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.1"
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