# regeneron-mpds/propermab architecture

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

- Interactive diagram: https://gitdiagram.com/regeneron-mpds/propermab
- Repository: https://github.com/regeneron-mpds/propermab

## Overview

##### Project type and purpose
- This is an open‑source Python package (library + CLI scripts) named **propermab**.
- It provides an integrative in silico pipeline to calculate and predict molecular features of monoclonal antibodies (mAbs), combining sequence‑ and structure‑based featurization, external tools (APBS, NanoShaper, HMMER, PDB2PQR, ABodyBuilder2), and a machine‑learning “model_trainer” component.

##### File structure
- Top‑level items:
- **default_config.json** – JSON template for external tool paths
- **conda_env.yml** – Python & dependency specification
- **propermab/** – main Python package subdivided into:
– **defaults.py** – system configuration loader
– **features/** – sequence & structural feature calculators
– **io/** – I/O code for geometry & structure files
– **models/** – ML model training & persistence
– **plot/** – plotting utilities
– **sequence/** – sequence numbering & utilities
– **structure/** – structure pipelines (MD, SASA, prediction)
– **utils/** – wrappers around APBS, NanoShaper, transforms
- **scripts/** – CLI entry points:
– `pdb_to_xyzr.py`, `create_surface_voxels.py`, etc.
- **tests/** – unit tests and fixture data

##### README for additional insights
- Highlights two API entry points:
- `calculate_features_from_pdb(pdb_path)`
- `get_all_mol_features(heavy_seq, light_seq, ...)` calling ABodyBuilder2
- Emphasizes external dependencies: APBS, NanoShaper, hmmer, pdb2pqr, multivalue.

1. **User/API Layer**
– Python API / CLI scripts (under `scripts/`)
2. **Configuration**
– `defaults.system_config` reading `default_config.json` and environment variables
3. **Sequence Pipeline** (`propermab/sequence` + `features/seq_*`)
– HMMER → sequence embedding & featurization
4. **Structure Pipeline** (`propermab/structure`, `features/struct_*`)
– ABodyBuilder2 → PDB file → `io/struct_io` → NanoShaper & APBS calls → geometry & electrostatics → structural featurizers
5. **Feature Aggregation** (`features/feature_utils`)
6. **Model Trainer** (`models/model_trainer`)
7. **Visualization** (`plot/protein.py`)
8. **External Tools** (APBS, NanoShaper, hmmer, pdb2pqr, multivalue, ABodyBuilder2)

b. Relationships & data flow
- **Sequence Pipeline** and **Structure Pipeline** both feed into **Feature Aggregation**.
- Aggregated features go into **Model Trainer** or returned to user.
- **Visualization** can subscribe to outputs of aggregation or modeling.

c. Architectural patterns / design principles
- Modular layering: API / config / pipelines / utilities / ML
- Single‑responsibility per module folder
- Clear separation of sequence vs. structure processing
- Pluggable external tool wrappers in `utils/`

d. Key technologies, frameworks, libraries
- Python 3.x, conda environment
- Third‑party tools: APBS v3, NanoShaper, HMMER, pdb2pqr, multivalue, ABodyBuilder2
- Python libs: NumPy, SciPy, Biopython (implicit), machine‑learning framework (scikit‑learn or PyTorch/TensorFlow indicated by conda_env.yml)

- Blue for internal Python modules
- Green for external tools/binaries
- Orange for data artifacts (PDB, XYZR, feature vectors)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User/API Layer"
        API1["pdb_to_xyzr.py"]:::internal
        API2["create_surface_voxels.py"]:::internal
        API3["generate_feature_tensors.py"]:::internal
        API4["seq_to_voxel_grid.py"]:::internal
    end

    subgraph "Configuration"
        CFG1["default_config.json"]:::data
        CFG2["defaults.py"]:::internal
    end

    subgraph "Sequence Pipeline"
        NUM["numbering.py"]:::internal
        SU["seq_utils.py"]:::internal
        EMB["seq_embedder.py"]:::internal
        SFSEQ["seq_featurizer.py"]:::internal
    end

    subgraph "Structure Pipeline"
        PIPE["pipelines.py"]:::internal
        PRED["struct_predictor.py"]:::internal
        MD["md.py"]:::internal
        SASA["sasa.py"]:::internal
        SCM["scm.py"]:::internal
        SUTIL["utils.py"]:::internal
        IO1["struct_io.py"]:::internal
        IO2["geometry_io.py"]:::internal
    end

    subgraph "Feature Aggregation"
        FU["feature_utils.py"]:::internal
        SFS["struct_featurizer.py"]:::internal
        GRID["grid.py"]:::internal
        HYDRO["hydrophobicity.py"]:::internal
        SPAT["spatial_stats.py"]:::internal
        SURF["surface.py"]:::internal
    end

    MT["model_trainer.py"]:::internal
    VIS["protein.py"]:::internal

    subgraph "External Tool Wrappers"
        W1["apbs.py"]:::external
        W2["nanoshaper.py"]:::external
        W3["transforms.py"]:::external
    end

    subgraph "External Binaries"
        EB1[(APBS)]:::external
        EB2[(NanoShaper)]:::external
        EB3[(HMMER)]:::external
        EB4[(pdb2pqr)]:::external
        EB5[(multivalue)]:::external
        EB6[(ABodyBuilder2)]:::external
    end

    API1 --> CFG2
    API2 --> CFG2
    API3 --> CFG2
    API4 --> CFG2

    CFG2 --> NUM
    CFG2 --> PIPE

    NUM --> SU --> EMB --> SFSEQ --> FU
    PIPE --> IO1 --> IO2 --> PRED --> MD --> SASA --> SCM --> SFS --> FU

    SFSEQ --> W3 --> EB3
    IO2 --> W1 --> EB1
    IO2 --> W2 --> EB2
    PRED --> EB6

    FU --> MT
    FU --> VIS
    MT --> VIS

    click API1 "https://github.com/regeneron-mpds/propermab/blob/main/scripts/pdb_to_xyzr.py"
    click API2 "https://github.com/regeneron-mpds/propermab/blob/main/scripts/create_surface_voxels.py"
    click API3 "https://github.com/regeneron-mpds/propermab/blob/main/scripts/generate_feature_tensors.py"
    click API4 "https://github.com/regeneron-mpds/propermab/blob/main/scripts/seq_to_voxel_grid.py"
    click CFG1 "https://github.com/regeneron-mpds/propermab/blob/main/default_config.json"
    click CFG2 "https://github.com/regeneron-mpds/propermab/blob/main/propermab/defaults.py"
    click NUM "https://github.com/regeneron-mpds/propermab/blob/main/propermab/sequence/numbering.py"
    click SU "https://github.com/regeneron-mpds/propermab/blob/main/propermab/sequence/seq_utils.py"
    click EMB "https://github.com/regeneron-mpds/propermab/blob/main/propermab/features/seq_embedder.py"
    click SFSEQ "https://github.com/regeneron-mpds/propermab/blob/main/propermab/features/seq_featurizer.py"
    click PIPE "https://github.com/regeneron-mpds/propermab/blob/main/propermab/structure/pipelines.py"
    click PRED "https://github.com/regeneron-mpds/propermab/blob/main/propermab/structure/struct_predictor.py"
    click MD "https://github.com/regeneron-mpds/propermab/blob/main/propermab/structure/md.py"
    click SASA "https://github.com/regeneron-mpds/propermab/blob/main/propermab/structure/sasa.py"
    click SCM "https://github.com/regeneron-mpds/propermab/blob/main/propermab/structure/scm.py"
    click SUTIL "https://github.com/regeneron-mpds/propermab/blob/main/propermab/structure/utils.py"
    click IO1 "https://github.com/regeneron-mpds/propermab/blob/main/propermab/io/struct_io.py"
    click IO2 "https://github.com/regeneron-mpds/propermab/blob/main/propermab/io/geometry_io.py"
    click FU "https://github.com/regeneron-mpds/propermab/blob/main/propermab/features/feature_utils.py"
    click SFS "https://github.com/regeneron-mpds/propermab/blob/main/propermab/features/struct_featurizer.py"
    click GRID "https://github.com/regeneron-mpds/propermab/blob/main/propermab/features/grid.py"
    click HYDRO "https://github.com/regeneron-mpds/propermab/blob/main/propermab/features/hydrophobicity.py"
    click SPAT "https://github.com/regeneron-mpds/propermab/blob/main/propermab/features/spatial_stats.py"
    click SURF "https://github.com/regeneron-mpds/propermab/blob/main/propermab/features/surface.py"
    click MT "https://github.com/regeneron-mpds/propermab/blob/main/propermab/models/model_trainer.py"
    click VIS "https://github.com/regeneron-mpds/propermab/blob/main/propermab/plot/protein.py"
    click W1 "https://github.com/regeneron-mpds/propermab/blob/main/propermab/utils/apbs.py"
    click W2 "https://github.com/regeneron-mpds/propermab/blob/main/propermab/utils/nanoshaper.py"
    click W3 "https://github.com/regeneron-mpds/propermab/blob/main/propermab/utils/transforms.py"

    classDef internal fill:#AED6F1,stroke:#1F618D,color:#1D2D44
    classDef external fill:#A9DFBF,stroke:#145A32,color:#1D2D44
    classDef data fill:#F9E79F,stroke:#B9770E,color:#1D2D44
```
