How kunwang34/phylovelo works
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