TarPass

The official implementation of Revisiting Target-Aware de novo Molecular Generation with TarPass: Between Rational Design and Texas Sharpshooter

TarPass is a comprehensive benchmark designed for target-aware de novo molecular generation.

Contents

• Quick Setup
• Input Folder Structure
• Usage
• CLI Help
• Notebooks and Scripts

Quick Setup

⚠️ We strongly recommend running TarPass on devices with a GPU.

conda env create -f tarpass.yml
conda activate tarpass
pip install -e .

⚠️ It should be noted that the packages required for running Jupyter Notebook are not included.

Docking with Gnina (Suggested)

wget https://github.com/gnina/gnina/releases/download/v1.3/gnina

export PATH=<GNINA_PATH>:$PATH
# Change <GNINA_PATH> to your own path!
export PYTHONUNBUFFERED=1

Docking with AutoDock-Vina (Deprecated, NOT suggested)

conda install -c conda-forge swig boost-cpp libboost sphinx sphinx_rtd_theme
conda install -c conda-forge vina gemmi prody
conda install -c conda-forge autogrid # >=4.2.7

python -m pip install git+https://github.com/Valdes-Tresanco-MS/AutoDockTools_py3

cd dock
unzip autodock_depends.zip

Input Folder Structure

Warning
We strongly recommend that you place the molecule files to be tested according to the following folder structure.
We only accept SDF format files as input for 3D molecules, as reading molecules in MOL or MOL2 format may result in the loss of stereochemical information. For SMILES format input, most of file formats (e.g. .smi or .txt) are acceptable.

test_folder
├── 5HT2A
│   ├── 1.sdf (or smi format,  
│   │      it's also acceptable to store all molecules in a single file)
│   ├── 2.sdf
│   └── ...
│ 
├── 5HT2A-AF
│   ├── 1.sdf
│   └── ...
└── ...

test_folder
├── 5HT2A
│   ├── results
│   │   ├── xx_docking_results.pkl
│   │   ├── xx_results.json
│   │   └──...
│   ├── 1.sdf
│   └── ...
└── ...

Usage

The simplest process for benchmarking with default settings is as follows:

Packaing generated molecules in designated format ->  
docking -> evaluation -> analysis -> collecting results (Optional)

The following sequence must be strictly followed:

Docking

tarpass -p <path> dock

On devices equipped with GPUs, completing docking across all 20 proteins requires more than 16 hours, with the exact time depending on the number of molecules and the hardware performance.

After execution, pkl files xx-dock_docking_results.pkl or xx-score_only_docking_results.pkl (3D only) containing docking scores, and docking poses will be generated under the <target>/results directory.

Evaluation

tarpass -p <path> eval

After execution, a json file dock_eval_results.json with PLI-related results and a csv file mole_eval_results.csv for molecular properties will be generated under the <target>/results directory.

Analysis

Warning: Random_eval_results.pkl and Reference_eval_results.pkl must be placed in the data folder.

tarpass -p <path> analysis

After execution, a series of csv files analysis_<term>.csv of analysis results will be save at <path>.

Collection

tarpass -p <path> collect

After running, the results of eval will be collected into xx_eval_results.pkl under <path>.

Note:

• The collected pickle files can also be used as input for the analysis module; simply replace <path> with the specific file path.
• For more details on how to work with and make use of this file, please refer to notebook/read_results.ipynb.

CLI Help

tarpass [-n NUM] -p PATH {module} --option

options:
  -n NUM, --num NUM     number of unique molecules to verify per target (default: 1000).
  -p PATH, --path PATH  path to the folder where generated molecules for testing will be stored.

  {module}     modules that need to be executed: dock, interactions, dock_eval, etc.
  --option     Options specific to each module, which may vary between modules.

Notebooks and Scripts

In addition to the main CLI tool, we provide several Jupyter Notebooks and auxiliary scripts in the notebook/ directory for data analysis, filtering, and visualization.

Notebooks

• extract_nearby_res.ipynb: A utility for extracting residues near the binding site, useful for detailed protein-ligand interaction analysis.
• filter_with_eval.ipynb: Provides a stepwise filtering workflow. After running the eval module, you can use this notebook to filter molecules based on specific targets and evaluation metrics (e.g., docking scores, PLI criteria).
• generation_size.ipynb: Used for analyzing the scale and distribution of the generated molecular datasets.
• read_results.ipynb: Instructions for using collected results.

Auxiliary Scripts

The notebook/scripts/ directory contains several utility scripts for specific tasks:

• pose_check.py: A helper script to verify and visualize docking poses.
• cross_docking.py: Facilitates cross-docking experiments between different targets and ligands.
• collect_reset.py / tmpanaly_reset.py: Maintenance scripts for conformation-reset docking.

Note: As mentioned in the Setup section, ensure you have jupyter and its dependencies installed in your environment to run the .ipynb files, as they are not included in the default tarpass.yml.