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.
- {iaode-0.2.1 → iaode-0.2.3}/LICENSE +1 -1
- {iaode-0.2.1/iaode.egg-info → iaode-0.2.3}/PKG-INFO +27 -69
- {iaode-0.2.1 → iaode-0.2.3}/README.md +26 -68
- {iaode-0.2.1 → iaode-0.2.3}/iaode/BEN.py +8 -8
- {iaode-0.2.1 → iaode-0.2.3}/iaode/DRE.py +5 -6
- {iaode-0.2.1 → iaode-0.2.3}/iaode/LSE.py +9 -9
- {iaode-0.2.1 → iaode-0.2.3}/iaode/__init__.py +6 -5
- {iaode-0.2.1 → iaode-0.2.3}/iaode/agent.py +78 -79
- {iaode-0.2.1 → iaode-0.2.3}/iaode/annotation.py +8 -8
- {iaode-0.2.1 → iaode-0.2.3}/iaode/datasets.py +2 -2
- {iaode-0.2.1 → iaode-0.2.3}/iaode/environment.py +2 -2
- {iaode-0.2.1 → iaode-0.2.3}/iaode/mixin.py +3 -3
- {iaode-0.2.1 → iaode-0.2.3}/iaode/model.py +34 -34
- {iaode-0.2.1 → iaode-0.2.3}/iaode/module.py +3 -2
- {iaode-0.2.1 → iaode-0.2.3}/iaode/utils.py +1 -1
- {iaode-0.2.1 → iaode-0.2.3/iaode.egg-info}/PKG-INFO +27 -69
- {iaode-0.2.1 → iaode-0.2.3}/iaode.egg-info/SOURCES.txt +2 -1
- {iaode-0.2.1 → iaode-0.2.3}/pyproject.toml +1 -1
- {iaode-0.2.1 → iaode-0.2.3}/setup.py +1 -1
- iaode-0.2.3/tests/test_smoke.py +21 -0
- {iaode-0.2.1 → iaode-0.2.3}/MANIFEST.in +0 -0
- {iaode-0.2.1 → iaode-0.2.3}/iaode.egg-info/dependency_links.txt +0 -0
- {iaode-0.2.1 → iaode-0.2.3}/iaode.egg-info/requires.txt +0 -0
- {iaode-0.2.1 → iaode-0.2.3}/iaode.egg-info/top_level.txt +0 -0
- {iaode-0.2.1 → iaode-0.2.3}/requirements.txt +0 -0
- {iaode-0.2.1 → iaode-0.2.3}/setup.cfg +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: iaode
|
|
3
|
-
Version: 0.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
|
|
|
@@ -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
|
-
| **`
|
|
320
|
-
| **`atacseq_annotation.py`** | Peak-to-gene annotation + QC plots | Understanding peak annotation |
|
|
321
|
-
| **`
|
|
322
|
-
| **`
|
|
323
|
-
| **`
|
|
324
|
-
| **`
|
|
325
|
-
|
|
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
|
-
#
|
|
333
|
-
python
|
|
334
|
+
# Getting started with scATAC-seq
|
|
335
|
+
python basic_usage.py
|
|
334
336
|
|
|
335
|
-
#
|
|
336
|
-
python
|
|
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
|
-
#
|
|
342
|
-
python
|
|
340
|
+
# Benchmark models on scATAC-seq data
|
|
341
|
+
python model_evaluation_atac.py
|
|
343
342
|
|
|
344
|
-
#
|
|
345
|
-
python
|
|
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
|
|
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
|
-
|
|
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
|
-
| **`
|
|
271
|
-
| **`atacseq_annotation.py`** | Peak-to-gene annotation + QC plots | Understanding peak annotation |
|
|
272
|
-
| **`
|
|
273
|
-
| **`
|
|
274
|
-
| **`
|
|
275
|
-
| **`
|
|
276
|
-
|
|
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
|
-
#
|
|
284
|
-
python
|
|
285
|
+
# Getting started with scATAC-seq
|
|
286
|
+
python basic_usage.py
|
|
285
287
|
|
|
286
|
-
#
|
|
287
|
-
python
|
|
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
|
-
#
|
|
293
|
-
python
|
|
291
|
+
# Benchmark models on scATAC-seq data
|
|
292
|
+
python model_evaluation_atac.py
|
|
294
293
|
|
|
295
|
-
#
|
|
296
|
-
python
|
|
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
|
|
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
|
-
|
|
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['
|
|
352
|
-
results['
|
|
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
|
|
5
|
-
from scipy.linalg import svd
|
|
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(
|
|
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(
|
|
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(
|
|
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(
|
|
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(
|
|
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
|
|
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.
|
|
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
|
-
|
|
213
|
-
|
|
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
|
-
|
|
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
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
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(
|
|
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
|
|
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
|
-
|
|
825
|
-
|
|
826
|
-
|
|
827
|
-
|
|
828
|
-
|
|
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(
|
|
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(
|
|
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(
|
|
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(
|
|
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
|
-
|
|
145
|
-
pred_x = pred_x *
|
|
146
|
-
pred_x_ode = pred_x_ode *
|
|
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 *
|
|
154
|
-
pred_xl_ode = pred_xl_ode *
|
|
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
|
-
|
|
173
|
-
pred_x = pred_x *
|
|
174
|
-
pred_x_ode = pred_x_ode *
|
|
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 *
|
|
182
|
-
pred_xl_ode = pred_xl_ode *
|
|
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
|
-
|
|
200
|
-
pred_x = pred_x *
|
|
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 *
|
|
206
|
-
irecon_loss = -self.irecon * self._log_zinb(
|
|
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
|
-
|
|
215
|
-
pred_x = pred_x *
|
|
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 *
|
|
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
|
-
|
|
369
|
-
pred_x = pred_x *
|
|
370
|
-
pred_x_ode = pred_x_ode *
|
|
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 *
|
|
377
|
-
pred_xl_ode = pred_xl_ode *
|
|
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
|
-
|
|
398
|
-
pred_x = pred_x *
|
|
399
|
-
pred_x_ode = pred_x_ode *
|
|
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 *
|
|
406
|
-
pred_xl_ode = pred_xl_ode *
|
|
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
|
-
|
|
422
|
-
pred_x = pred_x *
|
|
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 *
|
|
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
|
-
|
|
437
|
-
pred_x = pred_x *
|
|
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 *
|
|
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
|
-
|
|
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,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: iaode
|
|
3
|
-
Version: 0.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
|
|
|
@@ -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
|
-
| **`
|
|
320
|
-
| **`atacseq_annotation.py`** | Peak-to-gene annotation + QC plots | Understanding peak annotation |
|
|
321
|
-
| **`
|
|
322
|
-
| **`
|
|
323
|
-
| **`
|
|
324
|
-
| **`
|
|
325
|
-
|
|
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
|
-
#
|
|
333
|
-
python
|
|
334
|
+
# Getting started with scATAC-seq
|
|
335
|
+
python basic_usage.py
|
|
334
336
|
|
|
335
|
-
#
|
|
336
|
-
python
|
|
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
|
-
#
|
|
342
|
-
python
|
|
340
|
+
# Benchmark models on scATAC-seq data
|
|
341
|
+
python model_evaluation_atac.py
|
|
343
342
|
|
|
344
|
-
#
|
|
345
|
-
python
|
|
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
|
|
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
|
-
|
|
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.
|
|
@@ -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
|
|
File without changes
|
|
File without changes
|