# bartongroup/ank-analysis architecture

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

- Interactive diagram: https://gitdiagram.com/bartongroup/ank-analysis
- Repository: https://github.com/bartongroup/ank-analysis

## Overview

##### Key Components
a. Input Data
- files/ (raw multiple-sequence alignments, variant tables)
- (Potential future additions: configuration files or additional datasets)
b. Data-Retrieval & Integration Modules
- retrieve_data_allsp.py — fetches and merges UniProt/InterPro annotations
- structure_validation.py — downloads/validates structural mappings
c. Alignment Modules
- new_aligner.py, alignment_editing.py, slaver.py — sequence-alignment functions
d. Analysis Modules
- variant_analysis.py — computes per-position variant enrichment
- contact_maps.py — builds intra-/inter-repeat contact maps
- structural_analysis.py — calculates RSA, secondary-structure, PPI enrichments
e. Orchestration Layer (Notebooks)
- def_data_extraction.ipynb
- def_database_integration.ipynb
- def_upset.ipynb (intersection plots)
- def_alignment.ipynb
- def_variant_analysis.ipynb
- def_structure_validation.ipynb
- def_contact_maps.ipynb
- def_structural_analysis.ipynb
f. Intermediate & Final Outputs
- Generated dataframes, plots, and summary tables (stored alongside notebooks or in dedicated output directories).

##### Relationships & Data Flow
1. Raw data (files/) → “retrieve_data_allsp” → merged annotation dataframe
2. Merged annotations → “database_integration” notebook → non-redundant sequences
3. Non-redundant sequences → alignment modules (new_aligner, slaver, editing) → final alignment
4. Final alignment → variant_analysis.py → variant enrichment results
5. Alignment + structure identifiers → structure_validation.py → validated PDB mappings
6. Validated structures → contact_maps.py → contact map results
7. Contact maps + PDB structures → structural_analysis.py → RSA, SS, PPI analyses
8. Each step is invoked and visualized in its corresponding notebook.

##### Architectural Patterns & Principles
- Modular pipeline: each functional area is a separate Python module + orchestrating notebook
- Data-centric flow: clear source → transform → output stages
- Single responsibility: modules focus on one type of processing
- Notebook layer decouples UI/visualization from core logic

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Stage 1: Data Extraction & Integration
    subgraph "Data Extraction Stage"
        direction TB
        F1["files/"]:::ds
        R1["retrieve_data_allsp.py"]:::module
        N1["def_data_extraction.ipynb"]:::notebook
        N2["def_database_integration.ipynb"]:::notebook
        U1["def_upset.ipynb"]:::notebook
        I1["merged_annotations.csv dataframe"]:::output
        S1["non-redundant_sequences.fasta"]:::output
    end

    F1 -->|".msa, .tsv"| R1
    R1 -->|".csv dataframe"| N1
    N1 -->|".csv dataframe"| I1
    I1 -->|".csv dataframe"| N2
    N2 -->|".fasta sequences"| S1
    S1 -->|".csv intersections"| U1

    %% Stage 2: Alignment
    subgraph "Alignment Stage"
        direction TB
        N3["def_alignment.ipynb"]:::notebook
        A1["new_aligner.py"]:::module
        A2["alignment_editing.py"]:::module
        A3["slaver.py"]:::module
        O1["final_alignment.sto"]:::output
    end

    S1 -->|"non-redundant fasta"| N3
    N3 -->|calls| A1
    A1 --> A2
    A2 --> A3
    A3 -->|".sto alignment"| O1

    %% Stage 3: Variant Analysis
    subgraph "Variant Analysis Stage"
        direction TB
        N4["def_variant_analysis.ipynb"]:::notebook
        V1["variant_analysis.py"]:::module
        O2["variant_enrichment_results.csv"]:::output
    end

    O1 -->|"alignment.sto"| N4
    N4 -->|calls| V1
    V1 -->|".csv results"| O2

    %% Stage 4: Structure Validation
    subgraph "Structure Validation Stage"
        direction TB
        N5["def_structure_validation.ipynb"]:::notebook
        S2["structure_validation.py"]:::module
        O3["validated_pdb_list.csv"]:::output
    end

    O1 -->|"alignment IDs"| N5
    N5 -->|calls| S2
    S2 -->|".csv mappings"| O3

    %% Stage 5: Contact Mapping
    subgraph "Contact Mapping Stage"
        direction TB
        N6["def_contact_maps.ipynb"]:::notebook
        C1["contact_maps.py"]:::module
        O4["contact_maps_results.csv"]:::output
    end

    O3 -->|".csv mappings"| N6
    N6 -->|calls| C1
    C1 -->|".csv maps"| O4

    %% Stage 6: Structural Analysis
    subgraph "Structural Analysis Stage"
        direction TB
        N7["def_structural_analysis.ipynb"]:::notebook
        S3["structural_analysis.py"]:::module
        O5["RSA_SS_PPI_analysis_results.csv"]:::output
    end

    O4 -->|".csv maps"| N7
    N7 -->|calls| S3
    S3 -->|".csv analyses"| O5

    %% Click Events
    click F1 "https://github.com/bartongroup/ank-analysis/tree/master/files/"
    click R1 "https://github.com/bartongroup/ank-analysis/blob/master/retrieve_data_allsp.py"
    click S2 "https://github.com/bartongroup/ank-analysis/blob/master/structure_validation.py"
    click A1 "https://github.com/bartongroup/ank-analysis/blob/master/new_aligner.py"
    click A2 "https://github.com/bartongroup/ank-analysis/blob/master/alignment_editing.py"
    click A3 "https://github.com/bartongroup/ank-analysis/blob/master/slaver.py"
    click V1 "https://github.com/bartongroup/ank-analysis/blob/master/variant_analysis.py"
    click C1 "https://github.com/bartongroup/ank-analysis/blob/master/contact_maps.py"
    click S3 "https://github.com/bartongroup/ank-analysis/blob/master/structural_analysis.py"
    click N1 "https://github.com/bartongroup/ank-analysis/blob/master/def_data_extraction.ipynb"
    click N2 "https://github.com/bartongroup/ank-analysis/blob/master/def_database_integration.ipynb"
    click U1 "https://github.com/bartongroup/ank-analysis/blob/master/def_upset.ipynb"
    click N3 "https://github.com/bartongroup/ank-analysis/blob/master/def_alignment.ipynb"
    click N4 "https://github.com/bartongroup/ank-analysis/blob/master/def_variant_analysis.ipynb"
    click N5 "https://github.com/bartongroup/ank-analysis/blob/master/def_structure_validation.ipynb"
    click N6 "https://github.com/bartongroup/ank-analysis/blob/master/def_contact_maps.ipynb"
    click N7 "https://github.com/bartongroup/ank-analysis/blob/master/def_structural_analysis.ipynb"

    %% Styles
    classDef ds fill:#f4a261,stroke:#d17b01;
    classDef module fill:#a8dadc,stroke:#2a9d8f;
    classDef notebook fill:#e9f5e9,stroke:#2a9d8f,stroke-dasharray: 5 5;
    classDef output fill:#f4d1b1,stroke:#e76f51;
```
