mk_export.py
============

A command-line script to export docking poses of ligand (and flexible residues) to an SD file (.sdf), and to export the full receptor structures with updated conformations of flexible residues to a PDB file. Currently supports PDBQT files from AutoDock-Vina and DLG files from AutoDock-GPU that have the REMARK lines containing Smiles and index mapping information. 

Basic usage
-----------

.. code-block:: bash

    mk_export.py vina_results.pdbqt -s vina_results.sdf
    mk_export.py autodock-gpu_results.dlg -s autodock-gpu_results.sdf

About
-----

Convert docking results to SDF
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

AutoDock-GPU and Vina write docking results in the PDBQT format. The DLG output
from AutoDock-GPU contains docked poses in PDBQT blocks, plus additional information.
Meeko generates RDKit molecules from PDBQT using the SMILES
string in the REMARK lines. The REMARK lines also have the mapping of atom indices
between SMILES and PDBQT. SD files with docked coordinates are written
from RDKit molecules. 

Why this matters
~~~~~~~~~~~~~~~~

Making RDKit molecules from SMILES is safer than guessing bond orders
from the coordinates, specially because the PDBQT lacks hydrogens bonded
to carbon. As an example, consider the following conversion, in which
OpenBabel adds an extra double bond, not because it has a bad algorithm,
but because this is a nearly impossible task.

.. code-block:: bash

    obabel -:"C1C=CCO1" -o pdbqt --gen3d | obabel -i pdbqt -o smi
    [C]1=[C][C]=[C]O1

Caveats
~~~~~~~

If docking does not use explicit Hs, which it often does not, the
exported positions of hydrogens are calculated from RDKit. This can
be annoying if a careful forcefield minimization is employed before
docking, as probably rigorous Hs positions will be replaced by the
RDKit geometry rules, which are empirical and much simpler than most
force fields.

Options
-------

Positional Argument (Input)
~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. option:: docking_results_filename

   One or more docking output files in either PDBQT format (from Vina) or DLG format (from AD-GPU).

Output Options
~~~~~~~~~~~~~~

.. option:: --suffix <suffix>

   Set a suffix for output filenames that are not explicitly specified. The default suffix is ``_docked``. 

.. option:: -s, --write_sdf <output_SDF_filename>

   Specify the output SDF filename. Defaults to the input filename with a suffix defined by ``--suffix``. 

.. option:: -j, --read_json <input_JSON_filename>

   Provide a receptor file generated by ``mk_prepare_receptor`` with the ``-j/--write_json`` option. Currently only effective when used with ``-p, --write_pdb``. 

.. option:: -p, --write_pdb <output_PDB_filename>

   Specify the output PDB filename. Defaults to the input filename with a suffix defined by ``--suffix``. Must be used together with ``-j, --read_json``. 

.. option:: --all_dlg_poses

   (Flag) Write all poses from AutoDock-GPU DLG output files, instead of only the lead of each cluster. Currently only effective for ``-s, --write_sdf``. 

.. option:: -k, --keep_flexres_sdf

   (Flag) Include flexible residues, if any, in the SDF output.

.. option:: -, --redirect_stdout

   (Flag) Instead of writing an SDF file, print it directly to the standard output (STDOUT).