NGLView Helper

GitHub Link to Code.

NGLView widget helper for Jupyter notebook visualization.

This module provides helper functions to create interactive 3D molecular visualizations using nglview in Jupyter notebooks with beta-factor coloring and feature highlighting.

class mdxplain.structure_visualization.helper.nglview_helper.NGLViewHelper

Helper for creating NGLView widgets with focus-based visualization.

Provides static methods to create interactive 3D molecular structure viewers with beta-factor gradient coloring, feature highlights, structure selection dropdowns, and 2x4 checkbox grid for independent control of own vs other structures and features.

Examples

>>> pdb_info = {
...     "cluster_0": {"path": "/path/to/c0.pdb", "color": "#bf4242"},
...     "cluster_1": {"path": "/path/to/c1.pdb", "color": "#4242bf"}
... }
>>> features = [{"feature_name": "ALA_5_CA-GLU_10_CA", ...}]
>>> colors = {"ALA_5_CA-GLU_10_CA": "#ff0000"}
>>> ui, view = NGLViewHelper.create_widget(pdb_info, features, colors)

static create_widget(pdb_info: Dict[str, Dict[str, str]], top_features_global: List[Dict[str, Any]], feature_colors_global: Dict[str, str], top_features_local: Dict[str, List[Dict[str, Any]]], feature_colors_local: Dict[str, Dict[str, str]], feature_own_color: bool = True, show_feature_legend: bool = True, show_structure_legend: bool = True, viz_name: str = 'structure') → Tuple

Create NGLView widget with focus-based structure visualization.

Creates interactive 3D viewer with beta-factor gradient coloring and feature highlights. Supports both global features (averaged across all clusters) and local features (cluster-specific). Includes dropdown for structure selection and 3x4 checkbox grid for independent control.

Parameters

pdb_infoDict[str, Dict[str, str]]: Structure information with ‘path’ and ‘color’ keys per structure
top_features_globalList[Dict[str, Any]]: Global features to highlight (averaged across all clusters)
feature_colors_globalDict[str, str]: Global feature name to HEX color mapping
top_features_localDict[str, List[Dict[str, Any]]]: Local features per structure {struct_name: features}
feature_colors_localDict[str, Dict[str, str]]: Local feature colors {struct_name: {feat_name: color}}
feature_own_colorbool, default=True: If True, features use their own color from feature_colors. If False, features use the color of their structure.
show_feature_legendbool, default=True: If True, display feature color legend below controls
show_structure_legendbool, default=True: If True, display structure color legend below controls
viz_namestr, default=”structure”: Visualization name for filename generation in save buttons

Returns

Tuple[widgets.VBox, nv.NGLWidget]: UI container (dropdown + checkbox grid + legend) and NGLWidget

Examples

>>> pdb_info = {"cluster_0": {"path": "c0.pdb", "color": "#bf4242"}}
>>> global_feats = [{"feature_name": "ALA_5_CA-GLU_10_CA", ...}]
>>> global_colors = {"ALA_5_CA-GLU_10_CA": "#ff0000"}
>>> local_feats = {"cluster_0": [{"feature_name": "GLY_3_phi", ...}]}
>>> local_colors = {"cluster_0": {"GLY_3_phi": "#00ff00"}}
>>> ui, view = NGLViewHelper.create_widget(
...     pdb_info, global_feats, global_colors,
...     local_feats, local_colors
... )
>>> from IPython.display import display
>>> display(ui, view)

Notes

Beta-factors: 0.0 (base color) → 1.0 (white)
PDBs must be pre-aligned for multi-structure visualization
Dropdown selects focus structure
3x4 grid controls: own/other x struct/global/local
Global features: shown for all structures
Local features: only for own structure
Each checkbox controls visibility and transparency independently