# idriskb/neurovelo architecture

> Architecture diagram of the GitHub repository idriskb/neurovelo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/idriskb/neurovelo
- Repository: https://github.com/idriskb/neurovelo

## Overview

##### 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`.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Input
    AnnData["AnnData Input\n(layers: spliced, unspliced)"]:::external

    %% Core Code Modules
    API["Package Init\nneurovelo/__init__.py"]:::code
    DataPipeline["Data Pipeline\nneurovelo/data.py"]:::code
    Module["Linear Projectors & Neural ODE\nneurovelo/module.py"]:::code
    Model["NeuroVeloModel\nneurovelo/model.py"]:::code
    Trainer["Training Engine\nneurovelo/train.py"]:::code
    Utils["Analysis Utilities\nneurovelo/utils.py"]:::code
    GRN["GRN Inference\nneurovelo/grn.py"]:::code

    %% Data Artifacts and External Systems
    Checkpoint["Checkpoint\n(.pth files)"]:::data
    Graph["Gene Regulatory Network\n(NetworkX Graph)"]:::data
    scVelo["scVelo Visualization"]:::external

    %% Connections
    AnnData -->|"AnnData object"| DataPipeline
    API --> DataPipeline
    API --> Module
    API --> Model
    API --> Trainer
    API --> Utils
    API --> GRN

    DataPipeline -->|"spliced/unspliced tensors\nDataLoader"| Trainer
    Module -->|"defines encoder,\nODE integrator,\ndecoder modules"| Model
    Trainer -->|"instantiates & calls\nforward/backprop"| Model
    Trainer -->|"saves .pth checkpoint"| Checkpoint
    Checkpoint -->|"loads checkpoint"| Utils
    Utils -->|"latent velocities\nand gene velocities"| scVelo
    Utils -->|"provides data for"| GRN
    GRN -->|"builds adjacency,\noutputs graph"| Graph

    %% Click Events
    click DataPipeline "https://github.com/idriskb/neurovelo/blob/main/neurovelo/data.py"
    click Module "https://github.com/idriskb/neurovelo/blob/main/neurovelo/module.py"
    click Model "https://github.com/idriskb/neurovelo/blob/main/neurovelo/model.py"
    click Trainer "https://github.com/idriskb/neurovelo/blob/main/neurovelo/train.py"
    click Utils "https://github.com/idriskb/neurovelo/blob/main/neurovelo/utils.py"
    click GRN "https://github.com/idriskb/neurovelo/blob/main/neurovelo/grn.py"
    click API "https://github.com/idriskb/neurovelo/blob/main/neurovelo/__init__.py"

    %% Styles
    classDef code fill:#D6EAF8,stroke:#2980B9,color:#154360;
    classDef data fill:#D5F5E3,stroke:#27AE60,color:#186A3B;
    classDef external fill:#FDEDEC,stroke:#C0392B,color:#641E16;

    class API,DataPipeline,Module,Model,Trainer,Utils,GRN code
    class Checkpoint,Graph data
    class AnnData,scVelo external
```
