# psipred/dmpfold architecture

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

- Interactive diagram: https://gitdiagram.com/psipred/dmpfold
- Repository: https://github.com/psipred/dmpfold

## Overview

##### Project Type and Purpose
- This is a scientific computational pipeline for protein structure prediction. It leverages deep learning (with PyTorch models) together with traditional bioinformatics tools (e.g., HH-suite, FreeContact, PSIPRED, CCMpred, CNS, MODELLER) to generate protein structure models from sequence or alignment input.
- The tool is run via shell scripts (such as run_dmpfold.sh, seq2maps.csh, aln2maps.csh) and produces several intermediate files (e.g., .21c, .map) and final outputs (e.g., final_1.pdb).

##### File Structure
- Top-Level Directories:
– bin: Contains executable scripts for various tasks such as file format conversion, statistics, and contact/distance predictions. These binaries coordinate lower-level operations.
– src: Holds C source files for utility programs like aln2fasta, contact2noe, and more that are compiled into the binaries in bin.
– nn: Contains deep learning components – specifically, neural network models (with pre-trained PyTorch models) and associated scripts for predictions (distances, hydrogen bonds, torsion predictions). These files indicate that the project uses deep neural networks to iteratively predict protein structural constraints.
– cnsfiles: Contains CNS-related configuration, scripts, and patches that are used to interface with the CNS software, a component for structure refinement and modelling.
– data: Contains required data files and weight files for PSIPRED and SOLVPRED, among others, which are essential for the computational predictions.
– pfam and example: Provide sample input data and validation sets, showing use cases on protein families from Pfam.
– web: Contains scripts and a temporary file for web-based running, which may indicate a lightweight integration for web submission or batch processing.
- Presence of a Makefile (in src) and several shell scripts indicates that the build and execution are divided among compiled binaries and scripting glue to string together external tools and data sources.

##### Information from the README
- The README explains the step-by-step use of the tool starting from generating intermediate files (via seq2maps.csh or aln2maps.csh) and then running the iterative modelling process through run_dmpfold.sh.
- It highlights the dependency on various external bioinformatics and deep learning libraries (Python with PyTorch, HH-suite, FreeContact, MODELLER, etc.).
- Specific instructions related to integration with CNS, including environment settings and build steps, show that a dedicated component is provided for structural refinement.
- The README also details how to predict the TM-score which is handled via a dedicated script (predict_tmscore.sh) – indicating the existence of an evaluation module.

A. Input & Preprocessing Layer:
- Input Files: FASTA sequences or multiple sequence alignments.
- Preprocessing scripts: seq2maps.csh and aln2maps.csh, which invoke alignment tools (like HHblits) and prepare .21c and .map files.
- Supporting binaries (found in bin and src) that convert raw alignment and sequence data into formats suitable for downstream processing.

B. Deep Learning & Prediction Layer:
- These components receive processed input data and output predicted structural constraints (such as distance maps, contact maps, torsion angles).

C. Structural Assembly & Refinement Layer:

D. Evaluation & Postprocessing Layer:
- Final structure output: A node labeled “Final Model (PDB)” (e.g., final_1.pdb) indicating the final output.
- TM-score prediction module represented by the predict_tmscore.sh script (which uses a trained predictor to estimate model quality).

E. External Dependencies:
- Python (with PyTorch), C compilers (for src binaries), and required libraries (NumPy, SciPy).

- Input files → Preprocessing scripts (seq2maps.csh/aln2maps.csh) → Intermediate files (.21c, .map)
- Intermediate files → Neural network components (nn/…) → Predicted structural constraints
- Predicted constraints → CNS (via run_dmpfold.sh) → Structural assembly & refinement → Final PDB model
- Final model → TM-score evaluation (predict_tmscore.sh)

##### Important Architectural and Design Principles
- Modularity: The project divides functionality among scripts (for running alignments and converting formats), compiled C programs (for performance-critical tasks), and Python deep learning modules. This modularity should be clearly represented.
- Data Flow: Highlight the transformation stages – from raw sequence input, through a series of preprocessing steps, to the generation of constraints that feed into model construction.
- Performance Considerations: There is an emphasis on parallelization (setting cores for some scripts) and iterative improvement of models, so you might note that certain modules are optimized for performance.

##### Instructing the Principal Software Engineer
— Inputs → Preprocessing Scripts (seq2maps.csh, aln2maps.csh) → Generation of intermediate files (.21c, .map)
— Intermediate outputs are then consumed by the deep learning modules (organized into several subcomponents under nn/)
— The predictions feed into the structural refinement stage via CNS (and optionally MODELLER) to produce final models.
— Postprocessing and evaluation (using predict_tmscore.sh) validate the results.
- In-house processing modules (e.g., bin, src, nn)
- External integration and dependencies (e.g., HH-suite, CNS, MODELLER)
- Data storage areas or result files (e.g., final_1.pdb, intermediate files, pfam data)
- Iterative refinement cycles if needed to represent improvements in model accuracy.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input & Preprocessing Layer
    subgraph "Input & Preprocessing Layer"
        A1("FASTA/Alignment Input"):::input
        A2("seq2maps.csh"):::script
        A3("aln2maps.csh"):::script
        A4("Compiled Utilities\n(src/aln2fasta.c,\nsrc/alnstats.c)"):::script
    end

    %% Intermediate Data Node
    B1("Intermediate Files\n(.21c, .map)"):::data

    %% Deep Learning & Prediction Layer
    subgraph "Deep Learning & Prediction Layer"
        C1("Distance Prediction\n(nn/dmp-softmax)"):::nn
        C2("Hydrogen Bond Prediction\n(nn/dmp-hb)"):::nn
        C3("Torsion Prediction\n(nn/torpred)"):::nn
        C4("Error Prediction (EMA)\n(nn/dg_ema)"):::nn
    end

    %% Structural Assembly & Refinement Layer
    subgraph "Structural Assembly & Refinement Layer"
        D1("run_dmpfold.sh"):::script
        D2("CNS Integration\n(cnsfiles)"):::assembly
    end

    %% Evaluation & Postprocessing Layer
    subgraph "Evaluation & Postprocessing Layer"
        E1("TM-score Prediction\n(predict_tmscore.sh)"):::script
        E2("Final Model (PDB)\n(example/final_1.pdb)"):::data
    end

    %% Auxiliary & External Tools Layer
    subgraph "Auxiliary & External Components"
        F1("External Tools\n(HH-suite,FreeContact,MODELLER, etc.)"):::external
        F2("Binaries\n(bin)"):::external
        F3("Data & Weights\n(data)"):::external
        F4("Example Inputs\n(example)"):::external
    end

    %% Data Flow Connections
    A1 -->|"reads"| A2
    A1 -->|"reads"| A3
    A2 -->|"generates"| B1
    A3 -->|"generates"| B1
    A4 -->|"supports"| A2
    A4 -->|"supports"| A3
    F2 -->|"used by"| A4
    F3 -->|"provides weights to"| C1
    F1 -->|"supplies dependency to"| A2
    F1 -->|"supplies dependency to"| A3

    B1 -->|"feeds"| C1
    B1 -->|"feeds"| C2
    B1 -->|"feeds"| C3
    B1 -->|"feeds"| C4

    %% Deep Learning outputs converge
    C1 -->|"predicted distances"| D1
    C2 -->|"predicted H-bonds"| D1
    C3 -->|"predicted torsions"| D1
    C4 -->|"error estimates"| D1

    D1 -->|"orchestrates"| D2
    D2 -->|"refined structure"| E2
    E1 -->|"evaluates"| E2

    %% External connections to Deep Learning & Assembly
    F1 -->|"required by"| D2

    %% Click events for Input & Preprocessing Scripts
    click A2 "https://github.com/psipred/dmpfold/blob/master/seq2maps.csh"
    click A3 "https://github.com/psipred/dmpfold/blob/master/aln2maps.csh"
    click A4 "https://github.com/psipred/dmpfold/tree/master/src"

    %% Click events for Deep Learning Modules
    click C1 "https://github.com/psipred/dmpfold/tree/master/nn/dmp-softmax"
    click C2 "https://github.com/psipred/dmpfold/tree/master/nn/dmp-hb"
    click C3 "https://github.com/psipred/dmpfold/tree/master/nn/torpred"
    click C4 "https://github.com/psipred/dmpfold/tree/master/nn/dg_ema"

    %% Click events for Structural Assembly & Refinement
    click D1 "https://github.com/psipred/dmpfold/blob/master/run_dmpfold.sh"
    click D2 "https://github.com/psipred/dmpfold/tree/master/cnsfiles"

    %% Click events for Evaluation & Postprocessing
    click E1 "https://github.com/psipred/dmpfold/blob/master/predict_tmscore.sh"
    click E2 "https://github.com/psipred/dmpfold/blob/master/example/final_1.pdb"

    %% Click events for Auxiliary & External Components
    click F2 "https://github.com/psipred/dmpfold/tree/master/bin"
    click F3 "https://github.com/psipred/dmpfold/tree/master/data"
    click F4 "https://github.com/psipred/dmpfold/tree/master/example"

    %% Styling Definitions
    classDef input fill:#ffe0b3,stroke:#cc6600,stroke-width:2px;
    classDef script fill:#cce5ff,stroke:#0066cc,stroke-width:2px;
    classDef nn fill:#d5e8d4,stroke:#82b366,stroke-width:2px;
    classDef assembly fill:#f8cecc,stroke:#b85450,stroke-width:2px;
    classDef data fill:#e1d5e7,stroke:#9673a6,stroke-width:2px;
    classDef external fill:#fff2cc,stroke:#d6b656,stroke-width:2px;
```
