How cbg-ethz/pyggdrasil works
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).