# grandrea/alphafold-analysis architecture

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

- Interactive diagram: https://gitdiagram.com/grandrea/alphafold-analysis
- Repository: https://github.com/grandrea/alphafold-analysis

## Overview

##### Main Components
- Input Data: The user’s output files from AlphaFold runs – including .fasta files (protein sequences), possibly .cif and .pdb files (protein structures), and potentially job request JSON files (for AlphaFold3).
- Processing Modules:
- Plot Generation: Scripts like “plot_AF_all.py” generate plots (PAE, pLDDT, MSA coverage) from a single run.
- Summary Creation: The “plot_all.sh”, “make_summary.sh”, and “alphafold_summary.py” collectively process a directory of runs to create summary statistics and aggregated plots.
- Confidence-Based Splitting: “alphacrop.py” processes structure files (.pdb or .cif) to split them based on the confidence threshold (using the b-factor column).
- Visualization Component: “make_structure_figure.pml” (a PyMOL script) that creates detailed structure figures based on the processed data.
- External Dependencies: Technologies like Python (with numpy, seaborn, pandas, matplotlib, biopython), optional jax (for unpacking .pkl files), and PyMOL for visualization.

##### Relationships and Data Flows
- The Input Data (AlphaFold run results) is loaded by the processing scripts.
- “plot_AF_all.py” is used to create basic visualizations (by directly processing a given directory’s data).
- For batch processing of multiple runs:
- “plot_all.sh” is used to iterate over directories, generating all necessary plots.
- “make_summary.sh” then creates summary files.
- “alphafold_summary.py” further aggregates these summaries into a final comprehensive plot.
- When high-quality structural visualization is needed, the user runs “make_structure_figure.pml” via PyMOL to generate detailed structure figures.
- “alphacrop.py” plays a role independent of the visualization pipeline – it processes structural files to “crop” them based on different confidence thresholds, outputting three separate files according to the plDDT cutoffs.

##### Architectural Patterns and Technologies
- Modular Script Design: Each script addresses a specific element of the analysis pipeline, lending itself to a “pipe and filter” or modular command-line tool design.
- Command-Line Driven Workflow: The use of shell script wrappers (“plot_all.sh”, “make_summary.sh”) indicates a sequential processing pipeline.
- Integration with External Tools: The project integrates Python-based analysis with PyMOL (for visualization) and potentially jax for specific file-unpacking tasks.
- Directory Scanning: There is an implicit architectural decision to organize and process multiple runs based on a file/directory naming convention, ensuring that each “run” is a discrete unit of processing.

##### Instructing the Principal Software Engineer
- Document how users are expected to interact with the system – for example, by running individual scripts for single directory analysis or batch processing via shell scripts.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Input
    InputData["Input Data (AlphaFold outputs)"]:::data

    %% External Dependencies
    PythonDeps["Python (numpy, seaborn, pandas, matplotlib, biopython)"]:::external
    PyMOLTool["PyMOL"]:::external

    %% Single Run Analysis
    subgraph "Single Run Analysis"
        PlotAF["plot_AF_all.py"]:::pythonScript
    end

    %% Batch Processing Pipeline
    subgraph "Batch Processing"
        BatchPlot["plot_all.sh"]:::shellScript
        Annotations["plot_all_annotations.sh"]:::shellScript
        SummaryShell["make_summary.sh"]:::shellScript
        SummaryAgg["alphafold_summary.py"]:::pythonScript
    end

    %% Confidence Filtering
    subgraph "Confidence Filtering"
        AlphaCrop["alphacrop.py"]:::pythonScript
    end

    %% Visualization
    subgraph "Visualization"
        PyMOLScript["make_structure_figure.pml"]:::pymolScript
    end

    %% Data Flow Connections
    InputData -->|"processes"| PlotAF
    InputData -->|"batch processes"| BatchPlot
    BatchPlot -->|"generates data"| Annotations
    Annotations -->|"feeds summary"| SummaryShell
    SummaryShell -->|"aggregates summaries"| SummaryAgg
    InputData -->|"structural filtering"| AlphaCrop
    AlphaCrop -->|"produces cropped files"| PyMOLScript

    %% External Dependencies Connections
    PythonDeps --- PlotAF
    PythonDeps --- SummaryAgg
    PythonDeps --- AlphaCrop
    PyMOLTool --- PyMOLScript

    %% Click Events
    click PlotAF "https://github.com/grandrea/alphafold-analysis/blob/main/plot_AF_all.py"
    click BatchPlot "https://github.com/grandrea/alphafold-analysis/blob/main/plot_all.sh"
    click Annotations "https://github.com/grandrea/alphafold-analysis/blob/main/plot_all_annotations.sh"
    click SummaryShell "https://github.com/grandrea/alphafold-analysis/blob/main/make_summary.sh"
    click SummaryAgg "https://github.com/grandrea/alphafold-analysis/blob/main/alphafold_summary.py"
    click AlphaCrop "https://github.com/grandrea/alphafold-analysis/blob/main/alphacrop.py"
    click PyMOLScript "https://github.com/grandrea/alphafold-analysis/blob/main/make_structure_figure.pml"

    %% Style Definitions
    classDef pythonScript fill:#f9e79f,stroke:#e67e22,stroke-width:2px;
    classDef shellScript fill:#aed6f1,stroke:#3498db,stroke-width:2px;
    classDef pymolScript fill:#d2b4de,stroke:#8e44ad,stroke-width:2px;
    classDef external fill:#a9dfbf,stroke:#27ae60,stroke-width:2px;
    classDef data fill:#f5b7b1,stroke:#c0392b,stroke-width:2px;
```
