# sfragkoul/synth4bench architecture

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

- Interactive diagram: https://gitdiagram.com/sfragkoul/synth4bench
- Repository: https://github.com/sfragkoul/synth4bench

## Overview

##### Project Overview and Purpose
- Recognize that synth4bench is a framework that uses the NEAT simulator to generate synthetic genomics datasets (focusing on the TP53 gene) and then benchmarks multiple somatic variant calling algorithms (GATK-Mutect2, Freebayes, VarDict, VarScan2, and LoFreq) by comparing their output against established ground truth.
- The framework is aimed at improving the detection accuracy for low frequency variants (≤10%), which is especially important in cancer genomic studies.

##### Analyzing the File Tree
- The top-level structure reveals directories and files for:
- R scripts that perform data processing, analysis, and plotting (found in the “R” directory). R scripts include main analysis scripts (S4BR.R), plotting scripts (S4BR_plot.R, paper_plots.R), and several helper modules (helpers_*.R).
- Bash templates (e.g., freebayes_template.sh, lofreq_template.sh, mutect2_template.sh, vardict_template.sh, variant_calling_template.sh, synth_generation_template.sh) which provide standardized ways to run the data generation and variant calling processes.
- A “bam-readcount” subdirectory which houses an external tool meant to assess read counts in BAM files.
- Configuration files such as environment.yml and parameters.yaml that set up dependencies and parameters for execution.
- Documentation folders (docs) and the toy dataset directory that provides sample input files (BAM, VCF, fastq).
- This layout informs you of several “layers” in the system: data generation, variant calling execution, post-processing/analysis, and documentation.

##### Key Components
a. Data Generation Module:
- NEATv3.3 as an external tool that generates synthetic genomics data based on the TP53 gene.
- That the synthetic datasets consist of multiple ground truth datasets, which are later merged.
- Dependency on the “synth_generation_template.sh” bash script and associated parameter configuration (parameters.yaml).

b. Variant Calling Module:
- Out the multiple variant callers integrated into the framework:
– GATK-Mutect2
– Freebayes (with freebayes_template.sh)
– VarDict (with varscan_template.sh and the link to the external VarScan2VCF script for VarScan handling)
– VarScan2 (helper scripts and templates)
– LoFreq (with lofreq_template.sh)
- You might also want to represent the tool “bam-readcount” used for read-level analysis.

c. Post-Processing and Analysis (Evaluation) Module:
- R scripts (S4BR.R, S4BR_plot.R, paper_plots.R) as separate nodes that receive outputs (VCF, statistical data, etc.) from the variant calling processes.
- Utility/helper scripts within the R folder (helpers_*.R) that support tasks like data cleaning, contacting variant callers (e.g., helpers_Freebayes.R, helpers_VarDict.R), and additional statistical analyses (extra scripts such as stats.R, stats_*.Rmd).

d. Infrastructure and Supporting Components:
- Role of configuration files: environment.yml (for setting up the conda ecosystem and necessary dependencies) and parameters.yaml (for managing run-time parameters).
- An external dependency block for additional tools (like NEATv3.3, bam-readcount, and R libraries installed via install.packages).
- A “Documentation/Support” block that references the docs directory (Documentation.md, UserGuide.md) and image resources (presentation PDFs and posters) for end-user reference.

##### Relationships and Interactions
- Variant caller back to the evaluation module, indicating that they produce output (VCF files, read count summaries) that are then fed into the R scripts for quality assessment and visual presentation.
- Interactions between helper scripts and core functions: for instance, R/common_helpers.R links custom R logic with data produced by variant callers.

##### Architectural Patterns and Technologies
- That the project uses a modular approach, separating data generation, variant calling, and analysis.
- That it leverages scripting (bash, R) to executive workflows and that configuration management (parameters.yaml and environment.yml) plays a crucial role.
- Integration of external tools (NEAT simulator, bam-readcount) alongside in-house scripts.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Synthetic Data Generation Layer
    subgraph "Synthetic Data Generation Layer"
        A1["Synthetic Data Generation (NEAT & synth_generation_template.sh)"]:::bash
        A2["TP53 Synthetic Dataset"]:::data
    end

    %% Variant Calling Module
    subgraph "Variant Calling Module"
        VC1["GATK-Mutect2 (mutect2_template.sh)"]:::bash
        VC2["Freebayes (freebayes_template.sh)"]:::bash
        VC3["VarDict (vardict_template.sh)"]:::bash
        VC4["VarScan2 (varscan_template.sh)"]:::bash
        VC5["LoFreq (lofreq_template.sh)"]:::bash
        VC6["Read-Level Analysis (bam-readcount)"]:::external
    end

    %% Post-Processing and Analysis
    subgraph "Post-Processing and Analysis"
        R1["S4BR.R"]:::rscript
        R2["S4BR_plot.R"]:::rscript
        R3["paper_plots.R"]:::rscript
        RH["R Helper Scripts (helpers_*.R, common_helpers.R)"]:::rscript
    end

    %% Configuration & Infrastructure
    subgraph "Configuration & Infrastructure"
        C1["environment.yml"]:::config
        C2["parameters.yaml"]:::config
    end

    %% Documentation & User Resources
    subgraph "Documentation & User Resources"
        D1["Docs (Documentation.md, UserGuide.md)"]:::docs
    end

    %% Data Flow Connections
    A1 --> A2
    A2 -->|"Synthetic Data"| VC1
    A2 -->|"Synthetic Data"| VC2
    A2 -->|"Synthetic Data"| VC3
    A2 -->|"Synthetic Data"| VC4
    A2 -->|"Synthetic Data"| VC5
    A2 -->|"Synthetic Data"| VC6

    VC1 -->|"Output VCF/Counts"| R1
    VC2 -->|"Output VCF/Counts"| R1
    VC3 -->|"Output VCF/Counts"| R1
    VC4 -->|"Output VCF/Counts"| R1
    VC5 -->|"Output VCF/Counts"| R1
    VC6 -->|"ReadCount Data"| R1

    R1 --> R2
    R1 --> R3
    RH --- R1

    %% Configuration & Environment Feeding
    C2 -->|"Parameters"| A1
    C2 --> VC1
    C2 --> VC2
    C2 --> VC3
    C2 --> VC4
    C2 --> VC5
    C2 --> VC6
    C1 -->|"Conda Setup"| A1

    %% Documentation Links
    D1 --- C1
    D1 --- RH
    D1 --- A1

    %% Click Events
    click A1 "https://github.com/sfragkoul/synth4bench/blob/main/synth_generation_template.sh"
    click VC1 "https://github.com/sfragkoul/synth4bench/blob/main/mutect2_template.sh"
    click VC2 "https://github.com/sfragkoul/synth4bench/blob/main/freebayes_template.sh"
    click VC3 "https://github.com/sfragkoul/synth4bench/blob/main/vardict_template.sh"
    click VC4 "https://github.com/sfragkoul/synth4bench/blob/main/varscan_template.sh"
    click VC5 "https://github.com/sfragkoul/synth4bench/blob/main/lofreq_template.sh"
    click VC6 "https://github.com/sfragkoul/synth4bench/tree/main/bam-readcount"
    click R1 "https://github.com/sfragkoul/synth4bench/blob/main/R/S4BR.R"
    click R2 "https://github.com/sfragkoul/synth4bench/blob/main/R/S4BR_plot.R"
    click R3 "https://github.com/sfragkoul/synth4bench/blob/main/R/paper_plots.R"
    click RH "https://github.com/sfragkoul/synth4bench/blob/main/R/common_helpers.R"
    click C1 "https://github.com/sfragkoul/synth4bench/blob/main/environment.yml"
    click C2 "https://github.com/sfragkoul/synth4bench/blob/main/parameters.yaml"
    click D1 "https://github.com/sfragkoul/synth4bench/blob/main/docs/Documentation.md"
    click VC1 "https://github.com/sfragkoul/synth4bench/blob/main/R/helpers_gatk.R"
    click VC2 "https://github.com/sfragkoul/synth4bench/blob/main/R/helpers_freebayes.R"
    click VC3 "https://github.com/sfragkoul/synth4bench/blob/main/R/helpers_VarDict.R"
    click VC4 "https://github.com/sfragkoul/synth4bench/blob/main/R/helpers_VarScan.R"
    click VC5 "https://github.com/sfragkoul/synth4bench/blob/main/R/helpers_LoFreq.R"

    %% Styles
    classDef bash fill:#f9e79f,stroke:#b9770e,stroke-width:2px;
    classDef rscript fill:#aed6f1,stroke:#2471a3,stroke-width:2px;
    classDef data fill:#a9dfbf,stroke:#1e8449,stroke-width:2px;
    classDef external fill:#f5b7b1,stroke:#c0392b,stroke-width:2px;
    classDef config fill:#d7bde2,stroke:#8e44ad,stroke-width:2px;
    classDef docs fill:#f9e79f,stroke:#b9770e,stroke-width:2px;
```
