iaode 0.2.0__tar.gz → 0.2.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.
iaode-0.2.1/PKG-INFO ADDED
@@ -0,0 +1,697 @@
1
+ Metadata-Version: 2.4
2
+ Name: iaode
3
+ Version: 0.2.1
4
+ Summary: Interpretable Autoencoder with Ordinary Differential Equations for single-cell omics analysis
5
+ Author-email: Zeyu Fu <fuzeyu99@126.com>
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/PeterPonyu/iAODE
8
+ Project-URL: Documentation, https://iaode.readthedocs.io
9
+ Project-URL: Repository, https://github.com/PeterPonyu/iAODE
10
+ Project-URL: Bug Tracker, https://github.com/PeterPonyu/iAODE/issues
11
+ Keywords: single-cell,omics,dimensionality-reduction,neural-ode,variational-autoencoder,trajectory-inference,scRNA-seq,scATAC-seq
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: Intended Audience :: Science/Research
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.9
17
+ Classifier: Programming Language :: Python :: 3.10
18
+ Classifier: Programming Language :: Python :: 3.11
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
21
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
22
+ Requires-Python: >=3.9
23
+ Description-Content-Type: text/markdown
24
+ License-File: LICENSE
25
+ Requires-Dist: numpy>=1.20.0
26
+ Requires-Dist: pandas>=1.3.0
27
+ Requires-Dist: scipy>=1.7.0
28
+ Requires-Dist: scikit-learn>=1.0.0
29
+ Requires-Dist: torch>=1.10.0
30
+ Requires-Dist: torchdiffeq>=0.2.0
31
+ Requires-Dist: anndata>=0.8.0
32
+ Requires-Dist: scanpy>=1.8.0
33
+ Requires-Dist: scvi-tools>=0.16.0
34
+ Requires-Dist: requests>=2.25.0
35
+ Requires-Dist: tqdm>=4.60.0
36
+ Provides-Extra: dev
37
+ Requires-Dist: pytest>=7.0.0; extra == "dev"
38
+ Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
39
+ Requires-Dist: black>=22.0.0; extra == "dev"
40
+ Requires-Dist: flake8>=4.0.0; extra == "dev"
41
+ Requires-Dist: mypy>=0.950; extra == "dev"
42
+ Requires-Dist: build>=0.7.0; extra == "dev"
43
+ Requires-Dist: twine>=4.0.0; extra == "dev"
44
+ Provides-Extra: docs
45
+ Requires-Dist: sphinx>=4.5.0; extra == "docs"
46
+ Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "docs"
47
+ Requires-Dist: sphinx-autodoc-typehints>=1.18.0; extra == "docs"
48
+ Dynamic: license-file
49
+
50
+ # iAODE: Interpretable Accessibility ODE VAE for scATAC-seq
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)
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:
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
60
+
61
+ The design targets the unique characteristics of scATAC data: extreme sparsity, library size variability, heterogeneous peak accessibility kinetics, and dynamic regulatory trajectories.
62
+
63
+ ---
64
+
65
+ ## Core Architecture
66
+
67
+ ```
68
+ Raw Peak Counts --(TF-IDF)--> Normalized Matrix --(HVP Selection)--> Peak Subset
69
+ |
70
+ v
71
+ Encoder (MLP / Residual / Transformer) --> q(z|x)
72
+ | \
73
+ | +--> Bottleneck (i_dim) -> Interpretable factors
74
+ v
75
+ Neural ODE f(z,t) -> z_ode(t) (pseudotime + dynamics)
76
+ | \
77
+ | +--> Consistency Loss (q_z vs z_ode)
78
+ v
79
+ Decoder (NB / ZINB / MSE) -> Reconstruction x_hat
80
+ ```
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
89
+
90
+ **Loss Function**:
91
+ ```
92
+ Loss = recon + i_recon + ODE_consistency + β·KL + dip·DIP + tc·TC + info·MMD
93
+ ```
94
+
95
+ ---
96
+
97
+ ## Installation
98
+
99
+ ### From PyPI (Recommended)
100
+
101
+ ```bash
102
+ pip install iaode
103
+ ```
104
+
105
+ ### From Source
106
+
107
+ ```bash
108
+ git clone https://github.com/PeterPonyu/iAODE.git
109
+ cd iAODE
110
+ pip install -e .
111
+ ```
112
+
113
+ ### Requirements
114
+
115
+ - Python ≥ 3.9
116
+ - PyTorch ≥ 1.10.0
117
+ - AnnData ≥ 0.8.0
118
+ - Scanpy ≥ 1.8.0
119
+ - scvi-tools ≥ 0.16.0
120
+
121
+ See `requirements.txt` for complete dependencies.
122
+
123
+ ---
124
+
125
+ ## Quick Start
126
+
127
+ ### Basic scATAC-seq Workflow
128
+
129
+ ```python
130
+ import scanpy as sc
131
+ import iaode
132
+ from iaode.utils import tfidf_normalization, select_highly_variable_peaks
133
+ from iaode.annotation import load_10x_h5_data
134
+
135
+ # 1. Download and load scATAC-seq data (auto-cached)
136
+ h5_file, gtf_file = iaode.datasets.mouse_brain_5k_atacseq()
137
+ print(f"Data downloaded to: {h5_file.parent}")
138
+
139
+ # Load peak count matrix
140
+ adata = load_10x_h5_data(str(h5_file))
141
+ adata.layers['counts'] = adata.X.copy()
142
+ print(f"Loaded: {adata.n_obs} cells × {adata.n_vars} peaks")
143
+
144
+ # 2. TF-IDF normalization (Signac/SnapATAC2 best practice)
145
+ tfidf_normalization(
146
+ adata,
147
+ scale_factor=1e4,
148
+ log_tf=False,
149
+ log_idf=True,
150
+ inplace=True
151
+ )
152
+
153
+ # 3. Highly variable peak (HVP) selection
154
+ select_highly_variable_peaks(
155
+ adata,
156
+ n_top_peaks=20000,
157
+ method='signac',
158
+ min_accessibility=0.01,
159
+ max_accessibility=0.95,
160
+ inplace=True
161
+ )
162
+
163
+ # Subset to HVPs
164
+ hvp_mask = adata.var['highly_variable']
165
+ adata = adata[:, hvp_mask].copy()
166
+ print(f"Retained {adata.n_vars} highly variable peaks")
167
+
168
+ # 4. Train iAODE model
169
+ model = iaode.agent(
170
+ adata,
171
+ layer='counts',
172
+ latent_dim=32, # Higher for scATAC complexity
173
+ hidden_dim=512, # Deeper for regulatory patterns
174
+ encoder_type='mlp',
175
+ loss_mode='zinb', # Best for sparse scATAC data
176
+ use_ode=False
177
+ )
178
+
179
+ model.fit(epochs=400, patience=25, val_every=10)
180
+
181
+ # 5. Extract latent representation
182
+ latent = model.get_latent()
183
+ adata.obsm['X_iaode'] = latent
184
+
185
+ # 6. Visualize with UMAP
186
+ sc.pp.neighbors(adata, use_rep='X_iaode')
187
+ sc.tl.umap(adata)
188
+
189
+ # Color by QC metrics
190
+ sc.pl.umap(adata, color=['n_genes_by_counts', 'total_counts'])
191
+ ```
192
+
193
+ ### scATAC-seq with Trajectory Inference
194
+
195
+ ```python
196
+ import scanpy as sc
197
+ import iaode
198
+ from iaode.utils import tfidf_normalization, select_highly_variable_peaks
199
+ from iaode.annotation import load_10x_h5_data
200
+
201
+ # 1. Load and preprocess scATAC-seq data
202
+ h5_file, gtf_file = iaode.datasets.mouse_brain_5k_atacseq()
203
+ adata = load_10x_h5_data(str(h5_file))
204
+ adata.layers['counts'] = adata.X.copy()
205
+
206
+ # TF-IDF normalization
207
+ tfidf_normalization(adata, scale_factor=1e4, log_tf=False, log_idf=True, inplace=True)
208
+
209
+ # Select highly variable peaks
210
+ select_highly_variable_peaks(adata, n_top_peaks=20000, method='signac', inplace=True)
211
+ adata = adata[:, adata.var['highly_variable']].copy()
212
+
213
+ # 2. Train iAODE with Neural ODE for trajectory inference
214
+ model = iaode.agent(
215
+ adata,
216
+ layer='counts',
217
+ use_ode=True, # Enable Neural ODE dynamics
218
+ i_dim=16, # Interpretable bottleneck dimension
219
+ latent_dim=32,
220
+ hidden_dim=512,
221
+ encoder_type='mlp',
222
+ loss_mode='zinb'
223
+ )
224
+
225
+ model.fit(epochs=400, patience=25, val_every=10)
226
+
227
+ # 3. Extract trajectory-related representations
228
+ latent = model.get_latent() # Latent space (z)
229
+ iembed = model.get_iembed() # Interpretable regulatory factors
230
+ pseudotime = model.get_pseudotime() # ODE time parameter
231
+ velocity = model.get_velocity() # Latent velocity field
232
+
233
+ # Store in AnnData
234
+ adata.obsm['X_iaode'] = latent
235
+ adata.obsm['X_iembed'] = iembed
236
+ adata.obs['pseudotime'] = pseudotime
237
+ adata.obsm['velocity'] = velocity
238
+
239
+ # 4. Visualize trajectory
240
+ sc.pp.neighbors(adata, use_rep='X_iaode')
241
+ sc.tl.umap(adata)
242
+
243
+ # Color UMAP by pseudotime to reveal developmental trajectory
244
+ sc.pl.umap(adata, color='pseudotime', cmap='viridis')
245
+
246
+ # Visualize velocity field (requires UMAP coordinates)
247
+ E_grid, V_grid = model.get_vfres(
248
+ adata,
249
+ zs_key='X_iaode',
250
+ E_key='X_umap',
251
+ stream=True,
252
+ density=1.5
253
+ )
254
+
255
+ import matplotlib.pyplot as plt
256
+ fig, ax = plt.subplots(figsize=(8, 6))
257
+ sc.pl.umap(adata, color='pseudotime', ax=ax, show=False)
258
+ ax.streamplot(E_grid[0], E_grid[1], V_grid[0], V_grid[1],
259
+ color='gray', density=1.5, linewidth=0.5, arrowsize=1)
260
+ plt.tight_layout()
261
+ plt.show()
262
+ ```
263
+
264
+ ### scATAC-seq Peak Annotation Pipeline
265
+
266
+ **Automatic data download** - iAODE automatically downloads and caches datasets:
267
+
268
+ ```python
269
+ import iaode
270
+
271
+ # Downloads mouse brain 5k scATAC-seq + GENCODE vM25 GTF
272
+ # Files cached in ~/.iaode/data/ and reused on subsequent runs
273
+ h5_file, gtf_file = iaode.datasets.mouse_brain_5k_atacseq()
274
+
275
+ # Run complete annotation pipeline
276
+ adata = iaode.annotation_pipeline(
277
+ h5_file=str(h5_file),
278
+ gtf_file=str(gtf_file),
279
+ promoter_upstream=2000, # TSS upstream region
280
+ promoter_downstream=500, # TSS downstream region
281
+ apply_tfidf=True, # TF-IDF normalization
282
+ select_hvp=True, # Select highly variable peaks
283
+ n_top_peaks=20000 # Number of HVPs to retain
284
+ )
285
+
286
+ # AnnData now contains:
287
+ # - adata.var['peak_type']: promoter/exonic/intronic/intergenic
288
+ # - adata.var['gene_name']: Associated gene names
289
+ # - adata.var['distance_to_tss']: Distance to nearest TSS
290
+ # - adata.var['highly_variable']: HVP selection mask
291
+ # - Preprocessed with TF-IDF and HVP selection
292
+ ```
293
+
294
+ **Available datasets:**
295
+
296
+ ```python
297
+ # Mouse brain 5k scATAC-seq
298
+ h5, gtf = iaode.datasets.mouse_brain_5k_atacseq()
299
+
300
+ # Human PBMC 5k scATAC-seq
301
+ h5, gtf = iaode.datasets.human_pbmc_5k_atacseq()
302
+
303
+ # Cache management
304
+ iaode.datasets.list_cached_files() # Show cached files
305
+ iaode.datasets.clear_cache() # Clear all cached data
306
+ ```
307
+
308
+
309
+ ---
310
+
311
+ ## Examples
312
+
313
+ Comprehensive examples are available in the `examples/` directory. See **[examples/README.md](examples/README.md)** for detailed documentation.
314
+
315
+ ### Example Scripts
316
+
317
+ | Script | Purpose | Best For |
318
+ |--------|---------|----------|
319
+ | **`scATAC_quickstart.py`** | Complete scATAC pipeline (TF‑IDF → HVP → iAODE) | Real scATAC-seq analysis |
320
+ | **`atacseq_annotation.py`** | Peak-to-gene annotation + QC plots | Understanding peak annotation |
321
+ | **`trajectory_ode.py`** | Neural ODE pseudotime & velocity | Trajectory inference |
322
+ | **`evaluation_metrics.py`** | DR quality + clustering metrics | Model evaluation |
323
+ | **`model_evaluation.py`** | Benchmark vs scVI models | Comparative analysis |
324
+ | **`basic_usage.py`** | Simple scRNA-seq workflow | Getting started |
325
+ | **`trajectory_inference.py`** | Trajectory with vector field | Velocity visualization |
326
+
327
+ ### Running Examples
328
+
329
+ ```bash
330
+ cd examples
331
+
332
+ # Complete scATAC-seq workflow with auto-download
333
+ python atacseq_annotation.py
334
+
335
+ # Or use your own data
336
+ python scATAC_quickstart.py \
337
+ --h5 filtered_peak_bc_matrix.h5 \
338
+ --gtf gencode.vM25.annotation.gtf.gz \
339
+ --use-ode --latent-dim 32 --i-dim 16
340
+
341
+ # Trajectory inference with synthetic data
342
+ python trajectory_ode.py
343
+
344
+ # Comprehensive benchmarking
345
+ python model_evaluation.py
346
+ ```
347
+
348
+ All examples save outputs to `examples/outputs/` with visualizations and processed data. See **[examples/README.md](examples/README.md)** for detailed usage instructions and output descriptions.
349
+
350
+ ---
351
+
352
+ ## API Reference
353
+
354
+ ### `iaode.agent` - Main Model Interface
355
+
356
+ **Initialization:**
357
+
358
+ ```python
359
+ model = iaode.agent(
360
+ adata, # AnnData object
361
+ layer='counts', # Data layer to use
362
+ latent_dim=10, # Latent space dimension
363
+ hidden_dim=128, # Hidden layer dimension
364
+ i_dim=None, # Interpretable bottleneck dim (required if use_ode=True)
365
+ use_ode=False, # Enable Neural ODE
366
+ loss_mode='nb', # Loss function: 'mse', 'nb', 'zinb'
367
+ encoder_type='mlp', # Encoder: 'mlp', 'residual_mlp', 'transformer', 'linear'
368
+ lr=1e-4, # Learning rate
369
+ batch_size=128, # Batch size
370
+ beta=1.0, # KL divergence weight
371
+ recon=1.0, # Reconstruction loss weight
372
+ tc=0.0, # Total correlation weight
373
+ dip=0.0, # DIP weight
374
+ info=0.0 # InfoVAE MMD weight
375
+ )
376
+ ```
377
+
378
+ **Training:**
379
+
380
+ ```python
381
+ model.fit(
382
+ epochs=100, # Maximum epochs
383
+ patience=20, # Early stopping patience
384
+ val_every=5, # Validation frequency
385
+ early_stop=True # Enable early stopping
386
+ )
387
+ ```
388
+
389
+ **Representation Extraction:**
390
+
391
+ ```python
392
+ # Basic representations
393
+ latent = model.get_latent() # Latent space (n_cells, latent_dim)
394
+ iembed = model.get_iembed() # Interpretable factors (n_cells, i_dim)
395
+
396
+ # Trajectory-specific (requires use_ode=True)
397
+ pseudotime = model.get_pseudotime() # ODE time parameter (n_cells,)
398
+ velocity = model.get_velocity() # Latent velocity (n_cells, latent_dim)
399
+
400
+ # Vector field for visualization (requires UMAP in adata.obsm['X_umap'])
401
+ E_grid, V_grid = model.get_vfres(
402
+ adata,
403
+ zs_key='X_iaode', # Latent representation key
404
+ E_key='X_umap', # Embedding key for visualization
405
+ stream=True, # Return streamplot-compatible format
406
+ density=1.5 # Grid density
407
+ )
408
+ ```
409
+
410
+ **Evaluation Metrics:**
411
+
412
+ ```python
413
+ # Training metrics
414
+ metrics = model.get_resource_metrics()
415
+ # Returns: {'train_time': float, 'actual_epochs': int, 'peak_memory_gb': float}
416
+ ```
417
+
418
+ ---
419
+
420
+ ### `iaode.annotation_pipeline` - scATAC-seq Preprocessing
421
+
422
+ **Complete annotation and preprocessing pipeline:**
423
+
424
+ ```python
425
+ adata = iaode.annotation_pipeline(
426
+ h5_file, # Path to 10X H5 file
427
+ gtf_file, # Path to GTF annotation
428
+ promoter_upstream=2000, # TSS upstream extension (bp)
429
+ promoter_downstream=500, # TSS downstream extension (bp)
430
+ apply_tfidf=True, # Apply TF-IDF normalization
431
+ select_hvp=True, # Select highly variable peaks
432
+ n_top_peaks=20000, # Number of HVPs to retain
433
+ hvp_method='signac', # HVP method: 'signac', 'snapatac2', 'deviance'
434
+ min_accessibility=0.01, # Min peak accessibility fraction
435
+ max_accessibility=0.95 # Max peak accessibility fraction
436
+ )
437
+ ```
438
+
439
+ **Returns AnnData with:**
440
+ - `adata.var['peak_type']`: Peak annotation (promoter/exonic/intronic/intergenic)
441
+ - `adata.var['gene_name']`: Associated gene names
442
+ - `adata.var['distance_to_tss']`: Distance to nearest TSS
443
+ - `adata.var['highly_variable']`: HVP selection mask
444
+ - Preprocessed and normalized counts
445
+
446
+ ---
447
+
448
+ ### Evaluation Functions
449
+
450
+ #### Dimensionality Reduction Quality
451
+
452
+ ```python
453
+ from iaode import evaluate_dimensionality_reduction
454
+
455
+ metrics = evaluate_dimensionality_reduction(
456
+ X_high, # High-dimensional data (n_cells, n_features)
457
+ X_low, # Low-dimensional embedding (n_cells, n_latent)
458
+ k=10, # Number of neighbors
459
+ verbose=True
460
+ )
461
+
462
+ # Returns:
463
+ # - distance_correlation: Global structure preservation (Spearman ρ)
464
+ # - Q_local: Local neighborhood quality
465
+ # - Q_global: Global structure quality
466
+ # - K_max: Local-global transition point
467
+ ```
468
+
469
+ #### Latent Space Quality
470
+
471
+ ```python
472
+ from iaode import evaluate_single_cell_latent_space
473
+
474
+ metrics = evaluate_single_cell_latent_space(
475
+ latent_space, # Latent representation (n_cells, n_latent)
476
+ data_type='trajectory', # 'trajectory' or 'steady_state'
477
+ verbose=True
478
+ )
479
+
480
+ # Returns:
481
+ # - manifold_dimensionality: Dimensional efficiency (0-1)
482
+ # - spectral_decay_rate: Eigenvalue concentration
483
+ # - participation_ratio: Dimensional balance
484
+ # - anisotropy_score: Directionality strength
485
+ # - trajectory_directionality: Dominant axis strength
486
+ # - noise_resilience: Signal-to-noise ratio
487
+ # - overall_quality: Aggregate score
488
+ ```
489
+
490
+ #### Model Benchmarking
491
+
492
+ ```python
493
+ from iaode import DataSplitter, train_scvi_models, evaluate_scvi_models
494
+
495
+ # Create consistent train/val/test splits
496
+ splitter = DataSplitter(
497
+ n_samples=adata.n_obs,
498
+ test_size=0.15,
499
+ val_size=0.15,
500
+ random_state=42
501
+ )
502
+
503
+ # Train scVI family models
504
+ scvi_results = train_scvi_models(
505
+ adata,
506
+ splitter,
507
+ n_latent=10,
508
+ n_epochs=400,
509
+ batch_size=128
510
+ )
511
+
512
+ # Evaluate all models
513
+ scvi_metrics = evaluate_scvi_models(
514
+ scvi_results,
515
+ adata,
516
+ splitter.test_idx
517
+ )
518
+ ```
519
+
520
+ ---
521
+
522
+ ### Preprocessing Utilities
523
+
524
+ ```python
525
+ from iaode.utils import tfidf_normalization, select_highly_variable_peaks
526
+
527
+ # TF-IDF normalization (Signac/SnapATAC2 style)
528
+ tfidf_normalization(
529
+ adata,
530
+ scale_factor=1e4,
531
+ log_tf=False,
532
+ log_idf=True,
533
+ inplace=True
534
+ )
535
+
536
+ # Highly variable peak selection
537
+ select_highly_variable_peaks(
538
+ adata,
539
+ n_top_peaks=20000,
540
+ method='signac', # or 'snapatac2', 'deviance'
541
+ min_accessibility=0.01,
542
+ max_accessibility=0.95,
543
+ inplace=True
544
+ )
545
+ ```
546
+
547
+ ---
548
+
549
+ ## Advanced Usage
550
+
551
+ ### Custom Encoder Architecture
552
+
553
+ ```python
554
+ # Transformer encoder for large-scale data
555
+ model = iaode.agent(
556
+ adata,
557
+ encoder_type='transformer',
558
+ encoder_num_layers=4,
559
+ encoder_n_heads=8,
560
+ encoder_d_model=256,
561
+ hidden_dim=512,
562
+ latent_dim=32
563
+ )
564
+ ```
565
+
566
+ ### Multi-Objective Regularization
567
+
568
+ ```python
569
+ # Fine-tune regularization weights
570
+ model = iaode.agent(
571
+ adata,
572
+ recon=1.0, # Reconstruction loss
573
+ beta=1.0, # KL divergence
574
+ tc=0.5, # Total correlation (disentanglement)
575
+ dip=0.1, # DIP (dimension-wise independence)
576
+ info=0.05 # InfoVAE MMD (distribution matching)
577
+ )
578
+ ```
579
+
580
+ ### Custom Training Loop
581
+
582
+ ```python
583
+ # Manual training with custom logic
584
+ for epoch in range(100):
585
+ train_loss = model.train_epoch()
586
+
587
+ if epoch % 5 == 0:
588
+ val_loss, val_score = model.validate()
589
+ print(f"Epoch {epoch}: Val Loss={val_loss:.4f}")
590
+
591
+ if should_stop(val_loss):
592
+ model.load_best_model()
593
+ break
594
+ ```
595
+
596
+ ---
597
+
598
+ ## Citation
599
+
600
+ If you use iAODE in your research, please cite:
601
+
602
+ ```bibtex
603
+ @software{iaode2025,
604
+ author = {Zeyu Fu},
605
+ title = {iAODE: Interpretable Accessibility ODE VAE for Single-Cell Chromatin Dynamics},
606
+ year = {2025},
607
+ publisher = {GitHub},
608
+ url = {https://github.com/PeterPonyu/iAODE}
609
+ }
610
+ ```
611
+
612
+ ---
613
+
614
+ ## Contributing
615
+
616
+ Contributions are welcome! Please:
617
+
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
623
+
624
+ For major changes, please open an issue first to discuss proposed changes.
625
+
626
+ ---
627
+
628
+ ## License
629
+
630
+ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
631
+
632
+ ---
633
+
634
+ ## Acknowledgments
635
+
636
+ Built upon ideas from:
637
+ - **scVI-tools**: scVI, PEAKVI, POISSONVI architectures
638
+ - **Signac** and **SnapATAC2**: scATAC-seq best practices
639
+ - **Neural ODE** literature: Continuous latent dynamics
640
+
641
+ PyTorch, AnnData, and Scanpy ecosystems provide the foundation.
642
+
643
+ ---
644
+
645
+ ## Contact
646
+
647
+ - **GitHub Issues**: [https://github.com/PeterPonyu/iAODE/issues](https://github.com/PeterPonyu/iAODE/issues)
648
+ - **Email**: fuzeyu99@126.com
649
+
650
+ ---
651
+
652
+ ## Changelog
653
+
654
+ ### v0.2.0 (2025-11-20)
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)