# bartongroup/prointvar architecture

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

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

## Overview

##### Project type and purpose
- ProIntVar is a Python library and CLI tool for working with protein structures (mmCIF/PDB), secondary-structure (DSSP), cross-mapping (SIFTS), interface contacts (Arpeggio, HBPLUS, Reduce), and genetic variants (UniProt, Ensembl), all unified via Pandas DataFrames.
- It is not a web or full-stack app but an analysis/processing toolkit with a command-line interface and modular components.

##### File structure
- Top-level:
- cli/ – CLI entrypoint (`main.py`)
- prointvar/ – core modules (`pdbx`, `dssp`, `sifts`, `fetchers`, `merger`, etc.)
- tests/ – unit tests and test data
- Config: `prointvar/config.py` and `config_template.ini` define folder layout (db_pdbx, db_dssp, etc.).
- Setup: `setup.py`, `requirements.txt`.
- No server or database; storage is file-system-based under configured directories.

##### README for additional insights
- Core classes each produce/consume Pandas DataFrames.
- `TableMerger` merges multiple DataFrames into one unified table.
- CLI commands orchestrate downloads, runs of external binaries (DSSP, HBPLUS, Reduce), and invoke readers/parsers.

##### Main components and interactions
a. Components:
- CLI Layer (cli/main.py)
- Configuration Manager (`prointvar/config.py`)
- Core Data Processors:
- PDBXreader / PDBXwriter
- DSSPrunner / DSSPreader
- SIFTSreader
- ArpeggioParser, HBPLUSParser, ReduceRunner
- Fetchers (Proteins API, PDBe, Ensembl)
- TableMerger
- Utility modules (`utils.py`, `library.py`, `variants.py`, `rmsd.py`, `stamp.py`)
- External Tools / Services:
- DSSP, HBPLUS, Reduce, Arpeggio binaries
- UniProt, PDBe REST API, Ensembl REST API
- File System (configured folders: db_pdbx, db_dssp, db_sifts, db_contacts, db_tmp)

b. Data flow:
1. CLI parses user args → loads config
2. Fetchers download raw files to folders
3. Runners (DSSP, Reduce, HBPLUS, Arpeggio) generate analysis files
4. Readers/parsers convert files into Pandas DataFrames
5. TableMerger merges DataFrames → final DataFrame
6. Output: write DataFrame to disk or pipe to user script

c. Architectural patterns:
- Modular single-responsibility classes
- Pipeline pattern: successive transformations of data files → DataFrames
- Plugin-like extensibility: new fetchers or parsers can be dropped into `prointvar/`

d. Key technologies:
- Python 3.5+, Pandas
- Third-party binaries (DSSP, HBPLUS, Reduce)
- REST APIs for external data
- CLI via `argparse` or similar

## Diagram (Mermaid)

```mermaid
flowchart TD
  classDef coreModule fill:#D0E8FF,stroke:#0366D6,stroke-width:1px
  classDef external fill:#E8FFD0,stroke:#228B22,stroke-width:1px
  classDef storage fill:#FFF5D0,stroke:#DAA520,stroke-width:1px
  classDef cli fill:#F0D0FF,stroke:#800080,stroke-width:1px

  CLI["CLI (cli/main.py)"]:::cli
  Config["Config Manager (config.py)"]:::coreModule
  ConfigTemplate["Config Template (config_template.ini)"]:::storage
  Fetchers["Fetchers (fetchers.py)"]:::coreModule

  UniProtAPI["UniProt & Ensembl REST API"]:::external
  PDBeAPI["PDBe REST API"]:::external

  FS_pdbx["Folder: db_pdbx"]:::storage
  FS_dssp["Folder: db_dssp"]:::storage
  FS_sifts["Folder: db_sifts"]:::storage
  FS_contacts["Folder: db_contacts"]:::storage
  FS_tmp["Folder: db_tmp"]:::storage

  DSSPRunner["DSSPrunner / Reader (dssp.py)"]:::coreModule
  DSSPBinary["DSSP Binary"]:::external
  HBPLUSRunner["HBPLUS Runner / Parser (hbplus.py)"]:::coreModule
  HBPLUSBinary["HBPLUS Binary"]:::external
  ReduceRunner["Reduce Runner / Parser (reduce.py)"]:::coreModule
  ReduceBinary["Reduce Binary"]:::external
  ArpeggioParser["Arpeggio Parser (arpeggio.py)"]:::coreModule
  ArpeggioService["Arpeggio Web/API"]:::external

  PDBXModule["PDBXreader / Writer (pdbx.py)"]:::coreModule
  SIFTSModule["SIFTSreader (sifts.py)"]:::coreModule

  Merger["TableMerger (merger.py)"]:::coreModule

  subgraph "Utility Modules"
    utils["Utils (utils.py)"]:::coreModule
    library["Library (library.py)"]:::coreModule
    variants["Variants (variants.py)"]:::coreModule
    rmsd["RMSD (rmsd.py)"]:::coreModule
    stamp["STAMP (stamp.py)"]:::coreModule
    msas["MSAs (msas.py)"]:::coreModule
  end

  CLI -->|loads| Config
  CLI -->|loads| ConfigTemplate
  CLI -->|invokes| Fetchers
  Fetchers -->|writes files| FS_pdbx
  Fetchers -->|writes files| FS_sifts
  Fetchers -->|calls| UniProtAPI
  Fetchers -->|calls| PDBeAPI

  CLI -->|runs| DSSPRunner
  DSSPRunner -->|executes| DSSPBinary
  DSSPRunner -->|writes .dssp| FS_dssp

  CLI -->|runs| HBPLUSRunner
  HBPLUSRunner -->|executes| HBPLUSBinary
  HBPLUSRunner -->|writes contacts| FS_contacts
  HBPLUSRunner -->|parses| FS_pdbx

  CLI -->|runs| ReduceRunner
  ReduceRunner -->|executes| ReduceBinary
  ReduceRunner -->|writes| FS_pdbx

  CLI -->|runs| ArpeggioParser
  ArpeggioParser -->|writes| FS_contacts
  ArpeggioParser -->|calls| ArpeggioService

  PDBXModule -->|reads| FS_pdbx
  PDBXModule -->|outputs DF| Merger
  DSSPRunner -->|reads .dssp| Merger
  SIFTSModule -->|reads .xml| FS_sifts
  SIFTSModule -->|outputs DF| Merger
  ArpeggioParser -->|outputs DF| Merger
  HBPLUSRunner -->|outputs DF| Merger
  ReduceRunner -->|outputs DF| Merger

  Merger -->|merged DF| utils
  utils -->|final output| FS_tmp

  class CLI cli
  class Config,Fetchers,PDBXModule,DSSPRunner,SIFTSModule,ArpeggioParser,HBPLUSRunner,ReduceRunner,Merger coreModule
  class DSSPBinary,HBPLUSBinary,ReduceBinary,ArpeggioService,UniProtAPI,PDBeAPI external
  class FS_pdbx,FS_dssp,FS_sifts,FS_contacts,FS_tmp,ConfigTemplate storage

  click CLI "https://github.com/bartongroup/prointvar/blob/master/cli/main.py"
  click Config "https://github.com/bartongroup/prointvar/blob/master/prointvar/config.py"
  click ConfigTemplate "https://github.com/bartongroup/prointvar/blob/master/prointvar/config_template.ini"
  click Fetchers "https://github.com/bartongroup/prointvar/blob/master/prointvar/fetchers.py"
  click PDBXModule "https://github.com/bartongroup/prointvar/blob/master/prointvar/pdbx.py"
  click DSSPRunner "https://github.com/bartongroup/prointvar/blob/master/prointvar/dssp.py"
  click SIFTSModule "https://github.com/bartongroup/prointvar/blob/master/prointvar/sifts.py"
  click ArpeggioParser "https://github.com/bartongroup/prointvar/blob/master/prointvar/arpeggio.py"
  click HBPLUSRunner "https://github.com/bartongroup/prointvar/blob/master/prointvar/hbplus.py"
  click ReduceRunner "https://github.com/bartongroup/prointvar/blob/master/prointvar/reduce.py"
  click Merger "https://github.com/bartongroup/prointvar/blob/master/prointvar/merger.py"
  click utils "https://github.com/bartongroup/prointvar/blob/master/prointvar/utils.py"
  click library "https://github.com/bartongroup/prointvar/blob/master/prointvar/library.py"
  click variants "https://github.com/bartongroup/prointvar/blob/master/prointvar/variants.py"
  click rmsd "https://github.com/bartongroup/prointvar/blob/master/prointvar/rmsd.py"
  click stamp "https://github.com/bartongroup/prointvar/blob/master/prointvar/stamp.py"
  click msas "https://github.com/bartongroup/prointvar/blob/master/prointvar/msas.py"
```
