[ VLS Overview ]

[ Receptor | Choosing ligands | Docking timing | Scoring | Docking intro | Project setup | _dockBatch | Converting chemicals | Running dock job | VLS Introduction | Vls threshold | Mf score | Admet selection | Parallelization | Vls cluster | Vls scores storage | Make Hitlist | DockScan | SLURM SGE | GINGER | RIDGE | Template docking | V-SYNTHES | GigaScreen ]

1. Where to dock. Building Receptor and Pocket Model

The goal here is to have an adequate three-dimensional model of the receptor pocket you are planning to dock ligands to. And the pitfalls are that your model is not accurate overall, or does not reflect the induced fit, or alternative conformations of the receptor binding pocket are missed.
Receptor from PDB
If you have only a single entry with your receptor, convert the protein with convertObject yes yes no no , after deleting water molecules and irrelevant chains (e.g. delete a_!1 ), or use menus as in the ligand docking section.
However, if you have a choice between several templates, take the following into account:

• X-ray structure is preferable to an NMR structure
• high resolution X-ray structure ( less than 2.1A ) is much better than, say 2.5A .
• watch out for high-B-factor regions and avoid them; sometimes crystallographers deposit fantasy coordinates with high-B-factors. Use:

   
   color a_//* Bfactor( a_//* )  # from command line 
  

  or Color/B-factor from the Gui-menu .
• place polar hydrogens and choose correct form of histidine ( convertObject yes yes no no takes care of that )
• a bound conformation of the receptor is preferable, however if you use an apo-model, an NMR structure or a model by homology, the side-chains in a pocket may be incorrect. Frequently they stick out and prevent a ligand from binding. Those stubborn side-chains can be 'tamed', (i) manually; (ii) by a side chain simulation with elevated surfaceTension; or (iii) by an explicit flexible docking calculation with a known ligand.

2. What to dock. Ligand, ligands, a database or a library.

Usually a good start is to try to dock the known ligand(s) to the receptor model. You may also want to dock a library of compounds in order to identify lead candidates. In this case the main pitfall is that the library is too restricted, molecules are not chemically feasible or not drug-like.
Ligand from PDB
Then to dock a ligand from pdb, go through the procedure described in the ligand docking section.
Ligand(s) from a mol/mol2- file, or SMILES strings.
The main prerequisite is that the formal charges and the bond types are correct. If they are not correct, you need to process each molecule manually as described in the ligand docking section. From a command line you may use the build smiles or convert2Dto3D macro.

Flexible docking considerations.

After the receptor maps are built, you will start a docking simulation. The goal of the flexible docking calculation is prediction of correct binding geometry for each binder. ICM stochastic global optimization algorithm attempts to find the global minimum of the energy function which includes five grid potentials describing interaction of the flexible ligand with the receptor and internal conformational energy of the ligand. During this process a stack of alternative low energy conformations is saved ( one of the choices in the Docking menu ). Some facts about ICM docking:

• an average docking time is 2-30 seconds per ligand per processor
• ICM docking performed very well in predicting the binding geometry in several comparative benchmarks.
• the time per ligand was chosen to be the smallest possible to allow screening of very large data sets. To increase the time spent per ligand, change the Docking_effort parameter from the Docking.Small Set Docking Batch menu to 3. or 5., or supply this parameter to the rundock script directly.

The vls module allows you to access a good scoring function.

Introduction and pre-requisites

ICM ligand docking procedure performs docking of the fully flexible small-molecule ligand to a known receptor 3D structure. Before setting up the docking project, ICM object of the receptor has to be created. In most cases, x-ray structure of the receptor is initially in the PDB format. Thus, it has to be converted to the ICM format. This process involves addition of the hydrogen atoms, assignment of atom types and charges from the residue templates (icm.res) and imposition of internal coordinates tree (icm-tree) on the original pdb coordinates. The easiest way to convert pdb structure into icm object is through the GUI as described in the GUI Manual or you can automate the setup in the command line using _dockBatch.

Docking project setup

Start project setup by defining the project name (GUI menu Docking/New Project ). Avoid spaces and leading digits in the name. All files related to the docking project will be stored under names, which start from the project name. Most customized parameters will be saved in the table file under the project name dockProjName.dtb as well:

 
DOCK1.dtb     # control table
DOCK1_rec.ob  # receptor object 
DOCK1_gb.map  # 3D potential grids, or 'maps' 
DOCK1_gc.map 
DOCK1_ge.map 
DOCK1_gh.map 
DOCK1_gl.map 
DOCK1_gs.map 
DOCK1_probe.ob # 4 atom probe for initial superposition (or)
DOCK1_tmplt.ob # template ligand (optional)

The receptor setup procedure will first display the grid box, allowing you to adjust the box dimensions, and then the 'probe' which defines the initial positioning of the ligand's center of mass and long/short axis. The probe can be moved/rotated. While its positioning has only minor influence on the results as long as it remains inside the binding site, it may help the procedure to find the correct docked orientation more reliably and/or in shorter time.
After the receptor setup is complete, the program normally displays the receptor with the selected binding site residues highlighted in yellow xstick representation. Ligand setup offers a number of ways (submenu docking/ligand setup ) to define the ligand, depending on the source of the ligand structure(s).

To run the docking job from a unix shell, use the _dockScan macro with appropriate parameters, e.g.

$ICMHOME/icm -c /icm/_dockScan abl -a -S confs=10 effort=2. from=10 to=20 outdir=/tmp/ name=ou >& abl10.ou &

Automated docking project setup

You can automate docking setup using _dockBatch and/or immediately start the screen.

e.g.

$ICMHOME/icm $ICMHOME/_dockBatch 1xbb.pdb ligmol=asti

Arguments:

• ligmol= : ligand in the input structure, used to define site (or redock with -r)
• pocket= : pocket selection in a_chain/resNumList format, e.g. a_b/5,8:10,115
• box=x,y,z,X,Y,Z : site definition as a box, e.g. -1.,3,-10.,10.,13.,0. Our box definition is x,y,z,X,Y,Z which is to say two corners of the box (with lowest/HIGHEST xyz coordinates). If you want to use center Xc,Yc,Zc and size (box dimension) d you could calculate xyzXYZ as Xc - d/2 Yc - d/2 Zc - d/2 Xc + d/2 Yc + d/2 Zc + d/2
• -r : re-dock mode, takes ligand from the receptor complex input
• -R : same, with RMSD calculation
• -u : do not automatically set protonation/charge state of the ligand
• -w : delete all water in the receptor input
• -e : use stack embedded in receptor as ensemble for '4D' docking
• covres= : covalent docking mode, modified residue in a_chain/resNum format
• react= : table with custom covalent reaction mechanisms
• reactNum= : selects reaction from multiple mechanisms in the default or custom table

Fully Automated Optional - you can run screening automatically by defining the sdf file at the end

e.g.

$ICMHOME/icm64 $ICMHOME/_dockBatch 1xbb.pdb ligmol=asti chem_database.sdf

Note about Ionization State of Ligand setup using _dockBatch There is a setting within the docking project that controls protonation state handling. When project is set up by _dockBatch , the default is to apply built-in pKa model to determine predominant protonation state. To keep protonation as in input sdf, you can turn this off with _dockBatch -u option (or change it in .dtb file later). If you just want to see results of automatic protonation state assignment, you can load your sdf in icm and use dialog under Chemistry/Set Formal Charges

Converting a chemical from pdb.

The Protein data bank, due to unprecedented ignorance, for the last 15 years has not been storing any information about covalent bond types and formal charges of the chemical compounds interacting with proteins! This oversight makes it impossible to automatically convert those molecules to anything sensible and requires your manual interactive assignment of bond types and formal charges for each compound in a pdb-entry. Therefore, if you apply the convert command to a pdb-entry with ligands, the ligands will just become some crippled incomplete molecules which can not be further conformationally optimized.
Follow these steps to convert a chemical properly from a pdb form to an a correct icm object.

• display the molecule, set wireStyle=2 (or via top-left gui-menu), and selection type to GRAPHICS.selectionMode=1 (the first item of the gui-selection-mode menu)
• invoke MolMechanics.Structure.SetBondType menu item
• graphically select groups of atoms (e.g. a ring) and set appropriate bond type
• invoke the next menu item, MolMechanics.Structure.SetFormalCharge and set formal charges
• proceed to the MolMechanics.ICM-Convert.Chemical menu (see below)

Running docking simulations

Use menu docking/Small Set Docking Batch to start docking of one or few ligands in the background. You can also view the process interactively (menu docking/Interactive Docking ) although it is much slower due to the time spent on drawing the molecules. The results of the batch docking job are saved in the

 
PROJECTNAME_answers*.ob  #icm-object file with best solutions for each ligand 
PROJECTNAME_*.cnf        # icm conformational stack files with multiple docked conf. 
PROJECTNAME_*.ou         # output file were various messages are stored. 

Virtual Ligand Screening Introduction

Virtual Ligand Screening (VLS) in ICM is performed via docking of each ligand in the database to the receptor structure, with subsequent evaluation of the docked conformation with a binding-score function. Best-scoring ligands are then stored in the multiple icm-object file. The set-up of the VLS is largely identical to the set-up of the docking simulation (see How-to: Ligand Docking Simulations). In most cases the ligand input file will be an SDF or MOL2 file. These files need to be indexed by ICM before they can be used in VLS runs. The index is used to allow fast access to an arbitrary molecular record in a large file. Use menu Docking/Tools/Index Mol/Mol2 File/Database to generate the index, then set up the SDF/MOL2 file as a ligand source (menu Docking/Ligand Setup/From Database ). As in docking, _dockScan ICM script can be ran directly from UNIX shell/command line to start simulations.

Score Threshold

An important parameter of the VLS run is the score threshold. Docked conformation for a particular ligand will only be stored by ICM VLS procedure if its binding-score is below the threshold. Edit the project .dtb file to adjust this value:

 
#>r DOCK1.r_ScoreThreshold 
  -35. 

1. based on the scores calculated by docking known ligands. Generally, a value somewhat above typical score observed for known ligands is a good guess.
2. if no ligands are known, a pre-simulation can be run using ~1000 compounds from the target database. Using the resulting statistics for the scores, the threshold should be set to retain ~1% of the ligands.

 
#>r PROJECTNAME.r_mfScoreThreshold 
  999. 

Other selection criteria

ICM VLS uses a number of criteria to pre-select compounds before docking. Edit the project .dtb file to change their defaults. A full description of each field in the .tab file can be found here ftp://ftp.molsoft.com/man/dockTable.pdf

 
#>i DOCK1.i_maxHdonors 
 5 
#>i DOCK1.i_maxLigSize 
 500 
#>i DOCK1.i_maxNO 
 10 
#>i DOCK1.i_maxTorsion 
 10 
#>i DOCK1.i_minLigSize 
 100 

 
icm _dockScan from=1     to=10000 MYPROJECT
icm _dockScan from=10001 to=20000 MYPROJECT
icm _dockScan from=20001 to=30000 MYPROJECT
.. 

 
#>r PROJECTNAME.r_mfScoreThreshold 
  999. 

The hitlist can also be prepared by a macro. In this case the scores will be extracted.

Analysis of the results

The hits found by the screening procedure and stored in *answers*.ob files can be processed into a hitlist spreadsheet which is browsable and exportable as SDF: (menu Docking/Make Hit List... ). An older way to export hits as SD file is using (menu Docking/Tools/Export scan answers as mol ). The score and its components are stored in the resulting SD file as well. Simple analysis of the score distribution can be performed by making a histogram (menu Docking/Tools/Scan results histogram ).

To make a hitlist in GUI use Docking/Make hitlist and on the command line use _scanMakeHitlist

scanMakeHitList "DOCK1" ""//vls/DOCK1_answers*.ob" Name(Name( "//vls/DOCK1_answers*.ob"")) no no yes 0

The logical arguments at the end are:

• l_import2DfromDB (no)   - you can make the hitlist smaller by not saving 2D 
• l_makeUnique (no) - if you had made mulitple runs you can choose the highest scoring ligand
• l_import3D (yes) - will import 3D coordinates
• i_topScored (0) - if you had a large hitlist you can choose to import just the top hits e.g. top 1000 based on score.

Please see the GUI Manual for a description of the physics-based score (Score) and the Neural Network score (RTCCN).

Running ICM batch docking script with _dockScan

After the project, the project directory and the maps have been created, you can start docking different sets of ligands into this receptor. To run it directly by ICM instead of through an intermediate Unix shell script, use the _dockScan script.

To run the _dockScan script just run ICM and provide the script as the first argument. All _dockScan arguments need to be provided after it.

Prerequisites:Complete these steps of the Docking menu:

• Receptor Setup
• Make receptor maps
• Ligand setup ( Note: you do not need this step if you dock directly from an .sdf file)

The full syntax of the _dockScan script is the following. icm _dockScan [ optional arguments ] projName

The arguments could be the following

argument	comment	example
	dock according to parameters and ligand source settings from the file projName.dtb
input=	dock directly from an sdf file (other modes require input specification in the PROJECT.dtb file)
input=	dock peptides from an se file containing sequence(s) of aminoacid residues, which may have modifications (modres)
-a	dock and save ALL molecules, ignore filters and score threshold (default if less than 100 molecules)	icm $ICMHOME/_dockScan -a /home/dock/PROJECT
-d	docking only, NO scoring
-E	evaluates binding score for several poses, resorts them but does save all the stacks in files (convenient for screening) -S
-p	"probe" mode: dock probes from the input sdf file, encourage spacial coverage
-r	RIGID ligand docking
-s	save stacks of multiple docking poses for each ligand
-S	same as -s but reSCORE ALL saved poses, see also -E
-f	apply property filters to exclude molecules outside ranges specified in PROJECT.dtb (this is the default if there are more than 100 molecules being docked)
confs=	score/save only up to poses (with -S/-E)
from= to=	range of molecules from an indexed .sdf file or molcart ids	from=1 to=10000
jobs=	spaws n processes, default is 1
name=	the result file with poses will be named accordingly (the default is 'answers')
outdir=	directory for the output files
output=	process answers.ob into a hitlist sdf file at the end of the run
seed=|random seed from the previous docking to reproduce the results exactly
effort=|a 'thoroughness' factor that allows one to extend the docking effort or reduce it (default is 1., reasonable range from 0.5 to 20. )

Example:

Docking an sdf file (first configure the receptor, make the grid maps and setup the ligand input source in GUI).

icm _dockScan /home/gpcr/PROJECTNAME -a -S confs=10 effort=3.

This will dock all compounds with 3-fold longer (more thorough) simulations, and rescore up to 10 conformations per ligand.

If you have a cluster license without graphics you will need to use -vlscluster flag after calling icm.

icm -vlslcuster  _dockScan /home/gpcr/PROJECTNAME -a -S confs=10 effort=3.

In the /bin directory you will find a script called docksub.icm. This script prepares your docking run and distributes it via SGE or SLURM job queueing system on your cluster or cloud.

use:

$ICMHOME/icm  docksub.icm  -vlscluster <chemTable.sdf|.inx> {<dockProj>|<APF_template.mol>} [jobs=100] [-sub] [-apf] [qtype=sge|slurm] [<dockProj_and_dockScan_options>|<APF_options>]

e.g. submit 100 slurm jobs

icm64 docksub.icm qtype=slurm chemTable.inx DOCK1 jobs=100 –sub

icm64 docksub.icm input.inx DOCK1 jobs=2 proc=18

GINGER

GINGER - Graph Internal-coordinate Neural-network conformer Generator with Energy Refinement

Overview:

Read More...

Usage> icm64 _ginger input.sdf|.tsv|.csv header=no smicol=A idcol=B output.sdf|.molt

• maxenergy=(10.) : skip conformations with higher than 10. kcal/mole energies from the base
• mnconf=(30) : the maximal number of conformers per compound
• sizelimit=(60) : do not sample bigger molecules than atoms
• vicinity=(10.) : [deg] the torsion root-mean-square deviation threshold for cluster size.
• header=yes|no : for TSV/CSV input reads first line as column names
• smicol= : for TSV/CSV input name of the smiles column
• idcol= : for TSV/CSV input name of ID column
• sdfcompress=yes|no : for SDF output store each conformation as a separate MOL entry (sdfcompress=no) or into CONF_LIST list field
• -C : set formal charges according to pKa model
• -f : Force overwriting of the output file
• -h : Help
• -fr=.. -to=.. from and to indexes of the database to be screened.

Example:

  
icm64 _ginger input.csv outut.sdf header=yes -f smicol=mol idcol=id sdfcompress=yes

RIDGE

RIDGE - Rapid Docking GPU Engine

RIDGE is a very fast GPU accelerated structure-based docking method. Read More...

• To run you RIDGE you first need to setup a docking project either automated in the command line or via the GUI.
• You need to download one or more conformer databases from here
• To run RIDGE on the command line use the _ridge script in the $ICMHOME directory. See the syntax below:

$ICMHOME/icm $ICMHOME/_ridge DockingProjectName <projFile> output= .sdf [<options>] input= DB_3D_Confs.molt

Options:

• confs= : score/save only up to top poses (with -S/-E)
• randomSelect= : dock N random compounds (default - 0, dock everything )
• fr=,to=: dock range i_fr/i_to (default, dock everything )
• index=,,... : dock specific ID numbers
• output=<.sdf> : process answers.ob into a hitlist sdf file or icb at the end of the run
• gpuid= : use specific GPU (default -1)
• scoreCutoff=: accept ligs with score better than Default: -25
• clashWeight= : clash penalty weight (default 20.)
• clashScale= : clash van der Waals scale (default 0.82)
• threads= : GPU threads per block (default 1024)
• -C : perform cartesian optimization for best poses
• -S : rescore with physics-based ICM VLS score

We recommend to use if possible a most recent NVIDIA GPU. For optimal performance you would use a GEFORCE 4090 but RIDGE will run on older versions (e.g. 3090 2080).

Please note multiple .molt files can be screened using comma separated filenames.

Example

Dock 1000 random compounds from /path/to/conf_db.molt with Cartesian minimization (-C)

$ICMHOME/icm64 $ICMHOME/_ridge <mydockProj> -C input=/path/to/conf_db.molt randomSelect=1000  

Template constrained docking

It is possible to use a template object to tether part of the ligand structure to a preferred position during the docking simulation. Prepare an object file containing the group of atoms to be tethered to. Edit the .dtb docking setup file, setting the s_templateObj field to the name of the template object file (it is 'none' by default). The variable l_superByName controls the way correspondence is established between the ligand and template atoms. If it is 'no', chemical substructure search is performed and tethers imposed according to the substructure match. If l_superByName is 'yes', simple matching according to atom names is performed. Tethers can be individually weighted by assigning b-factor values to the template atoms. Weights are reversely proportional to b-factor, default b-factor of 20. corresponds to the weight of 1.

V-SYNTHES

V-SYNTHES is a method that allows you to screen the Enamine REAL Space library (~21 Billion Chemicals). Read more here. V-SYNTHES requires an additional license - once the license is acquired MolSoft will send you the following files:

• scripts.zip # scripts and protocol description
• markush.zip # Enamine enumeration stuff
• files_MEL_example.zip # small example Minimal Enumeration Library (MEL) file for testing if you have a trial license
• files_MEL_all.zip # full MEL

Unpack the files:

• unpack scripts.zip and copy eveything into working folder ( e.g: 'vsyn_example' )
• unpack markush.zip and MEL library

Create a link to MEL library and Markush

cd vsyn_example
ln -s /path/to/files_MEL_example files   # or files_MEL_all
ln -s /path/to/markush markush

Create your docking Project

You can setup your docking project files in the GUI or fully automated in the command line using _dockBatch

STEP 1 - Minimal Enumeration Library (MEL) Docking
Create directory 'run' in the main 'vsyn_example'

mkdir run 

Copy docking project files to the 'run' directory .dtb _rec.ob _*.map

Submit docking job(s) in 'run' directory Single Machine

$ICMHOME/icm64 _dockScan <dockproj> input=../files/files_MEL_275592_.inx effort=2. scoreCutoff=-18. name=files_MEL_275592_ proc=<n_parallel>
<c>
$ICMHOME/icm64 _dockScan <dockproj> input=../files/files_MEL_2comp_.inx effort=2. scoreCutoff=-18. name=files_MEL_2comp_ proc=<n_parallel>

Cluster using docksub.icm script in /bin directory

$ICMHOME/icm64 docksub.icm ../files/files_MEL_275592_.inx <dockproj> jobs=<n_jobs> effort=2. scoreCutoff=-18. name=files_MEL_275592_ proc=<n_proc>

$ICMHOME/icm64 docksub.icm ../files/files_MEL_2comp_.inx <dockproj> jobs=<n_jobs> effort=2. scoreCutoff=-18. name=files_MEL_2comp_  proc=<n_proc> 

At the end of this stage you expect multiple answer files in the 'run' directory.

_files_MEL_275592_*.ob _files_MEL_2comp_*.ob

STEP 2.1 (Load and Process Hits)

cd ..   #  go to main 'vsyn_example' directory)
$ICMHOME/icm64 icm_load_hits_enamine_CARC_062021.icm
bash CapSelectMP_full.sh

STEP 2.2 (Enumerate)

# Default number of output molecules is 2500000
# This can be changed by editing script icm_enumerate_REAL_frags_112021_chunkify_charge_CARC.icm
# MAX_MOLS="2500000"

$ICMHOME/icm64 icm_enumerate_REAL_frags_112021_chunkify_charge_CARC.icm

# Result files will be placed into

run/processing_files/enumerated_best_frags_<dockproj>__<MAX_MOLS>/*.sdf 

STEP 3 (Dock final hits)

• concatenate individual SDF into final docking selection

cat run/processing_files/enumerated_best_frags_<dockproj>__<MAX_MOLS>/*.sdf > run/enumerated_best_frags_all.sdf

• Index and Dock run/enumerated_best_frags_all.sdf to get final poses

GigaScreen

The GigaScreen method combines machine learning and deep learning tools to tackle the computational intensity of screening very large chemical databases. To overcome these challenges several protocols are employed:

• MolSoft's RIDGE as a structure-based docking engine.
• MolSoft's neural network scoring function RTCNN.
• Chemical GCNN model.

Read more here about GigaScreen.

System Requirements

• Linux workstation (preferably Ubuntu 20.x or higher)
• CUDA 11.x or higher
• GPU >= RTX 3090 or equivalent
• RAM 64Gb or more

How to run GigaScreen:

1) Download and install icm-mxnet package - contact MolSoft to download this package and a RIDGE GPU license is required.

sh icm-mxnet-3.9-3b-linux.sh -p/path/to/icm393b
export ICMHOME=/path/to/icm393b

Make sure you can run the binary (no missing dependencies)

$ICMHOME/icm64 

1.1) Download compressed conformation DB - contact MolSoft to obtain these databases.

2) gigaScreen.icm script is provided with distribution ($ICMHOME/bin/gigaScreen.icm)

2.1) create working directory and copy docking project files

mkdir giga_test
cd giga_test

# docking project consists of following files (copy them into working directory) .dtb _rec.ob *.map

2.2) run gigaScreen.icm inside working directory

$ICMHOME/icm64 gigaScreen.icm project=<dock_proj> niter=5 /path/to/REAL/*.molt

That should perform 5 iterations of RIDGE/Build Model/Predict + Final Docking

All intermediate results will be stored inside 'screen_out' directory

Each stage will create the following files:

* ridge_out_.csv # return of RIDGE docking (scores + compound IDs) * M_score_cnn_.icb # GCNN model built from RIDGE/RTCNN scores * top_score_out_.csv # result of applying model to the entire DB (top hits) This will be used as RIDGE input on the next operation

Final Docking will be saved as screen_out/ridge_final.sdf