Skip to content
Message Passing Neural Networks for Molecule Property Prediction
HTML Python CSS Other
Branch: master
Clone or download
Pull request Compare This branch is 231 commits ahead, 11 commits behind wengong-jin:master.
Latest commit ab304d2 Jul 23, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
chemprop add mse metric Jul 23, 2019
scripts Fixing inf stuff Jul 3, 2019
test Option to use compound names/ids in data file during training Mar 12, 2019
web Added easy production deployment. Apr 23, 2019
.gitignore Ignore .sqlite3 files. Feb 15, 2019
LICENSE.txt Added detail to readme. Apr 23, 2019 Changing utils structure Nov 6, 2018
data.tar.gz Adding qm7 to data.tar.gz Mar 5, 2019
environment.yml Makedirs helper function Feb 14, 2019 Further cleaning up code, removing unneeded functions, improving docu… Jan 29, 2019 Fixing random forest parsing Apr 19, 2019
setup.cfg Adding setup and license Nov 6, 2018 Moving dependencies to conda yml and adding info about features to re… Feb 11, 2019
splits.tar.gz use tar.gz instead of zip for splits Mar 6, 2019 Further cleaning up code, removing unneeded functions, improving docu… Jan 29, 2019

Property Prediction

This repository contains message passing neural networks for molecular property prediction.

Table of Contents


While it is possible to run all of the code on a CPU-only machine, GPUs make training significantly faster. To run with GPUs, you will need:

  • cuda >= 8.0
  • cuDNN


Option 1: Conda

The easiest way to install the chemprop dependencies is via conda. Here are the steps:

  1. Install Miniconda from
  2. cd /path/to/chemprop
  3. conda env create -f environment.yml
  4. source activate chemprop (or conda activate chemprop for newer versions of conda)
  5. (Optional) pip install git+

The optional descriptastorus package is only necessary if you plan to incorporate computed RDKit features into your model (see Additional Features). The addition of these features improves model performance on some datasets but is not necessary for the base model.

Option 2: Docker

Docker provides a nice way to isolate the chemprop code and environment. To install and run our code in a Docker container, follow these steps:

  1. Install Docker from
  2. cd /path/to/chemprop
  3. docker build -t chemprop .
  4. docker run -it chemprop:latest /bin/bash

Note that you will need to run the latter command with nvidia-docker if you are on a GPU machine in order to be able to access the GPUs.

(Optional) Installing chemprop as a Package

If you would like to use functions or classes from chemprop in your own code, you can install chemprop as a pip package as follows:

  1. cd /path/to/chemprop
  2. pip install .

Then you can use import chemprop or from chemprop import ... in your other code.


If you get warning messages about kyotocabinet not being installed, it's safe to ignore them.

Web Interface

For those less familiar with the command line, we also have a web interface which allows for basic training and predicting. After installing the dependencies following the instructions above, you can start the web interface in two ways:

  1. Run python web/ and then navigate to localhost:5000 in a web browser. This will start the site in development mode.
  2. Run gunicorn --bind {host}:{port} 'wsgi:build_app()'. This will start the site in production mode.
    • To run this server in the background, add the --daemon flag.
    • Arguments including init_db and demo can be passed with this pattern: 'wsgi:build_app(init_db=True, demo=True)'
    • Gunicorn documentation can be found here.

Training with our web interface

Predicting with our web interface


In order to train a model, you must provide training data containing molecules (as SMILES strings) and known target values. Targets can either be real numbers, if performing regression, or binary (i.e. 0s and 1s), if performing classification. Target values which are unknown can be left as blanks.

Our model can either train on a single target ("single tasking") or on multiple targets simultaneously ("multi-tasking").

The data file must be be a CSV file with a header row. For example:


Datasets from MoleculeNet and a 450K subset of ChEMBL from have been preprocessed and are available in data.tar.gz. To uncompress them, run tar xvzf data.tar.gz.


To train a model, run:

python --data_path <path> --dataset_type <type> --save_dir <dir>

where <path> is the path to a CSV file containing a dataset, <type> is either "classification" or "regression" depending on the type of the dataset, and <dir> is the directory where model checkpoints will be saved.

For example:

python --data_path data/tox21.csv --dataset_type classification --save_dir tox21_checkpoints


  • The default metric for classification is AUC and the default metric for regression is RMSE. Other metrics may be specified with --metric <metric>.
  • --save_dir may be left out if you don't want to save model checkpoints.
  • --quiet can be added to reduce the amount of debugging information printed to the console. Both a quiet and verbose version of the logs are saved in the save_dir.

Train/Validation/Test Splits

Our code supports several methods of splitting data into train, validation, and test sets.

Random: By default, the data will be split randomly into train, validation, and test sets.

Scaffold: Alternatively, the data can be split by molecular scaffold so that the same scaffold never appears in more than one split. This can be specified by adding --split_type scaffold_balanced.

Separate val/test: If you have separate data files you would like to use as the validation or test set, you can specify them with --separate_val_path <val_path> and/or --separate_test_path <test_path>.

Note: By default, both random and scaffold split the data into 80% train, 10% validation, and 10% test. This can be changed with --split_sizes <train_frac> <val_frac> <test_frac>. For example, the default setting is --split_sizes 0.8 0.1 0.1. Both also involve a random component and can be seeded with --seed <seed>. The default setting is --seed 0.

Cross validation

k-fold cross-validation can be run by specifying --num_folds <k>. The default is --num_folds 1.


To train an ensemble, specify the number of models in the ensemble with --ensemble_size <n>. The default is --ensemble_size 1.

Hyperparameter Optimization

Although the default message passing architecture works quite well on a variety of datasets, optimizing the hyperparameters for a particular dataset often leads to marked improvement in predictive performance. We have automated hyperparameter optimization via Bayesian optimization (using the hyperopt package) in This script finds the optimal hidden size, depth, dropout, and number of feed-forward layers for our model. Optimization can be run as follows:

python --data_path <data_path> --dataset_type <type> --num_iters <n> --config_save_path <config_path>

where <n> is the number of hyperparameter settings to try and <config_path> is the path to a .json file where the optimal hyperparameters will be saved. Once hyperparameter optimization is complete, the optimal hyperparameters can be applied during training by specifying the config path as follows:

python --data_path <data_path> --dataset_type <type> --config_path <config_path>

Additional Features

While the model works very well on its own, especially after hyperparameter optimization, we have seen that adding computed molecule-level features can further improve performance on certain datasets. Features can be added to the model using the --features_generator <generator> flag.

RDKit 2D Features

As a starting point, we recommend using pre-normalized RDKit features by using the --features_generator rdkit_2d_normalized --no_features_scaling flags. In general, we recommend NOT using the --no_features_scaling flag (i.e. allow the code to automatically perform feature scaling), but in the case of rdkit_2d_normalized, those features have been pre-normalized and don't require further scaling.

Note: In order to use the rdkit_2d_normalized features, you must have descriptastorus installed. If you installed via conda, you can install descriptastorus by running pip install git+ If you installed via Docker, descriptastorus should already be installed.

The full list of available features for --feagrtures_generator is as follows.

morgan is binary Morgan fingerprints, radius 2 and 2048 bits. morgan_count is count-based Morgan, radius 2 and 2048 bits. rdkit_2d is an unnormalized version of 200 assorted rdkit descriptors. Full list can be found at the bottom of our paper: rdkit_2d_normalized is the CDF-normalized version of the 200 rdkit descriptors.

Custom Features

If you would like to load custom features, you can do so in two ways:

  1. Generate features: If you want to generate features in code, you can write a custom features generator function in chemprop/features/ Scroll down to the bottom of that file to see a features generator code template.
  2. Load features: If you have features saved as a numpy .npy file or as a .csv file, you can load the features by using --features_path /path/to/features. Note that the features must be in the same order as the SMILES strings in your data file. Also note that .csv files must have a header row and the features should be comma-separated with one line per molecule.


To load a trained model and make predictions, run and specify:

  • --test_path <path> Path to the data to predict on.
  • A checkpoint by using either:
    • --checkpoint_dir <dir> Directory where the model checkpoint(s) are saved (i.e. --save_dir during training). This will walk the directory, load all .pt files it finds, and treat the models as an ensemble.
    • --checkpoint_path <path> Path to a model checkpoint file (.pt file).
  • --preds_path Path where a CSV file containing the predictions will be saved.

For example:

python --test_path data/tox21.csv --checkpoint_dir tox21_checkpoints --preds_path tox21_preds.csv


python --test_path data/tox21.csv --checkpoint_path tox21_checkpoints/fold_0/model_0/ --preds_path tox21_preds.csv


During training, TensorBoard logs are automatically saved to the same directory as the model checkpoints. To view TensorBoard logs, run tensorboard --logdir=<dir> where <dir> is the path to the checkpoint directory. Then navigate to http://localhost:6006.


We compared our model against MolNet by Wu et al. on all of the MolNet datasets for which we could reproduce their splits (all but Bace, Toxcast, and qm7). When there was only one fold provided (scaffold split for BBBP and HIV), we ran our model multiple times and reported average performance. In each case we optimize hyperparameters on separate folds, use rdkit_2d_normalized features when useful, and compare to the best-performing model in MolNet as reported by Wu et al. We did not ensemble our model in these results.

Results on classification datasets (AUC score, the higher the better)

Dataset Size Ours MolNet Best Model
BBBP 2,039 0.735 ± 0.0064 0.729
Tox21 7,831 0.855 ± 0.0052 0.829 ± 0.006
Sider 1,427 0.678 ± 0.019 0.648 ± 0.009
clintox 1,478 0.9 ± 0.0089 0.832 ± 0.037
MUV 93,087 0.0897 ± 0.015 0.184 ± 0.02
HIV 41,127 0.793 ± 0.0012 0.792
PCBA 437,928 0.397 ± .00075 0.136 ± 0.004

Results on regression datasets (score, the lower the better)

Dataset Size Ours GraphConv/MPNN (deepchem)
delaney 1,128 0.567 ± 0.026 0.58 ± 0.03
Freesolv 642 1.11 ± 0.035 1.15 ± 0.12
Lipo 4,200 0.542 ± 0.02 0.655 ± 0.036
qm8 21,786 0.0082 ± 0.00019 0.0143 ± 0.0011
qm9 133,884 2.03 ± 0.021 2.4 ± 1.1

Lastly, you can find the code to our original repo at and for the Mayr et al. baseline at .

You can’t perform that action at this time.