How genentech/gneprop works
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 gneprop_pyg.py · clr.py clr.py · data.py data.py · models.py models.py
Components 18
Entrypoints
Primary training and evaluation scripts.
- clr.py · Self-supervised contrastive pretraining pipeline.
clr.py - gneprop_pyg.py · Supervised fine-tuning and evaluation pipeline for antibacterial prediction.
gneprop_pyg.py
Core model
GNN encoder, task heads, and training configuration.
- models.py · Graph encoder and prediction head definitions.
models.py - options.py · Command-line arguments and experiment settings.
gneprop/options.py - custom_objects.py · 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 · Dataset construction, splitting, and loader setup.
data.py - featurizer · Chemprop-style atom and bond feature generation.
chemprop_featurizer.py - featurization.py · Feature construction utilities for molecular graphs.
gneprop/featurization.py - chem_utils.py · SMILES and chemistry-specific helper functions.
gneprop/chem_utils.py - features.py · Vendored or adapted Chemprop feature logic.
gneprop/chemprop/features.py
SSL and augmentation
Contrastive pretraining and view generation.
- augmentations.py · Molecular and structural augmentations for multiple views.
gneprop/augmentations.py
Analysis
OOD, explainability, plotting, and notebook-driven post hoc analysis.
- scaffold.py · Scaffold-based splitting and scaffold utilities.
gneprop/scaffold.py - ood.py · Novelty and out-of-distribution analysis utilities.
gneprop/ood.py - explainability.py · Integrated gradients and graph attribution workflows.
gneprop/explainability.py - plot utils · Shared plotting helpers for figures and notebooks.
gneprop/plot_utils.py - image_utils.py · Image and visualization helpers.
gneprop/image_utils.py - utils.py · General utilities, including similarity and helper routines.
gneprop/utils.py - Notebooks · Post hoc UMAP and visualization notebooks.
Notebooks/plot_enamine_space_umap_notebook.ipynb
Connections 22
- 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.