# genentech/gneprop architecture

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

- Interactive diagram: https://gitdiagram.com/genentech/gneprop
- Repository: https://github.com/genentech/gneprop

## Overview

GNEprop is organized as a research codebase with two main executable pipelines and a supporting library of chemistry, graph-learning, and analysis utilities.

##### 1) Top-level execution entrypoints

The repository is centered around two scripts:

- `clr.py` — self-supervised contrastive pretraining
- `gneprop_pyg.py` — supervised fine-tuning / evaluation for antibacterial activity prediction

These scripts are the primary orchestration layer: they parse configuration, build datasets, create graph models, run training loops, save checkpoints, and report metrics. The README indicates that they support multi-GPU training, scaffold or random splits, pretrained weight loading, and a range of training modes such as adversarial augmentation and meta-learning.

##### 2) Core model and training subsystem

The main learning stack appears to be built around PyTorch and PyTorch Geometric:

- `models.py` — model definitions and likely the GNN encoder/head composition
- `gneprop_pyg.py` — supervised training logic around those models
- `clr.py` — contrastive self-supervised objective and augmentation-driven pretraining
- `options.py` — command-line argument definitions and experiment configuration

Architecturally, the model is described in the README as a graph neural network encoder based on Graph Isomorphism Networks, with optional extensions such as:

- Jumping Knowledge / multi-scale representations
- attention-based or multiset readout layers
- adversarial perturbation training via FLAG
- meta-learning-based fine-tuning
- integrated gradients support for explainability

So the “model” boundary is not just a single encoder; it is a configurable GNN backbone plus task-specific heads and optional training-time wrappers.

##### 3) Molecular representation and featurization layer

A substantial portion of the repo is dedicated to converting molecules into graph inputs and auxiliary descriptors:

- `data.py` — dataset loading, splitting, and likely PyG dataset construction
- `chemprop_featurizer.py` — molecule featurization compatible with Chemprop-style atom/bond features
- `gneprop/featurization.py` — feature construction utilities
- `gneprop/chem_utils.py` — chemistry-specific helpers and filters
- `gneprop/chemprop/` and `gneprop/chemprop/features.py` — vendored or adapted Chemprop feature logic
- `gneprop_pyg.py` consumes these representations for training

The data flow is roughly:

CSV / spreadsheet molecule records -> SMILES parsing and chemistry utilities -> graph or feature tensors -> model input objects

This layer is a key architectural boundary because the repository supports both graph-based representations and additional molecular descriptors, and the README explicitly mentions optional RDKit molecular features.

##### 4) Graph augmentation and self-supervised learning subsystem

The repository includes a dedicated augmentation layer for contrastive and robust training:

- `gneprop/augmentations.py` — structural and molecular augmentations
- `clr.py` — uses these augmentations to construct contrastive views

This subsystem creates multiple “views” of the same molecule or graph for self-supervised training, and it can also be reused during supervised learning. The README highlights complex multi-augmentation combinations, adversarial augmentation, and dataset-dependent augmentation choices.

In diagram terms, this is a branching preprocessing path:
one original molecular graph can be transformed into one or more augmented views before being passed through the encoder.

##### 5) Out-of-distribution, scaffold, and evaluation utilities

The repository is clearly designed with OOD generalization in mind. Relevant modules include:

- `gneprop/scaffold.py` — scaffold-based splitting and chemical scaffold logic
- `gneprop/ood.py` — out-of-distribution / novel mechanism-of-action analysis
- `gneprop/utils.py` — assorted utilities, including molecular similarity calculations
- `gneprop/custom_objects.py` — likely custom losses, metrics, or training hooks
- `gneprop/plot_utils.py` and top-level `Notebooks/plot_utils.py` — plotting helpers

This subsystem is important because the repo is not just doing standard train/test splits. It supports:
- scaffold splits
- scaffold-cluster predetermined splits
- cluster or distance-based novelty analysis
- similarity-based comparisons between compound sets

##### 6) Explainability and attribution path

Explainability is treated as a first-class downstream workflow:

- `gneprop/explainability.py` — integrated gradients / graph-level attribution
- README notes that training must include `--ig_baseline_ratio` for compatibility

The explainability path depends on a model trained with the right baseline configuration. In practice, the architecture is:

trained checkpoint + input graph + baseline specification -> per-node / per-feature attributions

This is a downstream analysis subsystem, separate from core prediction training but sharing the same model and featurization stack.

##### 7) Visualization and analysis artifacts

The repo includes notebooks and plotting utilities for post hoc analysis:

- `Notebooks/plot_enamine_space_umap_notebook.ipynb`
- `Notebooks/plot_moa_umap_notebook.ipynb`
- `gneprop/plot_utils.py`
- `gneprop/image_utils.py`

These are not part of the training path, but they consume embeddings, similarity metrics, or prediction outputs to produce figures and UMAP visualizations. This suggests a workflow where model embeddings and predictions are exported for external analysis rather than kept entirely inside training scripts.

##### 8) Packaging, configuration, and environment boundaries

Supporting infrastructure includes:

- `environment.yml` — conda environment definition
- `LICENSE`
- `additional_pages/checkpoints.md` — checkpoint references and availability notes
- `figures/` — documentation figures
- `Notebooks/.gitkeep` — notebook directory placeholder

The repository also vendors or namespaces chemistry-related helpers under `gneprop/chemprop`, which implies a local dependency boundary around feature generation rather than relying only on an external package at runtime.

##### 9) Data and pretrained model boundaries

The README makes it clear that the repo expects external data and pretrained artifacts:

- Public and manuscript datasets in `support_data/`
- Self-supervised pretraining data in a large ZINC15-derived CSV/TGZ file
- Pretrained checkpoints available separately
- Predetermined scaffold-cluster split metadata in a pickle file

So the architecture has a strong separation between:
- code in this repo
- external datasets
- pretrained weights / checkpoints
- analysis outputs and plots

##### 10) End-to-end data flow summary

A typical supervised workflow is:

1. Molecule records are loaded from CSV or spreadsheet inputs.
2. Chemistry utilities and featurizers convert molecules to graph/descriptor representations.
3. Optional scaffold or cluster split logic partitions the data.
4. The graph encoder predicts antibacterial activity.
5. Optional pretrained weights are loaded before fine-tuning.
6. Optional adversarial augmentation, meta-learning, and molecular features are applied.
7. Metrics, checkpoints, and logs are produced.
8. Downstream modules consume embeddings/predictions for explainability, OOD analysis, similarity, or UMAP visualization.

A typical self-supervised workflow is similar, but instead of labels it uses paired augmented views of the same molecule to train the encoder with a contrastive objective.

##### 11) Suggested architecture diagram boundaries

If you were drawing the system, the main boxes would be:

- **Experiment entrypoints**: `clr.py`, `gneprop_pyg.py`
- **Modeling core**: `models.py`, `gneprop/`
- **Featurization and chemistry**: `data.py`, `chemprop_featurizer.py`, `gneprop/chem_utils.py`, `gneprop/featurization.py`
- **Augmentation and SSL**: `gneprop/augmentations.py`
- **OOD / explainability / analysis**: `gneprop/ood.py`, `gneprop/explainability.py`, plotting notebooks/utilities
- **Artifacts and external inputs**: datasets, checkpoints, conda environment

The dominant architectural theme is a graph-learning pipeline for molecules, with separate but connected paths for pretraining, supervised prediction, and downstream interpretation.

Main entry points: [`gneprop_pyg.py`](https://github.com/genentech/gneprop/blob/HEAD/gneprop_pyg.py) (gneprop_pyg.py), [`clr.py`](https://github.com/genentech/gneprop/blob/HEAD/clr.py) (clr.py), [`data.py`](https://github.com/genentech/gneprop/blob/HEAD/data.py) (data.py), [`models.py`](https://github.com/genentech/gneprop/blob/HEAD/models.py) (models.py)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "Entrypoints"
  clr["clr.py<br/>ssl pretrain<br/>[clr.py]"]
  gneprop_pyg["gneprop_pyg.py<br/>supervised train<br/>[gneprop_pyg.py]"]
end

subgraph "Core model"
  models["models.py<br/>gnn models<br/>[models.py]"]
  options["options.py<br/>config<br/>[options.py]"]
  custom_objects["custom_objects.py<br/>hooks<br/>[custom_objects.py]"]
end

subgraph "Molecular input"
  data["data.py<br/>dataset loading<br/>[data.py]"]
  chemprop_featurizer["featurizer<br/>chemprop features"]
  featurization["featurization.py<br/>feature utils<br/>[featurization.py]"]
  chem_utils["chem_utils.py<br/>chemistry utils<br/>[chem_utils.py]"]
  chemprop_features["features.py<br/>vendored features<br/>[features.py]"]
end

subgraph "SSL and augmentation"
  augmentations["augmentations.py<br/>graph augments<br/>[augmentations.py]"]
end

subgraph "Analysis"
  scaffold["scaffold.py<br/>split logic<br/>[scaffold.py]"]
  ood["ood.py<br/>ood analysis<br/>[ood.py]"]
  explainability["explainability.py<br/>attribution<br/>[explainability.py]"]
  plot_utils["plot utils<br/>visualization<br/>[plot_utils.py]"]
  image_utils["image_utils.py<br/>rendering<br/>[image_utils.py]"]
  utils["utils.py<br/>general utils<br/>[utils.py]"]
  notebooks["Notebooks"]
end

clr -->|"parse cfg"| options
gneprop_pyg -->|"parse cfg"| options
clr -->|"load data"| data
gneprop_pyg -->|"load data"| data
data -->|"parse molecules"| chem_utils
data -->|"featurize"| featurization
data -->|"atom/bond feats"| chemprop_featurizer
featurization -->|"feature basis"| chemprop_features
clr -->|"views"| augmentations
gneprop_pyg -->|"optional aug"| augmentations
clr -->|"encode"| models
gneprop_pyg -->|"predict"| models
models -->|"losses/hooks"| custom_objects
gneprop_pyg -->|"split data"| scaffold
gneprop_pyg -->|"analyze"| ood
gneprop_pyg -->|"attribution"| explainability
explainability -->|"reuse model"| models
ood -->|"similarity"| utils
plot_utils -->|"plotting"| notebooks
image_utils -->|"rendering"| plot_utils
gneprop_pyg -->|"report"| plot_utils
clr -->|"report"| plot_utils

click clr "https://github.com/genentech/gneprop/blob/main/clr.py"
click gneprop_pyg "https://github.com/genentech/gneprop/blob/main/gneprop_pyg.py"
click models "https://github.com/genentech/gneprop/blob/main/models.py"
click options "https://github.com/genentech/gneprop/blob/main/gneprop/options.py"
click data "https://github.com/genentech/gneprop/blob/main/data.py"
click chemprop_featurizer "https://github.com/genentech/gneprop/blob/main/chemprop_featurizer.py"
click featurization "https://github.com/genentech/gneprop/blob/main/gneprop/featurization.py"
click chem_utils "https://github.com/genentech/gneprop/blob/main/gneprop/chem_utils.py"
click chemprop_features "https://github.com/genentech/gneprop/blob/main/gneprop/chemprop/features.py"
click augmentations "https://github.com/genentech/gneprop/blob/main/gneprop/augmentations.py"
click scaffold "https://github.com/genentech/gneprop/blob/main/gneprop/scaffold.py"
click ood "https://github.com/genentech/gneprop/blob/main/gneprop/ood.py"
click explainability "https://github.com/genentech/gneprop/blob/main/gneprop/explainability.py"
click plot_utils "https://github.com/genentech/gneprop/blob/main/gneprop/plot_utils.py"
click image_utils "https://github.com/genentech/gneprop/blob/main/gneprop/image_utils.py"
click utils "https://github.com/genentech/gneprop/blob/main/gneprop/utils.py"
click custom_objects "https://github.com/genentech/gneprop/blob/main/gneprop/custom_objects.py"
click notebooks "https://github.com/genentech/gneprop/blob/main/Notebooks/plot_enamine_space_umap_notebook.ipynb"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class clr,gneprop_pyg toneBlue
class models,options,custom_objects toneAmber
class data,chemprop_featurizer,featurization,chem_utils,chemprop_features toneMint
class augmentations toneRose
class scaffold,ood,explainability,plot_utils,image_utils,utils,notebooks toneIndigo
```

## Components

### Entrypoints

Primary training and evaluation scripts.

- [clr.py](https://github.com/genentech/gneprop/blob/HEAD/clr.py): ssl pretrain · Self-supervised contrastive pretraining pipeline. · `clr.py`
- [gneprop_pyg.py](https://github.com/genentech/gneprop/blob/HEAD/gneprop_pyg.py): supervised train · Supervised fine-tuning and evaluation pipeline for antibacterial prediction. · `gneprop_pyg.py`

### Core model

GNN encoder, task heads, and training configuration.

- [models.py](https://github.com/genentech/gneprop/blob/HEAD/models.py): gnn models · Graph encoder and prediction head definitions. · `models.py`
- [options.py](https://github.com/genentech/gneprop/blob/HEAD/gneprop/options.py): config · Command-line arguments and experiment settings. · `gneprop/options.py`
- [custom_objects.py](https://github.com/genentech/gneprop/blob/HEAD/gneprop/custom_objects.py): hooks · Custom losses, metrics, or training-time helper objects. · `gneprop/custom_objects.py`

### Molecular input

Data loading, chemistry helpers, and featurization into graph inputs.

- [data.py](https://github.com/genentech/gneprop/blob/HEAD/data.py): dataset loading · Dataset construction, splitting, and loader setup. · `data.py`
- [featurizer](https://github.com/genentech/gneprop/blob/HEAD/chemprop_featurizer.py): chemprop features · Chemprop-style atom and bond feature generation. · `chemprop_featurizer.py`
- [featurization.py](https://github.com/genentech/gneprop/blob/HEAD/gneprop/featurization.py): feature utils · Feature construction utilities for molecular graphs. · `gneprop/featurization.py`
- [chem_utils.py](https://github.com/genentech/gneprop/blob/HEAD/gneprop/chem_utils.py): chemistry utils · SMILES and chemistry-specific helper functions. · `gneprop/chem_utils.py`
- [features.py](https://github.com/genentech/gneprop/blob/HEAD/gneprop/chemprop/features.py): vendored features · Vendored or adapted Chemprop feature logic. · `gneprop/chemprop/features.py`

### SSL and augmentation

Contrastive pretraining and view generation.

- [augmentations.py](https://github.com/genentech/gneprop/blob/HEAD/gneprop/augmentations.py): graph augments · Molecular and structural augmentations for multiple views. · `gneprop/augmentations.py`

### Analysis

OOD, explainability, plotting, and notebook-driven post hoc analysis.

- [scaffold.py](https://github.com/genentech/gneprop/blob/HEAD/gneprop/scaffold.py): split logic · Scaffold-based splitting and scaffold utilities. · `gneprop/scaffold.py`
- [ood.py](https://github.com/genentech/gneprop/blob/HEAD/gneprop/ood.py): ood analysis · Novelty and out-of-distribution analysis utilities. · `gneprop/ood.py`
- [explainability.py](https://github.com/genentech/gneprop/blob/HEAD/gneprop/explainability.py): attribution · Integrated gradients and graph attribution workflows. · `gneprop/explainability.py`
- [plot utils](https://github.com/genentech/gneprop/blob/HEAD/gneprop/plot_utils.py): visualization · Shared plotting helpers for figures and notebooks. · `gneprop/plot_utils.py`
- [image_utils.py](https://github.com/genentech/gneprop/blob/HEAD/gneprop/image_utils.py): rendering · Image and visualization helpers. · `gneprop/image_utils.py`
- [utils.py](https://github.com/genentech/gneprop/blob/HEAD/gneprop/utils.py): general utils · General utilities, including similarity and helper routines. · `gneprop/utils.py`
- [Notebooks](https://github.com/genentech/gneprop/blob/HEAD/Notebooks/plot_enamine_space_umap_notebook.ipynb): analysis notebooks · Post hoc UMAP and visualization notebooks. · `Notebooks/plot_enamine_space_umap_notebook.ipynb`

## Connections

- clr.py → options.py: parse cfg · Loads experiment configuration and flags.
- gneprop_pyg.py → options.py: parse cfg · Loads experiment configuration and flags.
- clr.py → data.py: load data · Builds molecular datasets and loaders.
- gneprop_pyg.py → data.py: load data · Builds molecular datasets and loaders.
- data.py → chem_utils.py: parse molecules · Converts records into chemistry-aware representations.
- data.py → featurization.py: featurize · Constructs graph and descriptor inputs.
- data.py → featurizer: atom/bond feats · Generates Chemprop-style molecular features.
- featurization.py → features.py: feature basis · Uses low-level Chemprop feature definitions.
- clr.py → augmentations.py: views · Creates paired augmented molecular views for contrastive learning.
- gneprop_pyg.py → augmentations.py: optional aug · Applies augmentation-driven robustness training when enabled.
- clr.py → models.py: encode · Runs the graph encoder for self-supervised objectives.
- gneprop_pyg.py → models.py: predict · Trains and evaluates the supervised graph model.
- models.py → custom_objects.py: losses/hooks · Uses custom training components and metrics.
- gneprop_pyg.py → scaffold.py: split data · Supports scaffold-based partitioning and evaluation.
- gneprop_pyg.py → ood.py: analyze · Supports novelty and OOD evaluation workflows.
- gneprop_pyg.py → explainability.py: attribution · Exports trained models for integrated gradients analysis.
- explainability.py → models.py: reuse model · Consumes trained checkpoints and model structure.
- ood.py → utils.py: similarity · Relies on helper routines for compound comparisons.
- plot utils → Notebooks: plotting · Shared visualization code used by analysis notebooks.
- image_utils.py → plot utils: rendering · Supports figure and image generation.
- gneprop_pyg.py → plot utils: report · Produces plots and evaluation summaries.
- clr.py → plot utils: report · Produces plots and training summaries.
