• Introduction
  • Dependency
  • Repo Structure
• Data Preprocessing
  • Data Format
• Training
  • Class Weighting
  • Sample Weighting
  • Early Stop
  • Resume Training
  • Multi-fold Cross Validation
  • Hyperparameter Tuning
  • Comparative Re-run
• Cite Us

Code for "Enhance Information Propagation for Graph Neural Network by Heterogeneous Aggregations", also lite version of package for ligand-based virtual screening.

For input data preprocessing, use ligand_based_VS_data_preprocessing.py. Check

python ligand_based_VS_data_preprocessing.py --help

for argument details.

During the preprocessing, each input SMILES string will be validated, if invalid, a runtime warning will be raised. There will be two log files saved along with the preprocessing output file, named as <dataset>_preprocessing_stdout@<time_stamp>.txt and <dataset>_preprocessing_stderr@<time_stamp>.txt. Check any warning/error message in <dataset>_preprocessing_stderr@<time_stamp>.txt and check other runtime info in <dataset>_preprocessing_stdout@<time_stamp>.txt

Preprocessed data, as well as trainset & testset for training & evaluation, will be saved into .gpkl files with dict format as follows:

For model training, use ligand_based_VS_train.py.
Check

python ligand_based_VS_train.py --help

for argument details.

• For classification task training, 3 different class weighting methods are supported:
  1. method 0: default method, use uniform weighting, set input arg as -weighting_method 0
  2. method 1: class weight equals to inverse of class distribution of training samples, set input arg as -weighting_method 1
  3. method 2: class weight equals to inverse of square root of class distribution of training samples, set input ars as -weighting_method 2

• Note the metrics calculated on train set don't count in sample weights except for the loss metric; test set does not support sample weights at all; for meaningful test metric results, you should organize test samples with the same weights together, and sperately run test on test sets with different weights.

• Enable early stop for training with input arg -early_stop m, in which m is the maximum number of consective test rounds without better metric got, after this number the training process will be stopped. Set -early_stop 0 to disable early stop.

• For plain training, there're two alternative ways to resume an interrupted training process:
  1. start a new training with input arg -model_file, this will pratically initialize the model with weights from the model_file
  2. or, start a new training with input arg -save_folder, the training will retrieve a) the last run epoch and b) the latest model file saved in save_folder (logs and model files will still be saved into this folder); in this case input arg -model_file will be ignored.

• Enable multi-fold cross validation with input arg -mfold m, in which m is the number of folds or the path of specified mfold_indexs.gpkl file if you want to use the same sample splitting indices among different runs.
• When multi-fold cross validation is activated, the input train set will be divided into m parts, at each fold one part will be used as test set, other parts will be used as train set. Test set specified by input arg -testset must be None now.
• Train results & log will be saved in seperate folder for each fold
• Multi-fold cross validation is mainly designed for small data scenarios, m is recommended to be in range [3, 5]
• Parallel running: multi-fold cross validation supports local parallel running
  1. First start a multi-fold training as usual, get the save_root_folder of this run
  2. Start one or more multi-fold trainings with all the settings the same with the first run, and explicitly set the input arg -save_root_folder to the root folder as above
  3. By local, it means the parallel syncronization is done through the local file system. On HPC or cloud enviroment, different training processes can run on different computing nodes as long as they share the same file system.
  4. arg -shuffle_trainset only affect the first training process.

• Auto hyperparameter tuning is supported by grid search. Enable grid search by arg -grid_search n in which n is the maximum number of trial. Set it to 0 to diable the grid search.
• Grid search and multi-fold cross validation should not be activated simultaneously.
• Best hyperparameter combinations will be saved into best_trial_xxx.json file under the training save_root_folder.
• Currently hyperparameter search spaces for model_4v4 and model_4v7 are defined, check out the details in grid_search.py; note these search spaces are pretty large, mainly defined for model structure optimization, not for per dataset tuning. If you intend to do per dataset tuning, these search spaces should be narrowed down dramatically. Contact the authors if you're not capable of modifying the default search space definitions.
• Resume running: to resume an interrupted grid search process, just start a new grid search process with input arg -save_root_folder set to the previous run
• Parallel running: grid search supports local parallel running
  1. First, start a grid search as usual, get the save_root_folder of this run, remember that the number of trials specified by input arg -grid_search should be reduced now (probably = # total_planned_trials / # parallel_runs)
  2. Start one or more grid search with all the settings the same with the first run (except for -grid_search, you can set it to any number appropriate), and explicitly set the input arg -save_root_folder to the root folder as above
  3. By local, it means the parallel syncronization is done through the local file system. On HPC or cloud enviroment, different grid search processes can run on different computing nodes as long as they share the same file system.

• For convenient re-run for comparison purpose, you can set -srcfolder to the folder path of a previous run, the training program will load trainset/testset as well as mfold_indexs.gpkl file from there.
• For plain training, trainset and testset will be loaded from -srcfolder for the new run
• For multi-fold cross validation, both trainset.gpkl and mfold_indexs.gpkl will be loaded from -srcfolder for the new run
• For bundle training, order of each run as well as trainset/testset for each run will be loaded from -srcfolder, and the new bundle training will be executed with the same order loaded.

If you find this work useful, cite us by

@article{leng2021enhance,
  title={Enhance Information Propagation for Graph Neural Network by Heterogeneous Aggregations},
  author={Leng, Dawei and Guo, Jinjiang, etc.},
  journal={arXiv preprint arXiv:2102.04064},
  year={2021}
}