Command line options

CaverDock

The main function of CaverDock is to analyze the transportation of a ligand through a tunnel. However, it can also be executed for a single docking. In the single docking mode, CaverDock performs single docking with restraints, which can be used as a building block for other tools using restrained docking.

The parameters accepted by CaverDock can be divided into three categories:

• docking options, derived from AutoDock Vina

• options configuring tunnel analysis

• options for restrained docking

Apart from the required mandatory parameters, we recommend the use of --dump_bottlenecks and --dump_energies (with selected threshold). The files generated by these two parameters can facilitate the analysis of important protein residues along the trajectory. Another, interesting but not critically important, parameter --catomnum can be used to specify the number of an atom from the ligand pdbqt file and which will then be used as a drag atom. In some cases, the explicitly select drag atom can solve failures during the calculation.

Docking options

CaverDock accepts the same parameters as AutoDock Vina 1.1.2, which are used to configure, how the docking is performed. When only those parameters are given, and only one process is executed (by direct execution of the binary or executing it via mpirun -np 1), CaverDock works exactly like AutoDock Vina. When a tunnel analysis or a single restrained docking is executed, docking options described in this section must also be defined, as they parametrize docking internally used in CaverDock. The list of basic docking parameters can be found in the table Docking parameters. For more information about AutoDock Vina docking and all docking parameters, we refer to AutoDock Vina Users Guide.

Docking parameters

--receptor arg	Rigid part of the receptor (in PDBQT format).
--flex arg	Flexible side chains, if any (in PDBQT format).
--ligand arg	Ligand (in PDBQT format).
--center_x arg --center_y arg --center_z arg	Coordinates of the centre of the search box. The search box must contain the space for the whole tunnel and all flexible residues with their potential movement. The CaverDock package contains a script prepareconf.py which computes the search box automatically.
--size_x arg --size_y arg --size_z arg	Size of the search box in Å. The search box must contain the space for the whole tunnel and all flexible residues with their potential movement. The CaverDock package contains a script prepareconf.py which computes the search box automatically.
--out arg	Output file(s) prefix. When docked to the tunnel, a file with the suffix -lb.pdbqt is generated for the lower-bound trajectory, -ub.pdbqt for the upper-bound trajectory and occasionally -failed.pdbqt if the upper-bound trajectory is not computed (the failed trajectory contains the longest known contiguous trajectory).
--exhaustiveness arg	Exhaustiveness of the global optimization algorithm (a higher number means a higher number of tested conformations). Usually, values from the interval 1–8 are sufficient.
--cpu arg	Number of threads used per process.
--log	Writes a log file(s), usable for debugging.

Tunnel analysis options

In this section, we introduce all parameters related to the analysis of ligand transport through a tunnel. For the transport analysis, at least two processes must be executed mpirun -np 2 or greater). Note that the only required parameter is --tunnel, other parameters can be used to change the default settings. The basic parameters allow defining the type of the computed trajectory and the optimization strategy or hinting the initial position of a ligand (Table tunnel_basic), whereas advanced parameters affect restraints applied to the docking (Table tunnel_advanced).

Basic tunnel analysis parameters

--tunnel arg	The file containing discretized tunnel. This parameter is required.
--final_state LB|SMOOTHED	The final state of trajectory search. May be set to LB (compute the lower-bound trajectory only) or SMOOTHED (default), computing the lower and the upper-bound trajectories.
--optimization_strategy arg	Strategy for the upper-bound trajectory optimization. CaverDock may minimize the highest energy in a trajectory as a primary criterion and the cumulative energetic barrier as a secondary criterion (MAX, default value) or the cumulative energetic barrier across a whole trajectory (HILL).
--dock_like arg	PDBQT file defining the ideal position of the ligand in the active site. The starting disc is selected to bring a ligand closest to the active site. This parameter may help when the tunnel obtained from CAVER is too deep (and thus CaverDock pushes the ligand against the energetic barrier at the bottom of the tunnel).
--dump_bottlenecks arg	Dump the bottlenecks observed along the trajectory. There are multiple files generated: in the file arg, a list of bottleneck residues and a list of bottlenecks for the final upper-bound trajectory are given. For n disks, files arg.0.., arg.n-1 are generated: they contain the bottlenecks for the snapshots used in the final trajectory as well as the snapshots generated during the trajectory search and not used in the output trajectory. Reporting the bottlenecks in unused snapshots may help the user to recognize which residues prevent CaverDock from moving the ligand in alternative pathways.
--dump_energies arg	Dump the list of residues with favourable interactions with the ligand along the trajectory.
--dump_energies_thr arg	Threshold setting for the dump of interacting residues.
--refine_with_rrt	Use RRT to connect parts of the trajectory during upper-bound calculation (v2.0.a)
--rrt_activation	Energy threshold for initialisation of RRT (v2.0.a)

Whereas the basic tunnel analysis options can be set by beginner users and should not affect the robustness of the CaverDock computation, a suboptimal setting of advanced options may lead to very slow computation or a failure of the search for contiguous conformation. Thus, these should be set carefully.

Advanced tunnel analysis parameters

--backtrack_threshold arg	The energy increment over the lower-bound trajectory, which leads to the execution of backtracking. A lower value, lower energy of the upper-bound trajectory and higher computation time can be expected. The default value is 1 kcal/mol.
--backtrack_limit arg	The minimal number of steps (visited discs) which must be performed after backtracking, before new backtracking is executed. Values higher than 1 forbid frequent executions of backtracking from unfeasible areas. The default value is 5.
--cont_threshold arg	The maximal atom movement (in Angstroms) between adjacent snapshots, which is considered to be contiguous. The default value is 0.8 Å.
--pattern_limit arg	The maximal distance (in Angstroms) between adjacent snapshots, which is not penalized by a contiguity restraint. The default value is 0.6 Å, which must be smaller than --cont_threshold and higher than the maximal distance of discs created during a tunnel discretization.
--dock_like_limit arg	The maximal distance (in Angstroms) between the first snapshot and the ideal position of the ligand (defined by --dock_like, which is not penalized as a restraint. The default value is 2.0 Å.
--allow_flex_discontinuity	Allows the receptor side-chain residues to perform non-contiguous movements even when the upper-bound trajectory is computed. The default behaviour is that a contiguous movement is required for both the ligand and the side-chain residues.
--parallel_workers_lb arg	Allows the receptor side-chain residues to perform non-contiguous movements even when the upper-bound trajectory is computed. The default behaviour is that a contiguous movement is required for both the ligand and the side-chain residues.
--parallel_workers_smooth arg	The number of processes solving each docking task of an upper-bound trajectory computation in parallel (alternative to exhaustiveness, scales better). The default value is 4.
--early_exit	Allows CaverDock to immediately halt when lower-bound at some disc cannot be computed. The parameter can be used with screening, where rapid discarding of narrow tunnels is required.

Restrained docking options

In this section, parameters applicable to performing a single docking with restraints are introduced. Note that those parameters are not employed in the standard usage scenario of CaverDock (an analysis of the whole trajectory). However, they may be used for debugging or building a tool on the top of CaverDock.

There are essentially two types of restraints implemented: a disc, which fixes a ligand’s atom and a pattern, which restricts the positions of all ligand’s atoms. When the disc is defined, docking is performed in the way that a selected ligand atom must be placed in close vicinity of the disc. The discs may define a cut of a tunnel, or a point in space (when the disc radius is set to a very small number). The pattern holds the whole ligand in the vicinity of pattern atoms. So, it is possible to search only for the ligand conformations which are close to the one defined by the pattern.

Restrained docking parameters

--ccenter_x arg --ccenter_y arg --ccenter_z arg	Coordinates of the centre of a disc attracting a ligand (its central atom, or the atom selected by catomnum parameter).
--cnormal_x arg --cnormal_y arg --cnormal_z arg	The normal vector of a disc attracting a ligand (its central atom, or the atom selected by catomnum parameter).
--cradius arg	The radius of a disc attracting a ligand (its central atom, or atom selected by catomnum parameter).
--catomnum arg	The ID of an atom in PDB, which is attracted to a disc.
--ctemplate arg	PDB or PDBID of the template, which restricts the ligand’s atoms movement (they must remain in a vicinity of the template atoms, defined by --ctemplate_limit)
--ctemplate_limit arg	The distance (in Angstroms) of the docked ligand atoms to their counterparts in a template (defined by --ctemplate), which is tolerated without applying an attractive force to the template.
--ctemplate_restrict arg	The subset of the template’s atoms, which are used to restrict position of ligand atoms movement. Defined as a list of atom IDs delimited by “_”, e.g. 1_3_4 applies the template to the first, the third and the fourth atoms only.

Discretizer

In this section, we describe the options for the discretization tool.

Discretizer parameters

-f	Specify the input tunnel pdb file.
--delta	Change the distance between discretized discs. The default is 0.3 Å. Changes the resolution of the discretization. Using a number lower than default can significantly extend the computational time.
-o	Specify the name of the output discretized tunnel dsd file.
-t	Change the number of used CPUs.