iaode 0.2.3__tar.gz → 0.2.6__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.3 → iaode-0.2.6}/MANIFEST.in +2 -0
- {iaode-0.2.3/iaode.egg-info → iaode-0.2.6}/PKG-INFO +49 -51
- {iaode-0.2.3 → iaode-0.2.6}/README.md +47 -49
- {iaode-0.2.3 → iaode-0.2.6}/iaode/BEN.py +4 -8
- {iaode-0.2.3 → iaode-0.2.6}/iaode/LSE.py +0 -1
- {iaode-0.2.3 → iaode-0.2.6}/iaode/__init__.py +1 -1
- {iaode-0.2.3 → iaode-0.2.6}/iaode/datasets.py +7 -8
- {iaode-0.2.3 → iaode-0.2.6}/iaode/environment.py +28 -16
- {iaode-0.2.3 → iaode-0.2.6}/iaode/model.py +74 -42
- {iaode-0.2.3 → iaode-0.2.6}/iaode/module.py +21 -12
- {iaode-0.2.3 → iaode-0.2.6/iaode.egg-info}/PKG-INFO +49 -51
- {iaode-0.2.3 → iaode-0.2.6}/pyproject.toml +2 -2
- {iaode-0.2.3 → iaode-0.2.6}/LICENSE +0 -0
- {iaode-0.2.3 → iaode-0.2.6}/iaode/DRE.py +0 -0
- {iaode-0.2.3 → iaode-0.2.6}/iaode/agent.py +0 -0
- {iaode-0.2.3 → iaode-0.2.6}/iaode/annotation.py +0 -0
- {iaode-0.2.3 → iaode-0.2.6}/iaode/mixin.py +0 -0
- {iaode-0.2.3 → iaode-0.2.6}/iaode/utils.py +0 -0
- {iaode-0.2.3 → iaode-0.2.6}/iaode.egg-info/SOURCES.txt +0 -0
- {iaode-0.2.3 → iaode-0.2.6}/iaode.egg-info/dependency_links.txt +0 -0
- {iaode-0.2.3 → iaode-0.2.6}/iaode.egg-info/requires.txt +0 -0
- {iaode-0.2.3 → iaode-0.2.6}/iaode.egg-info/top_level.txt +0 -0
- {iaode-0.2.3 → iaode-0.2.6}/requirements.txt +0 -0
- {iaode-0.2.3 → iaode-0.2.6}/setup.cfg +0 -0
- {iaode-0.2.3 → iaode-0.2.6}/setup.py +0 -0
- {iaode-0.2.3 → iaode-0.2.6}/tests/test_smoke.py +0 -0
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: iaode
|
|
3
|
-
Version: 0.2.
|
|
3
|
+
Version: 0.2.6
|
|
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,16 +49,16 @@ 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
|
|
|
@@ -79,16 +79,16 @@ Encoder (MLP / Residual / Transformer) --> q(z|x)
|
|
|
79
79
|
Decoder (NB / ZINB / MSE) -> Reconstruction x_hat
|
|
80
80
|
```
|
|
81
81
|
|
|
82
|
-
**Key Components
|
|
82
|
+
**Key Components:**
|
|
83
83
|
|
|
84
|
-
- **TF‑IDF Normalization
|
|
85
|
-
- **Highly Variable Peaks (HVP)
|
|
86
|
-
- **NB/ZINB Likelihoods
|
|
87
|
-
- **Neural ODE
|
|
88
|
-
- **Interpretable Bottleneck
|
|
89
|
-
- **Multi‑Objective Regularization
|
|
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
90
|
|
|
91
|
-
**Loss Function
|
|
91
|
+
**Loss Function:**
|
|
92
92
|
|
|
93
93
|
```python
|
|
94
94
|
Loss = recon + i_recon + ODE_consistency + β·KL + dip·DIP + tc·TC + info·MMD
|
|
@@ -120,7 +120,7 @@ pip install -e .
|
|
|
120
120
|
- Scanpy ≥ 1.8.0
|
|
121
121
|
- scvi-tools ≥ 0.16.0
|
|
122
122
|
|
|
123
|
-
See `requirements.txt` for complete dependencies.
|
|
123
|
+
See `requirements.txt` for the complete list of dependencies.
|
|
124
124
|
|
|
125
125
|
---
|
|
126
126
|
|
|
@@ -171,10 +171,10 @@ print(f"Retained {adata.n_vars} highly variable peaks")
|
|
|
171
171
|
model = iaode.agent(
|
|
172
172
|
adata,
|
|
173
173
|
layer='counts',
|
|
174
|
-
latent_dim=32, # Higher for scATAC complexity
|
|
175
|
-
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
|
|
176
176
|
encoder_type='mlp',
|
|
177
|
-
loss_mode='zinb', #
|
|
177
|
+
loss_mode='zinb', # Recommended for sparse scATAC data
|
|
178
178
|
use_ode=False
|
|
179
179
|
)
|
|
180
180
|
|
|
@@ -265,13 +265,13 @@ plt.show()
|
|
|
265
265
|
|
|
266
266
|
### scATAC-seq Peak Annotation Pipeline
|
|
267
267
|
|
|
268
|
-
**Automatic
|
|
268
|
+
**Automatic Data Download** - iAODE automatically downloads and caches datasets:
|
|
269
269
|
|
|
270
270
|
```python
|
|
271
271
|
import iaode
|
|
272
272
|
|
|
273
|
-
#
|
|
274
|
-
# 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
|
|
275
275
|
h5_file, gtf_file = iaode.datasets.mouse_brain_5k_atacseq()
|
|
276
276
|
|
|
277
277
|
# Run complete annotation pipeline
|
|
@@ -279,21 +279,21 @@ adata = iaode.annotation_pipeline(
|
|
|
279
279
|
h5_file=str(h5_file),
|
|
280
280
|
gtf_file=str(gtf_file),
|
|
281
281
|
promoter_upstream=2000, # TSS upstream region
|
|
282
|
-
promoter_downstream=500,
|
|
283
|
-
apply_tfidf=True, # TF-IDF normalization
|
|
282
|
+
promoter_downstream=500, # TSS downstream region
|
|
283
|
+
apply_tfidf=True, # Apply TF-IDF normalization
|
|
284
284
|
select_hvp=True, # Select highly variable peaks
|
|
285
285
|
n_top_peaks=20000 # Number of HVPs to retain
|
|
286
286
|
)
|
|
287
287
|
|
|
288
|
-
# AnnData
|
|
289
|
-
# - adata.var['peak_type']: promoter/exonic/intronic/intergenic
|
|
288
|
+
# The returned AnnData object contains:
|
|
289
|
+
# - adata.var['peak_type']: Annotation (promoter/exonic/intronic/intergenic)
|
|
290
290
|
# - adata.var['gene_name']: Associated gene names
|
|
291
291
|
# - adata.var['distance_to_tss']: Distance to nearest TSS
|
|
292
292
|
# - adata.var['highly_variable']: HVP selection mask
|
|
293
|
-
# - Preprocessed
|
|
293
|
+
# - Preprocessed counts (TF-IDF)
|
|
294
294
|
```
|
|
295
295
|
|
|
296
|
-
**Available
|
|
296
|
+
**Available Datasets:**
|
|
297
297
|
|
|
298
298
|
```python
|
|
299
299
|
# Mouse brain 5k scATAC-seq
|
|
@@ -307,12 +307,11 @@ iaode.datasets.list_cached_files() # Show cached files
|
|
|
307
307
|
iaode.datasets.clear_cache() # Clear all cached data
|
|
308
308
|
```
|
|
309
309
|
|
|
310
|
-
|
|
311
310
|
---
|
|
312
311
|
|
|
313
312
|
## Examples
|
|
314
313
|
|
|
315
|
-
Comprehensive examples are
|
|
314
|
+
Comprehensive examples are provided in the `examples/` directory. See **[examples/README.md](examples/README.md)** for detailed documentation.
|
|
316
315
|
|
|
317
316
|
### Example Scripts
|
|
318
317
|
|
|
@@ -325,7 +324,6 @@ Comprehensive examples are available in the `examples/` directory. See **[exampl
|
|
|
325
324
|
| **`trajectory_inference_atac.py`** | Neural ODE trajectory with scATAC-seq | scATAC | Chromatin accessibility dynamics |
|
|
326
325
|
| **`trajectory_inference_rna.py`** | Neural ODE trajectory with scRNA-seq | scRNA | Transcriptional trajectory |
|
|
327
326
|
|
|
328
|
-
|
|
329
327
|
### Running Examples
|
|
330
328
|
|
|
331
329
|
```bash
|
|
@@ -344,7 +342,7 @@ python model_evaluation_atac.py
|
|
|
344
342
|
python trajectory_inference_rna.py
|
|
345
343
|
```
|
|
346
344
|
|
|
347
|
-
|
|
345
|
+
By default, all examples save outputs to `examples/outputs/<example_name>/`.
|
|
348
346
|
|
|
349
347
|
---
|
|
350
348
|
|
|
@@ -357,13 +355,13 @@ All examples save outputs to `examples/outputs/<example_name>/` by default. See
|
|
|
357
355
|
```python
|
|
358
356
|
model = iaode.agent(
|
|
359
357
|
adata, # AnnData object
|
|
360
|
-
layer='counts', # Data layer to use
|
|
358
|
+
layer='counts', # Data layer to use (key in adata.layers or 'X')
|
|
361
359
|
latent_dim=10, # Latent space dimension
|
|
362
360
|
hidden_dim=128, # Hidden layer dimension
|
|
363
|
-
i_dim=
|
|
361
|
+
i_dim=2, # Interpretable bottleneck dimension (default: 2)
|
|
364
362
|
use_ode=False, # Enable Neural ODE
|
|
365
363
|
loss_mode='nb', # Loss function: 'mse', 'nb', 'zinb'
|
|
366
|
-
encoder_type='mlp', # Encoder: 'mlp', '
|
|
364
|
+
encoder_type='mlp', # Encoder: 'mlp', 'mlp_residual', 'transformer', 'linear'
|
|
367
365
|
lr=1e-4, # Learning rate
|
|
368
366
|
batch_size=128, # Batch size
|
|
369
367
|
beta=1.0, # KL divergence weight
|
|
@@ -613,15 +611,15 @@ If you use iAODE in your research, please cite:
|
|
|
613
611
|
|
|
614
612
|
## Contributing
|
|
615
613
|
|
|
616
|
-
Contributions are welcome! Please:
|
|
614
|
+
Contributions are welcome! Please follow these steps:
|
|
617
615
|
|
|
618
|
-
1. Fork the repository
|
|
619
|
-
2. Create a feature branch (`git checkout -b feature/AmazingFeature`)
|
|
620
|
-
3. Commit changes (`git commit -m 'Add AmazingFeature'`)
|
|
621
|
-
4. Push to branch (`git push origin feature/AmazingFeature`)
|
|
622
|
-
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.
|
|
623
621
|
|
|
624
|
-
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.
|
|
625
623
|
|
|
626
624
|
---
|
|
627
625
|
|
|
@@ -633,20 +631,20 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
|
|
|
633
631
|
|
|
634
632
|
## Acknowledgments
|
|
635
633
|
|
|
636
|
-
Built upon
|
|
634
|
+
Built upon concepts from:
|
|
637
635
|
|
|
638
|
-
- **scVI-tools
|
|
639
|
-
- **Signac** and **SnapATAC2
|
|
640
|
-
- **Neural ODE
|
|
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.
|
|
641
639
|
|
|
642
|
-
PyTorch, AnnData, and Scanpy ecosystems
|
|
640
|
+
Foundational support is provided by the PyTorch, AnnData, and Scanpy ecosystems.
|
|
643
641
|
|
|
644
642
|
---
|
|
645
643
|
|
|
646
644
|
## Contact
|
|
647
645
|
|
|
648
|
-
- **GitHub Issues
|
|
649
|
-
- **Email
|
|
646
|
+
- **GitHub Issues:** [https://github.com/PeterPonyu/iAODE/issues](https://github.com/PeterPonyu/iAODE/issues)
|
|
647
|
+
- **Email:** <fuzeyu99@126.com>
|
|
650
648
|
|
|
651
649
|
---
|
|
652
650
|
|
|
@@ -1,15 +1,15 @@
|
|
|
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
|
|
|
@@ -30,16 +30,16 @@ Encoder (MLP / Residual / Transformer) --> q(z|x)
|
|
|
30
30
|
Decoder (NB / ZINB / MSE) -> Reconstruction x_hat
|
|
31
31
|
```
|
|
32
32
|
|
|
33
|
-
**Key Components
|
|
33
|
+
**Key Components:**
|
|
34
34
|
|
|
35
|
-
- **TF‑IDF Normalization
|
|
36
|
-
- **Highly Variable Peaks (HVP)
|
|
37
|
-
- **NB/ZINB Likelihoods
|
|
38
|
-
- **Neural ODE
|
|
39
|
-
- **Interpretable Bottleneck
|
|
40
|
-
- **Multi‑Objective Regularization
|
|
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
41
|
|
|
42
|
-
**Loss Function
|
|
42
|
+
**Loss Function:**
|
|
43
43
|
|
|
44
44
|
```python
|
|
45
45
|
Loss = recon + i_recon + ODE_consistency + β·KL + dip·DIP + tc·TC + info·MMD
|
|
@@ -71,7 +71,7 @@ pip install -e .
|
|
|
71
71
|
- Scanpy ≥ 1.8.0
|
|
72
72
|
- scvi-tools ≥ 0.16.0
|
|
73
73
|
|
|
74
|
-
See `requirements.txt` for complete dependencies.
|
|
74
|
+
See `requirements.txt` for the complete list of dependencies.
|
|
75
75
|
|
|
76
76
|
---
|
|
77
77
|
|
|
@@ -122,10 +122,10 @@ print(f"Retained {adata.n_vars} highly variable peaks")
|
|
|
122
122
|
model = iaode.agent(
|
|
123
123
|
adata,
|
|
124
124
|
layer='counts',
|
|
125
|
-
latent_dim=32, # Higher for scATAC complexity
|
|
126
|
-
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
|
|
127
127
|
encoder_type='mlp',
|
|
128
|
-
loss_mode='zinb', #
|
|
128
|
+
loss_mode='zinb', # Recommended for sparse scATAC data
|
|
129
129
|
use_ode=False
|
|
130
130
|
)
|
|
131
131
|
|
|
@@ -216,13 +216,13 @@ plt.show()
|
|
|
216
216
|
|
|
217
217
|
### scATAC-seq Peak Annotation Pipeline
|
|
218
218
|
|
|
219
|
-
**Automatic
|
|
219
|
+
**Automatic Data Download** - iAODE automatically downloads and caches datasets:
|
|
220
220
|
|
|
221
221
|
```python
|
|
222
222
|
import iaode
|
|
223
223
|
|
|
224
|
-
#
|
|
225
|
-
# 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
|
|
226
226
|
h5_file, gtf_file = iaode.datasets.mouse_brain_5k_atacseq()
|
|
227
227
|
|
|
228
228
|
# Run complete annotation pipeline
|
|
@@ -230,21 +230,21 @@ adata = iaode.annotation_pipeline(
|
|
|
230
230
|
h5_file=str(h5_file),
|
|
231
231
|
gtf_file=str(gtf_file),
|
|
232
232
|
promoter_upstream=2000, # TSS upstream region
|
|
233
|
-
promoter_downstream=500,
|
|
234
|
-
apply_tfidf=True, # TF-IDF normalization
|
|
233
|
+
promoter_downstream=500, # TSS downstream region
|
|
234
|
+
apply_tfidf=True, # Apply TF-IDF normalization
|
|
235
235
|
select_hvp=True, # Select highly variable peaks
|
|
236
236
|
n_top_peaks=20000 # Number of HVPs to retain
|
|
237
237
|
)
|
|
238
238
|
|
|
239
|
-
# AnnData
|
|
240
|
-
# - adata.var['peak_type']: promoter/exonic/intronic/intergenic
|
|
239
|
+
# The returned AnnData object contains:
|
|
240
|
+
# - adata.var['peak_type']: Annotation (promoter/exonic/intronic/intergenic)
|
|
241
241
|
# - adata.var['gene_name']: Associated gene names
|
|
242
242
|
# - adata.var['distance_to_tss']: Distance to nearest TSS
|
|
243
243
|
# - adata.var['highly_variable']: HVP selection mask
|
|
244
|
-
# - Preprocessed
|
|
244
|
+
# - Preprocessed counts (TF-IDF)
|
|
245
245
|
```
|
|
246
246
|
|
|
247
|
-
**Available
|
|
247
|
+
**Available Datasets:**
|
|
248
248
|
|
|
249
249
|
```python
|
|
250
250
|
# Mouse brain 5k scATAC-seq
|
|
@@ -258,12 +258,11 @@ iaode.datasets.list_cached_files() # Show cached files
|
|
|
258
258
|
iaode.datasets.clear_cache() # Clear all cached data
|
|
259
259
|
```
|
|
260
260
|
|
|
261
|
-
|
|
262
261
|
---
|
|
263
262
|
|
|
264
263
|
## Examples
|
|
265
264
|
|
|
266
|
-
Comprehensive examples are
|
|
265
|
+
Comprehensive examples are provided in the `examples/` directory. See **[examples/README.md](examples/README.md)** for detailed documentation.
|
|
267
266
|
|
|
268
267
|
### Example Scripts
|
|
269
268
|
|
|
@@ -276,7 +275,6 @@ Comprehensive examples are available in the `examples/` directory. See **[exampl
|
|
|
276
275
|
| **`trajectory_inference_atac.py`** | Neural ODE trajectory with scATAC-seq | scATAC | Chromatin accessibility dynamics |
|
|
277
276
|
| **`trajectory_inference_rna.py`** | Neural ODE trajectory with scRNA-seq | scRNA | Transcriptional trajectory |
|
|
278
277
|
|
|
279
|
-
|
|
280
278
|
### Running Examples
|
|
281
279
|
|
|
282
280
|
```bash
|
|
@@ -295,7 +293,7 @@ python model_evaluation_atac.py
|
|
|
295
293
|
python trajectory_inference_rna.py
|
|
296
294
|
```
|
|
297
295
|
|
|
298
|
-
|
|
296
|
+
By default, all examples save outputs to `examples/outputs/<example_name>/`.
|
|
299
297
|
|
|
300
298
|
---
|
|
301
299
|
|
|
@@ -308,13 +306,13 @@ All examples save outputs to `examples/outputs/<example_name>/` by default. See
|
|
|
308
306
|
```python
|
|
309
307
|
model = iaode.agent(
|
|
310
308
|
adata, # AnnData object
|
|
311
|
-
layer='counts', # Data layer to use
|
|
309
|
+
layer='counts', # Data layer to use (key in adata.layers or 'X')
|
|
312
310
|
latent_dim=10, # Latent space dimension
|
|
313
311
|
hidden_dim=128, # Hidden layer dimension
|
|
314
|
-
i_dim=
|
|
312
|
+
i_dim=2, # Interpretable bottleneck dimension (default: 2)
|
|
315
313
|
use_ode=False, # Enable Neural ODE
|
|
316
314
|
loss_mode='nb', # Loss function: 'mse', 'nb', 'zinb'
|
|
317
|
-
encoder_type='mlp', # Encoder: 'mlp', '
|
|
315
|
+
encoder_type='mlp', # Encoder: 'mlp', 'mlp_residual', 'transformer', 'linear'
|
|
318
316
|
lr=1e-4, # Learning rate
|
|
319
317
|
batch_size=128, # Batch size
|
|
320
318
|
beta=1.0, # KL divergence weight
|
|
@@ -564,15 +562,15 @@ If you use iAODE in your research, please cite:
|
|
|
564
562
|
|
|
565
563
|
## Contributing
|
|
566
564
|
|
|
567
|
-
Contributions are welcome! Please:
|
|
565
|
+
Contributions are welcome! Please follow these steps:
|
|
568
566
|
|
|
569
|
-
1. Fork the repository
|
|
570
|
-
2. Create a feature branch (`git checkout -b feature/AmazingFeature`)
|
|
571
|
-
3. Commit changes (`git commit -m 'Add AmazingFeature'`)
|
|
572
|
-
4. Push to branch (`git push origin feature/AmazingFeature`)
|
|
573
|
-
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.
|
|
574
572
|
|
|
575
|
-
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.
|
|
576
574
|
|
|
577
575
|
---
|
|
578
576
|
|
|
@@ -584,20 +582,20 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
|
|
|
584
582
|
|
|
585
583
|
## Acknowledgments
|
|
586
584
|
|
|
587
|
-
Built upon
|
|
585
|
+
Built upon concepts from:
|
|
588
586
|
|
|
589
|
-
- **scVI-tools
|
|
590
|
-
- **Signac** and **SnapATAC2
|
|
591
|
-
- **Neural ODE
|
|
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.
|
|
592
590
|
|
|
593
|
-
PyTorch, AnnData, and Scanpy ecosystems
|
|
591
|
+
Foundational support is provided by the PyTorch, AnnData, and Scanpy ecosystems.
|
|
594
592
|
|
|
595
593
|
---
|
|
596
594
|
|
|
597
595
|
## Contact
|
|
598
596
|
|
|
599
|
-
- **GitHub Issues
|
|
600
|
-
- **Email
|
|
597
|
+
- **GitHub Issues:** [https://github.com/PeterPonyu/iAODE/issues](https://github.com/PeterPonyu/iAODE/issues)
|
|
598
|
+
- **Email:** <fuzeyu99@126.com>
|
|
601
599
|
|
|
602
600
|
---
|
|
603
601
|
|
|
@@ -1,10 +1,6 @@
|
|
|
1
|
-
import gc
|
|
2
|
-
import os
|
|
3
1
|
import time
|
|
4
2
|
import numpy as np
|
|
5
|
-
import pandas as pd # type: ignore
|
|
6
3
|
import scanpy as sc # type: ignore
|
|
7
|
-
import scipy.sparse as sp # type: ignore
|
|
8
4
|
import torch
|
|
9
5
|
from sklearn.cluster import KMeans # type: ignore
|
|
10
6
|
from sklearn.metrics import ( # type: ignore
|
|
@@ -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:
|
|
@@ -10,8 +10,7 @@ import urllib.request
|
|
|
10
10
|
import gzip
|
|
11
11
|
import shutil
|
|
12
12
|
from pathlib import Path
|
|
13
|
-
from typing import
|
|
14
|
-
import anndata as ad # type: ignore
|
|
13
|
+
from typing import Tuple
|
|
15
14
|
|
|
16
15
|
|
|
17
16
|
def get_data_dir() -> Path:
|
|
@@ -63,7 +62,7 @@ def _download_file(url: str, output_path: Path, desc: str = "file") -> None:
|
|
|
63
62
|
|
|
64
63
|
urllib.request.urlretrieve(url, output_path, reporthook=reporthook)
|
|
65
64
|
print() # New line after progress
|
|
66
|
-
print(
|
|
65
|
+
print(" ✓ Downloaded successfully")
|
|
67
66
|
except Exception as e:
|
|
68
67
|
print(f"\n ✗ Download failed: {e}")
|
|
69
68
|
raise
|
|
@@ -145,10 +144,10 @@ def mouse_brain_5k_atacseq(force_download: bool = False, use_local: bool = True)
|
|
|
145
144
|
print(f"✓ Using local files from: {local_examples_dir}")
|
|
146
145
|
# Copy to cache for consistency
|
|
147
146
|
if not h5_file.exists():
|
|
148
|
-
print(
|
|
147
|
+
print(" Copying H5 to cache...")
|
|
149
148
|
shutil.copy(local_h5, h5_file)
|
|
150
149
|
if not gtf_file.exists():
|
|
151
|
-
print(
|
|
150
|
+
print(" Copying GTF to cache...")
|
|
152
151
|
shutil.copy(local_gtf, gtf_file)
|
|
153
152
|
print()
|
|
154
153
|
print("=" * 70)
|
|
@@ -172,7 +171,7 @@ def mouse_brain_5k_atacseq(force_download: bool = False, use_local: bool = True)
|
|
|
172
171
|
print("MANUAL DOWNLOAD REQUIRED")
|
|
173
172
|
print("=" * 70)
|
|
174
173
|
print("Please download the file manually:")
|
|
175
|
-
print(
|
|
174
|
+
print("\n1. Visit: https://www.10xgenomics.com/datasets/fresh-cortex-from-adult-mouse-brain-p-50-1-standard-2-0-0")
|
|
176
175
|
print(" Or try direct link:")
|
|
177
176
|
print(f" {h5_url}")
|
|
178
177
|
print(f"\n2. Save as: {h5_file}")
|
|
@@ -194,7 +193,7 @@ def mouse_brain_5k_atacseq(force_download: bool = False, use_local: bool = True)
|
|
|
194
193
|
# Clean up compressed file to save space
|
|
195
194
|
if gtf_gz.exists():
|
|
196
195
|
gtf_gz.unlink()
|
|
197
|
-
print(
|
|
196
|
+
print(" ✓ Removed compressed file to save space")
|
|
198
197
|
else:
|
|
199
198
|
print(f"✓ Using cached GTF: {gtf_file}")
|
|
200
199
|
|
|
@@ -265,7 +264,7 @@ def human_pbmc_5k_atacseq(force_download: bool = False) -> Tuple[Path, Path]:
|
|
|
265
264
|
# Clean up compressed file
|
|
266
265
|
if gtf_gz.exists():
|
|
267
266
|
gtf_gz.unlink()
|
|
268
|
-
print(
|
|
267
|
+
print(" ✓ Removed compressed file to save space")
|
|
269
268
|
else:
|
|
270
269
|
print(f"✓ Using cached GTF: {gtf_file}")
|
|
271
270
|
|