How johnlyj/vae_omics works
Project type and purpose
• This is a research‐oriented full-pipeline machine learning project implementing a Multimodal Variational Autoencoder (VAE) to integrate single-cell RNA-seq and ATAC-seq data.
• The goal is to learn a shared latent representation for cross-modal imputation and downstream analysis (clustering, visualization).
File structure
• Top–level scripts:
• main.py – orchestrates preprocessing, model instantiation, training, and saving checkpoints
• Directories:
• data/ – raw‐data loader and preprocess.py (normalization, log-transform, HVG selection, LSI)
• models/ – encoder.py, fusion.py (MLP or Product of Experts), decoder.py, vae.py (VAE assembly)
• training/ – train.py, eval.py, loss.py (training loop, KL annealing, evaluation metrics)
• results/ – output plots
• Supporting files: requirements.txt, .gitignore, README.md
Key insights from README
• Separate modality pipelines (RNA vs ATAC) → two encoders, two decoders
• Fusion strategies: MLP vs PoE
• KL-annealing schedule for posterior collapse mitigation
• Quantitative evaluation: cosine similarity & Pearson correlation
• Visualization: UMAP + Leiden clustering
Main components
a. Data ingestion & preprocessing
• Input: 10x Multiome H5 file
• RNA-seq pipeline: normalization → log-transform → HVG selection
• ATAC-seq pipeline: filtering → LSI (SVD)
b. Model
• Encoder_RNA → latent parameters (µ_r, σ_r)
• Encoder_ATAC → latent parameters (µ_a, σ_a)
• Fusion module
– MLP Fusion: concat(µ_r, µ_a, σ_r, σ_a) → MLP → µ_z, σ_z
– PoE Fusion: combine distributions mathematically → µ_z, σ_z
• Sampling z ∼ N(µ_z, σ_z)
• Decoder_RNA(z) → reconstructed RNA
• Decoder_ATAC(z) → reconstructed ATAC
c. Training loop
• Loss computation: reconstruction losses + KL divergence (with KL-annealing schedule)
• Optimizer step (e.g., Adam)
• Checkpointing
d. Evaluation & Visualization
• eval.py: compute cosine similarity & Pearson correlation for cross-modal imputation
Relationships & interactions
• Data → Preprocess → Batch tensors → Model (encode → fuse → decode)
• Training orchestrates forward/backward passes → checkpoint outputs → metrics logged
• Post‐training: checkpoints + raw data → evaluation → quantitative metrics
• Visualization scripts consume checkpoints + data → output plots
Architectural patterns & design principles
• Modular components: clear separation of data, models, training, and visualization
• Pipeline pattern: data-flow graph from raw input to final plots
• Dependency inversion: components interact via well-defined interfaces (e.g., model.forward, preprocess functions)
• Configurable fusion strategy injected at model‐construction time
Technologies & frameworks
• Python 3.x
• ML framework: likely PyTorch or TensorFlow (inferred from model code structure)
• Scientific libs: NumPy, SciPy, scikit-learn (SVD/LSI), scanpy/anndata (optional)
• Visualization: Matplotlib, Seaborn, UMAP, Leiden clustering (leidenalg)