# jonahrileyhuggins/sparced architecture

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

- Interactive diagram: https://gitdiagram.com/jonahrileyhuggins/sparced
- Repository: https://github.com/jonahrileyhuggins/sparced

## Overview

##### Project Type and Purpose
- This project is a large-scale, single-cell mechanistic modeling pipeline. Its purpose is to “construct, merge, expand and simulate” whole-cell models (particularly for MCF-10A cells) using mechanistic sub-models (e.g., cell cycle, DNA damage, apoptosis, receptor signaling, etc.).
- The README emphasizes that the platform is designed both for systems biology modelers (with containerized and notebook-based workflows) and for developers (with command-line scripts, Python modules, and reproducible environments).

##### Analyzing the File Structure
- The top-level directories and files are organized into several key areas:
- Core project code in the “SPARCED” directory (with __main__.py, models, results, src, and toolkit). This directory holds the executable entry point along with the model definitions and simulation logic.
- Subdirectories under “SPARCED/models” house multiple model variants such as “Basic_model”, “SPARCED_legacy”, “SPARCED_standard”, and “SPARCED_tutorial”. Each variant has configuration files (YAML, TSV, etc.), SBML files, and experimental protocol definitions.
- The “SPARCED/src” directory contains modularized code:
- “cli” for command-line operations,
- “compilation” which itself has several submodules (amici_scripts, antimony_scripts, conversion_scripts, sbml_scripts) that manage conversion between different modeling formats (e.g., from Antimony or SBML to simulation formats),
- “simulation” for running the computational experiments (with separate scripts to prepare, run, and perform simulation tasks),
- “validation” to organize benchmarking and correctness checking as well as visualization components.
- Other directories such as “benchmarks”, “docs”, “container”, “build”, and “tests” support external specifications, documentation, deployment (e.g., Docker), packaging, and automated testing.
- The project leverages a modular pipeline design where input model specifications (SBML, YAML, TSV) get processed through several transformation and simulation phases.

##### Key Components and Their Relationships
a. Input/Definition Layer:
- Model Files and Experiments (located in “SPARCED/models” and “benchmarks”) represent raw biological network definitions, experimental conditions, perturbations, and configuration parameters.
b. Conversion/Compilation Layer:
- Modules under “src/compilation” are responsible for converting raw model definitions (Antimony/SBML) into formats suitable for simulation (e.g., using AMICI or other conversion tools). Scripts here handle reaction definitions, initial conditions, and annotations.
c. Simulation/Execution Layer:
- The “src/simulation” modules execute simulation runs. They prepare simulation conditions (RunPrep.py), run simulation experiments (RunSPARCED.py), and implement specific simulation modules (e.g., SGEmodule).
- The executable entry point (__main__.py) and the CLI (in “src/cli”) allow users to trigger simulations via a command-line interface.
d. Validation and Analysis Layer:
- The “src/validation” subtree conducts benchmarks and run validations. It includes setup for performing single simulations, batch or benchmark simulation runs as well as visualization (analysis via notebooks and custom plotting scripts).
e. Utility and Toolkit Layer:
- “src/utils” contains helper modules such as argument parsing, file management, and data handling.
- “toolkit” (both in SPARCED and in build) provides additional helper functions (e.g., protlig and volcalc) that support specialized domain computations.
f. Packaging/Deployment Layer:
- The “container” directory (Dockerfile, sparced.def) and “build” directory support containerized deployment and build automation.
- “docs”, “examples”, and “tests” support documentation, usage examples, and testing routines.

##### Architectural Patterns and Relationships
- A clear separation of concerns is evident throughout:
- Data Model Definition (input specifications) → Model Compilation (format conversion) → Simulation (execution engine) → Validation/Visualization (results analysis).
- The modular design supports extensibility—new model types, experimental protocols, or simulation methods can be added into the corresponding modules.
- The use of separate directories for “cli”, “compilation”, “simulation”, and “validation” reflects layered architecture principles.
- Usage of Docker/Singularity and external environment setup (e.g., via environment.yml) hints at container-based deployment and parallelization capabilities.

- Nodes that reflect external interfaces:
- Input configuration files (YAML, TSV, SBML) on one side feeding into the pipeline.
- External visualization outcomes like notebooks or HTML docs generated under “docs” or “examples”.
- Incorporate dependencies among modules by showing explicit relationships:
- The conversion scripts depend on file formats produced in “models”.
- Simulation modules leverage utilities from the “utils” package.
- Validation uses output from Simulation and interfaces with visualization modules to generate benchmarks.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input/Model Definition Layer
    subgraph "Input/Model Definition"
        i1["SPARCED/models"]:::input
        i2["benchmarks"]:::input
    end

    %% Conversion/Compilation Layer
    subgraph "Conversion/Compilation Layer"
        c1["SPARCED/src/compilation"]:::conversion
        c2["amici_scripts"]:::conversion
        c3["antimony_scripts"]:::conversion
        c4["conversion_scripts"]:::conversion
        c5["sbml_scripts"]:::conversion
    end

    %% Simulation/Execution Layer
    subgraph "Simulation/Execution Layer"
        s1["SPARCED/__main__.py"]:::simulation
        s2["SPARCED/src/cli/cli.py"]:::simulation
        s3["SPARCED/src/simulation"]:::simulation
        s4["RunPrep.py"]:::simulation
        s5["RunSPARCED.py"]:::simulation
        s6["SGEmodule.py"]:::simulation
    end

    %% Validation and Analysis Layer
    subgraph "Validation and Analysis Layer"
        v1["SPARCED/src/validation"]:::validation
    end

    %% Utility and Toolkit Layer
    subgraph "Utility and Toolkit Layer"
        u1["SPARCED/src/utils"]:::utility
        t1["SPARCED/toolkit"]:::utility
        t2["protlig.py"]:::tool
        t3["volcalc.py"]:::tool
    end

    %% Packaging/Deployment Layer
    subgraph "Packaging/Deployment Layer"
        p1["container"]:::deployment
        p2["build"]:::deployment
    end

    %% Connections - Data Flow
    i1 --> c1
    i2 --> c1
    c1 --> c2
    c1 --> c3
    c1 --> c4
    c1 --> c5
    c1 --> s3
    s1 --> s3
    s2 --> s3
    s3 --> s4
    s4 --> s5
    s5 --> s6
    s6 --> v1
    u1 --> s3
    t1 --> s3
    t1 --> t2
    t1 --> t3
    v1 --> p1
    p1 --> p2

    %% Click Events
    click i1 "https://github.com/jonahrileyhuggins/sparced/tree/master/SPARCED/models"
    click i2 "https://github.com/jonahrileyhuggins/sparced/tree/master/benchmarks"
    click c1 "https://github.com/jonahrileyhuggins/sparced/tree/master/SPARCED/src/compilation"
    click c2 "https://github.com/jonahrileyhuggins/sparced/tree/master/SPARCED/src/compilation/amici_scripts"
    click c3 "https://github.com/jonahrileyhuggins/sparced/tree/master/SPARCED/src/compilation/antimony_scripts"
    click c4 "https://github.com/jonahrileyhuggins/sparced/tree/master/SPARCED/src/compilation/conversion_scripts"
    click c5 "https://github.com/jonahrileyhuggins/sparced/tree/master/SPARCED/src/compilation/sbml_scripts"
    click s1 "https://github.com/jonahrileyhuggins/sparced/blob/master/SPARCED/__main__.py"
    click s2 "https://github.com/jonahrileyhuggins/sparced/blob/master/SPARCED/src/cli/cli.py"
    click s3 "https://github.com/jonahrileyhuggins/sparced/tree/master/SPARCED/src/simulation"
    click s4 "https://github.com/jonahrileyhuggins/sparced/blob/master/SPARCED/src/simulation/RunPrep.py"
    click s5 "https://github.com/jonahrileyhuggins/sparced/blob/master/SPARCED/src/simulation/RunSPARCED.py"
    click s6 "https://github.com/jonahrileyhuggins/sparced/blob/master/SPARCED/src/simulation/SGEmodule.py"
    click v1 "https://github.com/jonahrileyhuggins/sparced/tree/master/SPARCED/src/validation"
    click u1 "https://github.com/jonahrileyhuggins/sparced/tree/master/SPARCED/src/utils"
    click t1 "https://github.com/jonahrileyhuggins/sparced/tree/master/SPARCED/toolkit"
    click t2 "https://github.com/jonahrileyhuggins/sparced/blob/master/SPARCED/toolkit/protlig.py"
    click t3 "https://github.com/jonahrileyhuggins/sparced/blob/master/SPARCED/toolkit/volcalc.py"
    click p1 "https://github.com/jonahrileyhuggins/sparced/tree/master/container"
    click p2 "https://github.com/jonahrileyhuggins/sparced/tree/master/build"

    %% Styles
    classDef input fill:#d0f0c0,stroke:#333,stroke-width:2px;
    classDef conversion fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef simulation fill:#ffcc99,stroke:#333,stroke-width:2px;
    classDef validation fill:#fff2ab,stroke:#333,stroke-width:2px;
    classDef utility fill:#dda0dd,stroke:#333,stroke-width:2px;
    classDef deployment fill:#eeeeee,stroke:#333,stroke-width:2px;
    classDef tool fill:#f9d790,stroke:#333,stroke-width:2px;
```
