# unique379r/strspy architecture

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

- Interactive diagram: https://gitdiagram.com/unique379r/strspy
- Repository: https://github.com/unique379r/strspy

## Overview

##### Project Type and Purpose
- This is an open‐source bioinformatics pipeline tool (STRspy) for short tandem repeat (STR) detection in long‐read sequencing data (ONT or PacBio).
- It provides a command‐line interface, uses Conda environments, calls external tools, and generates STR quantification, variant calls, and visualizations.

##### File Structure
- Top‐level directories:
- config – user input/configuration files
- customDB – STR reference databases (Fasta/Bed)
- scripts – main pipeline scripts (parallel and nested versions)
- setup – environment and tool‐config setup scripts
- utilities – post‐processing and plotting scripts
- demodata – example data and results
- figs – static figures (logo, benchmarking images)
- Key files:
- STRspy_run_v1.0.sh – wrapper launcher
- scripts/STRspy_v1.0.sh – core pipeline
- setup/STRspy_setup.sh & MakeToolConfig.sh – environment and ToolsConfig
- External tools invoked (configured in config/ToolsConfig.txt): minimap2, samtools, bedtools, xatlas, GNU parallel.

##### README for Architectural Insights
- Inputs: FASTQ or BAM, STR Fasta/Bed, genome reference, normalization cutoff.
- Workflow steps: alignment → coverage estimation → allele counting & normalization → SNP/indel calling → stutter analysis → reporting.
- Outputs: allele counts, normalized counts, mapping summary, stutter plots, heatmaps.

##### Main Components
a. Input Layer
- User CLI (STRspy_run_v1.0.sh)
- config/InputConfig.txt and config/ToolsConfig.txt
- Raw sequencing data directory (FASTQ/BAM)
b. Setup Layer
- Conda environment (STRspy_env)
- setup scripts (environment.yml, STRspy_setup.sh, MakeToolConfig.sh)
c. Reference Data
- customDB/Y-str-prep (STR Fasta/Bed)
d. Pipeline Engine
- scripts/STRspy_v1.0.sh (core workflow)
- GNU parallel (optional parallel execution)
e. External Bioinformatics Tools
- minimap2 for alignment
- samtools and bedtools for coverage and mapping summary
- xatlas for variant calling
f. Post‐Processing Utilities
- utilities/*.sh and *.py/.R for benchmarking, stutter analysis, plotting
g. Output Layer
- OUTPUT_DIR: raw allele counts, normalized counts, variant reports, plots
- demodata/test_results for comparison

##### Relationships and Data Flow
- From Pipeline Engine to Reference Data (STR DB) for region definitions.
- From Pipeline Engine to Post‐Processing Utilities, then to Output Layer.

##### Architectural Patterns and Design Principles
- Modular pipeline: separation of setup, core workflow, utilities.
- Configuration‐driven: all paths and tool executables defined in config files.
- Extensible reference database (customDB) separate from code.
- Optional parallelization layer (GNU parallel) for scalability.

##### Technologies and Frameworks
- Conda for environment management
- Bash scripts orchestrating workflow
- Python and R for plotting and analysis (utilities)
- Third‐party genomics tools: minimap2, samtools, bedtools, xatlas, GNU parallel

##### Essential Elements
- Component names and roles
- Version or tool‐name annotations near external tools

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Layer
    subgraph "Input Layer"
        CLI["User CLI\nSTRspy_run_v1.0.sh"]:::process
        InputConfig["Input Config\nconfig/InputConfig.txt"]:::data
        ToolsConfig["Tools Config\nconfig/ToolsConfig.txt"]:::data
    end

    %% Setup Layer
    subgraph "Setup Layer"
        EnvDef["Conda Env Def\nenvironment.yml"]:::data
        EnvSetup["Env Setup Script\nSTRspy_setup.sh"]:::process
        ToolsConfGen["ToolsConfig Script\nMakeToolConfig.sh"]:::process
    end

    %% Reference Data
    subgraph "Reference Data"
        STRRefDB["STR Reference DB\nY.slop500bpNameCor.bed.fa"]:::data
        STRRefIdx["STR Ref Regions\nY.slop500bp.bed\nleft-right500.tab.txt"]:::data
    end

    %% Pipeline Engine
    subgraph "Pipeline Engine"
        SeqPipeline["Core Pipeline (Seq)\nSTRspy_v1.0.sh"]:::process
        ParPipeline["Core Pipeline (Par)\nSTRspy_Parallel_v1.0.sh"]:::process
    end

    %% External Tools
    subgraph "External Tools"
        Minimap2["minimap2"]:::exttool
        Samtools["samtools"]:::exttool
        Bedtools["bedtools"]:::exttool
        Xatlas["xatlas"]:::exttool
        Parallel["GNU parallel"]:::exttool
    end

    %% Post-Processing Utilities
    subgraph "Post-Processing Utilities"
        Bench["1. Benchmarking\nSTRspy_bencharkingscript.sh"]:::process
        Summary["2. Summary\nSTRspy_resultsWithBenchmarkMeasures.sh"]:::process
        HeatPrep["3. Heatmap Prep\nSTRspy_prepareHeatFileNumericFormat.sh"]:::process
        StutterWrap["4. Stutter Analysis\nSTRspy_StutterSpy_v1.sh"]:::process
        LinePrep["5. Line Plot Prep\nSTRspy_prepare_files_forLinePlot.sh"]:::process
        LineWrap["6. Line Plot Wrapper\nSTRspy_stuttersLinePlotWrapper.sh"]:::process
        PyStutter["Python Stutter Script\nStutterSpy_v1.py"]:::process
        RLine["R Line Plot Script\nStutters_Line_plot.R"]:::process
    end

    %% Output Layer
    subgraph "Output Layer"
        RawAllele["Raw Allele Counts\n& Reports"]:::data
        NormCounts["Normalized Counts"]:::data
        Variants["Variant Reports"]:::data
        Plots["Plots & Heatmaps"]:::data
        DemoInput["Example Input Data\ndemodata/testset.tar.gz"]:::data
        DemoResults["Example Results\ndemodata/test_results.tar.gz"]:::data
    end

    %% Documentation
    subgraph "Documentation"
        Figs["Figs Directory"]:::data
        License["LICENSE"]:::meta
        Readme["README.md"]:::meta
    end

    %% Connections: Input to Setup and Pipeline
    CLI -->|uses| EnvSetup
    CLI -->|generates| ToolsConfGen
    CLI -->|reads| InputConfig
    CLI -->|reads| ToolsConfig
    CLI -->|launches| SeqPipeline
    CLI -->|launches| ParPipeline

    EnvSetup -->|loads| EnvDef
    ToolsConfGen -->|writes| ToolsConfig

    %% Pipeline to Reference and Tools
    SeqPipeline -->|reads| STRRefDB
    SeqPipeline -->|reads| STRRefIdx
    SeqPipeline -->|calls| Minimap2
    SeqPipeline -->|calls| Samtools
    SeqPipeline -->|calls| Bedtools
    SeqPipeline -->|calls| Xatlas
    SeqPipeline -->|parallelizes| Parallel

    ParPipeline -->|uses| Parallel
    ParPipeline -->|calls| Minimap2
    ParPipeline -->|calls| Samtools
    ParPipeline -->|calls| Bedtools
    ParPipeline -->|calls| Xatlas

    %% Pipeline to Outputs
    SeqPipeline -->|outputs| RawAllele
    SeqPipeline -->|outputs| Variants

    %% Utilities flow
    RawAllele -->|input| Bench
    RawAllele -->|input| Summary
    Bench -->|data| HeatPrep
    Summary -->|data| HeatPrep
    HeatPrep -->|prepares| StutterWrap
    StutterWrap -->|runs| PyStutter
    LinePrep -->|prepares| LineWrap
    LineWrap -->|runs| RLine
    PyStutter -->|produces| Plots
    RLine -->|produces| Plots
    Variants -->|normalized| NormCounts

    %% Documentation connections
    DemoInput -->|example| SeqPipeline
    Plots -->|stored in| DemoResults

    %% Click Events
    click CLI "https://github.com/unique379r/strspy/blob/main/STRspy_run_v1.0.sh"
    click InputConfig "https://github.com/unique379r/strspy/blob/main/config/InputConfig.txt"
    click ToolsConfig "https://github.com/unique379r/strspy/blob/main/config/ToolsConfig.txt"
    click EnvDef "https://github.com/unique379r/strspy/blob/main/setup/environment.yml"
    click EnvSetup "https://github.com/unique379r/strspy/blob/main/setup/STRspy_setup.sh"
    click ToolsConfGen "https://github.com/unique379r/strspy/blob/main/setup/MakeToolConfig.sh"
    click STRRefDB "https://github.com/unique379r/strspy/blob/main/customDB/Y-str-prep/references/Y.slop500bpNameCor.bed.fa"
    click STRRefIdx "https://github.com/unique379r/strspy/blob/main/customDB/Y-str-prep/references/Y.slop500bp.bed"
    click SeqPipeline "https://github.com/unique379r/strspy/blob/main/scripts/STRspy_v1.0.sh"
    click ParPipeline "https://github.com/unique379r/strspy/blob/main/scripts/STRspy_Parallel_v1.0.sh"
    click Bench "https://github.com/unique379r/strspy/blob/main/utilities/1.STRspy_bencharkingscript.sh"
    click Summary "https://github.com/unique379r/strspy/blob/main/utilities/2.STRspy_resultsWithBenchmarkMeasures.sh"
    click HeatPrep "https://github.com/unique379r/strspy/blob/main/utilities/3.STRspy_prepareHeatFileNumericFormat.sh"
    click StutterWrap "https://github.com/unique379r/strspy/blob/main/utilities/4.STRspy_StutterSpy_v1.sh"
    click LinePrep "https://github.com/unique379r/strspy/blob/main/utilities/5.STRspy_prepare_files_forLinePlot.sh"
    click LineWrap "https://github.com/unique379r/strspy/blob/main/utilities/6.STRspy_stuttersLinePlotWrapper.sh"
    click PyStutter "https://github.com/unique379r/strspy/blob/main/utilities/StutterSpy_v1.py"
    click RLine "https://github.com/unique379r/strspy/blob/main/utilities/Stutters_Line_plot.R"
    click DemoInput "https://github.com/unique379r/strspy/blob/main/demodata/testset.tar.gz"
    click DemoResults "https://github.com/unique379r/strspy/blob/main/demodata/test_results.tar.gz"
    click Figs "https://github.com/unique379r/strspy/tree/main/figs/"
    click License "https://github.com/unique379r/strspy/tree/main/LICENSE"
    click Readme "https://github.com/unique379r/strspy/blob/main/README.md"

    %% Styles
    classDef process fill:#ADD8E6,stroke:#000;
    classDef data fill:#90EE90,stroke:#000;
    classDef exttool fill:#FFA500,stroke:#000;
    classDef meta fill:#D3D3D3,stroke:#000;
```
