PyPLIF HIPPOS Documentation

PyPLIF HIPPOS DocumentationRelease 0.1

Muhammad Radifar

Sep 13, 2021

CONTENTS:

1 PyPLIF HIPPOS: A Molecular Interaction Fingerprinting Tool for Docking Results of AutoDock Vinaand PLANTS 1

2 Citing HIPPOS 5

3 Acknowledgment 73.1 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73.2 Parameter Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93.3 Generating Reference Bitstring using HIPPOS-genref . . . . . . . . . . . . . . . . . . . . . . . . . 103.4 HIPPOS-genref Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143.5 Getting Started (HIPPOS on VINA) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153.6 Getting Started (HIPPOS on PLANTS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203.7 Advanced Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253.8 HIPPOS Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283.9 LICENSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

i

CHAPTER

ONE

PYPLIF HIPPOS: A MOLECULAR INTERACTION FINGERPRINTINGTOOL FOR DOCKING RESULTS OF AUTODOCK VINA AND PLANTS

Welcome to PyPLIF-HIPPOS’s documentation. PyPLIF-HIPPOS is an upgraded version of PyPLIF (Python-basedProtein-Ligand Interaction Fingerprinting), a tool for molecular docking post-analysis. It will translate the 3Dcoordinates of both ligand(s) (generated from docking simulation) and protein into a series of interaction bitstring(also known as Interaction Fingerprint) (see image below). HIPPOS (/hipoz/) is a recursive acronym of HIPPOS IsPyPLIF On Steroids. From this point forward, PyPLIF-HIPPOS is simplified to HIPPOS.

Compared to PyPLIF, HIPPOS is not only faster and able to generate more customized interaction bitstring, but alsosupports both PLANTS & VINA! More over, unlike its predecessor it is (far) more well-documented.

1

https://github.com/radifar/pyplif/

https://uni-tuebingen.de/fakultaeten/mathematisch-naturwissenschaftliche-fakultaet/fachbereiche/pharmazie-und-biochemie/pharmazie/pharmazeutische-chemie/pd-dr-t-exner/research/plants/

http://vina.scripps.edu/

PyPLIF HIPPOS Documentation, Release 0.1

Reprinted with permission from https://doi.org/10.1021/acs.jcim.0c00305. Copyright 2020 American Chemical Soci-ety.

2 Chapter 1. PyPLIF HIPPOS: A Molecular Interaction Fingerprinting Tool for Docking Results ofAutoDock Vina and PLANTS

https://doi.org/10.1021/acs.jcim.0c00305


3


4 Chapter 1. PyPLIF HIPPOS: A Molecular Interaction Fingerprinting Tool for Docking Results ofAutoDock Vina and PLANTS

CHAPTER

TWO

CITING HIPPOS

If you are using HIPPOS please cite this paper:

Istyastono, E., Radifar, M., Yuniarti, N., Prasasty, V. and Mungkasi, S., 2020. PyPLIF HIPPOS: A Molecular Interac-tion Fingerprinting Tool for Docking Results of AutoDock Vina and PLANTS. Journal of Chemical Information andModeling. https://doi.org/10.1021/acs.jcim.0c00305

5



6 Chapter 2. Citing HIPPOS

CHAPTER

THREE

ACKNOWLEDGMENT

This project has received funding from the Indonesian National Research and Innovation Agency under grant agreementNo. 807.7/LL5/PG/2020. This project has been restructured based on the MOLSSI Computational Molecular SciencePython Cookiecutter version 1.3, and benefited greatly from MOLSSI Python Package Development Best Practicesworkshop.

3.1 Installation

3.1.1 Quick Installation (Recommended)

The easiest way to install HIPPOS is using Conda, you can choose either Anaconda or Miniconda. If you never usedConda before then most likely Miniconda is more suitable for you.

After you installed Conda in your machine, install HIPPOS using the following command:

conda install -c conda-forge pyplif-hippos

Conda will deal with the dependencies like Open Babel, Bitarray, and Numpy libraries. Therefore you won’t need theextra step below.

To check if HIPPOS installed correctly try these commands:

hippos

hippos-genref

If HIPPOS installed correctly you should get a message that inform you the configuration file not found. Next, you canjust jump to Getting Started with PLANTS or Vina tutorial. But if you prefer not to use Conda then you can installHIPPOS using the instructions below.

3.1.2 Requirement

• Python >= 2.6 or >= 3.6

• Open Babel (library) >= 2.2

• Python-OpenBabel >= 2.1

• Python-BitArray

• Python-Numpy >= 1.3

7

https://international.ristekdikti.go.id/

https://github.com/molssi/cookiecutter-cms

https://github.com/molssi/cookiecutter-cms

https://molssi.org/2020/04/20/may-webinar-series-python-package-development/

https://docs.anaconda.com/anaconda/install/


3.1.3 Getting HIPPOS

You can get HIPPOS at Github by cloning the repository or download the code here.

3.1.4 Installing on Linux

In Ubuntu you can simply enter these commands to install the requirements above (Python is already installed in Linux):

sudo apt-get install openbabel

sudo apt-get install python-openbabel

sudo apt-get install python-bitarray

sudo apt-get install python-numpy

In Fedora you can enter these commands instead:

sudo yum install openbabel

sudo yum install python-openbabel

sudo yum install python-bitarray

sudo yum install numpy

After the requirements fulfilled

After all of the dependencies installed, you can install HIPPOS by opening the terminal and enter the HIPPOS directoryand run setup.sh like so:

./setup.sh

You will be prompted with a question whether to install HIPPOS in [HOME_DIRECTORY]/.hippos which is a hiddendirectory inside your HOME_DIRECTORY. Or would you rather choose your own directory. If you want to keep the defaultthen just press enter or if you would like to choose your own installation directory you can type y and press enter, thenyou have to type the installation directory for example /home/radifar/apps/hippos then press enter.

If HIPPOS installed successfully then a message like ‘HIPPOS successfully installed’ should appear. When HIPPOSis already installed and you’re running setup.sh a message like ‘HIPPOS is already installed’ will appear, and theinstallation process will stop and exit.

If you would like to install newer version of HIPPOS and overwrite the old one then all you need to do is by adding‘force’ option to setup.sh like so:

./setup.sh force

To test if HIPPOS had been installed, open new command line window and type the following:

hippos

Then press enter. Please note that it is imperative to open the new command line window right after the installation toallow the alias in your system get updated. Next type the following:

hippos-genref

Then press enter

If there are no error message then the installation is success.

8 Chapter 3. Acknowledgment

https://github.com/radifar/PyPLIF-HIPPOS


3.1.5 Installing on Windows 10

Windows 10 provides Ubuntu in their Microsoft Store. After you successfully add Ubuntu on your Windows, the nextstep is to do the same installation steps on Ubuntu.

3.2 Parameter Options

The parameters to identify the interactions refer to those used in PyPLIF, which inspired by the IFP of Marcou andRognan. These parameters can be modified in .hippos/PARAMETERS.py in your home directory after HIPPOS in-stalled.

In general there are two rules that can be modified:

1. Maximum distance value.

2. Interaction angle limit (for hydrogen bond and aromatic interaction).

Here is the content of .hippos/PARAMETERS.py

'''Parameter for interaction distanceInteraction exist if lower or equalthan these values

'''

HYDROPHOBIC = 4.5AROMATIC = 4.0HBOND = 3.5ELECTROSTATIC = 4.0

'''Parameter for minimum H bond angle.Interaction exist if O --- H-D anglehigher or equal than HBOND_ANGLE value.

'''

HBOND_ANGLE = 135

'''Parameter for aromatic interaction angle.

Face to Face if:AROMATIC_ANGLE_LOW >= Angle between aromatic planeOr AROMATIC_ANGLE_HIGH <= Angle between aromatic plane

Edge to Face if:AROMATIC_ANGLE_LOW < Angle between aromatic plane <AROMATIC_ANGLE_HIGH

'''

AROMATIC_ANGLE_LOW = 30.0AROMATIC_ANGLE_HIGH = 150.0

The explanation of each value can be seen from the comment above the value assignment.

3.2. Parameter Options 9

https://www.microsoft.com/en-us/p/ubuntu/9nblggh4msv6

https://doi.org/10.6026/97320630009325

https://doi.org/10.1021/ci600342e

https://doi.org/10.1021/ci600342e


3.2.1 Simplified Bitstring Rule

HIPPOS provides simplified interaction bitstring to reduce unnecessary string in the output. The bitstring simplificationrule can be seen in the table below. Number 1-7 in the header of the table correspond to the interaction type describedin PyPLIF

1 Correspond to Hydrophobic2 Correspond to Aromatic Face to Face3 Correspond to Aromatic Edge to Face4 Correspond to H-bond (protein is donor)5 Correspond to H-bond (protein is acceptor)6 Correspond to Electrostatic (protein +)7 Correspond to Electrostatic (protein -)

3.3 Generating Reference Bitstring using HIPPOS-genref

3.3.1 Generating Reference Bitstring with Backbone (Default Setting)

Reference bitstring is an essential requirement for similarity coefficient (eg. Tanimoto or McConnaughey coefficient)calculation, which is the common method for comparing the interaction fingerprinting of a test compound and a refer-ence (native ligand) interactions on certain protein.

To generate Reference bitstring, first of all, you need to open the command prompt and enter the examples\01-na_reference folder. This example uses the Neuraminidase enzyme for two reasons, first, it is one of the enzymesused in DUD-E (Directory of Useful Decoy Enhanced) therefore you could use it to measure the effect of interactionfingerprinting on the enrichment factor. Second, it can demonstrate all of the seven interaction types in interactionfingerprinting.

As you can see there are three folders and two txt configuration files. Each folder represents a crystal structure ofNeuraminidase, and contain the original PDB file and the split component (protein, ligand, and water) generated withSPORES. PDB file alone can not be used as the reference, it has to be in mol2 or pdbqt to ensure that the atomtyping, charge assignment, and protonation is identical to the docking environment (whether for PLANTS or VINA).So the PDB files here only act as the source if you want to use PDBQT files as the reference instead. 1b9s, 1b9t, and1b9v are the PDB ID of the same Neuraminidase, where each of them bound to different ligand (FDI, RAI, and RA2respectively). Therefore the protein name and ligand name should use protein.mol2 and the corresponding ligand filename as you can see in genref-config.txt.

# first residue is 77residue_name ARG116 GLU117 LEU132 LYS148 ASP149 ARG150 ARG154 TRP177 SER178 ILE221␣→˓ARG223 THR224 GLU226 ALA245 HIS273 GLU275 GLU276 ARG292 ASP294 GLY347 ARG374 TRP408␣→˓TYR409residue_number 40 41 56 72 73 74 78 101 102 145 147 148 150 169 197 199 200 216 218 271␣→˓298 332 333

proteins 1b9s/protein.mol2 1b9t/protein.mol2 1b9v/protein.mol2ligands 1b9s/ligand_FDI468_0.mol2 1b9t/ligand_RAI468_0.mol2 1b9v/ligand_RA2468_0.→˓mol2

outfile ref-results.txt

The first line is merely the commented line, everything started with # sign will be ignored by hippos andhippos-genref. If you open the mol2 protein file with a text editor you will see that the first residue is Glutamatewith residue number 77. However, when the file is read by Openbabel it will count as residue number 1.


https://uni-tuebingen.de/fakultaeten/mathematisch-naturwissenschaftliche-fakultaet/fachbereiche/pharmazie-und-biochemie/pharmazie/pharmazeutische-chemie/pd-dr-t-exner/research/spores/


This is where things started to get tricky, because we have to supply both residue_name and residue_numberproperly, or else it will not work as to how we want it to be. residue_name can be acquired easily by converting yourprotein into mol2 format, while the corresponding residue_number must be retrieved from the column before residuename (eg. residue name ARG116 and GLU117 correspond to residue number 40 and 41 respectively):

The residue_name and residue_number in genref-config above are retrieved by visualizing any residue within5 angstroms from the native ligand using VMD (you can use any other molecule visualization tool), regardless of howimportant the residue in enzyme inhibition.

The next lines are proteins and ligands, notice that there are 3 protein molecules and 3 ligand molecules whichmeans that there are 3 protein-ligand pairs as references. Where the first protein will be matched with first ligandand so on. However in most cases, one protein-ligand pair is enough, this example uses 3 protein-ligand pairs as ademonstration of multiple references.

The last line is the output file name, it is optional so when not defined the output file will be genref-results.txt.

3.3. Generating Reference Bitstring using HIPPOS-genref 11


After we understand the input file and the configuration file, hippos-genref could be run with the following command:

hippos-genref genref-config.txt

After hippos-genref finished file ref-results.txt will be generated.

Inside ref-results.txt we can see that there are 3 results from 3 protein-ligand pairs. Each result consisted of protein-ligand pair name and interaction bitstring where each residue represented by 7 bit of interactions from both the side-chain and the backbone.

3.3.2 Generating Reference Bitstring without Backbone

Sometimes we would like to omit the interaction between ligand and the backbone protein. In that case, we shouldchange the output_mode to full_nobb by adding output_mode full_nobb to our hippos-genref config file asappear in genref-config-nobb.txt


proteins 1b9s/protein.mol2 1b9t/protein.mol2 1b9v/protein.mol2ligands 1b9s/ligand_FDI468_0.mol2 1b9t/ligand_RAI468_0.mol2 1b9v/ligand_RA2468_0.mol2

output_mode full_nobb

outfile ref-results-nobb.txt

Now run hippos-genref again with the following command:

hippos-genref genref-config-nobb.txt

After hippos-genref finished file ref-results-nobb.txt will be generated.



Just like in the default setting, it will generate 3 results. And although they appear the same as before, this time thebitstrings are generated without taking backbone atoms into account.

3.3.3 Generating Simplified Reference Bitstring

It is also possible to calculate simplified interaction between ligand and the backbone protein. In that case, we shouldchange the output_mode to simplified by adding output_mode simplified to our hippos-genref config file asappear in genref-config-simplified.txt


proteins 1b9s/protein.mol2 1b9t/protein.mol2 1b9v/protein.mol2ligands 1b9s/ligand_FDI468_0.mol2 1b9t/ligand_RAI468_0.mol2 1b9v/ligand_RA2468_0.mol2

output_mode simplified

outfile ref-results-simplified.txt

Now run hippos-genref again with the following command:

hippos-genref genref-config-simplified.txt

After hippos-genref finished file ref-results-simplified.txt will be generated.

3.3. Generating Reference Bitstring using HIPPOS-genref 13


Just like in the default setting, it will generate 3 results. And although they appear the same as before, this time thebitstrings are simplified.

3.4 HIPPOS-genref Configuration Options

There are two kinds of options, essential and optional. When nothing declared it means the option is essential. Someoptions have default value. Also keep in mind that all file names must never use space! So use underscore instead.

You can also inserting comments at the beginning of the line or after the option-value pair by inserting the # sign beforethe comment. Everything inserted after the # sign will be ignored by the software.

3.4.1 Input Options

• residue_name value: list of residue_name , eg. ASP107 SER111 THR112

The list of residue_name, each residue separated by space. It is used in PLANTS post-analysis but notin VINA analysis as pdbqt don’t hold the residue_name-residue_number pair field. However it is highlyrecommended to define it in VINA post analysis as it will be included in output file, making the resultseasier to interpret.

• residue_number value: list of residue_number , eg. 80 84 85

The list of residue number, each number separated by space. Essential option in VINA post-analysis butoptional in PLANTS post-analysis.

• proteins value: list of reference_protein, eg. protein1.mol2 protein2.mol2 protein3.mol2

The list of reference_protein structure, each reference separated by space. Must be in mol2 or pdbqt format.

• ligands value: list of reference_ligand , eg. ligand1.mol2 ligand2.mol2 ligand3.mol2

The list of reference_ligand structure, each reference separated by space. Must be in mol2 or pdbqt for-mat. Please note that the first reference_protein will be paired with first reference_ligand, the second refer-ence_protein will be paired with second reference_ligand, and so on.



3.4.2 Output Options

• outfile (optional) value: output_file_name, default genref-results.txt

3.4.3 Advanced Options

• output_mode (optional) value: output_mode , default: full, options: full, full_nobb, and simplified

output_mode define the bistring calculation and output. fullmeans all interaction including the backboneinteraction taken into account. full_nobb means backbone interactions are omitted. simplified meansirrelevant interaction omitted (see Simplified Bitstring Rule). When this option not used output_modefull will be used.

3.5 Getting Started (HIPPOS on VINA)

There are two ways to use HIPPOS, the first one is to use HIPPOS without any reference, and the second one is to useHIPPOS with reference and calculate the similarity coefficient against the reference.

3.5.1 Generating Protein-Ligand Interaction Bitstring without reference

First, enter the examples folder and check the configuration example for this method, config-vina-na-notc.txt

docking_method vina # plants or vinadocking_conf 03-na_vina/vina-003.conf

residue_name ARG116 GLU117 LEU132 LYS148 ASP149 ARG150 ARG154 TRP177 SER178 ILE221␣→˓ARG223 THR224 GLU226 ALA245 HIS273 GLU275 GLU276 ARG292 ASP294 GLY347 ARG374 TRP408␣→˓TYR409residue_number 40 41 56 72 73 74 78 101 102 145 147 148 150 169 197 199 200 216 218 271␣→˓298 332 333

full_outfile vina_notc_ifp.csvlogfile vina_notc.log

The configuration here is pretty much self-explaining. docking_method here is vina, which correspond to the dockingresult we would like to analyse. Then the docking_conf is the configuration file used for docking, HIPPOS requirethis file to find the details about docking input and output from Vina.

For residue_name and residue_number check the explanation for the configuration on generating reference withHippos-genref for more details.

Next, you can run HIPPOS by entering the following command:

hippos config-vina-na-notc.txt

After the calculation finished HIPPOS will generate 2 files, vina_notc.log and vina_notc_ifp.csv. vina_notc.log con-tain the information about ligand name, number of poses, and the running time. If output_mode set to simplifiedor combo there will be a table for bit position for each residue (useful for deciphering the simplified bitstring). Thevina_notc_ifp.csv file will contain the ligand name, pose number, energy from docking result, and the interaction bit-string as can be seen below:

3.5. Getting Started (HIPPOS on VINA) 15


In the next section you will learn how to not only generate the interaction bitstring but also calculate the similaritycoefficient using reference bitstring.

3.5.2 Generating Protein-Ligand Interaction Bitstring and Similarity coefficient

This procedure will require a reference bitstring which can be generated using hippos-genref included in the package.Open this link to learn how to generate the reference bitstring.

After we acquire the full bitstring we can use it for reference bitstring as shown in examples/04-na_config_default/config-vina-na-tc-mc.txt which is the configuration file for HIPPOS

docking_method vina # plants or vinadocking_conf ../03-na_vina/vina-003.conf

similarity_coef tanimoto mcconnaughey

full_ref ␣→˓00000100000000000000000000000000000100000000000001000000000000010000001000000000000000000001000000000000000000000000000000101000000000000000000101000000000010000␣→˓00010101000000000000000000000000000100000000000001010000000000010000001000000000000010000000000000000000000001011000001000001000000000000000000101000000000000000␣→˓00010101000000100000000000000000000100000000000001010100100000010000001000000000000010000001000000000000010000000000100000101010000000000000000001000000000000000


full_outfile vina_full_ifp.csv(continues on next page)



(continued from previous page)

sim_outfile vina_similarity.csvlogfile vina.log

Always remember that full_ref should be using the full bitstring from reference. Using bitstring reference ofdifferent length will cause an error and the program will stop.

Here the residue_name and residue_number must be the same as the one used for reference bitstring generation, andyou have to set similarity_coef value, such as tanimoto or mccounaughey or both of them.

docking_method here is vina which correspond to the docking result we would like to analyse. Then thedocking_conf is the configuration file used for docking, HIPPOS require this file to find the details about dockinginput and output from Vina.

Next, run HIPPOS with the following command inside examples directory:

hippos config-vina-na-tc-mc.txt

there will be 3 output file vina.log, vina_similarity.csv, and vina_full_ifp.csv. The vina_full_ifp.csv will be the same asthe one without reference above. The vina_similarity.csv contain the similarity coefficient for every pose comparison.Notice that there are 6 similarity coefficient results which correspond to Tanimoto coefficient and McConnaugheycoefficient calculation for 3 reference bitstring

Last but not least the hippos.log contain the information about ligand name, number of poses, similarity coefficient used,and the table for bit position for each residue (only appear when output_mode set to simplified, useful for decipheringthe simplified bitstring), and the total time taken.



3.5.3 Generating Protein-Ligand Interaction Bitstring and Similarity coefficient(without Backbone)

The example above is the default setting where the interaction between ligand and protein backbone is included. Toomit the interaction between ligand and protein backbone, we need to set the output_mode value to full_nobb, and inorder for this setting to work properly we also need to change the bitstring reference (full_nobb_ref) accordingly (seehow to generate bitstring reference without backbone). Here is the content of configuration file example examples/05-na_config_nobb/config-vina-na-tc-mc.txt




full_nobb_ref ␣→˓00000100000000000000000000000000000100000000000001000000000000010000001000000000000000000001000000000000000000000000000000101000000000000000000101000000000010000␣→˓␣→˓00010101000000000000000000000000000100000000000001010000000000010000001000000000000010000000000000000000000001011000001000001000000000000000000101000000000000000␣→˓␣→˓00010101000000100000000000000000000100000000000001010000000000010000001000000000000010000001000000000000010000000000100000101010000000000000000001000000000000000


full_nobb_outfile vina_nobb_ifp.csvsim_outfile vina_similarity.csvlogfile vina.log

Always remember that full_nobb_ref should be using the full_nobb bitstring from reference. Using bitstringreference of different length will cause an error and the program will stop.

Like before, run hippos with the following command:


Just like before, 3 output file will be generated, but the fingerprint (vina_nobb_ifp.csv) and vina_similarity.csv willbe different.

3.5.4 Generating Simplified Interaction Bitstring and Similarity coefficient

It is also possible to calculate simplified interaction between ligand and protein. To do so set the output_modevalue to simplified, and in order for this setting to work properly we also need to change the bitstring reference(simplified_ref) accordingly (see how to generate simplified bitstring reference). Here is the content of configura-tion file example examples/06-na_config_simplified/config-vina-na-tc-mc.txt


(continues on next page)






simplified_ref 0010000000000100000100000110000000010000000000000110000011000000100 ␣→˓0111000000000100000101000110000010000000000111010010000011000000000 ␣→˓0111001000000100000101000110000010010000001000100111000001000000000


simplified_outfile vina_simplified_ifp.csvsim_outfile vina_similarity.csvlogfile vina.log

Always remember that simplified_ref should be using the simplified bitstring from reference. Using bitstringreference of different length will cause an error and the program will stop.



Just like before, 3 output file will be generated, but the fingerprint (vina_simplified_ifp.csv) andvina_similarity.csv will be different.

3.5.5 Generating Multiple Interaction Bitstring

Last but not least, multiple output_mode is also allowed in generation interaction bitstring but without calculation ofsimilarity coefficient. Here is the content of the configuration file example examples/07-na_config_multiple/config-vina-na.txt


output_mode full full_nobb simplified


full_outfile vina_full.csvfull_nobb_outfile vina_nobb.csvsimplified_outfile vina_simplified_ifp.csvlogfile vina.log




hippos config-vina-na.txt

Now, four output file will be generated, three for three different output, and one for the log file.

3.6 Getting Started (HIPPOS on PLANTS)

There are two ways to use HIPPOS, the first one is to use HIPPOS without any reference, and the second one is to useHIPPOS with reference and calculate the similarity coefficient against the reference.

3.6.1 Generating Protein-Ligand Interaction Bitstring without reference

First, enter the examples folder and check the configuration example for this method, config-plants-na-notc.txt

docking_method plants # plants or vinadocking_conf 02-na_plants/plants-003.conf

residue_name ARG116 GLU117 LEU132 LYS148 ASP149 ARG150 ARG154 TRP177 SER178 ILE221␣→˓ARG223 THR224 GLU226 ALA245 HIS273 GLU275 GLU276 ARG292 ASP294 GLY347 ARG374 TRP408␣→˓TYR409residue_number 40 41 56 72 73 74 78 101 102 145 147 148 150 169 197 199 200 216 218␣→˓271 298 332 333

full_outfile plants_notc_ifp.csvlogfile plants_notc.log

The configuration here is pretty much self-explaining. docking_method here is plants, which correspond to the dock-ing result we would like to analyse. Then the docking_conf is the configuration file used for docking, HIPPOS requirethis file to find the details about docking input and output from PLANTS.

For residue_name and residue_number check the explanation for the configuration on generating reference withHippos-genref for more details.

Next, you can run HIPPOS by entering the following command:

hippos config-plants-na-notc.txt

After the calculation finished HIPPOS will generate 2 files, hippos.log and plants_notc_ifp.csv. plants_notc.log con-tain the information about ligand name, number of poses, and the running time. If output_mode set to simplifiedor combo there will be a table for bit position for each residue (useful for deciphering the simplified bitstring). Theplants_notc_ifp.csv file will contain the ligand name, pose number, energy from docking result, and the interactionbitstring as can be seen below:



In the next section you will learn how to not only generate the interaction bitstring but also calculate the similaritycoefficient using reference bitstring.

3.6.2 Generating Protein-Ligand Interaction Bitstring and Similarity coefficient

This procedure will require a reference bitstring which can be generated using hippos-genref included in the package.Open this link to learn how to generate the reference bitstring.

After we acquire the full bitstring we can use it for reference bitstring as shown in examples/04-na_config_default/config-plants-na-tc-mc.txt which is the configuration file for HIPPOS

docking_method plants # plants or vinadocking_conf ../02-na_plants/plants-003.conf


full_ref ␣→˓00000100000000000000000000000000000100000000000001000000000000010000001000000000000000000001000000000000000000000000000000101000000000000000000101000000000010000␣→˓00010101000000000000000000000000000100000000000001010000000000010000001000000000000010000000000000000000000001011000001000001000000000000000000101000000000000000␣→˓00010101000000100000000000000000000100000000000001010100100000010000001000000000000010000001000000000000010000000000100000101010000000000000000001000000000000000


full_outfile plants_full_ifp.csv(continues on next page)

3.6. Getting Started (HIPPOS on PLANTS) 21



sim_outfile plants_similarity.csvlogfile plants.log

Always remember that full_ref should be using the full bitstring from reference. Using bitstring reference ofdifferent length will cause an error and the program will stop.

Here the residue_name and residue_number must be the same as the one used for reference bitstring generation, andyou have to set similarity_coef value, such as tanimoto or mccounaughey or both of them.

docking_method here is plants which correspond to the docking result we would like to analyse. Then thedocking_conf is the configuration file used for docking, HIPPOS require this file to find the details about dockinginput and output from PLANTS.

Next, run HIPPOS with the following command inside examples directory:

hippos config-plants-na-tc-mc.txt

there will be 3 output file plants.log, plants_similarity.csv, and plants_full_ifp.csv. The plants_full_ifp.csv will bethe same as the one without reference above. The plants_similarity.csv contain the similarity coefficient for everypose comparison. Notice that there are 6 similarity coefficient results which correspond to Tanimoto coefficient andMcConnaughey coefficient calculation for 3 reference bitstring

Last but not least the plants.log contain the information about ligand name, number of poses, similarity coefficient used,and the table for bit position for each residue (only appear when output_mode set to simplified, useful for decipheringthe simplified bitstring), and the total time taken.



3.6.3 Generating Protein-Ligand Interaction Bitstring and Similarity coefficient(without Backbone)

The example above is the default setting where the interaction between ligand and protein backbone is included. Toomit the interaction between ligand and protein backbone, we need to set the output_mode value to full_nobb, and inorder for this setting to work properly we also need to change the bitstring reference (full_nobb_ref) accordingly (seehow to generate bitstring reference without backbone). Here is the content of configuration file example examples/05-na_config_nobb/config-plants-na-tc-mc.txt)




full_nobb_ref ␣→˓00000100000000000000000000000000000100000000000001000000000000010000001000000000000000000001000000000000000000000000000000101000000000000000000101000000000010000␣→˓␣→˓00010101000000000000000000000000000100000000000001010000000000010000001000000000000010000000000000000000000001011000001000001000000000000000000101000000000000000␣→˓␣→˓00010101000000100000000000000000000100000000000001010000000000010000001000000000000010000001000000000000010000000000100000101010000000000000000001000000000000000


full_nobb_outfile plants_nobb_ifp.csvsim_outfile plants_similarity.csvlogfile plants.log

Always remember that full_nobb_ref should be using the full_nobb bitstring from reference. Using bitstringreference of different length will cause an error and the program will stop.



Just like before, 3 output file will be generated, but the fingerprint (plants_nobb_ifp.csv) and plants_similarity.csvwill be different.

3.6.4 Generating Simplified Interaction Bitstring and Similarity coefficient

It is also possible to calculate simplified interaction between ligand and protein. To do so set the output_modevalue to simplified, and in order for this setting to work properly we also need to change the bitstring reference(simplified_ref) accordingly (see how to generate simplified bitstring reference). Here is the content of configura-tion file example examples/06-na_config_simplified/config-plants-na-tc-mc.txt



3.6. Getting Started (HIPPOS on PLANTS) 23





simplified_ref 0010000000000100000100000110000000010000000000000110000011000000100 ␣→˓0111000000000100000101000110000010000000000111010010000011000000000 ␣→˓0111001000000100000101000110000010010000001000100111000001000000000


simplified_outfile plants_simplified_ifp.csvsim_outfile plants_similarity.csvlogfile plants.log

Always remember that simplified_ref should be using the simplified bitstring from reference. Using bitstringreference of different length will cause an error and the program will stop.



Just like before, 3 output file will be generated, but the fingerprint (plants_simplified_ifp.csv) andplants_similarity.csv will be different.

3.6.5 Generating Multiple Interaction Bitstring

Last but not least, multiple output_mode is also allowed in generation interaction bitstring but without calculation ofsimilarity coefficient. Here is the content of the configuration file example examples/07-na_config_multiple/config-plants-na.txt


output_mode full full_nobb simplified


full_outfile plants_full.csvfull_nobb_outfile plants_nobb.csvsimplified_outfile plants_simplified_ifp.csvlogfile plants.log




hippos config-plants-na.txt

Now, four output file will be generated, three for three different output, and one for the log file.

3.7 Advanced Usage

3.7.1 Customize Bitstring by Omitting Specific Interactions

It is possible to omit certain interaction(s) in selected residue(s). This will cause PyPLIF HIPPOS to replace the omittedinteraction in the bitstring with n character (eg. from 1010001 to 1n10001). As a consequence, the omitted interactionwill not be included in similarity calculation. This is done by removing the omitted interaction bit both in the targetand the reference bitstring. As a result the similarity coefficient could be different from the default one.

To omit interaction just add the following line to the configuration file:

omit_interaction interaction_type residue_name [single or multiple]

where interaction_type is one of the following value:

• hydrophobic or HPB

• aromatic or ARM

• h_bond or HBD

• electrostatic or ELE

• h_bond_donor or HBD_DON

• h_bond_acceptor or HBD_ACC

• electrostatic_positive or ELE_POS

• electrostatic_negative or ELE_NEG

• aromatic_facetoface or ARM_F2F

• aromatic_edgetoface or ARM_E2F

As for the residue_name it could be one or more residue name. Here is one example of a valid omit_interactiondefinition:

omit_interaction hydrophobic ARG223

As a quick start here is three different scenario on omitting interaction.

Omit single interaction

This configuration file (examples-input/08-na_omit_interaction/vina-omit-simple.txt) shows how you can omit hy-drophobic interaction on ARG223 residue



full_ref ␣→˓00000100000000000000000000000000000100000000000001000000000000010000001000000000000000000001000000000000000000000000000000101000000000000000000101000000000010000␣→˓␣→˓00010101000000000000000000000000000100000000000001010000000000010000001000000000000010000000000000000000000001011000001000001000000000000000000101000000000000000␣→˓␣→˓00010101000000100000000000000000000100000000000001010000000000010000001000000000000010000001000000000000010000000000100000101010000000000000000001000000000000000


3.7. Advanced Usage 25





full_outfile omit-simple.csvsim_outfile omit-simple-similarity.csvlogfile omit-simple.log

Here is the excerpt from the bitstring output using the above configuration file

129821_1 -6.9 ␣→˓0000000100000000000000000000100000010010000000000000000000000001000000n000000000000010000001000000000000000000000000000000100000000010000000000100000000000001000129821_2 -6.8 ␣→˓0000000000000000000000000000000000010000000000000101000000000001000000n000000000000000000001000000000000000001010000000000100000000010000000000000000000000001000129821_3 -6.6 ␣→˓0000000000000000000000000000100000110000000000000101000000000001000000n000000000000000000001000000000000000000000000000000000000000000000000000000000000000000000129821_4 -6.4 ␣→˓0000000000000000000000000000100010000000000000000000000000000001000000n000000000000000000001000000000000000000010000101000000000000000000000000000000000000000000129821_5 -6.2 ␣→˓0000000000000000000000000000100000010000000000000101000000000001000000n000000000000000000001000000000000000000000000000000000000001010000000000100000000000001000

Notice that there is an n character that replace one of the bit.

Omit single interaction in several residue

The following configuration file (examples-input/08-na_omit_interaction/vina-omit-residues.txt) shows how you canomit hydrophobic interaction on ARG150 TRP177 ARG223 residues



full_ref ␣→˓00000100000000000000000000000000000100000000000001000000000000010000001000000000000000000001000000000000000000000000000000101000000000000000000101000000000010000␣→˓␣→˓00010101000000000000000000000000000100000000000001010000000000010000001000000000000010000000000000000000000001011000001000001000000000000000000101000000000000000␣→˓␣→˓00010101000000100000000000000000000100000000000001010000000000010000001000000000000010000001000000000000010000000000100000101010000000000000000001000000000000000

omit_interaction hydrophobic ARG150 TRP177 ARG223






full_outfile omit-residues.csvsim_outfile omit-residues-similarity.csvlogfile omit-residues.log


129821_1 -6.9 ␣→˓00000001000000000000000000001000000n0010000000000n00000000000001000000n000000000000010000001000000000000000000000000000000100000000010000000000100000000000001000129821_2 -6.8 ␣→˓00000000000000000000000000000000000n0000000000000n01000000000001000000n000000000000000000001000000000000000001010000000000100000000010000000000000000000000001000129821_3 -6.6 ␣→˓00000000000000000000000000001000001n0000000000000n01000000000001000000n000000000000000000001000000000000000000000000000000000000000000000000000000000000000000000129821_4 -6.4 ␣→˓00000000000000000000000000001000100n0000000000000n00000000000001000000n000000000000000000001000000000000000000010000101000000000000000000000000000000000000000000129821_5 -6.2 ␣→˓00000000000000000000000000001000000n0000000000000n01000000000001000000n000000000000000000001000000000000000000000000000000000000001010000000000100000000000001000

Notice that there are three n, each of them replace hydrophobic interaction in one residue.

Omit more than one interaction

And here is how you can omit more than one interaction, this configuration file (examples-input/08-na_omit_interaction/vina-omit-interactions.txt) shows you how to omit the hydrophobic interaction on ARG223 andhydrogen bond (both as donor and acceptor) on ARG292



full_ref ␣→˓00000100000000000000000000000000000100000000000001000000000000010000001000000000000000000001000000000000000000000000000000101000000000000000000101000000000010000␣→˓␣→˓00010101000000000000000000000000000100000000000001010000000000010000001000000000000010000000000000000000000001011000001000001000000000000000000101000000000000000␣→˓␣→˓00010101000000100000000000000000000100000000000001010000000000010000001000000000000010000001000000000000010000000000100000101010000000000000000001000000000000000

omit_interaction hydrophobic ARG223omit_interaction h_bond ARG292


full_outfile omit-interactions.csvsim_outfile omit-interactions-similarity.csvlogfile omit-interactions.log


3.7. Advanced Usage 27


129821_1 -6.9 ␣→˓0000000100000000000000000000100000010010000000000000000000000001000000n000000000000010000001000000000000000000000000000000nn0000000010000000000100000000000001000129821_2 -6.8 ␣→˓0000000000000000000000000000000000010000000000000101000000000001000000n000000000000000000001000000000000000001010000000000nn0000000010000000000000000000000001000129821_3 -6.6 ␣→˓0000000000000000000000000000100000110000000000000101000000000001000000n000000000000000000001000000000000000000000000000000nn0000000000000000000000000000000000000129821_4 -6.4 ␣→˓0000000000000000000000000000100010000000000000000000000000000001000000n000000000000000000001000000000000000000010000101000nn0000000000000000000000000000000000000129821_5 -6.2 ␣→˓0000000000000000000000000000100000010000000000000101000000000001000000n000000000000000000001000000000000000000000000000000nn0000001010000000000100000000000001000

Notice that there are three n, the first one is replacing the hydrophobic interaction on ARG223, while the second andthird both are replacing the hydrogen bond interaction on ARG292.

3.8 HIPPOS Configuration Options

There are two kinds of options, essential and optional. When nothing declared it means the option is essential. Someoptions have default value. Also keep in mind that all file names must never use space! So use underscore instead.

You can also inserting comments at the beginning of the line or after the option-value pair by inserting the # sign beforethe comment. Everything inserted after the # sign will be ignored by the software.

3.8.1 Basic Options

• docking_method value: vina or plants

• docking_conf value: docking_configuration_file_name , eg. vina.conf or plants.conf

3.8.2 Input Options

• residue_name value: list of residue_name , eg. ASP107 SER111 THR112

The list of residue_name, each residue separated by space. It is used in PLANTS post-analysis but notin VINA analysis as pdbqt don’t hold the residue_name-residue_number pair field. However it is highlyrecommended to define it in VINA post analysis as it will be included in output file, making the resultseasier to interpret.

• residue_number value: list of residue_number , eg. 80 84 85

The list of residue number, each number separated by space. Essential option in VINA post-analysis butoptional in PLANTS post-analysis.

• similarity_coef (optional) value: list of similarity_coef , eg. tanimoto or mcconnaughey ortanimoto mcconnaughey

If the value is set then full_ref or full_nobb_ref or simplified_ref (depends on output_mode used) mustbe provided, so interaction fingerprint can be compared against reference.

– full_ref value: bitstring1 bitstring2 ... n

At least 1 uniform bitstring must be provided

– full_nobb_ref value: bitstring1 bitstring2 ... n

At least 1 uniform bitstring must be provided



– simplified_ref value: bitstring1 bitstring2 ... n

At least 1 simplified bitstring must be provided

3.8.3 Output Options

• full_outfile (optional) value: full_output_file_name , default: full_ifp.csv

Only used by full output_mode. It is recommended to use the csv extensions for clarity.

• full_nobb_outfile (optional) value: full_output_file_name , default: full_nobb_ifp.csv

Only used by full_nobb output_mode. It is recommended to use the csv extensions for clarity.

• simplified_outfile (optional) value: simplified_output_file_name , default: simplified_ifp.csv

Only used by simplified output_mode. It is recommended to use the csv extensions for clarity.

• sim_outfile (optional) value: similarity_output_file_name, default: similarity.csv

Only used when the similarity coefficient is calculated.

• logfile (optional) value: log_file_name , default: hippos.log

3.8.4 Advanced Options

• output_mode (optional) value: list of output_mode , default: full, options: full, full_nobb, andsimplified

The list of output_mode, at least one value required. When multiple value provided each value must beseparated by space. Multiple value can only be used in HIPPOS without reference. When nothing providedoutput_mode full will be used.

• docking_score (optional) value: yes or no , default: yes

Extract the docking score of ligand poses from docking results and attach them to output file.

• omit_interaction (optional) value: interaction_type and residue_name

where interaction_type is one of the following value:

– hydrophobic or HPB

– aromatic or ARM

– h_bond or HBD

– electrostatic or ELE

– h_bond_donor or HBD_DON

– h_bond_acceptor or HBD_ACC

– electrostatic_positive or ELE_POS

– electrostatic_negative or ELE_NEG

– aromatic_facetoface or ARM_F2F

– aromatic_edgetoface or ARM_E2F

While residue_name specify which residue will be omitted. Usage example:


3.8. HIPPOS Configuration Options 29


3.9 LICENSE

3.9.1 Modified Historical Permission Notice and Disclaimer (MHPND)

This copyright notice is a modified version of HPND

3.9.2 Free Software Permission

Permission to use, copy, modify and distribute this software and its documentation for any purpose and without fee ishereby granted, provided that:

1. The above copyright notice appear in all copies,

2. Both the copyright notice and this permission notice appear in supporting documentation,

3. The user agrees that any reports or published results obtained with the software or the modified software or partof the software will acknowledge its use by citing this paper:

Istyastono, E., Radifar, M., Yuniarti, N., Prasasty, V. and Mungkasi, S., 2020. PyPLIF HIPPOS: A Molecular Interac-tion Fingerprinting Tool for Docking Results of AutoDock Vina and PLANTS. Journal of Chemical Information andModeling (https://doi.org/10.1021/acs.jcim.0c00305).

4. The name of Muhammad Radifar & Enade Perdana Istyastono not be used in advertising or publicity pertainingto distribution of the software without specific, written prior permission.

3.9.3 DISCLAIMER

Muhammad Radifar & Enade Perdana Istyastono make no representations about the suitability of this software for anypurpose. It is provided “as is” without express or implied warranty.

Muhammad Radifar & Enade Perdana Istyastono DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFT-WARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENTSHALL Muhammad Radifar & Enade Perdana Istyastono BE LIABLE FOR ANY SPECIAL, INDIRECT OR CON-SEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATAOR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.


https://opensource.org/licenses/HPND


PyPLIF HIPPOS Documentation

Documents

Transcript of PyPLIF HIPPOS Documentation