Skip to content

AD4Docking API#

docksuitex.autodock4.AD4Docking #

AutoDock4 molecular docking interface.

This module provides a Python wrapper for AutoDock4 and AutoGrid, implementing the classic genetic algorithm-based docking approach. AutoDock4 is widely used for protein-ligand docking with detailed energy calculations.

The docking workflow
  1. Directory setup: Creates output directory and copies input files.
  2. Grid Generation (AutoGrid):
    • Creates Grid Parameter File (GPF).
    • Runs AutoGrid to generate affinity maps (.map) and electrostatics.
  3. Docking (AutoDock):
    • Creates Docking Parameter File (DPF).
    • Runs AutoDock4 using the Lamarckian Genetic Algorithm.
  4. Result Processing:
    • Validates execution and output files.
    • Extracts docked conformations from the DLG log file.
    • Saves the best poses to a multi-model PDBQT file.

AutoDock4 uses Lamarckian Genetic Algorithm (LGA) which combines genetic algorithm with local search for efficient conformational sampling.

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",
    spacing: float = 0.375,
    dielectric: float = -0.1465,
    smooth: float = 0.5,
    ga_pop_size: int = 150,
    ga_num_evals: int = 2500000,
    ga_num_generations: int = 27000,
    ga_elitism: int = 1,
    ga_mutation_rate: float = 0.02,
    ga_crossover_rate: float = 0.8,
    ga_run: int = 10,
    rmstol: float = 2.0,
    seed: tuple[Union[int, str], Union[int, str]] = (27, 6),
)

Initialize an AutoDock4 docking run.

Parameters:

Name Type Description Default
receptor Union[str, Path]

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

 required
ligand Union[str, Path]

Path to the 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, or "blind_docking" to auto-compute from receptor heavy atoms. Defaults to "blind_docking".

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

Grid box dimensions in Ångströms per axis, or "blind_docking" to auto-compute from receptor heavy atoms. The conversion to AutoGrid npts (grid points) is done internally as npts = ceil(size_Å / spacing). Defaults to "blind_docking".

 'blind_docking'
spacing float

Grid spacing in Å. Defaults to 0.375.

 0.375
dielectric float

Dielectric constant for electrostatics. Defaults to -0.1465.

 -0.1465
smooth float

Smoothing factor for potential maps. Defaults to 0.5.

 0.5
ga_pop_size int

Genetic algorithm population size. Defaults to 150.

 150
ga_num_evals int

Maximum number of energy evaluations in GA. Defaults to 2_500_000.

 2500000
ga_num_generations int

Maximum number of generations in GA. Defaults to 27_000.

 27000
ga_elitism int

Number of top individuals preserved during GA. Defaults to 1.

 1
ga_mutation_rate float

Probability of mutation in GA. Defaults to 0.02.

 0.02
ga_crossover_rate float

Probability of crossover in GA. Defaults to 0.8.

 0.8
ga_run int

Number of independent GA runs. Defaults to 10.

 10
rmstol float

RMSD tolerance for clustering. Defaults to 2.0.

 2.0
seed tuple[Union[int, str], Union[int, str]]

Seed for random number generation. Defaults to (27, 6).

 (27, 6)

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 AutoDock4 docking simulation.

Runs the complete AutoDock4 docking workflow, including grid map generation with AutoGrid and molecular docking with AutoDock4. It manages the creation of parameter files (GPF, DPF), executes the binaries, and processes the results.

Parameters:

Name Type Description Default
save_to Union[str, Path]

Directory path where docking results will be saved. If None, creates a directory named "ad4_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). - receptor.gpf, receptor.glg: AutoGrid parameter and log files. - ligand.dpf, results.dlg: AutoDock parameter and log files. - receptor.*.map: Affinity maps generated by AutoGrid. - output.pdbqt: Extracted docked ligand poses (multi-model PDBQT).

Raises:

Type Description
RuntimeError

If AutoGrid or AutoDock execution fails, or if expected output files (e.g., .fld, .dlg) are not created.
CalledProcessError

If the binary execution returns a non-zero exit code.

parse_results #

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

Parse the AutoDock4 DLG file and return a DataFrame of docking results.

Delegates to :func:docksuitex.utils.parser.parse_ad4_dlg to extract receptor/ligand names, grid parameters, GA settings, and cluster docking results from the DLG file generated by run().

Parameters:

Name Type Description Default
save_to str | Path

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

 None

Returns:

Type Description
DataFrame

pd.DataFrame: DataFrame with columns including Receptor, Ligand, Cluster_Rank, Binding_Energy, RMSD, 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.