FragNet is a Graph Neural Network designed for molecular property prediction, that can offer insights into how different substructures influence the predictions. More details of FragNet can be found in our paper,
Arxiv version: https://arxiv.org/abs/2410.12156
Figure 1: FragNet’s architecture and data representation. (a) Atom and Fragment graphs’ edge features are learned from Bond and Fragment connection graphs respectively. b) Initial fragment features for the fragment graph are the summation of the updated atom features that compose the fragment. (c) Illustration of FragNet’s message passing taking place be- tween two non-covalently bonded substructures. Fragment-Fragment connections are also present between adjacent fragments in each non-covalently bonded structure of the com- pound.
Figure 2: Different types of attention weights and contribution values available in FragNet visualized for CCNH+CCOc1cccc2ccccc12.[Cl-] with atom, bond, and fragment at- tention weights shown in (a),(b), and (c) and fragment contribution values shown in (d). The top table provides the atom to fragment mapping and the bottom table provides the fragment connection attention weights. Atom and bond attention weights are scaled to val- ues between 0 and 1. The fragment and fragment connection weights are not scaled. The numbers in blue boxes in (d) correspond to Fragment IDs in ‘Atoms in Fragments’ table.
New to FragNet? The fastest way to get started:
- Install FragNet (see Installation section below)
- Explore visualizations: See how atoms, bonds, and fragments contribute to predictions
For the web application or advanced usage, continue reading below.
The installation has been tested with python 3.11 and cuda 12.1
- Create a python 3.11 virtual environment and install the required packages using the command
pip install -r requirements.txt - Install torch-scatter using
pip install torch-scatter -f https://data.pyg.org/whl/torch-2.4.0+cpu.html - Next install FragNet. In the directory where
setup.pyis, run the commandpip install .
Alternatively and more conveniently, you can run bash install_cpu.sh which will install FragNet and create pretraining and finetuning data for ESOL dataset.
- Create a python 3.11 virtual environment and install the required packages using the command
pip instal -r requirements.txt - Install torch-scatter using
pip install torch-scatter -f https://data.pyg.org/whl/torch-2.4.0+cu121.html - Next install FragNet. In the directory where
setup.pyis, run the commandpip install .
Alternatively do bash install_gpu.sh.
FragNet was pretrained using part of the data used by UniMol.
Here, we use ESOL dataset to demonstrate the data creation. The following commands should be run at the FragNet/fragnet directory.
First, create a directory to save data.
mkdir -p finetune_data/moleculenet/esol/raw/
Next, download ESOL dataset.
wget -O finetune_data/moleculenet/esol/raw/delaney-processed.csv https://deepchemdata.s3-us-west-1.amazonaws.com/datasets/delaney-processed.csv
Next, run the following command to create pretraining data.
python data_create/create_pretrain_datasets.py --save_path pretrain_data/esol --data_type exp1s --maxiters 500 --raw_data_path finetune_data/moleculenet/esol/raw/delaney-processed.csv
- save_path: where the datasets should be saved
- data_type: use exp1s for all the calculations
- maxiters: maximum number of iterations for 3D coordinate generation
- raw_data_path: location of the smiles dataset
Creating data for finetuning for MoleculeNet datasets can be done as follows,
python data_create/create_finetune_datasets.py --dataset_name moleculenet --dataset_subset esol --use_molebert True --output_dir finetune_data/moleculenet_exp1s --data_dir finetune_data/moleculenet --data_type exp1s
- dataset_name: dataset type
- dataset_subset: dataset sub-type
- use_molebert: whether to use the dataset splitting method used by MoleBert model
To pretrain run the following command. All the input parameters have to be given in a config file.
python train/pretrain/pretrain_gat2.py --config exps/pt/unimol_exp1s4/config.yaml
python train/finetune/finetune_gat2.py --config exps/ft/esol/e1pt4.yaml
FragNet provides multiple user-friendly ways to interact with the model and visualize molecular property predictions:
We provide two ready-to-use Jupyter notebooks that require no additional setup beyond installation:
- fragnet/notebooks/FragNet.ipynb - A streamlined notebook for quick interpretability analysis
How to use:
# Navigate to the FragNet directory
cd /path/to/FragNet
# Launch Jupyter
jupyter notebook
# Open either FragNet_Interactive_Demo.ipynb or fragnet/notebooks/interprete.ipynb
# Run all cells (Cell → Run All) and follow the inline instructionsThese notebooks provide:
- Step-by-step guidance with clear explanations
- Pre-configured examples you can run immediately
- Visualizations of atom weights, bond contributions, and fragment attributions
- Easy modification of SMILES strings to analyze your own molecules
For a browser-based GUI experience, you can launch the Streamlit application:
Prerequisites:
- Ensure FragNet is installed (see Installation section above)
- Install Streamlit:
pip install streamlit streamlit-ketcher
To launch the application:
# From the root FragNet directory
streamlit run fragnet/vizualize/app.pyThe application will open in your browser at http://localhost:8501
Features:
- Draw molecules directly in the browser using the Ketcher molecular editor
- Input SMILES strings for prediction
- Select different property types (Solubility, Lipophilicity, Energy, Drug Response)
- Interactive visualizations of molecular interpretability
Troubleshooting:
- If the app doesn't open automatically, manually navigate to
http://localhost:8501 - Ensure no other applications are using port 8501
- Check that all dependencies are installed:
pip install -r requirements.txt
python hp/hpoptuna.py --config exps/ft/esol/e1pt4.yaml --n_trials 10 \
--chkpt hpruns/pt.pt --seed 10 --ft_epochs 10 --prune 1
- config: initial parameters
- n_trials: number of hp optimization trails
- chkpt: this is where the checkoint during hp optimization will be saved. Note that you will have to create an output directory for this (in this case hpruns). Otherwise the output directory is assumed to be the current working directory.
- seed: random seed
- ft_epochs: number of training epochs
- prune: For Optuna runs. Whether to prune an optimization.
If you use our work, please cite it as,
@article{doi:10.1021/jacs.5c22620,
author = {Panapitiya, Gihan and Gao, Peiyuan and Maupin, C. Mark and Saldanha, Emily G.},
title = {FragNet: A Graph Neural Network for Molecular Property Prediction with Four Levels of Interpretability},
journal = {Journal of the American Chemical Society},
volume = {148},
number = {9},
pages = {9930-9950},
year = {2026},
doi = {10.1021/jacs.5c22620},note ={PMID: 41738545},
URL = { https://doi.org/10.1021/jacs.5c22620},
eprint = { https://doi.org/10.1021/jacs.5c22620}
}
To run the FragNet Streamlit app in a Docker container:
- Build the Docker image:
docker build -t fragnet-app . - Run the container:
docker run -p 8501:8501 fragnet-app
This will start the app at http://localhost:8501.
Note: The Dockerfile installs required system libraries (e.g., libxrender1, libxext6) and Python build tools for compatibility with scientific packages. If you encounter missing library errors, install the relevant system package in the Dockerfile.
This material was prepared as an account of work sponsored by an agency of the United States Government. Neither the United States Government nor the United States Department of Energy, nor Battelle, nor any of their employees, nor any jurisdiction or organization that has cooperated in the development of these materials, makes any warranty, express or implied, or assumes any legal liability or responsibility for the accuracy, completeness, or usefulness or any information, apparatus, product, software, or process disclosed, or represents that its use would not infringe privately owned rights. Reference herein to any specific commercial product, process, or service by trade name, trademark, manufacturer, or otherwise does not necessarily constitute or imply its endorsement, recommendation, or favoring by the United States Government or any agency thereof, or Battelle Memorial Institute. The views and opinions of authors expressed herein do not necessarily state or reflect those of the United States Government or any agency thereof. PACIFIC NORTHWEST NATIONAL LABORATORY operated by BATTELLE for the UNITED STATES DEPARTMENT OF ENERGY under Contract DE-AC05-76RL01830