Merge pull request #378 from rwxayheee/doc_update

Update Vina documentation

.gitignore

@@ -2,3 +2,5 @@
 *.o
 build/python/vina/autodock_vina_wrap.cpp
 build/python/vina/vina_wrapper.py
+build/python/vina.egg-info/
+build/python/build/

docs/source/colab_examples.rst

@@ -5,7 +5,7 @@ Colab Examples
 
 `Google Colaboratory <https://colab.google/>`_ (Colab) is a cloud-based platform that allows users to write and execute Python codes through a browser. Regardless of the user's operating system, Colab provides Linux computing backends and some free GPU access. 
 
-The following Colab examples are created to provide **an install-free experience** & **some generalizable workflows** of AutoDock Vina via Google Colab notebooks, which work in a similar manner to `Jupyter Notebooks <https://jupyter.org/>`_, in the pre-configured environment with `Meeko <https://github.com/forlilab/Meeko>`_ for receptor and ligand preparation, and other modules - `RDKit <https://rdkit.org/>`_, `Scrubber <https://github.com/forlilab/scrubber>`_, `ProDy <http://www.bahargroup.org/prody/>`_, `reduce2 <https://github.com/cctbx/cctbx_project/tree/master/mmtbx/reduce#reduce2>`_ (formerly `reduce <https://github.com/rlabduke/reduce>`_), and `py3Dmol <https://github.com/avirshup/py3dmol>`_ - for conformer generation, manipulation & pre-processing of protein structures and visualization. 
+The following Colab examples are created to provide **an install-free experience** & **some generalizable workflows** of AutoDock Vina via Google Colab notebooks, which work in a similar manner to `Jupyter Notebooks <https://jupyter.org/>`_, in the pre-configured environment with `Meeko <https://github.com/forlilab/Meeko>`_ for receptor and ligand preparation, and other modules - `RDKit <https://rdkit.org/>`_, `Molscrub <https://github.com/forlilab/molscrub>`_, `ProDy <http://www.bahargroup.org/prody/>`_, `reduce2 <https://github.com/cctbx/cctbx_project/tree/master/mmtbx/reduce#reduce2>`_ (formerly `reduce <https://github.com/rlabduke/reduce>`_), and `py3Dmol <https://github.com/avirshup/py3dmol>`_ - for conformer generation, manipulation & pre-processing of protein structures and visualization. 
 
 **Subscription is NOT required to run these Colab examples.** Additionally, the input files for the docking calculations are either directly pulled from open databases or generated from user inputs. With that, one can easily customize the notebooks and reuse the workflow for similar calculations on different biochemical systems. 
 
@@ -22,7 +22,7 @@ Overview
 *Major Python packages used* 
 
 * **RDKit** `https://rdkit.org/ <https://rdkit.org/>`_ 
-* **Scrubber** `https://github.com/forlilab/scrubber <https://github.com/forlilab/scrubber>`_ 
+* **Molscrub (formerly scrubber)** `https://github.com/forlilab/molscrub <https://github.com/forlilab/molscrub>`_ 
 * **Meeko** `https://github.com/forlilab/Meeko <https://github.com/forlilab/Meeko>`_ 
 * **ProDy** `http://www.bahargroup.org/prody/ <http://www.bahargroup.org/prody/>`_ 
 * **cctbx-base** (for reduce2) `https://github.com/cctbx/cctbx_project <https://github.com/cctbx/cctbx_project>`_ 

docs/source/docking_basic.rst

@@ -10,7 +10,7 @@ System and software requirements
 
 This is a command-line tutorial for a basic docking experiment with AutoDock-Vina. It can be done on macOS, Linux, and Windows Subsystem for Linux (WSL). 
 
-This tutorial uses python package **Meeko for receptor and ligand preparation**. Installation guide and advanced usage can be found from the `Meeko documentation <https://meeko.readthedocs.io/en/release>`_.
+This tutorial uses python package **Meeko for receptor and ligand preparation**. Installation guide and advanced usage can be found from the `Meeko documentation <https://meeko.readthedocs.io>`_.
 
 The **input and expected output files** can be found here on `GitHub <https://github.com/ccsb-scripps/AutoDock-Vina/tree/develop/example/basic_docking>`_.
 
@@ -50,7 +50,7 @@ This step is very similar to the previous step. We will also create a PDBQT file
 
   We strongly advice you against using PDB format for preparing small molecules, since it does not contain information about bond connections. Please don't forget to always check the protonation state of your molecules before docking. Your success can sometimes hang by just an hydrogen atom. ;-)
 
-In case your starting ligand structure does not contain hydrogens, you may consider the command-line script ``scrub.py`` from the python package `Scrubber <https://github.com/forlilab/scrubber>`_ to protonate the ligand. If given the Smiles string of the ligand, ``scrub.py`` is also able to generate 3D conformers and enumerate tautomeric and protonation states of ligand. 
+In case your starting ligand structure does not contain hydrogens, you may consider the command-line script ``scrub.py`` from the python package `Molscrub <https://github.com/forlilab/molscrub>`_ to protonate the ligand. If given the Smiles string of the ligand, ``scrub.py`` is also able to generate 3D conformers and enumerate tautomeric and protonation states of ligand. 
 
 .. code-block:: bash
 

docs/source/docking_flexible.rst

@@ -10,7 +10,7 @@ System and software requirements
 
 This is a command-line tutorial for a flexible docking experiment with AutoDock-Vina. It can be done on macOS, Linux, and Windows Subsystem for Linux (WSL). 
 
-This tutorial uses python package **Meeko for receptor and ligand preparation**. Installation guide and advanced usage can be found from the `Meeko documentation <https://meeko.readthedocs.io/en/release>`_.
+This tutorial uses python package **Meeko for receptor and ligand preparation**. Installation guide and advanced usage can be found from the `Meeko documentation <https://meeko.readthedocs.io>`_.
 
 The **input and expected output files** can be found here on `GitHub <https://github.com/ccsb-scripps/AutoDock-Vina/tree/develop/example/flexible_docking>`_.
 

docs/source/docking_hydrated.rst

@@ -18,7 +18,7 @@ System and software requirements
 
 This is a command-line tutorial for a hydrated docking experiment with AutoDock-Vina. It can be done on macOS, Linux, and Windows Subsystem for Linux (WSL). 
 
-This tutorial uses python package **Meeko for receptor and ligand preparation**. Installation guide and advanced usage can be found from the `Meeko documentation <https://meeko.readthedocs.io/en/release>`_.
+This tutorial uses python package **Meeko for receptor and ligand preparation**. Installation guide and advanced usage can be found from the `Meeko documentation <https://meeko.readthedocs.io>`_.
 
 The **input and expected output files** can be found here on `GitHub <https://github.com/ccsb-scripps/AutoDock-Vina/tree/develop/example/hydrated_docking>`_. 
 
@@ -45,7 +45,7 @@ The receptor can be prepared using the method described earlier in the following
 2. Preparing the ligand
 -----------------------
 
-For the hydrated docking, explicit water molecules (W atoms) must be added to the molecule. And for that, we will use ``Meeko`` (see installation instruction here: :ref:`docking_requirements`). For convenience, the molecule file ``1uw6_ligand.sdf`` is provided (see ``data`` directory). But you can obtain it directly from the `PDB <https://www.rcsb.org>`_ here: `1uw6 <https://www.rcsb.org/structure/1UW6>`_ (see ``Download instance Coordinates`` link for the NCT molecule (chain U [A])). Since the ligand file does not include the hydrogen atoms, we are going to add them using ``scrub.py`` from python package Scrubber. The option ``-w`` is use to add explicit water molecule to the molecule.
+For the hydrated docking, explicit water molecules (W atoms) must be added to the molecule. And for that, we will use ``Meeko`` (see installation instruction here: :ref:`docking_requirements`). For convenience, the molecule file ``1uw6_ligand.sdf`` is provided (see ``data`` directory). But you can obtain it directly from the `PDB <https://www.rcsb.org>`_ here: `1uw6 <https://www.rcsb.org/structure/1UW6>`_ (see ``Download instance Coordinates`` link for the NCT molecule (chain U [A])). Since the ligand file does not include the hydrogen atoms, we are going to add them using ``scrub.py`` from python package Molscrub. The option ``-w`` is use to add explicit water molecule to the molecule.
 
 .. warning::
 

docs/source/docking_in_batch.rst

@@ -0,0 +1,45 @@
+.. _docking_in_batch:
+
+Docking in batch mode
+================
+
+Docking many ligands sequentially, one after the other, is possible with AutoDock Vina. This is useful to perform virtual screening of a large number of ligands against a receptor. The following sections describe how to do this using the command line. For possible ways of doing this with the Python API, see :ref:`python_docking`. 
+
+Do not confuse this with multiple ligand docking (:ref:`multiple_ligands_docking`), in which multiple ligands are docked simultaneously. 
+
+Command line options
+--------------------
+
+The command line usage is similar to the one for a single ligand. The only difference is that instead of specifying a single ligand using the ``--ligand`` option, we use the ``--batch`` option once or multiple times to include all ligands. 
+
+Use ``--dir`` to specify the output directory. The output filename will be ``<ligand_name>_out.pdbqt`` under the specified directory, where ``<ligand_name>`` is the name of the input ligand file without the path. When the name of the ligand is duplicated, an index will be added to the name to avoid the name collision. 
+
+Assuming we have multiple ligand PDBQT files in the directory named ``ligands`` in the current path. For Linux and macOS, the command line would look like this: 
+
+.. code-block:: bash
+
+    $ vina --receptor 1iep_receptor.pdbqt --batch ligands/1iep_ligand_1.pdbqt --batch ligands/1iep_ligand_2.pdbqt --batch ligands/1iep_ligand_3.pdbqt --config config.txt --dir poses
+    $ vina --receptor 1iep_receptor.pdbqt --batch ligands/1iep_ligand_*.pdbqt --config config.txt --dir poses
+
+For Windows, more precautions should be used with the wildcard expansion and the type of the path separators: 
+
+.. code-block:: bash
+
+    $ vina --receptor 1iep_receptor.pdbqt --batch $(ls .\ligands\*.pdbqt | % {$_.FullName}) --config config.txt --dir poses
+
+Looping over a list of receptors
+--------------------------------
+
+Currently, there is no option to iterate multiple receptors in a series of docking runs. However, it is possible to loop over a list of receptors and ligands using a shell script or a batch file. 
+
+Assuming we have multiple receptor PDBQT files in the directory named ``receptors`` in the current path, the following is an example of a shell script for Linux and macOS:  
+
+.. code-block:: bash
+
+    #!/bin/bash
+    for receptor in receptors/*.pdbqt; do
+        receptor_name=$(basename "$receptor" .pdbqt)
+        vina --receptor "$receptor" --batch ligands/1iep_ligand_*.pdbqt --config config.txt --dir "poses/$receptor_name"
+    done
+
+For Windows, a similar batch file or PowerShell script could be written to achieve the same result. The syntax may vary, but the logic of the routine remains the same. 

docs/source/docking_multiple_ligands.rst

@@ -12,7 +12,7 @@ System and software requirements
 
 This is a command-line tutorial for a flexible docking experiment with AutoDock-Vina. It can be done on macOS, Linux, and Windows Subsystem for Linux (WSL). 
 
-This tutorial uses python package **Meeko for receptor and ligand preparation**. Installation guide and advanced usage can be found from the `Meeko documentation <https://meeko.readthedocs.io/en/release>`_.
+This tutorial uses python package **Meeko for receptor and ligand preparation**. Installation guide and advanced usage can be found from the `Meeko documentation <https://meeko.readthedocs.io>`_.
 
 The **input and expected output files** can be found here on `GitHub <https://github.com/ccsb-scripps/AutoDock-Vina/tree/develop/example/mulitple_ligands_docking>`_.
 
@@ -33,7 +33,7 @@ Here again we're using the ``-a`` option to ignore the partially resolve residue
 2. Prepare ligands
 ------------------
 
-Here, we will prepare two ligands instead of only one. We will start from the SDF files ``5x72_ligand_p59.sdf`` and ``5x72_ligand_p69.sdf`` located in the ``data`` directory. They were also obtained directly from the `PDB <https://www.rcsb.org>`_ here: `5x72 <https://www.rcsb.org/structure/5X72>`_ (see ``Download instance Coordinates`` link for the P59 and P69 molecules). Since the ligand files do not include the hydrogen atoms, we are going to add them using ``scrub.py`` from python package Scrubber.
+Here, we will prepare two ligands instead of only one. We will start from the SDF files ``5x72_ligand_p59.sdf`` and ``5x72_ligand_p69.sdf`` located in the ``data`` directory. They were also obtained directly from the `PDB <https://www.rcsb.org>`_ here: `5x72 <https://www.rcsb.org/structure/5X72>`_ (see ``Download instance Coordinates`` link for the P59 and P69 molecules). Since the ligand files do not include the hydrogen atoms, we are going to add them using ``scrub.py`` from python package Molscrub.
 
 .. code-block:: bash
 

docs/source/docking_requirements.rst

@@ -8,7 +8,7 @@ In addition to AutoDockTools, the long standing GUI for docking calculation setu
 Python package Meeko
 -----
 
-The Python package ``meeko`` is package recently developped in the Forli lab also at the `Center for Computational Structural Biology (CCSB) <https://ccsb.scripps.edu>`_. As showcased in the Colab examples, `Meeko <https://github.com/forlilab/Meeko>`_ provides commandline scripts for ligand preparation, receptor preparation and other essential tools for the following docking protocols:
+The Python package `meeko <https://meeko.readthedocs.io>`_ is package recently developped in the Forli lab also at the `Center for Computational Structural Biology (CCSB) <https://ccsb.scripps.edu>`_. As showcased in the Colab examples, `Meeko <https://github.com/forlilab/Meeko>`_ provides commandline scripts for ligand preparation, receptor preparation and other essential tools for the following docking protocols:
 
     - Docking with flexible macrocycles
     - Flexible docking
@@ -44,9 +44,18 @@ Type the following command to install ``Meeko`` and (optionally) ``ProDy``:
     
     $ conda activate vina
     $ conda install python=3.10    # for ProDy interoperability
-    $ conda install -c conda-forge numpy scipy rdkit vina meeko gemmi
+    $ conda install -c conda-forge numpy scipy rdkit vina meeko gemmi autogrid
     $ pip install prody
 
+AutoGrid4
+--------
+Git Repository: `CCSB-Scripps AutoGrid <https://github.com/ccsb-scripps/AutoGrid>`_
+
+.. code-block:: bash
+
+    $ conda install -c conda-forge autogrid 
+
+Alternatively, see instruction in the repository's ``README`` to build the latest version of autogrid4. 
 
 ADFR software suite
 -------------------

docs/source/docking_zinc.rst

@@ -72,7 +72,7 @@ The execution of the second command will output the following message, telling u
 2. Preparing the ligand
 -----------------------
 
-The second step consists to prepare the ligand, by converting the SDF file ``1s63_ligand.sdf`` to a PDBQT file readable by AutoDock Vina. As usual, we will use the ``mk_prepare_ligand.py`` Python script from ``Meeko`` (see installation instruction here: :ref:`docking_requirements`) for this task. For your convenience, the molecule file ``1s63_ligand.sdf`` is provided (see ``data`` directory). But you can obtain it directly from the `PDB <https://www.rcsb.org>`_ here: `1s63 <https://www.rcsb.org/structure/1S63>`_ (see ``Download instance Coordinates`` link for the 778 molecule. Since the ligand file does not include the hydrogen atoms, we are going to add them using ``scrub.py`` from python package Scrubber. 
+The second step consists to prepare the ligand, by converting the SDF file ``1s63_ligand.sdf`` to a PDBQT file readable by AutoDock Vina. As usual, we will use the ``mk_prepare_ligand.py`` Python script from ``Meeko`` (see installation instruction here: :ref:`docking_requirements`) for this task. For your convenience, the molecule file ``1s63_ligand.sdf`` is provided (see ``data`` directory). But you can obtain it directly from the `PDB <https://www.rcsb.org>`_ here: `1s63 <https://www.rcsb.org/structure/1S63>`_ (see ``Download instance Coordinates`` link for the 778 molecule. Since the ligand file does not include the hydrogen atoms, we are going to add them using ``scrub.py`` from python package Molscrub. 
 
 .. code-block:: bash
 

docs/source/index.rst

@@ -38,6 +38,7 @@ AutoDock Vina is **open source** and welcomes your contributions. `Fork the repo
    docking_basic
    docking_flexible
    docking_multiple_ligands
+   docking_in_batch
    docking_zinc
    docking_hydrated
    docking_macrocycle