# kunwang34/phylovelo architecture

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

- Interactive diagram: https://gitdiagram.com/kunwang34/phylovelo
- Repository: https://github.com/kunwang34/phylovelo

## Overview

##### Project type and purpose
- PhyloVelo is primarily a Python computational library (an open-source bioinformatics tool) for quantifying transcriptomic velocity fields from phylogeny‐resolved single-cell RNA‐seq data.
- It provides a core package (`phylovelo`), command-line/demo scripts under `demo/`, Jupyter notebooks for tutorials and exploratory analysis, and Sphinx‐based documentation under `docs/`.

##### File structure
- Top‐level:
- `phylovelo/` – the core Python package with modules for data structures, utilities, simulations, inference, embedding, gene expression handling, and pseudotime estimation
- `demo/` – standalone Python scripts and sample datasets for quick simulations (linear, bifurcating, convergent lineages, C. elegans, TCR, etc.)
- `notebooks/` – Jupyter notebooks illustrating real‐world use cases and comparisons
- `docs/` – Sphinx source, configuration, and tutorial notebooks for building the published documentation
- `setup.py` & `requirements.txt` – installation and dependency management
- Patterns:
- Modular library design, with separable submodules under `phylovelo/`
- Driver scripts (`demo/`) invoke library APIs to simulate or analyze data
- Notebooks wrap scripts and core functions for interactive exploration
- Documentation built from RST and embedded notebooks

##### README for additional insights
- Confirms purpose, installation, data sources, and reference publication
- Points to ReadTheDocs site for API reference and user guides

a. Main components:
- Core library (`phylovelo` package)
– Data structures (data_struct.py)
– Utility functions (ana_utils.py, sim_utils.py, elegans_util.py, etc.)
– Simulation engines (gillespie_variable_paras.py, sim_utils.py)
– Inference and pseudotime modules (inference.py, pseudo_time.py)
– Embedding and gene expression handlers (embedding.py, gene_expr.py)
- Demo CLI scripts (`demo/run_simulation_*.py`)
- Jupyter notebooks (`notebooks/` & `docs/source/notebook/`)
- Documentation generator (Sphinx under `docs/`)
- External data sources (flat files: `.csv`, `.loom`, `.nwk`, Google Drive links)
b. Relationships and interactions:
– Notebooks and demo scripts import and call functions from the core library
– Core library modules interact in a pipeline:
Input data → data_struct → sim_utils/gillespie → inference/pseudo_time → embedding/gene_expr → output fields/visualizations
– Documentation builder reads Sphinx RST and notebook sources to produce HTML/PDF docs
– `setup.py` & `requirements.txt` manage packaging and dependencies
c. Architectural patterns and design principles:
– Modular, single‐responsibility submodules
– Clear separation between simulation, inference, and visualization logic
– Extensible API for adding new simulation types or gene‐expression models
– Notebook‐first approach for user tutorials
d. Key technologies and frameworks:
– Python 3.x (PyPI package)
– Jupyter Notebook / IPython
– Sphinx + recommonmark for docs
– Scientific stack (NumPy, SciPy, Pandas, Scanpy/AnnData likely as dependencies)
– CSV, Loom, Newick file formats for data

##### Detailed breakdown recommendation
- Above or below, place “Simulation Engine” (gillespie_variable_paras, sim_utils) flowing into “Inference & Pseudotime” then into “Embedding & Visualization”
- To the right, place “Outputs” (vector field data, plots)
- Surrounding this core, place “Demo Scripts” and “Jupyter Notebooks” as clients invoking library functions

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Input
    InputData["Input Data\n(CSV, Loom, Newick)"]:::data

    %% Core Library
    subgraph "Core Library (phylovelo)" 
        DS["data_struct.py"]:::core
        AU["ana_utils.py"]:::core
        SU["sim_utils.py"]:::core
        EU["elegans_util.py"]:::core
        GV["gillespie_variable_paras.py"]:::core
        INF["inference.py"]:::core
        PT["pseudo_time.py"]:::core
        EM["embedding.py"]:::core
        GE["gene_expr.py"]:::core
    end

    %% User Interfaces
    subgraph "User Interfaces"
        DScripts["Demo Scripts"]:::ui
        DNotebooks["Demo Notebooks"]:::ui
        TNotebooks["Tutorial Notebooks"]:::ui
    end

    %% Outputs
    Outputs["Results\n(Velocity fields, Plots)"]:::output

    %% Documentation
    subgraph "Documentation Pipeline"
        DSource["Docs Source\n(RST & Notebooks)"]:::docs
        Builder["Sphinx Builder"]:::docs
        Pub["Published Docs"]:::docs
    end

    %% Core Flow
    InputData --> DS
    DS --> SU
    SU --> GV
    GV --> INF
    INF --> PT
    PT --> EM
    PT --> GE
    EM --> Outputs
    GE --> Outputs

    %% UI interactions
    DScripts --> DS
    DScripts --> SU
    DScripts --> INF
    DNotebooks --> DS
    DNotebooks --> EM
    TNotebooks --> DS
    TNotebooks --> EM

    %% Documentation flow
    DS --> DSource
    AU --> DSource
    SU --> DSource
    DNotebooks --> DSource
    TNotebooks --> DSource
    DSource --> Builder
    Builder --> Pub

    %% Click Events
    click DScripts "https://github.com/kunwang34/phylovelo/blob/master/demo/run_simulation_linear.py"
    click DScripts "https://github.com/kunwang34/phylovelo/blob/master/demo/run_simulation_bifurcated.py"
    click DScripts "https://github.com/kunwang34/phylovelo/blob/master/demo/run_simulation_convergent.py"
    click DNotebooks "https://github.com/kunwang34/phylovelo/tree/master/demo/"
    click TNotebooks "https://github.com/kunwang34/phylovelo/tree/master/notebooks/"
    click DS "https://github.com/kunwang34/phylovelo/blob/master/phylovelo/data_struct.py"
    click AU "https://github.com/kunwang34/phylovelo/blob/master/phylovelo/ana_utils.py"
    click SU "https://github.com/kunwang34/phylovelo/blob/master/phylovelo/sim_utils.py"
    click EU "https://github.com/kunwang34/phylovelo/blob/master/phylovelo/elegans_util.py"
    click GV "https://github.com/kunwang34/phylovelo/blob/master/phylovelo/gillespie_variable_paras.py"
    click INF "https://github.com/kunwang34/phylovelo/blob/master/phylovelo/inference.py"
    click PT "https://github.com/kunwang34/phylovelo/blob/master/phylovelo/pseudo_time.py"
    click EM "https://github.com/kunwang34/phylovelo/blob/master/phylovelo/embedding.py"
    click GE "https://github.com/kunwang34/phylovelo/blob/master/phylovelo/gene_expr.py"
    click DS "https://github.com/kunwang34/phylovelo/blob/master/__init__.py" "phylovelo/__init__.py"
    click DSource "https://github.com/kunwang34/phylovelo/blob/master/docs/source/conf.py"
    click DSource "https://github.com/kunwang34/phylovelo/blob/master/docs/source/index.rst"
    click DSource "https://github.com/kunwang34/phylovelo/blob/master/docs/source/Installation.md"

    %% Styles
    classDef core fill:#d0e1f9,stroke:#2b6cb0,color:#2b6cb0;
    classDef ui fill:#c6f6d5,stroke:#2f855a,color:#2f855a;
    classDef docs fill:#fbd38d,stroke:#dd6b20,color:#dd6b20;
    classDef data fill:#e2e8f0,stroke:#718096,color:#2d3748;
    classDef output fill:#e9d8fd,stroke:#6b46c1,color:#6b46c1;
```
