BatchAD4Docking API

docksuitex.batch_docking.batch_autodock4.BatchAD4Docking

Batch docking manager for AutoDock4.

Runs AutoDock4 docking for multiple ligands against multiple proteins, each with its own set of binding pocket centers, in parallel using a process pool.

__init__

__init__(
    receptors_with_pockets: Dict[
        Union[str, Path], List[Dict]
    ],
    ligands: Union[Sequence[Union[str, Path]], str, Path],
    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 a batch docking job.

Parameters:

Name	Type	Description	Default
receptors_with_pockets	Dict[str | Path, List[Dict]]	Dictionary mapping receptor PDBQT files to their list of binding pockets (each pocket MUST be a dict with 'center' and 'grid_size').	required
ligands	Sequence[str | Path]	List of ligand PDBQT files.	required
spacing	float	Grid spacing in Å. Defaults to 0.375.	0.375
dielectric	float	Dielectric constant. 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	Max energy evaluations. Defaults to 2,500,000.	2500000
ga_num_generations	int	Max generations. Defaults to 27,000.	27000
ga_elitism	int	Elite individuals preserved. Defaults to 1.	1
ga_mutation_rate	float	GA mutation rate. Defaults to 0.02.	0.02
ga_crossover_rate	float	GA crossover rate. Defaults to 0.8.	0.8
ga_run	int	Independent GA runs. Defaults to 10.	10
rmstol	float	RMSD tolerance for clustering. Defaults to 2.0.	2.0
seed	tuple[int | str, int | str]	Random seed for docking. Each element can be an integer or the keywords "pid" or "time". Defaults to (27, 6).	(27, 6)

run_all

run_all(
    cpu: int = (os.cpu_count() or 2) - 1,
    save_to: Union[str, Path] = "./batch_ad4_results",
) -> dict[
    tuple[str, str, tuple[float, float, float]],
    Union[Path, str],
]

Run AutoDock4 docking for all ligands × all centers × all receptors in parallel.

Parameters:

Name	Type	Description	Default
cpu	int	Total number of CPU cores to use. Defaults to os.cpu_count() - 1. Each worker uses 1 CPU (AutoDock4 is single-threaded).	(cpu_count() or 2) - 1
save_to	str | Path	Directory where results are stored. Defaults to "./batch_ad4_results".	'./batch_ad4_results'

Returns:

Type	Description
dict[tuple[str, str, tuple[float, float, float]], Union[Path, str]]	dict[tuple[str, str, tuple[float, float, float]], Path | str]: Mapping from (receptor_name, ligand_name, center) to: - Path: Path to the docking result directory, if successful. - str: Error message if the docking failed.

parse_results

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

Parse all AutoDock4 DLG result files into a single CSV summary.

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 containing parsed docking results.

Raises:

Type	Description
FileNotFoundError	If run_all() has not been called yet.

interaction_profile

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

Compute ProLIF interaction fingerprints for all successful docking results.

Iterates over each successful docking run and executes :class:~docksuitex.interaction_profiler.InteractionProfiler. The protein PDB is automatically resolved from each receptor PDBQT using the intermediate_proteins/<stem>_prepared.pdb convention.

Must be called after :meth:run_all.

Parameters:

Name	Type	Description	Default
cpu	int	Number of CPUs for ProLIF per docking result. Defaults to os.cpu_count() - 1.	(cpu_count() or 2) - 1
save_to	str | Path	Base directory where ProLIF results will be saved. Each result gets a prolif_results subfolder inside its docking output directory. If provided, all results are saved under this directory instead. Defaults to None (saves inside each docking output directory).	None

Returns:

Type	Description
DataFrame	pd.DataFrame: Combined DataFrame of ProLIF interaction fingerprints from all successful docking results. Returns an empty DataFrame if no results could be profiled.

Raises:

Type	Description
FileNotFoundError	If run_all() has not been called yet.