/** \page idock_pcsk9 Integrative docking: combining experimental data with computational pairwise docking

\tableofcontents

\section idock_pcsk9_intro Introduction

This example demonstrates the
[integrative docking protocol](@ref IMP::integrative_docking)
by application
to the PCSK9 antigen–J16 Fab antibody complex. It uses a command line tool
called <tt>idock</tt>. For full help on this tool, run from a command line:

\code{.sh}
idock -h
\endcode

\section idock_pcsk9_setup Setup

First, obtain the input files used in this example and put them in the
current directory, by typing:

\code{.sh}
cp <imp_example_path>/saxs/idock/* .
\endcode

(On a Windows machine, use `copy` rather than `cp`.) Here, `<imp_example_path>`
is the directory containing the %IMP example files. The full path to the files
can be determined by running in a Python interpreter '<tt>import IMP.saxs;
print(IMP.saxs.get_example_path('idock'))</tt>'.

The input files include the Protein Data Bank (PDB) structures of the
isolated J16 Fab antibody and PCSK9 antigen,
<tt>antibody_cut.pdb</tt> and <tt>2p4e.pdb</tt>, respectively. The protocol
can also include one or more additional sources of experimental information.
In this case, a set of cross links between the antibody and antigen are
provided in the file <tt>cxms.txt</tt>. The cross links file has a simple
format; each line lists the residue name and chain ID of the antibody and
the antigen, followed by the minimum and maximum CA-CA distance in angstroms.

\section idock_pcsk9_calc Calculation

All steps of the integrative docking procedure are carried out by simply
running:

\code{.sh}
idock --complex_type AA --cxms=cxms.txt --precision=1 antibody_cut.pdb 2p4e.pdb
\endcode

The application makes use of the PatchDock program for docking, which must
be obtained separately from
\external{http://bioinfo3d.cs.tau.ac.il/PatchDock/,the PatchDock website}.
It must be told explicitly where to find PatchDock
(either by giving the <tt>--patch_dock</tt>
option to idock, or by setting the <tt>PATCH_DOCK_HOME</tt>
environment variable).

The <tt>--precision</tt> argument above controls how many candidate dockings
are sampled by PatchDock, and can range from 1 (normal) to 3 (high precision).
Higher values result in longer run times. The <tt>--complex_type</tt>
argument is passed to PatchDock, and identifies the type of
complex (AA means antibody-antigen in this case). It alters how the docking
is performed (for more information, see the
\external{http://bioinfo3d.cs.tau.ac.il/PatchDock/help.html,PatchDock help}).

\section idock_pcsk9_results Results

Once the docking procedure has finished, the primary output file generated is
<tt>results_cxms_soap.txt</tt>, the first few lines of which look similar to:

\verbatim
     # |  Score  | filt| ZScore |cxms    | Zscore |soap    | Zscore | Transformation
     1 |  -1.571 |  +  | -0.787 |  0.013 | -0.707 | 1435.624 | -0.864 |  -1.869 0.676 -2.196 -7.105 -2.340 25.311
     2 |  -1.245 |  +  | -0.624 |  0.013 | -0.707 | 1967.947 | -0.538 |  -2.811 0.568 -1.826 -3.739 -0.751 31.180
\endverbatim

Each line corresponds to one model; the models are ranked by total score,
best first. The scores and z-score pairs for each scoring method
(just cxms and SOAP in this case) are also shown (only docking solutions that
were not
filtered out by any of the data sources – i.e. they scored well against every
source – are included in this file). The last column is a transformation
(3 rotation angles and a translation vector) that transforms the antibody
relative to the antigen (the antigen is not transformed).
*/
