Feature Service

GitHub Link to Code.

Service for feature-selector-based structure visualization.

This service provides methods for creating and visualizing molecular structures based on feature selectors and data selectors without requiring feature importance analysis.

class mdxplain.structure_visualization.services.structure_viz_feature_service.StructureVizFeatureService(manager: StructureVisualizationManager, pipeline_data: PipelineData)

Service for feature-selector-based structure visualization.

Provides methods for creating PDB files from data selector centroids with optional feature highlighting from feature selectors. Does not require feature importance analysis.

Examples

>>> # Via PipelineManager
>>> pipeline.structure_visualization.feature.create_representative_pdbs(
...     "my_viz",
...     data_selectors=["cluster_0", "cluster_1"],
...     selector_centroid="coords_all",
...     selector_features="important_distances"
... )
>>> ui, view = pipeline.structure_visualization.feature.visualize_nglview_jupyter(
...     "my_viz"
... )
__init__(manager: StructureVisualizationManager, pipeline_data: PipelineData)

Initialize feature-based visualization service.

Parameters

managerStructureVisualizationManager

Parent manager instance

pipeline_dataPipelineData

Pipeline data object (injected by AutoInjectProxy)

Returns

None

Initializes service instance

create_representative_pdbs(structure_viz_name: str, data_selectors: List[str], selector_centroid: str, selector_features: str = None, output_dir: str = None) → None

Create PDB files from data selector centroids.

Generates PDB files for each data selector using centroid frames calculated from selector_centroid. Beta-factors are set to 0.0 (uniform). Optional feature highlighting from selector_features.

Parameters

structure_viz_namestr

Name for this visualization session

data_selectorsList[str]

List of data selector names (min 1 required)

selector_centroidstr

Feature selector name for centroid calculation (REQUIRED)

selector_featuresstr, optional

Feature selector for visualization highlights (default None)

output_dirstr, optional

Output directory for PDB files (defaults to cache_dir/structure_viz)

Returns

None

Stores PDB paths in pipeline_data.structure_visualization_data

Examples

>>> # With feature highlighting
>>> pipeline.structure_visualization.feature.create_representative_pdbs(
...     "my_viz",
...     data_selectors=["cluster_0", "cluster_1", "cluster_2"],
...     selector_centroid="coords_all",
...     selector_features="important_distances"
... )
>>> # Without features (only structures)
>>> pipeline.structure_visualization.feature.create_representative_pdbs(
...     "my_viz",
...     data_selectors=["cluster_0", "cluster_1"],
...     selector_centroid="coords_all"
... )

Notes

  • Creates one PDB per data selector

  • Beta-factors always 0.0 (uniform thickness)

  • Centroids calculated using selector_centroid

  • Features from selector_features shown as highlights (if provided)

visualize_nglview_jupyter(structure_viz_name: str, feature_own_color: bool = True) → Tuple

Create interactive NGLView widget for Jupyter notebooks.

Creates 3D interactive visualization widget using NGLView with uniform structure coloring and optional feature highlights. Requires PDFs to be created first via create_representative_pdbs(). Automatically displays the widget in Jupyter and returns it.

Warning

  • Only works in Jupyter notebook environment

  • Requires nglview and ipywidgets packages

Parameters

structure_viz_namestr

Name of visualization session (from create_representative_pdbs)

feature_own_colorbool, default=True

If True, features use their own color from feature_colors. If False, features use the color of their structure.

Returns

Tuple[widgets.VBox, nv.NGLWidget]

UI container (dropdown + checkboxes) and NGLView widget

Raises

RuntimeError

If not running in Jupyter notebook environment

KeyError

If structure_viz_name not found in pipeline_data

ImportError

If nglview or ipywidgets not installed

Examples

>>> # First create PDFs
>>> pipeline.structure_visualization.feature.create_representative_pdbs(
...     "my_viz",
...     data_selectors=["cluster_0", "cluster_1"],
...     selector_centroid="coords_all",
...     selector_features="distances"
... )
>>> # Then visualize in Jupyter (automatically displayed)
>>> ui, view = pipeline.structure_visualization.feature.visualize_nglview_jupyter(
...     "my_viz"
... )

Notes

  • All structures have uniform thickness (beta=0.0)

  • Feature highlights use licorice representation

  • Dropdown allows switching between structures

  • Widget is automatically displayed via IPython.display.display()

create_pymol_script(structure_viz_name: str, output_dir: str = None, feature_own_color: bool = True) → str

Create PyMOL script (.pml) for structure visualization.

Generates PyMOL script with uniform cartoons (beta=0.0) and optional feature objects as toggleable stick representations.

Parameters

structure_viz_namestr

Name of visualization session (from create_representative_pdbs)

output_dirstr, optional

Output directory (defaults to cache_dir/structure_viz)

feature_own_colorbool, default=True

If True, features use their own color from feature_colors. If False, features use the color of their structure.

Returns

str

Path to created .pml script file

Examples

>>> # First create PDFs
>>> pipeline.structure_visualization.feature.create_representative_pdbs(
...     "my_viz",
...     data_selectors=["cluster_0", "cluster_1"],
...     selector_centroid="coords_all",
...     selector_features="distances"
... )
>>> # Then create PyMOL script
>>> script_path = pipeline.structure_visualization.feature.create_pymol_script(
...     "my_viz"
... )
>>> print(f"Script saved to: {script_path}")

Notes

  • Focus groups named: all_focus_struct_{name}

  • Each group contains own structure + others for context

  • Only first focus group enabled by default

  • Toggle groups in PyMOL GUI to switch focus

  • Script saved as: output_dir/structure_viz_name.pml

  • Uniform cartoons (no beta-factor variation)

visualize_pymol(structure_viz_name: str, feature_own_color: bool = True) → None

Open PyMOL with structure visualization.

Validates environment (terminal, PyMOL available), creates script if needed, and launches PyMOL with pymol Python module.

Warning

  • Only works in terminal/script, NOT in Jupyter notebooks

  • Requires pymol Python module (conda install pymol-open-source)

Parameters

structure_viz_namestr

Name of visualization session (from create_representative_pdbs)

feature_own_colorbool, default=True

If True, features use their own color from feature_colors. If False, features use the color of their structure.

Returns

None

Opens PyMOL with visualization

Raises

RuntimeError

If running in Jupyter notebook

ImportError

If pymol Python module not available

Examples

>>> # First create PDFs
>>> pipeline.structure_visualization.feature.create_representative_pdbs(
...     "my_viz",
...     data_selectors=["cluster_0", "cluster_1"],
...     selector_centroid="coords_all"
... )
>>> # Then open in PyMOL (terminal only!)
>>> pipeline.structure_visualization.feature.visualize_pymol("my_viz")

Notes

  • PyMOL opens with all structures and features visible

  • Toggle structures: enable/disable struct_<name>

  • Toggle features: enable/disable feat_<name>

  • Uniform cartoons (no beta-factor variation)

  • Script created if not already exists