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.
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2024 Zeyu Fu
3
+ Copyright (c) 2025 Zeyu Fu
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
@@ -6,3 +6,5 @@ recursive-include iaode *.py
6
6
  recursive-exclude * __pycache__
7
7
  recursive-exclude * *.py[co]
8
8
  recursive-exclude * .DS_Store
9
+ recursive-exclude * .ipynb_checkpoints
10
+ prune */.ipynb_checkpoints
@@ -1,9 +1,9 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: iaode
3
- Version: 0.2.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
- [![PyPI version](https://badge.fury.io/py/iaode.svg)](https://badge.fury.io/py/iaode) [![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
52
+ [![PyPI version](https://badge.fury.io/py/iaode.svg)](https://pypi.org/project/iaode/) [![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![PyTorch >=1.10](https://img.shields.io/badge/PyTorch-%3E=1.10-EE4C2C?logo=pytorch)](https://pytorch.org/) [![Tests](https://github.com/PeterPonyu/iAODE/actions/workflows/test.yml/badge.svg)](https://github.com/PeterPonyu/iAODE/actions/workflows/test.yml)
53
53
 
54
- `iAODE` (interpretable Accessibility ODE VAE) is a lightweight deep learning framework purpose-built for single‑cell ATAC‑seq (scATAC‑seq) data. It couples a variational autoencoder (VAE) with a Neural ODE and an interpretable bottleneck to jointly achieve:
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 modeling** of sparse count accessibility profiles (NB / ZINB likelihoods)
57
- 2. **Continuous trajectory inference** (Neural ODE pseudotime + velocity)
58
- 3. **Interpretable latent factors** (biologically aligned bottleneck)
59
- 4. **Scalable preprocessing** (TF‑IDF + highly variable peak selection) aligned with Signac / SnapATAC2 best practices
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: extreme sparsity, library size variability, heterogeneous peak accessibility kinetics, and dynamic regulatory trajectories.
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
- **Loss Function**:
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', # Best for sparse scATAC data
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 data download** - iAODE automatically downloads and caches datasets:
268
+ **Automatic Data Download** - iAODE automatically downloads and caches datasets:
267
269
 
268
270
  ```python
269
271
  import iaode
270
272
 
271
- # Downloads mouse brain 5k scATAC-seq + GENCODE vM25 GTF
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, # TSS downstream region
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 now contains:
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 with TF-IDF and HVP selection
293
+ # - Preprocessed counts (TF-IDF)
292
294
  ```
293
295
 
294
- **Available datasets:**
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 available in the `examples/` directory. See **[examples/README.md](examples/README.md)** for detailed documentation.
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
- 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.
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=None, # Interpretable bottleneck dim (required if use_ode=True)
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', 'residual_mlp', 'transformer', 'linear'
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 changes.
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 ideas from:
634
- - **scVI-tools**: scVI, PEAKVI, POISSONVI architectures
635
- - **Signac** and **SnapATAC2**: scATAC-seq best practices
636
- - **Neural ODE** literature: Continuous latent dynamics
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 provide the foundation.
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**: [https://github.com/PeterPonyu/iAODE/issues](https://github.com/PeterPonyu/iAODE/issues)
645
- - **Email**: fuzeyu99@126.com
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
- ### v0.2.0 (2025-11-20)
652
-
653
- **Documentation & Usability**
654
- - Comprehensive documentation overhaul (README, examples/README, QUICKSTART)
655
- - Separated scRNA-seq and scATAC-seq workflows with clear examples
656
- - Added automatic dataset download and caching system
657
- - Created `examples/data/download_data.sh` helper script
658
- - Verified all API usage examples against actual implementation
659
-
660
- **Code Quality**
661
- - Cleaned example scripts: removed unused imports, improved error handling
662
- - Fixed all cross-references between examples and core modules
663
- - Enhanced inline documentation and error messages
664
- - Verified method signatures: `get_velocity()`, `get_vfres()`, `get_pseudotime()`, etc.
665
-
666
- **Package Improvements**
667
- - Complete scATAC-seq preprocessing pipeline with TF-IDF and HVP selection
668
- - Improved peak annotation with distance-to-TSS computation
669
- - Enhanced evaluation metrics (DRE + LSE frameworks)
670
- - Better handling of sparse data and zero inflation
671
-
672
- ### v0.1.2 (2025-11-19)
673
-
674
- **Metadata & Contact**
675
- - Updated author name to "Zeyu Fu"
676
- - Set primary contact email to fuzeyu99@126.com
677
- - Fixed BibTeX citation formatting
678
-
679
- ### v0.1.1 (2025-11-19)
680
-
681
- **Bug Fixes**
682
- - Added missing `requests` dependency for scvi-tools compatibility
683
- - Dropped Python 3.8 support (requires Python ≥3.9)
684
- - Fixed CI test imports and matrix configuration
685
-
686
- ### v0.1.0 (2025-11-19)
687
-
688
- **Initial Release**
689
- - VAE with Neural ODE support for trajectory inference
690
- - Complete scATAC-seq peak annotation pipeline
691
- - Comprehensive evaluation metrics
692
- - Benchmark framework vs scVI models
693
- - Multiple encoder types (MLP, Residual, Transformer, Linear)
694
- - Multiple loss modes (MSE, NB, ZINB)
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
- [![PyPI version](https://badge.fury.io/py/iaode.svg)](https://badge.fury.io/py/iaode) [![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
3
+ [![PyPI version](https://badge.fury.io/py/iaode.svg)](https://pypi.org/project/iaode/) [![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![PyTorch >=1.10](https://img.shields.io/badge/PyTorch-%3E=1.10-EE4C2C?logo=pytorch)](https://pytorch.org/) [![Tests](https://github.com/PeterPonyu/iAODE/actions/workflows/test.yml/badge.svg)](https://github.com/PeterPonyu/iAODE/actions/workflows/test.yml)
4
4
 
5
- `iAODE` (interpretable Accessibility ODE VAE) is a lightweight deep learning framework purpose-built for single‑cell ATAC‑seq (scATAC‑seq) data. It couples a variational autoencoder (VAE) with a Neural ODE and an interpretable bottleneck to jointly achieve:
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 modeling** of sparse count accessibility profiles (NB / ZINB likelihoods)
8
- 2. **Continuous trajectory inference** (Neural ODE pseudotime + velocity)
9
- 3. **Interpretable latent factors** (biologically aligned bottleneck)
10
- 4. **Scalable preprocessing** (TF‑IDF + highly variable peak selection) aligned with Signac / SnapATAC2 best practices
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: extreme sparsity, library size variability, heterogeneous peak accessibility kinetics, and dynamic regulatory trajectories.
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
- **Loss Function**:
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', # Best for sparse scATAC data
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 data download** - iAODE automatically downloads and caches datasets:
219
+ **Automatic Data Download** - iAODE automatically downloads and caches datasets:
218
220
 
219
221
  ```python
220
222
  import iaode
221
223
 
222
- # Downloads mouse brain 5k scATAC-seq + GENCODE vM25 GTF
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, # TSS downstream region
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 now contains:
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 with TF-IDF and HVP selection
244
+ # - Preprocessed counts (TF-IDF)
243
245
  ```
244
246
 
245
- **Available datasets:**
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 available in the `examples/` directory. See **[examples/README.md](examples/README.md)** for detailed documentation.
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
- 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.
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=None, # Interpretable bottleneck dim (required if use_ode=True)
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', 'residual_mlp', 'transformer', 'linear'
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 changes.
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 ideas from:
585
- - **scVI-tools**: scVI, PEAKVI, POISSONVI architectures
586
- - **Signac** and **SnapATAC2**: scATAC-seq best practices
587
- - **Neural ODE** literature: Continuous latent dynamics
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 provide the foundation.
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**: [https://github.com/PeterPonyu/iAODE/issues](https://github.com/PeterPonyu/iAODE/issues)
596
- - **Email**: fuzeyu99@126.com
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
- ### v0.2.0 (2025-11-20)
603
-
604
- **Documentation & Usability**
605
- - Comprehensive documentation overhaul (README, examples/README, QUICKSTART)
606
- - Separated scRNA-seq and scATAC-seq workflows with clear examples
607
- - Added automatic dataset download and caching system
608
- - Created `examples/data/download_data.sh` helper script
609
- - Verified all API usage examples against actual implementation
610
-
611
- **Code Quality**
612
- - Cleaned example scripts: removed unused imports, improved error handling
613
- - Fixed all cross-references between examples and core modules
614
- - Enhanced inline documentation and error messages
615
- - Verified method signatures: `get_velocity()`, `get_vfres()`, `get_pseudotime()`, etc.
616
-
617
- **Package Improvements**
618
- - Complete scATAC-seq preprocessing pipeline with TF-IDF and HVP selection
619
- - Improved peak annotation with distance-to-TSS computation
620
- - Enhanced evaluation metrics (DRE + LSE frameworks)
621
- - Better handling of sparse data and zero inflation
622
-
623
- ### v0.1.2 (2025-11-19)
624
-
625
- **Metadata & Contact**
626
- - Updated author name to "Zeyu Fu"
627
- - Set primary contact email to fuzeyu99@126.com
628
- - Fixed BibTeX citation formatting
629
-
630
- ### v0.1.1 (2025-11-19)
631
-
632
- **Bug Fixes**
633
- - Added missing `requests` dependency for scvi-tools compatibility
634
- - Dropped Python 3.8 support (requires Python ≥3.9)
635
- - Fixed CI test imports and matrix configuration
636
-
637
- ### v0.1.0 (2025-11-19)
638
-
639
- **Initial Release**
640
- - VAE with Neural ODE support for trajectory inference
641
- - Complete scATAC-seq peak annotation pipeline
642
- - Comprehensive evaluation metrics
643
- - Benchmark framework vs scVI models
644
- - Multiple encoder types (MLP, Residual, Transformer, Linear)
645
- - Multiple loss modes (MSE, NB, ZINB)
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 pandas as pd
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(f"\nData split sizes:")
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(f"✓ SCVI training completed")
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(f"✓ PEAKVI training completed")
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(f"✓ POISSONVI training completed")
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: