Ligand API

docksuitex.ligand.Ligand

Ligand structure preparation for molecular docking.

This module provides automated ligand preparation using Open Babel for optional energy minimization and water removal, combined with AutoDockTools (MGLTools) for PDBQT generation.

The preparation workflow

1. Optional energy minimization with forcefields: MMFF94, MMFF94S, UFF, GAFF (using Open Babel).
2. Optional water molecule removal (using Open Babel).
3. Optional pH-aware hydrogen addition (using Open Babel) and Gasteiger charge assignment (using AutoDockTools).
4. Removing non-polar hydrogens and converting to PDBQT format (using AutoDockTools).

Supported Input Formats

SDF, MOL2 (Single Molecule only).

Note

If you have files in other formats (PDB, SMILES, etc.) or multi-molecule libraries (multi-SDF), please use the Format Converter utility to prepare a single-molecule SDF or MOL2 file before using this module.

Intermediate processed files (prepared MOL2) are saved in an intermediate_ligands/ subfolder within the output directory.

__init__

__init__(
    input: Union[str, Path],
    minimize: Optional[str] = None,
    remove_water: bool = True,
    add_hydrogens: bool = True,
    ph: float = 7.4,
    add_charges: bool = True,
    preserve_charge_types: Optional[list[str]] = None,
)

Initialize a Ligand object with a given input file and preparation parameters.

Parameters:

Name	Type	Description	Default
input	str | Path	Path to the single-molecule ligand file (SDF or MOL2).	required
minimize	str	Forcefield for energy minimization ("mmff94", "mmff94s", "uff", "gaff").	None
remove_water	bool	Remove water molecules. Defaults to True.	True
add_hydrogens	bool	Add polar hydrogens via Open Babel at specified pH. Defaults to True.	True
ph	float	Custom pH for Open Babel hydrogen addition. Defaults to 7.4.	7.4
add_charges	bool	Assign Gasteiger charges. Defaults to True.	True
preserve_charge_types	list[str]	Atom types (e.g.,["Zn", "Fe"]) whose charges are preserved; others get Gasteiger charges; ignored if add_charges=False. Defaults to None.	None

Raises:

Type	Description
FileNotFoundError	If the input file does not exist.
ValueError	If the file extension is not a supported format.

prepare

prepare(save_to: Union[str, Path] = '.') -> Path

Handle ligand preparation for docking using Open Babel and AutoDockTools (ADT).

Saves the prepared PDBQT file to the specified location.

Parameters:

Name	Type	Description	Default
save_to	str | Path	Destination file or directory. - If directory: saves with the original filename. - If file path: saves with the given name. Defaults to current directory.	'.'

Returns:

Name	Type	Description
Path	Path	Path to the saved PDBQT file.

Raises:

Type	Description
ValueError	If an unsupported forcefield is provided.
RuntimeError	If Open Babel or AutoDockTools fails.

view_molecule

view_molecule() -> nv.NGLWidget

Visualize the ligand structure in a Jupyter notebook.

Uses NGLView to render either the prepared PDBQT file or the original input file in an interactive 3D viewer.

Returns:

Type	Description
NGLWidget	nglview.NGLWidget: Interactive 3D molecular viewer widget.

Raises:

Type	Description
FileNotFoundError	If neither prepared nor input file exists.
ImportError	If nglview is not installed.

Note

This method requires a Jupyter Notebook/Lab environment and the nglview package.