BatchVinaDocking API

docksuitex.batch_docking.batch_vina.BatchVinaDocking

Batch docking manager for AutoDock Vina.

Runs AutoDock Vina 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],
    exhaustiveness: int = 8,
    num_modes: int = 9,
    verbosity: int = 1,
    seed: int | None = 42,
)

Initialize a batch Vina 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
exhaustiveness	int	Sampling exhaustiveness. Higher values increase accuracy but also computation time. Defaults to 8.	8
num_modes	int	Maximum number of binding modes. Defaults to 9.	9
verbosity	int	Verbosity level (0 = quiet, 1 = normal, 2 = verbose). Defaults to 1.	1
seed	int	Random seed. If None, Vina selects automatically. Defaults to 42.	42

run_all

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

Run AutoDock Vina 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. CPUs are divided among workers, with each worker receiving multiple CPUs for Vina.	(cpu_count() or 2) - 1
save_to	str | Path	Directory where docking results will be stored. Defaults to "./batch_vina_results".	'./batch_vina_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 file, if successful. - str: Error message if the docking failed.

parse_results

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

Parse all Vina docking log 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>/vina_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.