# cbg-ethz/pyggdrasil architecture

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

- Interactive diagram: https://gitdiagram.com/cbg-ethz/pyggdrasil
- Repository: https://github.com/cbg-ethz/pyggdrasil

## Overview

##### Main Components
- Core Library (src/pyggdrasil): This is the heart of the system. Break it down into the following submodules:
– Analyze: Contains functions for calculations, convergence diagnostics (e.g., ESS, Rhat), metric computations, and utility functions for post-MCMC analysis.
– Tree Inference: Houses components for tree generation, simulation, MCMC sampling, and validation (e.g., _mcmc, _tree_generator, _simulate).
– Distances: Provides methods to compute similarity/distance metrics between trees, interfacing with external calls if necessary.
– Serialize: Responsible for transforming tree data into serializable formats (like JSON).
– Interface: Likely acts as an API wrapper for external interaction or additional processing.
- Scripts: Located in the scripts/ directory, these provide utilities for specific tasks (cell simulation, tree plotting, etc.) which can be seen as entry points or experimental workflows.
- Workflows: The workflows/ directory and the .github/workflows configurations indicate automated execution (e.g., using Snakemake and GitHub Actions) for testing, documentation, and reproducibility.
- Testing & Quality Assurance: Unit tests in the tests/ directory mirror the structure of the core modules; CI workflows with GitHub Actions and pre-commit hooks (Ruff, Black, Pyright, pytest, Interrogate) ensure code quality and type checking.
- Documentation: The docs/ directory (including API highlights, tutorials, and contributing guides) is crucial for understanding component interactions and usage patterns.

##### Relationships and Data Flow
- Data input may come from external sources or be generated via the provided simulation scripts.
- The input data flows into the Tree Inference module where MCMC sampling and tree generation occur.
- The Analyze module consumes the output from tree inference to compute convergence diagnostics and perform additional statistical analyses.
- The Distances module interacts with both the inferred trees and analysis results to compute tree similarities.
- The Serialize module allows tree objects and analysis outputs to be transformed into standard formats, facilitating storage or data exchange.

##### Architectural Patterns and Design Principles
- Modularization: The project is divided into distinct, self-contained packages—they communicate through clearly defined interfaces.
- Layering: There is a clear separation between core business logic (inference and analysis), utility functions (serialization, visualization), and external workflows (automation, CI/CD).
- Scientific Workflow: Emphasize the sequence from simulation through analysis to visualization, which mirrors a typical scientific data pipeline.

##### Additional Specifics
- Use of third-party tools (e.g., Poetry for dependency management and Black/Ruff/Pyright for code quality) in a “Tooling” or “DevOps” section. Although not part of the runtime architecture, these components support the development pipeline.
- Since the project is research-oriented, you may also want to denote where experimental workflows lie (the workflows directory) and how they integrate with the rest of the architecture.
- That every component is not just listed but also connected logically, as it helps reviewers understand the complexity and interdependencies (e.g., the serialization module is pivotal for both storing results and feeding into visualization).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Scripts & Data Input
    S1["Cell Simulation Script"]:::script
    S2["Make Tree Script"]:::script
    S3["Run MCMC Script"]:::script
    S4["Plot Trees Script"]:::script

    %% Core Library Submodules
    subgraph "Core Library"
        TI["Tree Inference Module: MCMC & Tree Generator"]:::core
        AN["Analyze Module: ESS, Rhat, Metrics"]:::core
        DI["Distances Module"]:::core
        SE["Serialize Module"]:::core
        VI["Visualize Module"]:::core
        IF["Interface Module"]:::core
    end

    %% DEV & Quality Section
    subgraph "DEV & Quality"
        TQA["Testing & Quality Assurance"]:::qa
        WA["Workflows & Automation"]:::qa
        DOC["Documentation"]:::qa
    end

    %% Data Flow Connections
    S1 -->|"simulation_data"| TI
    S2 -->|"tree_trigger"| TI
    S3 -->|"mcmc_execution"| TI
    S4 -->|"plot_request"| VI

    TI -->|"inferred_trees"| AN
    TI -->|"tree_data"| DI
    AN -->|"analysis_results"| DI
    DI -->|"serialized_output"| SE
    SE -->|"formatted_data"| VI

    %% Interaction with Interface Module (external interactions)
    TI ---|"exposes_API"| IF
    AN ---|"exposes_API"| IF
    DI ---|"exposes_API"| IF
    SE ---|"exposes_API"| IF
    VI ---|"exposes_API"| IF

    %% QA & Automation connections
    TI --> TQA
    AN --> TQA
    DI --> TQA
    SE --> TQA
    VI --> TQA
    IF --> TQA
    S1 --> WA
    S2 --> WA
    S3 --> WA
    S4 --> WA
    WA --> TQA
    DOC --> TQA

    %% Styles
    classDef core fill:#f9e79f,stroke:#d35400,stroke-width:2px;
    classDef script fill:#aed6f1,stroke:#2980b9,stroke-width:2px;
    classDef qa fill:#abebc6,stroke:#27ae60,stroke-width:2px;

    %% Click Events for Core Library Modules
    click TI "https://github.com/cbg-ethz/pyggdrasil/tree/main/src/pyggdrasil/tree_inference"
    click AN "https://github.com/cbg-ethz/pyggdrasil/tree/main/src/pyggdrasil/analyze"
    click DI "https://github.com/cbg-ethz/pyggdrasil/tree/main/src/pyggdrasil/distances"
    click SE "https://github.com/cbg-ethz/pyggdrasil/tree/main/src/pyggdrasil/serialize"
    click VI "https://github.com/cbg-ethz/pyggdrasil/tree/main/src/pyggdrasil/visualize"
    click IF "https://github.com/cbg-ethz/pyggdrasil/tree/main/src/pyggdrasil/interface"

    %% Click Events for Scripts
    click S1 "https://github.com/cbg-ethz/pyggdrasil/blob/main/scripts/cell_simulation.py"
    click S2 "https://github.com/cbg-ethz/pyggdrasil/blob/main/scripts/make_tree.py"
    click S3 "https://github.com/cbg-ethz/pyggdrasil/blob/main/scripts/run_mcmc.py"
    click S4 "https://github.com/cbg-ethz/pyggdrasil/blob/main/scripts/plot_trees.py"

    %% Click Events for DEV & Quality Components
    click WA "https://github.com/cbg-ethz/pyggdrasil/tree/main/workflows/"
    click TQA "https://github.com/cbg-ethz/pyggdrasil/tree/main/tests/"
    click DOC "https://github.com/cbg-ethz/pyggdrasil/tree/main/docs/"
```
