iaode 0.2.9__tar.gz → 0.3.1__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
  Metadata-Version: 2.4
2
2
  Name: iaode
3
- Version: 0.2.9
3
+ Version: 0.3.1
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-Expression: MIT
@@ -31,6 +31,7 @@ Requires-Dist: torchdiffeq>=0.2.0
31
31
  Requires-Dist: anndata>=0.8.0
32
32
  Requires-Dist: scanpy>=1.8.0
33
33
  Requires-Dist: scvi-tools>=0.16.0
34
+ Requires-Dist: zarr>=2.0.0
34
35
  Requires-Dist: requests>=2.25.0
35
36
  Requires-Dist: tqdm>=4.60.0
36
37
  Provides-Extra: dev
@@ -47,18 +48,36 @@ Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "docs"
47
48
  Requires-Dist: sphinx-autodoc-typehints>=1.18.0; extra == "docs"
48
49
  Dynamic: license-file
49
50
 
51
+ <div align="center">
52
+ <a href="https://peterponyu.github.io/">
53
+ <img src="https://peterponyu.github.io/assets/badges/iAODE.svg" width="64" alt="ZF Lab · iAODE">
54
+ </a>
55
+ </div>
56
+
50
57
  # iAODE: Interpretable Accessibility ODE VAE for scATAC-seq
51
58
 
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)
59
+ [![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) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18453104.svg)](https://doi.org/10.5281/zenodo.18453104)
60
+
61
+ > **Interactive Tools:** The dataset browser and continuity explorer have moved to [**SCPortal**](https://peterponyu.github.io/scportal/) — a unified single-cell data portal with expanded datasets, LAIOR benchmarks, and more. The [original project page](https://peterponyu.github.io/iAODE/) is preserved as the manuscript publication snapshot.
62
+
63
+ ## Public Pages and local application surfaces
64
+
65
+ `site/` is the public GitHub Pages landing at the canonical URL
66
+ `https://peterponyu.github.io/iAODE/`. It provides project documentation and
67
+ reproducible entry points only. No `/iAODE/frontend/` Pages route is supported.
68
+
69
+ `frontend/` and `api/static/` are local application assets for the training UI.
70
+ They remain local so model training and data handling are performed in the
71
+ user's environment rather than on the public Pages site.
53
72
 
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:
73
+ **iAODE** (Interpretable Accessibility ODE VAE) is a lightweight deep learning framework centered on single-cell ATAC-seq (scATAC-seq) data. It integrates a Variational Autoencoder (VAE) with a Neural ODE and an interpretable bottleneck to support:
55
74
 
56
- 1. **Robust Modeling:** Handles sparse count accessibility profiles using Negative Binomial (NB) or Zero-Inflated Negative Binomial (ZINB) likelihoods.
75
+ 1. **Count-based Modeling:** Handles sparse accessibility profiles with Negative Binomial (NB) or Zero-Inflated Negative Binomial (ZINB) likelihoods.
57
76
  2. **Continuous Trajectory Inference:** Infers dynamics via Neural ODE pseudotime and latent velocity fields.
58
77
  3. **Interpretable Latent Factors:** Utilizes a biologically aligned bottleneck to extract meaningful features.
59
78
  4. **Scalable Preprocessing:** Implements TF‑IDF normalization and Highly Variable Peak (HVP) selection, aligned with Signac and SnapATAC2 best practices.
60
79
 
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.
80
+ The core package targets scATAC-seq data, including sparse peak counts, library size variability, heterogeneous accessibility kinetics, and dynamic regulatory trajectories. Some bundled scripts and UI workflows also cover scRNA-seq comparison tasks, but scATAC-seq remains the primary scope of the repository.
62
81
 
63
82
  ---
64
83
 
@@ -98,39 +117,58 @@ Loss = recon + i_recon + ODE_consistency + β·KL + dip·DIP + tc·TC + info·MM
98
117
 
99
118
  ## Installation
100
119
 
101
- ### Method 1: Python Library (Standard)
102
- For users using iAODE in scripts or notebooks:
120
+ ### From PyPI (Recommended)
121
+
103
122
  ```bash
104
123
  pip install iaode
105
124
  ```
106
125
 
107
- ### Method 2: Web Interface (Full)
108
- For users who want the **Interactive Training UI**, you must clone the repository (since the UI requires the server files):
126
+ ### From Source
109
127
 
110
128
  ```bash
111
129
  git clone https://github.com/PeterPonyu/iAODE.git
112
130
  cd iAODE
113
131
  pip install -e .
114
- pip install fastapi uvicorn # Required for the UI server
115
132
  ```
116
133
 
134
+ ### Requirements
135
+
136
+ - Python ≥ 3.9
137
+ - PyTorch ≥ 1.10.0
138
+ - AnnData ≥ 0.8.0
139
+ - Scanpy ≥ 1.8.0
140
+ - scvi-tools ≥ 0.16.0
141
+
142
+ See `requirements.txt` for the complete list of dependencies.
143
+
117
144
  ---
145
+
118
146
  ## Quick Start
119
147
 
120
- ### 🖥️ Interactive Web Interface
121
- **No Node.js required.** The interface is pre-built and served via Python.
148
+ ### Training UI (Web Interface)
122
149
 
123
- 1. **Start the Server:**
124
- ```bash
125
- python api/run_server.py
126
- ```
127
- 2. **Access the UI:**
128
- Open **[http://localhost:8000/](http://localhost:8000/)** in your browser.
129
-
130
- *Features:*
131
- * Upload `.h5ad` or `.h5` files.
132
- * Configure Encoders, Loss functions, and ODE parameters visually.
133
- * Download trained embeddings directly.
150
+ iAODE includes an integrated web-based training interface for interactive model training:
151
+
152
+ ```bash
153
+ # Start the training UI (Python - cross-platform)
154
+ python start_training_ui.py
155
+
156
+ # Or use the shell script (Linux/macOS)
157
+ ./start_training_ui.sh
158
+ ```
159
+
160
+ Then open your browser to:
161
+ - **Training UI**: http://localhost:8000/ui
162
+ - **API Documentation**: http://localhost:8000/docs
163
+
164
+ **Features:**
165
+ - Upload scATAC-seq data and related `.h5ad` workflows through the UI
166
+ - Configure preprocessing parameters (TF-IDF, HVP selection, subsampling)
167
+ - Set training parameters interactively
168
+ - Monitor training progress in real-time
169
+ - Download trained embeddings (latent and interpretable)
170
+
171
+ ---
134
172
 
135
173
  ### Basic scATAC-seq Workflow
136
174
 
@@ -317,7 +355,7 @@ iaode.datasets.clear_cache() # Clear all cached data
317
355
 
318
356
  ## Examples
319
357
 
320
- Comprehensive examples are provided in the `examples/` directory. See **[examples/README.md](examples/README.md)** for detailed documentation.
358
+ Examples are provided in the `examples/` directory. See **[examples/README.md](examples/README.md)** for details.
321
359
 
322
360
  ### Example Scripts
323
361
 
@@ -604,12 +642,16 @@ for epoch in range(100):
604
642
  If you use iAODE in your research, please cite:
605
643
 
606
644
  ```bibtex
607
- @software{iaode2025,
608
- author = {Zeyu Fu},
609
- title = {iAODE: Interpretable Accessibility ODE VAE for Single-Cell Chromatin Dynamics},
610
- year = {2025},
611
- publisher = {GitHub},
612
- url = {https://github.com/PeterPonyu/iAODE}
645
+ @article{Fu2026iAODE,
646
+ author = {Fu, Zeyu and Chen, Chunlin and Wang, Song and Wang, Junping and Chen, Shilei},
647
+ title = {iAODE for benchmarking and continuum modeling of single-cell chromatin accessibility},
648
+ journal = {Communications Biology},
649
+ volume = {9},
650
+ number = {1},
651
+ pages = {507},
652
+ year = {2026},
653
+ doi = {10.1038/s42003-026-09768-8},
654
+ url = {https://doi.org/10.1038/s42003-026-09768-8}
613
655
  }
614
656
  ```
615
657
 
@@ -1,15 +1,33 @@
1
+ <div align="center">
2
+ <a href="https://peterponyu.github.io/">
3
+ <img src="https://peterponyu.github.io/assets/badges/iAODE.svg" width="64" alt="ZF Lab · iAODE">
4
+ </a>
5
+ </div>
6
+
1
7
  # iAODE: Interpretable Accessibility ODE VAE for scATAC-seq
2
8
 
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)
9
+ [![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) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18453104.svg)](https://doi.org/10.5281/zenodo.18453104)
10
+
11
+ > **Interactive Tools:** The dataset browser and continuity explorer have moved to [**SCPortal**](https://peterponyu.github.io/scportal/) — a unified single-cell data portal with expanded datasets, LAIOR benchmarks, and more. The [original project page](https://peterponyu.github.io/iAODE/) is preserved as the manuscript publication snapshot.
12
+
13
+ ## Public Pages and local application surfaces
14
+
15
+ `site/` is the public GitHub Pages landing at the canonical URL
16
+ `https://peterponyu.github.io/iAODE/`. It provides project documentation and
17
+ reproducible entry points only. No `/iAODE/frontend/` Pages route is supported.
18
+
19
+ `frontend/` and `api/static/` are local application assets for the training UI.
20
+ They remain local so model training and data handling are performed in the
21
+ user's environment rather than on the public Pages site.
4
22
 
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:
23
+ **iAODE** (Interpretable Accessibility ODE VAE) is a lightweight deep learning framework centered on single-cell ATAC-seq (scATAC-seq) data. It integrates a Variational Autoencoder (VAE) with a Neural ODE and an interpretable bottleneck to support:
6
24
 
7
- 1. **Robust Modeling:** Handles sparse count accessibility profiles using Negative Binomial (NB) or Zero-Inflated Negative Binomial (ZINB) likelihoods.
25
+ 1. **Count-based Modeling:** Handles sparse accessibility profiles with Negative Binomial (NB) or Zero-Inflated Negative Binomial (ZINB) likelihoods.
8
26
  2. **Continuous Trajectory Inference:** Infers dynamics via Neural ODE pseudotime and latent velocity fields.
9
27
  3. **Interpretable Latent Factors:** Utilizes a biologically aligned bottleneck to extract meaningful features.
10
28
  4. **Scalable Preprocessing:** Implements TF‑IDF normalization and Highly Variable Peak (HVP) selection, aligned with Signac and SnapATAC2 best practices.
11
29
 
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.
30
+ The core package targets scATAC-seq data, including sparse peak counts, library size variability, heterogeneous accessibility kinetics, and dynamic regulatory trajectories. Some bundled scripts and UI workflows also cover scRNA-seq comparison tasks, but scATAC-seq remains the primary scope of the repository.
13
31
 
14
32
  ---
15
33
 
@@ -49,39 +67,58 @@ Loss = recon + i_recon + ODE_consistency + β·KL + dip·DIP + tc·TC + info·MM
49
67
 
50
68
  ## Installation
51
69
 
52
- ### Method 1: Python Library (Standard)
53
- For users using iAODE in scripts or notebooks:
70
+ ### From PyPI (Recommended)
71
+
54
72
  ```bash
55
73
  pip install iaode
56
74
  ```
57
75
 
58
- ### Method 2: Web Interface (Full)
59
- For users who want the **Interactive Training UI**, you must clone the repository (since the UI requires the server files):
76
+ ### From Source
60
77
 
61
78
  ```bash
62
79
  git clone https://github.com/PeterPonyu/iAODE.git
63
80
  cd iAODE
64
81
  pip install -e .
65
- pip install fastapi uvicorn # Required for the UI server
66
82
  ```
67
83
 
84
+ ### Requirements
85
+
86
+ - Python ≥ 3.9
87
+ - PyTorch ≥ 1.10.0
88
+ - AnnData ≥ 0.8.0
89
+ - Scanpy ≥ 1.8.0
90
+ - scvi-tools ≥ 0.16.0
91
+
92
+ See `requirements.txt` for the complete list of dependencies.
93
+
68
94
  ---
95
+
69
96
  ## Quick Start
70
97
 
71
- ### 🖥️ Interactive Web Interface
72
- **No Node.js required.** The interface is pre-built and served via Python.
98
+ ### Training UI (Web Interface)
73
99
 
74
- 1. **Start the Server:**
75
- ```bash
76
- python api/run_server.py
77
- ```
78
- 2. **Access the UI:**
79
- Open **[http://localhost:8000/](http://localhost:8000/)** in your browser.
80
-
81
- *Features:*
82
- * Upload `.h5ad` or `.h5` files.
83
- * Configure Encoders, Loss functions, and ODE parameters visually.
84
- * Download trained embeddings directly.
100
+ iAODE includes an integrated web-based training interface for interactive model training:
101
+
102
+ ```bash
103
+ # Start the training UI (Python - cross-platform)
104
+ python start_training_ui.py
105
+
106
+ # Or use the shell script (Linux/macOS)
107
+ ./start_training_ui.sh
108
+ ```
109
+
110
+ Then open your browser to:
111
+ - **Training UI**: http://localhost:8000/ui
112
+ - **API Documentation**: http://localhost:8000/docs
113
+
114
+ **Features:**
115
+ - Upload scATAC-seq data and related `.h5ad` workflows through the UI
116
+ - Configure preprocessing parameters (TF-IDF, HVP selection, subsampling)
117
+ - Set training parameters interactively
118
+ - Monitor training progress in real-time
119
+ - Download trained embeddings (latent and interpretable)
120
+
121
+ ---
85
122
 
86
123
  ### Basic scATAC-seq Workflow
87
124
 
@@ -268,7 +305,7 @@ iaode.datasets.clear_cache() # Clear all cached data
268
305
 
269
306
  ## Examples
270
307
 
271
- Comprehensive examples are provided in the `examples/` directory. See **[examples/README.md](examples/README.md)** for detailed documentation.
308
+ Examples are provided in the `examples/` directory. See **[examples/README.md](examples/README.md)** for details.
272
309
 
273
310
  ### Example Scripts
274
311
 
@@ -555,12 +592,16 @@ for epoch in range(100):
555
592
  If you use iAODE in your research, please cite:
556
593
 
557
594
  ```bibtex
558
- @software{iaode2025,
559
- author = {Zeyu Fu},
560
- title = {iAODE: Interpretable Accessibility ODE VAE for Single-Cell Chromatin Dynamics},
561
- year = {2025},
562
- publisher = {GitHub},
563
- url = {https://github.com/PeterPonyu/iAODE}
595
+ @article{Fu2026iAODE,
596
+ author = {Fu, Zeyu and Chen, Chunlin and Wang, Song and Wang, Junping and Chen, Shilei},
597
+ title = {iAODE for benchmarking and continuum modeling of single-cell chromatin accessibility},
598
+ journal = {Communications Biology},
599
+ volume = {9},
600
+ number = {1},
601
+ pages = {507},
602
+ year = {2026},
603
+ doi = {10.1038/s42003-026-09768-8},
604
+ url = {https://doi.org/10.1038/s42003-026-09768-8}
564
605
  }
565
606
  ```
566
607
 
@@ -37,7 +37,7 @@ Usage Example:
37
37
  >>> latent = model.get_latent()
38
38
  """
39
39
 
40
- __version__ = "0.2.8"
40
+ __version__ = "0.3.1"
41
41
  __author__ = "Zeyu Fu"
42
42
 
43
43
  # Import main classes and functions
@@ -662,7 +662,9 @@ class agent(Env):
662
662
  T = adata.obsp[T_key].copy()
663
663
 
664
664
  if self_transition:
665
- max_t = T.max(1).A.flatten() if hasattr(T.max(1), 'A') else np.array(T.max(1)).flatten()
665
+ row_max = T.max(1)
666
+ # Sparse results have no .A since SciPy 1.14; densify explicitly.
667
+ max_t = np.asarray(row_max.todense() if issparse(row_max) else row_max).ravel()
666
668
  ub = np.percentile(max_t, 98)
667
669
  self_t = np.clip(ub - max_t, 0, 1)
668
670
  if hasattr(T, 'setdiag'):
@@ -877,6 +879,6 @@ def l2_norm(x: np.ndarray, axis: int = -1) -> np.ndarray:
877
879
  L2 norms
878
880
  """
879
881
  if issparse(x):
880
- return np.sqrt(x.multiply(x).sum(axis=axis).A1) # type: ignore[attr-defined]
882
+ return np.sqrt(np.asarray(x.multiply(x).sum(axis=axis)).ravel())
881
883
  else:
882
884
  return np.sqrt(np.sum(x * x, axis=axis))
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: iaode
3
- Version: 0.2.9
3
+ Version: 0.3.1
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-Expression: MIT
@@ -31,6 +31,7 @@ Requires-Dist: torchdiffeq>=0.2.0
31
31
  Requires-Dist: anndata>=0.8.0
32
32
  Requires-Dist: scanpy>=1.8.0
33
33
  Requires-Dist: scvi-tools>=0.16.0
34
+ Requires-Dist: zarr>=2.0.0
34
35
  Requires-Dist: requests>=2.25.0
35
36
  Requires-Dist: tqdm>=4.60.0
36
37
  Provides-Extra: dev
@@ -47,18 +48,36 @@ Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "docs"
47
48
  Requires-Dist: sphinx-autodoc-typehints>=1.18.0; extra == "docs"
48
49
  Dynamic: license-file
49
50
 
51
+ <div align="center">
52
+ <a href="https://peterponyu.github.io/">
53
+ <img src="https://peterponyu.github.io/assets/badges/iAODE.svg" width="64" alt="ZF Lab · iAODE">
54
+ </a>
55
+ </div>
56
+
50
57
  # iAODE: Interpretable Accessibility ODE VAE for scATAC-seq
51
58
 
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)
59
+ [![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) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18453104.svg)](https://doi.org/10.5281/zenodo.18453104)
60
+
61
+ > **Interactive Tools:** The dataset browser and continuity explorer have moved to [**SCPortal**](https://peterponyu.github.io/scportal/) — a unified single-cell data portal with expanded datasets, LAIOR benchmarks, and more. The [original project page](https://peterponyu.github.io/iAODE/) is preserved as the manuscript publication snapshot.
62
+
63
+ ## Public Pages and local application surfaces
64
+
65
+ `site/` is the public GitHub Pages landing at the canonical URL
66
+ `https://peterponyu.github.io/iAODE/`. It provides project documentation and
67
+ reproducible entry points only. No `/iAODE/frontend/` Pages route is supported.
68
+
69
+ `frontend/` and `api/static/` are local application assets for the training UI.
70
+ They remain local so model training and data handling are performed in the
71
+ user's environment rather than on the public Pages site.
53
72
 
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:
73
+ **iAODE** (Interpretable Accessibility ODE VAE) is a lightweight deep learning framework centered on single-cell ATAC-seq (scATAC-seq) data. It integrates a Variational Autoencoder (VAE) with a Neural ODE and an interpretable bottleneck to support:
55
74
 
56
- 1. **Robust Modeling:** Handles sparse count accessibility profiles using Negative Binomial (NB) or Zero-Inflated Negative Binomial (ZINB) likelihoods.
75
+ 1. **Count-based Modeling:** Handles sparse accessibility profiles with Negative Binomial (NB) or Zero-Inflated Negative Binomial (ZINB) likelihoods.
57
76
  2. **Continuous Trajectory Inference:** Infers dynamics via Neural ODE pseudotime and latent velocity fields.
58
77
  3. **Interpretable Latent Factors:** Utilizes a biologically aligned bottleneck to extract meaningful features.
59
78
  4. **Scalable Preprocessing:** Implements TF‑IDF normalization and Highly Variable Peak (HVP) selection, aligned with Signac and SnapATAC2 best practices.
60
79
 
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.
80
+ The core package targets scATAC-seq data, including sparse peak counts, library size variability, heterogeneous accessibility kinetics, and dynamic regulatory trajectories. Some bundled scripts and UI workflows also cover scRNA-seq comparison tasks, but scATAC-seq remains the primary scope of the repository.
62
81
 
63
82
  ---
64
83
 
@@ -98,39 +117,58 @@ Loss = recon + i_recon + ODE_consistency + β·KL + dip·DIP + tc·TC + info·MM
98
117
 
99
118
  ## Installation
100
119
 
101
- ### Method 1: Python Library (Standard)
102
- For users using iAODE in scripts or notebooks:
120
+ ### From PyPI (Recommended)
121
+
103
122
  ```bash
104
123
  pip install iaode
105
124
  ```
106
125
 
107
- ### Method 2: Web Interface (Full)
108
- For users who want the **Interactive Training UI**, you must clone the repository (since the UI requires the server files):
126
+ ### From Source
109
127
 
110
128
  ```bash
111
129
  git clone https://github.com/PeterPonyu/iAODE.git
112
130
  cd iAODE
113
131
  pip install -e .
114
- pip install fastapi uvicorn # Required for the UI server
115
132
  ```
116
133
 
134
+ ### Requirements
135
+
136
+ - Python ≥ 3.9
137
+ - PyTorch ≥ 1.10.0
138
+ - AnnData ≥ 0.8.0
139
+ - Scanpy ≥ 1.8.0
140
+ - scvi-tools ≥ 0.16.0
141
+
142
+ See `requirements.txt` for the complete list of dependencies.
143
+
117
144
  ---
145
+
118
146
  ## Quick Start
119
147
 
120
- ### 🖥️ Interactive Web Interface
121
- **No Node.js required.** The interface is pre-built and served via Python.
148
+ ### Training UI (Web Interface)
122
149
 
123
- 1. **Start the Server:**
124
- ```bash
125
- python api/run_server.py
126
- ```
127
- 2. **Access the UI:**
128
- Open **[http://localhost:8000/](http://localhost:8000/)** in your browser.
129
-
130
- *Features:*
131
- * Upload `.h5ad` or `.h5` files.
132
- * Configure Encoders, Loss functions, and ODE parameters visually.
133
- * Download trained embeddings directly.
150
+ iAODE includes an integrated web-based training interface for interactive model training:
151
+
152
+ ```bash
153
+ # Start the training UI (Python - cross-platform)
154
+ python start_training_ui.py
155
+
156
+ # Or use the shell script (Linux/macOS)
157
+ ./start_training_ui.sh
158
+ ```
159
+
160
+ Then open your browser to:
161
+ - **Training UI**: http://localhost:8000/ui
162
+ - **API Documentation**: http://localhost:8000/docs
163
+
164
+ **Features:**
165
+ - Upload scATAC-seq data and related `.h5ad` workflows through the UI
166
+ - Configure preprocessing parameters (TF-IDF, HVP selection, subsampling)
167
+ - Set training parameters interactively
168
+ - Monitor training progress in real-time
169
+ - Download trained embeddings (latent and interpretable)
170
+
171
+ ---
134
172
 
135
173
  ### Basic scATAC-seq Workflow
136
174
 
@@ -317,7 +355,7 @@ iaode.datasets.clear_cache() # Clear all cached data
317
355
 
318
356
  ## Examples
319
357
 
320
- Comprehensive examples are provided in the `examples/` directory. See **[examples/README.md](examples/README.md)** for detailed documentation.
358
+ Examples are provided in the `examples/` directory. See **[examples/README.md](examples/README.md)** for details.
321
359
 
322
360
  ### Example Scripts
323
361
 
@@ -604,12 +642,16 @@ for epoch in range(100):
604
642
  If you use iAODE in your research, please cite:
605
643
 
606
644
  ```bibtex
607
- @software{iaode2025,
608
- author = {Zeyu Fu},
609
- title = {iAODE: Interpretable Accessibility ODE VAE for Single-Cell Chromatin Dynamics},
610
- year = {2025},
611
- publisher = {GitHub},
612
- url = {https://github.com/PeterPonyu/iAODE}
645
+ @article{Fu2026iAODE,
646
+ author = {Fu, Zeyu and Chen, Chunlin and Wang, Song and Wang, Junping and Chen, Shilei},
647
+ title = {iAODE for benchmarking and continuum modeling of single-cell chromatin accessibility},
648
+ journal = {Communications Biology},
649
+ volume = {9},
650
+ number = {1},
651
+ pages = {507},
652
+ year = {2026},
653
+ doi = {10.1038/s42003-026-09768-8},
654
+ url = {https://doi.org/10.1038/s42003-026-09768-8}
613
655
  }
614
656
  ```
615
657
 
@@ -21,4 +21,5 @@ iaode.egg-info/SOURCES.txt
21
21
  iaode.egg-info/dependency_links.txt
22
22
  iaode.egg-info/requires.txt
23
23
  iaode.egg-info/top_level.txt
24
+ tests/test_pages_metadata.py
24
25
  tests/test_smoke.py
@@ -7,6 +7,7 @@ torchdiffeq>=0.2.0
7
7
  anndata>=0.8.0
8
8
  scanpy>=1.8.0
9
9
  scvi-tools>=0.16.0
10
+ zarr>=2.0.0
10
11
  requests>=2.25.0
11
12
  tqdm>=4.60.0
12
13
 
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "iaode"
7
- version = "0.2.9"
7
+ version = "0.3.1"
8
8
  description = "Interpretable Autoencoder with Ordinary Differential Equations for single-cell omics analysis"
9
9
  readme = "README.md"
10
10
  authors = [
@@ -44,6 +44,7 @@ dependencies = [
44
44
  "anndata>=0.8.0",
45
45
  "scanpy>=1.8.0",
46
46
  "scvi-tools>=0.16.0",
47
+ "zarr>=2.0.0",
47
48
  "requests>=2.25.0",
48
49
  "tqdm>=4.60.0",
49
50
  ]
@@ -0,0 +1,11 @@
1
+ from pathlib import Path
2
+
3
+
4
+ def test_public_page_contains_scpportal_tool_routes() -> None:
5
+ html = (Path(__file__).parents[1] / "site" / "index.html").read_text(encoding="utf-8")
6
+ assert "Dataset Browser" in html
7
+ assert "https://peterponyu.github.io/scportal/datasets/" in html
8
+ assert "Continuity Explorer" in html
9
+ assert "https://peterponyu.github.io/scportal/explorer/" in html
10
+ assert "localhost" not in html.lower()
11
+ assert "/iAODE/frontend/" not in html
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes