# konradjk/loftee architecture

> Architecture diagram of the GitHub repository konradjk/loftee, 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/konradjk/loftee
- Repository: https://github.com/konradjk/loftee

## Overview

##### Project Overview and Type
- LOFTEE (Loss-Of-Function Transcript Effect Estimator) is a VEP plugin written predominantly in Perl (with some Python utilities) that assesses putative loss‐of‐function variants. It focuses on three main variant types (stop‐gained, splice site disrupting, and frameshift) and applies a comprehensive set of filters based on transcript context, conservation, and splice modeling.
- The purpose is to flag “high-confidence” and “low-confidence” LoF variants by combining predictions from various modules (including splice models via MaxEntScan and SVM/logistic regression filters).

##### Analyzing the File Structure
- Top-Level Files: The project includes major Perl modules (e.g., LoF.pm, TissueExpression.pm, ancestral.pm, context.pm) that implement core variant analysis functionality.
- Executable scripts: Files like de_novo_donor.pl, extended_splice.pl, gerp_dist.pl, loftee_splice_utils.pl, splice_site_scan.pl, svm.pl, and utr_splice.pl serve as specialized tools or filters.
- The “maxEntScan” directory: Contains data, scoring scripts (score3.pl, score5.pl), and splice models that are used to predict splicing consequences.
- The “splice_data” folder: Includes reference files, donor/acceptor motifs, and SVM configuration files that support splice site rescue predictions.
- The “src” directory: Holds Python utility scripts such as loftee_utils.py and scripts that parse and process VEP VCF outputs.
- The rest of the structure (LICENSE, README.md) defines project licensing and comprehensive usage examples.

##### Key Components
a. Input/Integration Layer:
- External VEP Tool: LOFTEE is invoked via VEP as a plugin. VEP sends variant data (VCF lines) and expects annotated output.
- External dependencies: Samtools, the PhyloCSF database, and the ancestral sequence file (human_ancestor.fa) that are checked during processing.
b. Core LOFTEE Modules:
- Variant Filtering Logic: Implemented in several Perl modules (LoF.pm, TissueExpression.pm, ancestral.pm, context.pm) that handle variant categorization and filtering criteria.
- Splice Prediction Module: A dedicated branch that leverages MaxEntScan scripts (in the maxEntScan directory) and the splice_data files. This branch calculates MES scores and predicts rescue events.
- SVM and Logistic Regression Components: Scripts such as svm.pl indicate use of machine learning methods to predict de novo donor splice sites and extended splice site effects.
c. Utility Scripts for Output Handling:
- Data Parsing & Integration: Python scripts in “src” (e.g., read_vep_vcf.py, strip_vcf_to_sites.py, tableize_vcf.py) that help parse the VEP/LoF VCF output and reformat results.

##### Relationships and Data Flow
- Within LOFTEE, split the pipeline into parallel filtering/analysis paths:
- One branch for evaluating stop-gained and frameshift variants (referencing transcript boundaries, near-end exon filtering, etc.).
- A second branch for splice site analysis using both core splice site recognition and extended splice site predictions. This branch interacts with:
- MaxEntScan (scoring scripts and splice models)
- Splice data (donor/acceptor motif details and SVM parameters)
- SVM/Logistic regression components.
- Utility modules (the Python “src” scripts) can be drawn alongside these main flows to indicate how the raw output is post-processed for ease of analysis.

##### Final Elements to be Included
- A clear “VEP” block that feeds into the LOFTEE core.
- Branches for:
- Stop-gained/Frameshift analysis (using modules like LoF.pm).
- Splice site variant analysis (leveraging maxEntScan scripts, splice_data motifs, and rescue prediction logic).
- An SVM/Logistic Regression branch if needed.
- Output block annotated as “VCF with LoFTER Annotations” or “Parsed Variant Annotations” from the Python utilities.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Top Level: Input
    VEP("VEP (External)"):::external
    LOF("LOFTEE Plugin Core"):::core
    VEP -->|"VariantData"| LOF

    %% LOFTEE Core splits into two main processing branches
    %% Branch: Variant Filtering Module
    subgraph "Variant Filtering Module"
        direction TB
        VF1("LoF.pm"):::core
        VF2("TissueExpression.pm"):::core
        VF3("ancestral.pm"):::core
        VF4("context.pm"):::core
        GERP("GERP Integration"):::external
        %% External dependency feeds into filtering modules
        GERP --> VF1
        GERP --> VF2
        GERP --> VF3
        GERP --> VF4
    end

    %% Branch: Splice Site Analysis
    subgraph "Splice Site Analysis"
        direction TB
        SP1("MaxEntScan Splice Predictor"):::core
        SP2("Splice Data Resources"):::core
        SP3("SVM Predictor"):::core
        SP4("De Novo Donor Predictor"):::core
        subgraph "Extended Splice Analysis"
            direction TB
            ES1("extended_splice.pl"):::core
            ES2("utr_splice.pl"):::core
        end
        subgraph "Additional Splice Site Utility"
            direction TB
            AU1("loftee_splice_utils.pl"):::core
            AU2("splice_site_scan.pl"):::core
        end
    end

    %% Connect LOFTEE Core to each branch
    LOF --> VF1
    LOF --> SP1

    %% Branch outputs consolidation
    FilteringOutput("Filtering Output"):::core
    SpliceOutput("Splice Analysis Output"):::core
    VF4 --> FilteringOutput
    SP4 --> SpliceOutput

    %% Merge branch results into final annotated output
    Merged("Annotated VEP VCF Output"):::utility
    FilteringOutput --> Merged
    SpliceOutput --> Merged

    %% Post-processing by Python utilities
    subgraph "Python VCF Parser"
        direction TB
        P1("loftee_utils.py"):::utility
        P2("read_vep_vcf.py"):::utility
        P3("strip_vcf_to_sites.py"):::utility
        P4("tableize_vcf.py"):::utility
    end
    Merged --> P1

    %% Click Events for Component Mapping
    click VF1 "https://github.com/konradjk/loftee/blob/master/LoF.pm"
    click VF2 "https://github.com/konradjk/loftee/blob/master/TissueExpression.pm"
    click VF3 "https://github.com/konradjk/loftee/blob/master/ancestral.pm"
    click VF4 "https://github.com/konradjk/loftee/blob/master/context.pm"
    click GERP "https://github.com/konradjk/loftee/blob/master/gerp_dist.pl"
    click SP1 "https://github.com/konradjk/loftee/tree/master/maxEntScan"
    click SP2 "https://github.com/konradjk/loftee/tree/master/splice_data"
    click SP3 "https://github.com/konradjk/loftee/blob/master/svm.pl"
    click SP4 "https://github.com/konradjk/loftee/blob/master/de_novo_donor.pl"
    click ES1 "https://github.com/konradjk/loftee/blob/master/extended_splice.pl"
    click ES2 "https://github.com/konradjk/loftee/blob/master/utr_splice.pl"
    click AU1 "https://github.com/konradjk/loftee/blob/master/loftee_splice_utils.pl"
    click AU2 "https://github.com/konradjk/loftee/blob/master/splice_site_scan.pl"
    click P1 "https://github.com/konradjk/loftee/blob/master/src/loftee_utils.py"
    click P2 "https://github.com/konradjk/loftee/blob/master/src/read_vep_vcf.py"
    click P3 "https://github.com/konradjk/loftee/blob/master/src/strip_vcf_to_sites.py"
    click P4 "https://github.com/konradjk/loftee/blob/master/src/tableize_vcf.py"

    %% Styles
    classDef external fill:#ADD8E6,stroke:#000,stroke-width:2px
    classDef core fill:#90EE90,stroke:#000,stroke-width:2px
    classDef utility fill:#FFD700,stroke:#000,stroke-width:2px
```
