Viewer API#

docksuitex.utils.viewer #

Molecular visualization utilities for DockSuiteX.

view_molecule #

view_molecule(file_path: str | Path) -> nv.NGLWidget

Render a molecular structure in Jupyter Notebook using NGLView.

Parameters:

Name	Type	Description	Default
`file_path`	`str \| Path`	Path to the molecular file (.pdb, .pdbqt, .mol2, or .sdf).	required

Returns:

Type	Description
`NGLWidget`	nv.NGLWidget: An NGLView widget.

Raises:

Type	Description
`FileNotFoundError`	If the specified file does not exist.

view_grid_box #

view_grid_box(
    protein_file: str | Path,
    grid_center: tuple[float, float, float],
    grid_size: tuple[float, float, float] = (20, 20, 20),
    color: list[float] | None = None,
    center_color: list[float] | None = None,
    radius: float = 0.2,
    cross_size: float = 2.0,
) -> nv.NGLWidget

Visualize a protein structure with a docking grid box overlay.

Renders the protein and draws a wireframe box (12 edges as cylinders) around the specified grid center, plus a green 3-axis cross marking the pocket center. Useful for inspecting the search space before or after a docking run.

Parameters:

Name	Type	Description	Default
`protein_file`	`str \| Path`	Path to the protein structure file (.pdb, .pdbqt, .mol2, or .sdf).	required
`grid_center`	`tuple[float, float, float]`	(x, y, z) coordinates of the grid box center in Ångströms.	required
`grid_size`	`tuple[float, float, float]`	(sx, sy, sz) dimensions of the grid box in Ångströms. Defaults to (20, 20, 20).	`(20, 20, 20)`
`color`	`list[float] \| None`	RGB color for the box edges, each component in [0, 1]. Defaults to red `[1, 0, 0]`.	`None`
`center_color`	`list[float] \| None`	RGB color for the center cross. Defaults to green `[0, 1, 0]`.	`None`
`radius`	`float`	Cylinder radius for the box edges. Defaults to 0.2.	`0.2`
`cross_size`	`float`	Half-length of each axis line in the center cross, in Ångströms. Defaults to 2.0.	`2.0`

Returns:

Type	Description
`NGLWidget`	nv.NGLWidget: An interactive NGLView widget (display in Jupyter).

Raises:

Type	Description
`FileNotFoundError`	If protein_file does not exist.

Example::

from docksuitex.utils import view_grid_box
view_grid_box("receptor.pdbqt", grid_center=(10, 15, 20))

view_docked_poses #

view_docked_poses(
    protein_file: str | Path, ligand_file: str | Path
) -> None

Visualize docked poses (multiple poses) of a ligand with a protein.

This uses NGLView and interactive Jupyter widgets.

Features

Step through individual docking poses.
Toggle between showing one pose at a time or all poses simultaneously.
Play/Pause automatic animation of poses.
Adjust animation speed with a slider.

Parameters:

Name	Type	Description	Default
`protein_file`	`str \| Path`	Path to the receptor protein file (e.g., .pdb).	required
`ligand_file`	`str \| Path`	Path to the ligand docking results file (.pdbqt). The file should contain multiple docking poses in MODEL/ENDMDL blocks.	required

Returns:

Name	Type	Description
`None`	`None`	Displays the visualization and interactive controls directly
	`None`	in the Jupyter Notebook.