How idriskb/neurovelo works
Project type and purpose
• Type: A Python library/package for interpretable learning of cellular dynamics (not a full-stack web app or microservice).
• Purpose: Provide data loading, model definition (neural ODE + linear embedding), training routines, and utilities for post-hoc analysis (latent velocities, gene-velocity decoding, gene regulatory network inference).
Core file structure under neurovelo/
• data.py → data ingestion and preprocessing
• model.py → top-level model class (combines encoder, dynamics, decoder)
• module.py → building blocks (linear projection modules, ODE integrator)
• grn.py → gene regulatory network estimation routines
• train.py → Trainer class: training loop, loss computation, model checkpointing
• utils.py → analysis helpers: latent_data, evaluate, decode_gene_velocity, ModelAnalyzer
External dependencies
• PyTorch (neural-net modules, training)
• torchdiffeq or custom neural ODE solver (in module.py)
• AnnData / scVelo (data structures, visualization pipelines)
• Standard scientific stack (NumPy, pandas)
Main components & their interactions
A. Data Pipeline (data.py)
• Input: AnnData object with layers (‘spliced’, ‘unspliced’).
• Output: PyTorch tensors / DataLoader ready for model.
B. Model Construction (model.py + module.py)
• module.py defines:
– Linear projectors for spliced/unspliced → latent space
– Neural ODE block for latent dynamics
– Decoders back to gene space
• model.py instantiates and wires these sub-modules into a single NeuroVeloModel with forward methods.
C. Training Engine (train.py)
• Trainer wraps the model and DataLoader
• Defines loss (splicing dynamics)
• Runs epochs, computes gradients, updates model
• Saves checkpoints (.pth)
D. Analysis Utilities (utils.py)
• latent_data(): loads a checkpoint, runs encoder → latent velocities
• decode_gene_velocity(): uses decoder to get per-gene velocities
• ModelAnalyzer: takes trained models to perform gene ranking and build gene network via grn.py routines
E. GRN Inference (grn.py)
• Implements graph-maker: compute adjacency A, build network, threshold, output NetworkX graph
Architectural patterns and design principles
• Modularity: clear separation of data I/O, model definition, training logic, and post-hoc analysis
• Single Responsibility: Each file handles one stage of the pipeline
• Plug-and-play: Swappable sub-modules in module.py enable easy extension (e.g., alternate ODE solvers)
• Pipeline style: linear data flow from raw AnnData → model → checkpoint → analysis
Special notes for this library-style package
• Linear pipeline from data ingestion to model training to analysis.
• How module.py sub-modules feed into the higher-level model.py.
• Extensibility points: e.g., you could swap in a different ODE solver by modifying module.py without touching train.py.