# myersgroup/relate architecture

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

- Interactive diagram: https://gitdiagram.com/myersgroup/relate
- Repository: https://github.com/myersgroup/relate

## Overview

##### Main Components
- Data Input & File Formats:
– Represent components that deal with reading genetic/haplotype data (example/data, include/file_formats).
– Components for converting to intermediate representations (see “ConvertToTreeSequence.cpp”, “FileFormats.cpp” and the “tskit” subdirectory).
- Preprocessing / Input Preparation:
– Modules in scripts/PrepareInputFiles and parts in include/pipeline that prepare the input and segregate the data.
- Core Genealogy Construction:
– The “pipeline” components (e.g., BuildTopology, OptimizeParameters, MakeChunks, Paint) are the heart of the system that build genealogies.
– Include the “tree_builder”, “branch_length_estimator”, and “tree_comparer” modules (located in include/src) showing how the lineage trees are built and refined.
- Analysis Modules:
– Separate C++ modules for computing coalescent rate (include/evaluate/coalescent_rate) and mutation rate (include/evaluate/mutation_rate) along with selection assessment (include/evaluate/selection).
- Post-processing / Visualization:
– Modules dedicated to output formatting and visualization (e.g., include/treeview for the tree view module, scripts/TreeView).
- Build and Execution Infrastructure:
– The build system (cmake, CMakeLists.txt files) and bin directory containing compiled executables.
- Scripting and Job Management:
– Several shell and batch scripts (in scripts/, docs/download/…/scripts) that manage parallel execution (using SGE, LSF, Slurm) and the orchestration of the computational pipelines.
- Documentation & Examples:
– A separate module containing detailed documentation (docs/) and example run scripts (example/, documentation PDFs in docs/figures).

##### Relationships and Data Flow
- Input data flows from the external genotype/haplotype files (from example/data or user-specified data) into the “Data Input & File Formats” component.
- The “Preprocessing / Input Preparation” component adapts and cleans this data for the analysis pipeline.
- The “Core Genealogy Construction” component uses the preprocessed data to build the genealogical trees by invoking modules like BuildTopology, InferBranchLengths, and MakeChunks.
- Outputs from the genealogy construction feed into the “Analysis Modules” where coalescent rate, mutation rate, and selection analyses are performed.
- Finally, results flow into the “Post-processing / Visualization” component which formats results and provides visual outputs (tree view, plots, and summary files).

##### Architectural Patterns and Design Principles
- Modular Design:
- Pipeline & Workflow:
- Extensibility and Reusability:
– Notice the clear separation in the “include” directory with self-contained modules (and test support in include/test) that indicate good modular design.
- Use of Scripting for orchestration:
– Include an “orchestration” component to represent cron-like or scheduler interactions (SGE, LSF, Slurm) as there are many dedicated scripts.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Input & File Format Conversion
    subgraph "Data Input & File Format Conversion"
        DF["File Formats Converter"]:::core
        ED["Example Data"]:::core
    end

    %% Preprocessing / Input Preparation
    subgraph "Preprocessing / Input Preparation"
        PIF["Prepare Input Files (Script)"]:::script
        PIPE["Input Data Pipeline (C++)"]:::core
    end

    %% Core Genealogy Construction
    subgraph "Core Genealogy Construction"
        BT["Build Topology"]:::core
        IBL["Infer Branch Lengths"]:::core
        MC["Make Chunks"]:::core
        PT["Paint"]:::core
        TB["Tree Builder"]:::core
        BLE["Branch Length Estimator"]:::core
        TC["Tree Comparer"]:::core
    end

    %% Analysis Modules
    subgraph "Analysis Modules"
        CR["Coalescent Rate"]:::core
        MR["Mutation Rate"]:::core
        SE["Selection Analysis"]:::core
    end

    %% Post-processing / Visualization
    subgraph "Post-processing / Visualization"
        TV["Tree View Module"]:::core
        TVS["TreeView Script"]:::script
    end

    %% Build & Execution Infrastructure
    subgraph "Build & Execution Infrastructure"
        CML["CMakeLists.txt"]:::build
        BUILD["Build Directory"]:::build
        BIN["Bin Executables"]:::build
    end

    %% Job Scheduling / Scripting
    subgraph "Job Scheduling / Scripting"
        LSF["RelateLSF"]:::script
        SGE["RelateSGE"]:::script
        SLURM["RelateSlurm"]:::script
        OTH["Other Scripts"]:::script
    end

    %% Documentation & Examples
    subgraph "Documentation & Examples"
        DOC["Documentation"]:::doc
        EXAMPLE["Example Run Scripts & Data"]:::doc
    end

    %% Main Data Flow
    ED -->|"feeds"| PIF
    PIF -->|"cleans and forwards"| PIPE
    PIPE -->|"initiates"| BT
    BT --> IBL
    IBL --> MC
    MC --> PT
    PT --> TB
    TB --> BLE
    BLE --> TC
    TC --> CR
    CR --> MR
    MR --> SE
    SE --> TV
    TV -->|"formats output"| TVS

    %% Supporting Connections
    CML -->|"compilation support"| PIPE
    LSF -->|"orchestrates"| PIF
    SGE -->|"orchestrates"| PIF
    SLURM -->|"orchestrates"| PIF
    OTH -->|"orchestrates"| PIF
    EXAMPLE -->|"provides examples to"| ED
    DOC -->|"guides interpretation of"| TVS

    %% Styles
    classDef core fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef script fill:#A9DFBF,stroke:#229954,stroke-width:2px;
    classDef build fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef doc fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;

    %% Click Events
    click DF "https://github.com/myersgroup/relate/tree/master/include/file_formats"
    click ED "https://github.com/myersgroup/relate/tree/master/example/data"
    click PIF "https://github.com/myersgroup/relate/tree/master/scripts/PrepareInputFiles"
    click PIPE "https://github.com/myersgroup/relate/tree/master/include/pipeline"
    click BT "https://github.com/myersgroup/relate/tree/master/include/pipeline"
    click IBL "https://github.com/myersgroup/relate/tree/master/include/pipeline"
    click MC "https://github.com/myersgroup/relate/tree/master/include/pipeline"
    click PT "https://github.com/myersgroup/relate/tree/master/include/pipeline"
    click TB "https://github.com/myersgroup/relate/tree/master/include/src"
    click BLE "https://github.com/myersgroup/relate/tree/master/include/src"
    click TC "https://github.com/myersgroup/relate/tree/master/include/src"
    click CR "https://github.com/myersgroup/relate/tree/master/include/evaluate/coalescent_rate"
    click MR "https://github.com/myersgroup/relate/tree/master/include/evaluate/mutation_rate"
    click SE "https://github.com/myersgroup/relate/tree/master/include/evaluate/selection"
    click TV "https://github.com/myersgroup/relate/tree/master/include/treeview"
    click TVS "https://github.com/myersgroup/relate/tree/master/scripts/TreeView"
    click CML "https://github.com/myersgroup/relate/blob/master/CMakeLists.txt"
    click BUILD "https://github.com/myersgroup/relate/tree/master/build"
    click BIN "https://github.com/myersgroup/relate/tree/master/bin"
    click LSF "https://github.com/myersgroup/relate/tree/master/scripts/RelateLSF"
    click SGE "https://github.com/myersgroup/relate/tree/master/scripts/RelateSGE"
    click SLURM "https://github.com/myersgroup/relate/tree/master/scripts/RelateSlurm"
    click OTH "https://github.com/myersgroup/relate/tree/master/scripts"
    click DOC "https://github.com/myersgroup/relate/tree/master/docs"
    click EXAMPLE "https://github.com/myersgroup/relate/tree/master/example"
```
