Skip to content

VinaDocking API#

docksuitex.vina.VinaDocking #

Python wrapper for AutoDock Vina molecular docking.

This class provides a high-level interface to AutoDock Vina, handling parameter validation, command execution, result management, and visualization. It automates the docking workflow from input validation to result generation.

The docking workflow
  1. Directory setup: Creates output directory and copies input files.
  2. Docking (Vina):
    • Constructs command line arguments including receptor, ligand, and grid parameters.
    • Runs AutoDock Vina to perform docking.
  3. Result Processing:
    • Captures and saves the execution log.
    • Validates output files (pdbqt poses and log).
Note

Grid center coordinates should be determined from binding pocket prediction (e.g., using GridCalculator) or known binding site information.

__init__ #

__init__(
    receptor: Union[str, Path],
    ligand: Union[str, Path],
    grid_center: Union[
        tuple[float, float, float], str
    ] = "blind_docking",
    grid_size: Union[
        tuple[int, int, int], str
    ] = "blind_docking",
    exhaustiveness: int = 8,
    num_modes: int = 9,
    verbosity: int = 1,
    seed: Optional[int] = 42,
    _cpu: int = (os.cpu_count() or 2) - 1,
)

Initialize a Vina docking run.

Parameters:

Name Type Description Default
receptor Union[str, Path

Path to receptor PDBQT file. Must be a prepared protein structure in PDBQT format.

 required
ligand Union[str, Path

Path to ligand PDBQT file. Must be a prepared ligand structure in PDBQT format.

 required
grid_center Union[tuple[float, float, float], str]

Grid box center coordinates (x, y, z) in Angstroms, or "blind_docking" to auto-compute from receptor heavy atoms. Defaults to "blind_docking".

 'blind_docking'
grid_size Union[tuple[int, int, int], str]

Grid box dimensions (x, y, z) in Angstroms, or "blind_docking" to auto-compute from receptor heavy atoms. Defaults to "blind_docking".

 'blind_docking'
exhaustiveness int

Search exhaustiveness parameter. Higher values increase accuracy but also computation time. Typical range: 1-32. Defaults to 8.

 8
num_modes int

Maximum number of binding modes to generate. Vina will output up to this many poses ranked by predicted affinity. Defaults to 9.

 9
verbosity int

Output verbosity level. 0 = quiet, 1 = normal, 2 = verbose. Defaults to 1.

 1
seed Optional[int]

Random seed for reproducibility. If None, Vina uses a random seed. Defaults to 42.

 42
_cpu int

Number of CPU cores for Vina. Defaults to os.cpu_count() - 1.

 (cpu_count() or 2) - 1

Raises:

Type Description
FileNotFoundError

If receptor or ligand file does not exist.
ValueError

If input files are not PDBQT format or grid parameters are invalid (wrong tuple size or non-numeric values).
TypeError

If grid_center or grid_size contain non-numeric values.

run #

run(save_to: Union[str, Path] = None) -> Path

Execute AutoDock Vina docking simulation.

Runs the Vina docking calculation with the configured parameters, saves results to the specified directory, and generates output files including docked poses and a log file with binding energies.

Parameters:

Name Type Description Default
save_to Union[str, Path]

Directory path where docking results will be saved. If None, creates a directory named "vina_docked_{receptor}{ligand}_center{y}" in the current directory. Defaults to None.

 None

Returns:

Name Type Description
Path Path

Absolute path to the output directory containing: - Receptor and ligand PDBQT files (copies of inputs) - output.pdbqt: Docked ligand poses ranked by affinity - log.txt: Vina output log with binding energies and RMSD values

Raises:

Type Description
RuntimeError

If Vina execution fails (non-zero return code) or if expected output files (output.pdbqt, log.txt) are not created.

parse_results #

parse_results(
    save_to: Union[str, Path, None] = None,
) -> pd.DataFrame

Parse the Vina log file and return a DataFrame of docking results.

Delegates to :func:docksuitex.utils.parser.parse_vina_log to extract receptor/ligand names, grid parameters, and binding mode details (affinity, RMSD) from the log file generated by run().

Parameters:

Name Type Description Default
save_to str | Path

Path to save the CSV file. Defaults to <output_dir>/vina_summary.csv.

 None

Returns:

Type Description
DataFrame

pd.DataFrame: DataFrame with columns including Receptor, Ligand, Mode, Affinity (kcal/mol), RMSD LB, RMSD UB, etc.

Raises:

Type Description
FileNotFoundError

If run() has not been called yet or the output directory does not exist.

view_grid_box #

view_grid_box() -> nv.NGLWidget

Visualize the docking grid box on the receptor using NGLView.

Draws a red wireframe box representing the search space, overlaid on the receptor structure, with a sphere marking the grid center. Can be called before or after :meth:run.

Returns:

Type Description
NGLWidget

nv.NGLWidget: Interactive 3D widget (Jupyter Notebook only).

view_docked_poses #

view_docked_poses() -> None

Visualize docking results using NGLView in Jupyter Notebook.

Creates an interactive 3D visualization of the receptor-ligand complex with controls to browse through different docking poses. This method requires a Jupyter Notebook environment and the nglview package.

The visualization includes
  • Receptor structure displayed as cartoon representation
  • Ligand poses displayed as ball-and-stick models
  • Interactive controls to step through poses
  • Play/pause animation of poses
  • Speed control slider

Returns:

Name Type Description
None None

Displays the interactive widget directly in the notebook.

Raises:

Type Description
AttributeError

If run() has not been called yet (output files not set).
FileNotFoundError

If output files have been deleted or moved.
ImportError

If nglview is not installed.
Note

This method must be called after run() to ensure output files exist. It only works in Jupyter Notebook/Lab environments.

interaction_profile #

interaction_profile(
    cpu: int = (os.cpu_count() or 2) - 1,
    save_to: Union[str, Path, None] = None,
) -> pd.DataFrame

Compute protein–ligand interaction fingerprints with ProLIF.

Convenience wrapper around :class:~docksuitex.interaction_profiler.InteractionProfiler. Must be called after :meth:run.

The protein PDB is automatically resolved from the receptor PDBQT path using the intermediate_proteins/<stem>_prepared.pdb convention established by :meth:Protein.prepare.

Parameters:

Name Type Description Default
cpu int

Number of CPUs for ProLIF. Defaults to os.cpu_count() - 1.

 (cpu_count() or 2) - 1
save_to str | Path

Directory where results will be saved. Defaults to <output_dir>/prolif_results.

 None

Returns:

Type Description
DataFrame

pandas.DataFrame: Interaction fingerprint table with one row
DataFrame

per ligand pose and columns for each residue–interaction pair.

Raises:

Type Description
FileNotFoundError

If run() has not been called yet, the output directory does not exist, or the fixed PDB cannot be found.

view_interactions #

view_interactions() -> None

Display an interactive ProLIF interaction viewer in Jupyter.

Renders a widget with Prev/Next buttons and a 2D/3D/Barcode toggle to browse protein–ligand interactions for each docked pose.

Must be called after :meth:interaction_profile.

Raises:

Type Description
AttributeError

If :meth:interaction_profile has not been called yet.