iaode 0.2.2__tar.gz → 0.2.4__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.
- {iaode-0.2.2 → iaode-0.2.4}/LICENSE +1 -1
- {iaode-0.2.2 → iaode-0.2.4}/MANIFEST.in +2 -0
- {iaode-0.2.2/iaode.egg-info → iaode-0.2.4}/PKG-INFO +56 -97
- {iaode-0.2.2 → iaode-0.2.4}/README.md +54 -95
- {iaode-0.2.2 → iaode-0.2.4}/iaode/BEN.py +10 -14
- {iaode-0.2.2 → iaode-0.2.4}/iaode/DRE.py +5 -6
- {iaode-0.2.2 → iaode-0.2.4}/iaode/LSE.py +8 -9
- {iaode-0.2.2 → iaode-0.2.4}/iaode/__init__.py +6 -5
- {iaode-0.2.2 → iaode-0.2.4}/iaode/agent.py +78 -79
- {iaode-0.2.2 → iaode-0.2.4}/iaode/annotation.py +8 -8
- {iaode-0.2.2 → iaode-0.2.4}/iaode/datasets.py +8 -9
- {iaode-0.2.2 → iaode-0.2.4}/iaode/environment.py +2 -2
- {iaode-0.2.2 → iaode-0.2.4}/iaode/mixin.py +3 -3
- {iaode-0.2.2 → iaode-0.2.4}/iaode/model.py +34 -34
- {iaode-0.2.2 → iaode-0.2.4}/iaode/module.py +3 -2
- {iaode-0.2.2 → iaode-0.2.4}/iaode/utils.py +1 -1
- {iaode-0.2.2 → iaode-0.2.4/iaode.egg-info}/PKG-INFO +56 -97
- {iaode-0.2.2 → iaode-0.2.4}/iaode.egg-info/SOURCES.txt +2 -1
- {iaode-0.2.2 → iaode-0.2.4}/pyproject.toml +2 -2
- {iaode-0.2.2 → iaode-0.2.4}/setup.py +1 -1
- iaode-0.2.4/tests/test_smoke.py +21 -0
- {iaode-0.2.2 → iaode-0.2.4}/iaode.egg-info/dependency_links.txt +0 -0
- {iaode-0.2.2 → iaode-0.2.4}/iaode.egg-info/requires.txt +0 -0
- {iaode-0.2.2 → iaode-0.2.4}/iaode.egg-info/top_level.txt +0 -0
- {iaode-0.2.2 → iaode-0.2.4}/requirements.txt +0 -0
- {iaode-0.2.2 → iaode-0.2.4}/setup.cfg +0 -0
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: iaode
|
|
3
|
-
Version: 0.2.
|
|
3
|
+
Version: 0.2.4
|
|
4
4
|
Summary: Interpretable Autoencoder with Ordinary Differential Equations for single-cell omics analysis
|
|
5
5
|
Author-email: Zeyu Fu <fuzeyu99@126.com>
|
|
6
|
-
License: MIT
|
|
6
|
+
License-Expression: MIT
|
|
7
7
|
Project-URL: Homepage, https://github.com/PeterPonyu/iAODE
|
|
8
8
|
Project-URL: Documentation, https://iaode.readthedocs.io
|
|
9
9
|
Project-URL: Repository, https://github.com/PeterPonyu/iAODE
|
|
@@ -49,22 +49,22 @@ Dynamic: license-file
|
|
|
49
49
|
|
|
50
50
|
# iAODE: Interpretable Accessibility ODE VAE for scATAC-seq
|
|
51
51
|
|
|
52
|
-
[](https://
|
|
52
|
+
[](https://pypi.org/project/iaode/) [](https://www.python.org/downloads/) [](https://opensource.org/licenses/MIT) [](https://pytorch.org/) [](https://github.com/PeterPonyu/iAODE/actions/workflows/test.yml)
|
|
53
53
|
|
|
54
|
-
|
|
54
|
+
**iAODE** (Interpretable Accessibility ODE VAE) is a lightweight deep learning framework purpose-built for single‑cell ATAC‑seq (scATAC‑seq) data. It integrates a Variational Autoencoder (VAE) with a Neural ODE and an interpretable bottleneck to jointly achieve:
|
|
55
55
|
|
|
56
|
-
1. **Robust
|
|
57
|
-
2. **Continuous
|
|
58
|
-
3. **Interpretable
|
|
59
|
-
4. **Scalable
|
|
56
|
+
1. **Robust Modeling:** Handles sparse count accessibility profiles using Negative Binomial (NB) or Zero-Inflated Negative Binomial (ZINB) likelihoods.
|
|
57
|
+
2. **Continuous Trajectory Inference:** Infers dynamics via Neural ODE pseudotime and latent velocity fields.
|
|
58
|
+
3. **Interpretable Latent Factors:** Utilizes a biologically aligned bottleneck to extract meaningful features.
|
|
59
|
+
4. **Scalable Preprocessing:** Implements TF‑IDF normalization and Highly Variable Peak (HVP) selection, aligned with Signac and SnapATAC2 best practices.
|
|
60
60
|
|
|
61
|
-
The design targets the unique characteristics of scATAC data
|
|
61
|
+
The design specifically targets the unique characteristics of scATAC data, including extreme sparsity, library size variability, heterogeneous peak accessibility kinetics, and dynamic regulatory trajectories.
|
|
62
62
|
|
|
63
63
|
---
|
|
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
|
|
@@ -79,16 +79,18 @@ Encoder (MLP / Residual / Transformer) --> q(z|x)
|
|
|
79
79
|
Decoder (NB / ZINB / MSE) -> Reconstruction x_hat
|
|
80
80
|
```
|
|
81
81
|
|
|
82
|
-
**Key Components
|
|
83
|
-
- **TF‑IDF Normalization**: Stabilizes cell‑wise peak depth, emphasizes specific accessibility
|
|
84
|
-
- **Highly Variable Peaks (HVP)**: Variance / VMR / deviance‑based selection
|
|
85
|
-
- **NB/ZINB Likelihoods**: Models over‑dispersion & zero inflation
|
|
86
|
-
- **Neural ODE**: Smooth accessibility progression with pseudotime & velocity
|
|
87
|
-
- **Interpretable Bottleneck**: Linear compression preserving biologically decodable axes
|
|
88
|
-
- **Multi‑Objective Regularization**: β‑VAE KL, β‑TC, DIP, InfoVAE MMD, ODE consistency
|
|
82
|
+
**Key Components:**
|
|
89
83
|
|
|
90
|
-
**
|
|
91
|
-
|
|
84
|
+
- **TF‑IDF Normalization:** Stabilizes cell‑wise sequencing depth and highlights specific accessibility patterns.
|
|
85
|
+
- **Highly Variable Peaks (HVP):** Selects informative peaks using variance, VMR, or deviance‑based methods.
|
|
86
|
+
- **NB/ZINB Likelihoods:** Explicitly models over‑dispersion and zero inflation inherent in single-cell data.
|
|
87
|
+
- **Neural ODE:** Learns smooth accessibility progressions using pseudotime and velocity.
|
|
88
|
+
- **Interpretable Bottleneck:** A linear compression layer that preserves biologically decodable axes.
|
|
89
|
+
- **Multi‑Objective Regularization:** Includes $\beta$-VAE KL, $\beta$-TC, DIP, InfoVAE MMD, and ODE consistency losses.
|
|
90
|
+
|
|
91
|
+
**Loss Function:**
|
|
92
|
+
|
|
93
|
+
```python
|
|
92
94
|
Loss = recon + i_recon + ODE_consistency + β·KL + dip·DIP + tc·TC + info·MMD
|
|
93
95
|
```
|
|
94
96
|
|
|
@@ -118,7 +120,7 @@ pip install -e .
|
|
|
118
120
|
- Scanpy ≥ 1.8.0
|
|
119
121
|
- scvi-tools ≥ 0.16.0
|
|
120
122
|
|
|
121
|
-
See `requirements.txt` for complete dependencies.
|
|
123
|
+
See `requirements.txt` for the complete list of dependencies.
|
|
122
124
|
|
|
123
125
|
---
|
|
124
126
|
|
|
@@ -169,10 +171,10 @@ print(f"Retained {adata.n_vars} highly variable peaks")
|
|
|
169
171
|
model = iaode.agent(
|
|
170
172
|
adata,
|
|
171
173
|
layer='counts',
|
|
172
|
-
latent_dim=32, # Higher for scATAC complexity
|
|
173
|
-
hidden_dim=512, # Deeper for regulatory patterns
|
|
174
|
+
latent_dim=32, # Higher dimension for scATAC complexity
|
|
175
|
+
hidden_dim=512, # Deeper network for regulatory patterns
|
|
174
176
|
encoder_type='mlp',
|
|
175
|
-
loss_mode='zinb', #
|
|
177
|
+
loss_mode='zinb', # Recommended for sparse scATAC data
|
|
176
178
|
use_ode=False
|
|
177
179
|
)
|
|
178
180
|
|
|
@@ -263,13 +265,13 @@ plt.show()
|
|
|
263
265
|
|
|
264
266
|
### scATAC-seq Peak Annotation Pipeline
|
|
265
267
|
|
|
266
|
-
**Automatic
|
|
268
|
+
**Automatic Data Download** - iAODE automatically downloads and caches datasets:
|
|
267
269
|
|
|
268
270
|
```python
|
|
269
271
|
import iaode
|
|
270
272
|
|
|
271
|
-
#
|
|
272
|
-
# Files cached in ~/.iaode/data/ and reused on subsequent runs
|
|
273
|
+
# Download mouse brain 5k scATAC-seq + GENCODE vM25 GTF
|
|
274
|
+
# Files are cached in ~/.iaode/data/ and reused on subsequent runs
|
|
273
275
|
h5_file, gtf_file = iaode.datasets.mouse_brain_5k_atacseq()
|
|
274
276
|
|
|
275
277
|
# Run complete annotation pipeline
|
|
@@ -277,21 +279,21 @@ adata = iaode.annotation_pipeline(
|
|
|
277
279
|
h5_file=str(h5_file),
|
|
278
280
|
gtf_file=str(gtf_file),
|
|
279
281
|
promoter_upstream=2000, # TSS upstream region
|
|
280
|
-
promoter_downstream=500,
|
|
281
|
-
apply_tfidf=True, # TF-IDF normalization
|
|
282
|
+
promoter_downstream=500, # TSS downstream region
|
|
283
|
+
apply_tfidf=True, # Apply TF-IDF normalization
|
|
282
284
|
select_hvp=True, # Select highly variable peaks
|
|
283
285
|
n_top_peaks=20000 # Number of HVPs to retain
|
|
284
286
|
)
|
|
285
287
|
|
|
286
|
-
# AnnData
|
|
287
|
-
# - adata.var['peak_type']: promoter/exonic/intronic/intergenic
|
|
288
|
+
# The returned AnnData object contains:
|
|
289
|
+
# - adata.var['peak_type']: Annotation (promoter/exonic/intronic/intergenic)
|
|
288
290
|
# - adata.var['gene_name']: Associated gene names
|
|
289
291
|
# - adata.var['distance_to_tss']: Distance to nearest TSS
|
|
290
292
|
# - adata.var['highly_variable']: HVP selection mask
|
|
291
|
-
# - Preprocessed
|
|
293
|
+
# - Preprocessed counts (TF-IDF)
|
|
292
294
|
```
|
|
293
295
|
|
|
294
|
-
**Available
|
|
296
|
+
**Available Datasets:**
|
|
295
297
|
|
|
296
298
|
```python
|
|
297
299
|
# Mouse brain 5k scATAC-seq
|
|
@@ -305,12 +307,11 @@ iaode.datasets.list_cached_files() # Show cached files
|
|
|
305
307
|
iaode.datasets.clear_cache() # Clear all cached data
|
|
306
308
|
```
|
|
307
309
|
|
|
308
|
-
|
|
309
310
|
---
|
|
310
311
|
|
|
311
312
|
## Examples
|
|
312
313
|
|
|
313
|
-
Comprehensive examples are
|
|
314
|
+
Comprehensive examples are provided in the `examples/` directory. See **[examples/README.md](examples/README.md)** for detailed documentation.
|
|
314
315
|
|
|
315
316
|
### Example Scripts
|
|
316
317
|
|
|
@@ -323,7 +324,6 @@ Comprehensive examples are available in the `examples/` directory. See **[exampl
|
|
|
323
324
|
| **`trajectory_inference_atac.py`** | Neural ODE trajectory with scATAC-seq | scATAC | Chromatin accessibility dynamics |
|
|
324
325
|
| **`trajectory_inference_rna.py`** | Neural ODE trajectory with scRNA-seq | scRNA | Transcriptional trajectory |
|
|
325
326
|
|
|
326
|
-
|
|
327
327
|
### Running Examples
|
|
328
328
|
|
|
329
329
|
```bash
|
|
@@ -342,7 +342,7 @@ python model_evaluation_atac.py
|
|
|
342
342
|
python trajectory_inference_rna.py
|
|
343
343
|
```
|
|
344
344
|
|
|
345
|
-
|
|
345
|
+
By default, all examples save outputs to `examples/outputs/<example_name>/`.
|
|
346
346
|
|
|
347
347
|
---
|
|
348
348
|
|
|
@@ -355,13 +355,13 @@ All examples save outputs to `examples/outputs/<example_name>/` by default. See
|
|
|
355
355
|
```python
|
|
356
356
|
model = iaode.agent(
|
|
357
357
|
adata, # AnnData object
|
|
358
|
-
layer='counts', # Data layer to use
|
|
358
|
+
layer='counts', # Data layer to use (key in adata.layers or 'X')
|
|
359
359
|
latent_dim=10, # Latent space dimension
|
|
360
360
|
hidden_dim=128, # Hidden layer dimension
|
|
361
|
-
i_dim=
|
|
361
|
+
i_dim=2, # Interpretable bottleneck dimension (default: 2)
|
|
362
362
|
use_ode=False, # Enable Neural ODE
|
|
363
363
|
loss_mode='nb', # Loss function: 'mse', 'nb', 'zinb'
|
|
364
|
-
encoder_type='mlp', # Encoder: 'mlp', '
|
|
364
|
+
encoder_type='mlp', # Encoder: 'mlp', 'mlp_residual', 'transformer', 'linear'
|
|
365
365
|
lr=1e-4, # Learning rate
|
|
366
366
|
batch_size=128, # Batch size
|
|
367
367
|
beta=1.0, # KL divergence weight
|
|
@@ -434,6 +434,7 @@ adata = iaode.annotation_pipeline(
|
|
|
434
434
|
```
|
|
435
435
|
|
|
436
436
|
**Returns AnnData with:**
|
|
437
|
+
|
|
437
438
|
- `adata.var['peak_type']`: Peak annotation (promoter/exonic/intronic/intergenic)
|
|
438
439
|
- `adata.var['gene_name']`: Associated gene names
|
|
439
440
|
- `adata.var['distance_to_tss']`: Distance to nearest TSS
|
|
@@ -610,15 +611,15 @@ If you use iAODE in your research, please cite:
|
|
|
610
611
|
|
|
611
612
|
## Contributing
|
|
612
613
|
|
|
613
|
-
Contributions are welcome! Please:
|
|
614
|
+
Contributions are welcome! Please follow these steps:
|
|
614
615
|
|
|
615
|
-
1. Fork the repository
|
|
616
|
-
2. Create a feature branch (`git checkout -b feature/AmazingFeature`)
|
|
617
|
-
3. Commit changes (`git commit -m 'Add AmazingFeature'`)
|
|
618
|
-
4. Push to branch (`git push origin feature/AmazingFeature`)
|
|
619
|
-
5. Open a Pull Request
|
|
616
|
+
1. Fork the repository.
|
|
617
|
+
2. Create a feature branch (`git checkout -b feature/AmazingFeature`).
|
|
618
|
+
3. Commit your changes (`git commit -m 'Add AmazingFeature'`).
|
|
619
|
+
4. Push to the branch (`git push origin feature/AmazingFeature`).
|
|
620
|
+
5. Open a Pull Request.
|
|
620
621
|
|
|
621
|
-
For major changes, please open an issue first to discuss proposed
|
|
622
|
+
For major changes, please open an issue first to discuss the proposed modifications.
|
|
622
623
|
|
|
623
624
|
---
|
|
624
625
|
|
|
@@ -630,65 +631,23 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
|
|
|
630
631
|
|
|
631
632
|
## Acknowledgments
|
|
632
633
|
|
|
633
|
-
Built upon
|
|
634
|
-
|
|
635
|
-
- **
|
|
636
|
-
- **
|
|
634
|
+
Built upon concepts from:
|
|
635
|
+
|
|
636
|
+
- **scVI-tools:** scVI, PEAKVI, and POISSONVI architectures.
|
|
637
|
+
- **Signac** and **SnapATAC2:** Best practices for scATAC-seq data processing.
|
|
638
|
+
- **Neural ODE:** Literature regarding continuous latent dynamics.
|
|
637
639
|
|
|
638
|
-
PyTorch, AnnData, and Scanpy ecosystems
|
|
640
|
+
Foundational support is provided by the PyTorch, AnnData, and Scanpy ecosystems.
|
|
639
641
|
|
|
640
642
|
---
|
|
641
643
|
|
|
642
644
|
## Contact
|
|
643
645
|
|
|
644
|
-
- **GitHub Issues
|
|
645
|
-
- **Email
|
|
646
|
+
- **GitHub Issues:** [https://github.com/PeterPonyu/iAODE/issues](https://github.com/PeterPonyu/iAODE/issues)
|
|
647
|
+
- **Email:** <fuzeyu99@126.com>
|
|
646
648
|
|
|
647
649
|
---
|
|
648
650
|
|
|
649
651
|
## Changelog
|
|
650
652
|
|
|
651
|
-
|
|
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)
|
|
653
|
+
See [CHANGELOG.md](CHANGELOG.md) for detailed release notes and version history.
|
|
@@ -1,21 +1,21 @@
|
|
|
1
1
|
# iAODE: Interpretable Accessibility ODE VAE for scATAC-seq
|
|
2
2
|
|
|
3
|
-
[](https://
|
|
3
|
+
[](https://pypi.org/project/iaode/) [](https://www.python.org/downloads/) [](https://opensource.org/licenses/MIT) [](https://pytorch.org/) [](https://github.com/PeterPonyu/iAODE/actions/workflows/test.yml)
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
**iAODE** (Interpretable Accessibility ODE VAE) is a lightweight deep learning framework purpose-built for single‑cell ATAC‑seq (scATAC‑seq) data. It integrates a Variational Autoencoder (VAE) with a Neural ODE and an interpretable bottleneck to jointly achieve:
|
|
6
6
|
|
|
7
|
-
1. **Robust
|
|
8
|
-
2. **Continuous
|
|
9
|
-
3. **Interpretable
|
|
10
|
-
4. **Scalable
|
|
7
|
+
1. **Robust Modeling:** Handles sparse count accessibility profiles using Negative Binomial (NB) or Zero-Inflated Negative Binomial (ZINB) likelihoods.
|
|
8
|
+
2. **Continuous Trajectory Inference:** Infers dynamics via Neural ODE pseudotime and latent velocity fields.
|
|
9
|
+
3. **Interpretable Latent Factors:** Utilizes a biologically aligned bottleneck to extract meaningful features.
|
|
10
|
+
4. **Scalable Preprocessing:** Implements TF‑IDF normalization and Highly Variable Peak (HVP) selection, aligned with Signac and SnapATAC2 best practices.
|
|
11
11
|
|
|
12
|
-
The design targets the unique characteristics of scATAC data
|
|
12
|
+
The design specifically targets the unique characteristics of scATAC data, including extreme sparsity, library size variability, heterogeneous peak accessibility kinetics, and dynamic regulatory trajectories.
|
|
13
13
|
|
|
14
14
|
---
|
|
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
|
|
@@ -30,16 +30,18 @@ Encoder (MLP / Residual / Transformer) --> q(z|x)
|
|
|
30
30
|
Decoder (NB / ZINB / MSE) -> Reconstruction x_hat
|
|
31
31
|
```
|
|
32
32
|
|
|
33
|
-
**Key Components
|
|
34
|
-
- **TF‑IDF Normalization**: Stabilizes cell‑wise peak depth, emphasizes specific accessibility
|
|
35
|
-
- **Highly Variable Peaks (HVP)**: Variance / VMR / deviance‑based selection
|
|
36
|
-
- **NB/ZINB Likelihoods**: Models over‑dispersion & zero inflation
|
|
37
|
-
- **Neural ODE**: Smooth accessibility progression with pseudotime & velocity
|
|
38
|
-
- **Interpretable Bottleneck**: Linear compression preserving biologically decodable axes
|
|
39
|
-
- **Multi‑Objective Regularization**: β‑VAE KL, β‑TC, DIP, InfoVAE MMD, ODE consistency
|
|
33
|
+
**Key Components:**
|
|
40
34
|
|
|
41
|
-
**
|
|
42
|
-
|
|
35
|
+
- **TF‑IDF Normalization:** Stabilizes cell‑wise sequencing depth and highlights specific accessibility patterns.
|
|
36
|
+
- **Highly Variable Peaks (HVP):** Selects informative peaks using variance, VMR, or deviance‑based methods.
|
|
37
|
+
- **NB/ZINB Likelihoods:** Explicitly models over‑dispersion and zero inflation inherent in single-cell data.
|
|
38
|
+
- **Neural ODE:** Learns smooth accessibility progressions using pseudotime and velocity.
|
|
39
|
+
- **Interpretable Bottleneck:** A linear compression layer that preserves biologically decodable axes.
|
|
40
|
+
- **Multi‑Objective Regularization:** Includes $\beta$-VAE KL, $\beta$-TC, DIP, InfoVAE MMD, and ODE consistency losses.
|
|
41
|
+
|
|
42
|
+
**Loss Function:**
|
|
43
|
+
|
|
44
|
+
```python
|
|
43
45
|
Loss = recon + i_recon + ODE_consistency + β·KL + dip·DIP + tc·TC + info·MMD
|
|
44
46
|
```
|
|
45
47
|
|
|
@@ -69,7 +71,7 @@ pip install -e .
|
|
|
69
71
|
- Scanpy ≥ 1.8.0
|
|
70
72
|
- scvi-tools ≥ 0.16.0
|
|
71
73
|
|
|
72
|
-
See `requirements.txt` for complete dependencies.
|
|
74
|
+
See `requirements.txt` for the complete list of dependencies.
|
|
73
75
|
|
|
74
76
|
---
|
|
75
77
|
|
|
@@ -120,10 +122,10 @@ print(f"Retained {adata.n_vars} highly variable peaks")
|
|
|
120
122
|
model = iaode.agent(
|
|
121
123
|
adata,
|
|
122
124
|
layer='counts',
|
|
123
|
-
latent_dim=32, # Higher for scATAC complexity
|
|
124
|
-
hidden_dim=512, # Deeper for regulatory patterns
|
|
125
|
+
latent_dim=32, # Higher dimension for scATAC complexity
|
|
126
|
+
hidden_dim=512, # Deeper network for regulatory patterns
|
|
125
127
|
encoder_type='mlp',
|
|
126
|
-
loss_mode='zinb', #
|
|
128
|
+
loss_mode='zinb', # Recommended for sparse scATAC data
|
|
127
129
|
use_ode=False
|
|
128
130
|
)
|
|
129
131
|
|
|
@@ -214,13 +216,13 @@ plt.show()
|
|
|
214
216
|
|
|
215
217
|
### scATAC-seq Peak Annotation Pipeline
|
|
216
218
|
|
|
217
|
-
**Automatic
|
|
219
|
+
**Automatic Data Download** - iAODE automatically downloads and caches datasets:
|
|
218
220
|
|
|
219
221
|
```python
|
|
220
222
|
import iaode
|
|
221
223
|
|
|
222
|
-
#
|
|
223
|
-
# Files cached in ~/.iaode/data/ and reused on subsequent runs
|
|
224
|
+
# Download mouse brain 5k scATAC-seq + GENCODE vM25 GTF
|
|
225
|
+
# Files are cached in ~/.iaode/data/ and reused on subsequent runs
|
|
224
226
|
h5_file, gtf_file = iaode.datasets.mouse_brain_5k_atacseq()
|
|
225
227
|
|
|
226
228
|
# Run complete annotation pipeline
|
|
@@ -228,21 +230,21 @@ adata = iaode.annotation_pipeline(
|
|
|
228
230
|
h5_file=str(h5_file),
|
|
229
231
|
gtf_file=str(gtf_file),
|
|
230
232
|
promoter_upstream=2000, # TSS upstream region
|
|
231
|
-
promoter_downstream=500,
|
|
232
|
-
apply_tfidf=True, # TF-IDF normalization
|
|
233
|
+
promoter_downstream=500, # TSS downstream region
|
|
234
|
+
apply_tfidf=True, # Apply TF-IDF normalization
|
|
233
235
|
select_hvp=True, # Select highly variable peaks
|
|
234
236
|
n_top_peaks=20000 # Number of HVPs to retain
|
|
235
237
|
)
|
|
236
238
|
|
|
237
|
-
# AnnData
|
|
238
|
-
# - adata.var['peak_type']: promoter/exonic/intronic/intergenic
|
|
239
|
+
# The returned AnnData object contains:
|
|
240
|
+
# - adata.var['peak_type']: Annotation (promoter/exonic/intronic/intergenic)
|
|
239
241
|
# - adata.var['gene_name']: Associated gene names
|
|
240
242
|
# - adata.var['distance_to_tss']: Distance to nearest TSS
|
|
241
243
|
# - adata.var['highly_variable']: HVP selection mask
|
|
242
|
-
# - Preprocessed
|
|
244
|
+
# - Preprocessed counts (TF-IDF)
|
|
243
245
|
```
|
|
244
246
|
|
|
245
|
-
**Available
|
|
247
|
+
**Available Datasets:**
|
|
246
248
|
|
|
247
249
|
```python
|
|
248
250
|
# Mouse brain 5k scATAC-seq
|
|
@@ -256,12 +258,11 @@ iaode.datasets.list_cached_files() # Show cached files
|
|
|
256
258
|
iaode.datasets.clear_cache() # Clear all cached data
|
|
257
259
|
```
|
|
258
260
|
|
|
259
|
-
|
|
260
261
|
---
|
|
261
262
|
|
|
262
263
|
## Examples
|
|
263
264
|
|
|
264
|
-
Comprehensive examples are
|
|
265
|
+
Comprehensive examples are provided in the `examples/` directory. See **[examples/README.md](examples/README.md)** for detailed documentation.
|
|
265
266
|
|
|
266
267
|
### Example Scripts
|
|
267
268
|
|
|
@@ -274,7 +275,6 @@ Comprehensive examples are available in the `examples/` directory. See **[exampl
|
|
|
274
275
|
| **`trajectory_inference_atac.py`** | Neural ODE trajectory with scATAC-seq | scATAC | Chromatin accessibility dynamics |
|
|
275
276
|
| **`trajectory_inference_rna.py`** | Neural ODE trajectory with scRNA-seq | scRNA | Transcriptional trajectory |
|
|
276
277
|
|
|
277
|
-
|
|
278
278
|
### Running Examples
|
|
279
279
|
|
|
280
280
|
```bash
|
|
@@ -293,7 +293,7 @@ python model_evaluation_atac.py
|
|
|
293
293
|
python trajectory_inference_rna.py
|
|
294
294
|
```
|
|
295
295
|
|
|
296
|
-
|
|
296
|
+
By default, all examples save outputs to `examples/outputs/<example_name>/`.
|
|
297
297
|
|
|
298
298
|
---
|
|
299
299
|
|
|
@@ -306,13 +306,13 @@ All examples save outputs to `examples/outputs/<example_name>/` by default. See
|
|
|
306
306
|
```python
|
|
307
307
|
model = iaode.agent(
|
|
308
308
|
adata, # AnnData object
|
|
309
|
-
layer='counts', # Data layer to use
|
|
309
|
+
layer='counts', # Data layer to use (key in adata.layers or 'X')
|
|
310
310
|
latent_dim=10, # Latent space dimension
|
|
311
311
|
hidden_dim=128, # Hidden layer dimension
|
|
312
|
-
i_dim=
|
|
312
|
+
i_dim=2, # Interpretable bottleneck dimension (default: 2)
|
|
313
313
|
use_ode=False, # Enable Neural ODE
|
|
314
314
|
loss_mode='nb', # Loss function: 'mse', 'nb', 'zinb'
|
|
315
|
-
encoder_type='mlp', # Encoder: 'mlp', '
|
|
315
|
+
encoder_type='mlp', # Encoder: 'mlp', 'mlp_residual', 'transformer', 'linear'
|
|
316
316
|
lr=1e-4, # Learning rate
|
|
317
317
|
batch_size=128, # Batch size
|
|
318
318
|
beta=1.0, # KL divergence weight
|
|
@@ -385,6 +385,7 @@ adata = iaode.annotation_pipeline(
|
|
|
385
385
|
```
|
|
386
386
|
|
|
387
387
|
**Returns AnnData with:**
|
|
388
|
+
|
|
388
389
|
- `adata.var['peak_type']`: Peak annotation (promoter/exonic/intronic/intergenic)
|
|
389
390
|
- `adata.var['gene_name']`: Associated gene names
|
|
390
391
|
- `adata.var['distance_to_tss']`: Distance to nearest TSS
|
|
@@ -561,15 +562,15 @@ If you use iAODE in your research, please cite:
|
|
|
561
562
|
|
|
562
563
|
## Contributing
|
|
563
564
|
|
|
564
|
-
Contributions are welcome! Please:
|
|
565
|
+
Contributions are welcome! Please follow these steps:
|
|
565
566
|
|
|
566
|
-
1. Fork the repository
|
|
567
|
-
2. Create a feature branch (`git checkout -b feature/AmazingFeature`)
|
|
568
|
-
3. Commit changes (`git commit -m 'Add AmazingFeature'`)
|
|
569
|
-
4. Push to branch (`git push origin feature/AmazingFeature`)
|
|
570
|
-
5. Open a Pull Request
|
|
567
|
+
1. Fork the repository.
|
|
568
|
+
2. Create a feature branch (`git checkout -b feature/AmazingFeature`).
|
|
569
|
+
3. Commit your changes (`git commit -m 'Add AmazingFeature'`).
|
|
570
|
+
4. Push to the branch (`git push origin feature/AmazingFeature`).
|
|
571
|
+
5. Open a Pull Request.
|
|
571
572
|
|
|
572
|
-
For major changes, please open an issue first to discuss proposed
|
|
573
|
+
For major changes, please open an issue first to discuss the proposed modifications.
|
|
573
574
|
|
|
574
575
|
---
|
|
575
576
|
|
|
@@ -581,65 +582,23 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
|
|
|
581
582
|
|
|
582
583
|
## Acknowledgments
|
|
583
584
|
|
|
584
|
-
Built upon
|
|
585
|
-
|
|
586
|
-
- **
|
|
587
|
-
- **
|
|
585
|
+
Built upon concepts from:
|
|
586
|
+
|
|
587
|
+
- **scVI-tools:** scVI, PEAKVI, and POISSONVI architectures.
|
|
588
|
+
- **Signac** and **SnapATAC2:** Best practices for scATAC-seq data processing.
|
|
589
|
+
- **Neural ODE:** Literature regarding continuous latent dynamics.
|
|
588
590
|
|
|
589
|
-
PyTorch, AnnData, and Scanpy ecosystems
|
|
591
|
+
Foundational support is provided by the PyTorch, AnnData, and Scanpy ecosystems.
|
|
590
592
|
|
|
591
593
|
---
|
|
592
594
|
|
|
593
595
|
## Contact
|
|
594
596
|
|
|
595
|
-
- **GitHub Issues
|
|
596
|
-
- **Email
|
|
597
|
+
- **GitHub Issues:** [https://github.com/PeterPonyu/iAODE/issues](https://github.com/PeterPonyu/iAODE/issues)
|
|
598
|
+
- **Email:** <fuzeyu99@126.com>
|
|
597
599
|
|
|
598
600
|
---
|
|
599
601
|
|
|
600
602
|
## Changelog
|
|
601
603
|
|
|
602
|
-
|
|
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)
|
|
604
|
+
See [CHANGELOG.md](CHANGELOG.md) for detailed release notes and version history.
|
|
@@ -1,24 +1,20 @@
|
|
|
1
|
-
import gc
|
|
2
|
-
import os
|
|
3
1
|
import time
|
|
4
2
|
import numpy as np
|
|
5
|
-
import
|
|
6
|
-
import scanpy as sc
|
|
7
|
-
import scipy.sparse as sp
|
|
3
|
+
import scanpy as sc # type: ignore
|
|
8
4
|
import torch
|
|
9
|
-
from sklearn.cluster import KMeans
|
|
10
|
-
from sklearn.metrics import (
|
|
5
|
+
from sklearn.cluster import KMeans # type: ignore
|
|
6
|
+
from sklearn.metrics import ( # type: ignore
|
|
11
7
|
normalized_mutual_info_score,
|
|
12
8
|
adjusted_mutual_info_score,
|
|
13
9
|
silhouette_score,
|
|
14
10
|
davies_bouldin_score,
|
|
15
11
|
calinski_harabasz_score
|
|
16
12
|
)
|
|
17
|
-
from sklearn.model_selection import train_test_split
|
|
13
|
+
from sklearn.model_selection import train_test_split # type: ignore
|
|
18
14
|
|
|
19
15
|
# scVI imports
|
|
20
|
-
from scvi.model import SCVI, PEAKVI
|
|
21
|
-
from scvi.external import POISSONVI
|
|
16
|
+
from scvi.model import SCVI, PEAKVI # type: ignore
|
|
17
|
+
from scvi.external import POISSONVI # type: ignore
|
|
22
18
|
from .DRE import evaluate_dimensionality_reduction
|
|
23
19
|
from .LSE import evaluate_single_cell_latent_space
|
|
24
20
|
|
|
@@ -77,7 +73,7 @@ class DataSplitter:
|
|
|
77
73
|
self.test_idx = test_idx
|
|
78
74
|
self.train_val_idx = train_val_idx
|
|
79
75
|
|
|
80
|
-
print(
|
|
76
|
+
print("\nData split sizes:")
|
|
81
77
|
print(f" Total: {self.n_samples}")
|
|
82
78
|
print(f" Train: {len(train_idx)} ({len(train_idx)/self.n_samples*100:.1f}%)")
|
|
83
79
|
print(f" Val: {len(val_idx)} ({len(val_idx)/self.n_samples*100:.1f}%)")
|
|
@@ -245,7 +241,7 @@ def train_scvi_models(adata, splitter, n_latent=10, n_epochs=400, batch_size=128
|
|
|
245
241
|
'actual_epochs': actual_epochs
|
|
246
242
|
}
|
|
247
243
|
|
|
248
|
-
print(
|
|
244
|
+
print("✓ SCVI training completed")
|
|
249
245
|
print(f" Epochs: {actual_epochs}/{n_epochs}, Time: {train_time:.2f}s, Peak GPU Memory: {peak_memory:.3f} GB")
|
|
250
246
|
|
|
251
247
|
except Exception as e:
|
|
@@ -308,7 +304,7 @@ def train_scvi_models(adata, splitter, n_latent=10, n_epochs=400, batch_size=128
|
|
|
308
304
|
'actual_epochs': actual_epochs
|
|
309
305
|
}
|
|
310
306
|
|
|
311
|
-
print(
|
|
307
|
+
print("✓ PEAKVI training completed")
|
|
312
308
|
print(f" Epochs: {actual_epochs}/{n_epochs}, Time: {train_time:.2f}s, Peak GPU Memory: {peak_memory:.3f} GB")
|
|
313
309
|
|
|
314
310
|
except Exception as e:
|
|
@@ -371,7 +367,7 @@ def train_scvi_models(adata, splitter, n_latent=10, n_epochs=400, batch_size=128
|
|
|
371
367
|
'actual_epochs': actual_epochs
|
|
372
368
|
}
|
|
373
369
|
|
|
374
|
-
print(
|
|
370
|
+
print("✓ POISSONVI training completed")
|
|
375
371
|
print(f" Epochs: {actual_epochs}/{n_epochs}, Time: {train_time:.2f}s, Peak GPU Memory: {peak_memory:.3f} GB")
|
|
376
372
|
|
|
377
373
|
except Exception as e:
|