Feature Importance Service

GitHub Link to Code.

Service for feature-importance-based structure visualization.

This service provides methods for creating and visualizing molecular structures with beta-factors derived from feature importance analysis.

class mdxplain.structure_visualization.services.structure_viz_feature_importance_service.StructureVizFeatureImportanceService(manager: StructureVisualizationManager, pipeline_data: PipelineData)

Service for feature-importance-based structure visualization.

Provides methods for creating PDB files with beta-factors derived from feature importance analysis and visualizing them with NGLView (Jupyter) or PyMOL (terminal/script).

Examples

>>> # Via PipelineManager
>>> pipeline.structure_visualization.feature_importance.create_pdb_with_beta_factors(
...     "my_viz", "dt_analysis", n_top=10
... )
>>> ui, view = pipeline.structure_visualization.feature_importance.visualize_nglview_jupyter(
...     "my_viz", n_top_global=3
... )
__init__(manager: StructureVisualizationManager, pipeline_data: PipelineData)

Initialize feature importance visualization service.

Parameters

managerStructureVisualizationManager

Parent manager instance

pipeline_dataPipelineData

Pipeline data object (injected by AutoInjectProxy)

Returns

None

Initializes service instance

create_pdb_with_beta_factors(structure_viz_name: str, feature_importance_name: str, n_top: int = 10, representative_mode: str = 'best', output_dir: str = None) → None

Create PDB files with beta-factor coloring for all comparisons.

Generates PDB files with beta-factors encoding residue importance for all sub-comparisons in a feature importance analysis. Results are stored in pipeline_data for later visualization.

Parameters

structure_viz_namestr

Name for this visualization session

feature_importance_namestr

Name of feature importance analysis to visualize

n_topint, default=10

Number of top features to consider for beta-factors

representative_modestr, default=”best”

Mode for selecting representative frames:

  • “best”: Frame maximizing top feature values

  • “centroid”: Frame closest to cluster centroid

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

>>> pipeline.structure_visualization.feature_importance.create_pdb_with_beta_factors(
...     "my_viz", "dt_analysis", n_top=10
... )
>>> # Access later for visualization
>>> data = pipeline.data.structure_visualization_data["my_viz"]

Notes

  • Creates one PDB per sub-comparison

  • Beta-factors encode residue importance (0-100 scale)

  • Representative frames selected based on representative_mode

visualize_nglview_jupyter(structure_viz_name: str, n_top_global: int = 3, n_top_local: int = 3, feature_own_color: bool = True) → Tuple

Create interactive NGLView widget for Jupyter notebooks.

Creates 3D interactive visualization widget using NGLView with beta-factor gradient coloring and feature highlights. Requires PDFs to be created first via create_pdb_with_beta_factors(). Supports both global features (averaged across all clusters) and local features (cluster-specific top features).

Warning

  • Only works in Jupyter notebook environment

  • Requires nglview and ipywidgets packages

Parameters

structure_viz_namestr

Name of visualization session (from create_pdb_with_beta_factors)

n_top_globalint, default=3

Number of global top features (averaged across all clusters)

n_top_localint, default=3

Number of local top features per cluster (cluster-specific)

feature_own_colorbool, default=True

If True, features use structure color for local features and distinct colors for global features. If False, uses continuous distinct colors (global 0-N, local N-M).

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_importance.create_pdb_with_beta_factors(
...     "my_viz", "dt_analysis", n_top=10
... )
>>> # Visualize with global and local features
>>> ui, view = pipeline.structure_visualization.feature_importance.visualize_nglview_jupyter(
...     "my_viz", n_top_global=3, n_top_local=3
... )
>>> # Only global features (disable local)
>>> ui, view = pipeline.structure_visualization.feature_importance.visualize_nglview_jupyter(
...     "my_viz", n_top_global=5, n_top_local=0
... )

Notes

  • Beta-factor gradient: base color (important) → white (unimportant)

  • Dropdown allows switching between structures or “multiple” mode

  • Multi-view mode shows all structures with opacity checkboxes

  • Global features: Top N averaged across all clusters

  • Local features: Top N cluster-specific features

  • Both global and local features independently toggleable

  • Feature highlights use licorice representation

create_pymol_script(structure_viz_name: str, n_top_global: int = 3, n_top_local: int = 3, output_dir: str = None, feature_own_color: bool = True) → str

Create PyMOL script (.pml) for structure visualization.

Generates PyMOL script with putty cartoons (thickness from beta-factor), color gradients (base_color → white), and feature objects as toggleable stick representations. Supports both global features (averaged across all clusters) and local features (cluster-specific top features).

Parameters

structure_viz_namestr

Name of visualization session (from create_pdb_with_beta_factors)

n_top_globalint, default=3

Number of global top features (averaged across all clusters)

n_top_localint, default=3

Number of local top features per cluster (cluster-specific)

output_dirstr, optional

Output directory (defaults to cache_dir/structure_viz)

feature_own_colorbool, default=True

If True, features use structure color for local features and distinct colors for global features. If False, uses continuous distinct colors (global 0-N, local N-M).

Returns

str

Path to created .pml script file

Examples

>>> # First create PDFs
>>> pipeline.structure_visualization.feature_importance.create_pdb_with_beta_factors(
...     "my_viz", "dt_analysis", n_top=10
... )
>>> # Create PyMOL script with global and local features
>>> script_path = pipeline.structure_visualization.feature_importance.create_pymol_script(
...     "my_viz", n_top_global=3, n_top_local=3
... )
>>> # Only global features (disable local)
>>> script_path = pipeline.structure_visualization.feature_importance.create_pymol_script(
...     "my_viz", n_top_global=5, n_top_local=0
... )

Notes

  • Focus groups named: all_focus_struct_{name}

  • Each group contains 6 objects (if local features enabled):

    • Own structure (cartoon, opak)

    • Own global features (sticks, opak)

    • Own local features (sticks, opak)

    • Other structures (cartoon, 80% transparent)

    • Other global features (sticks, 80% transparent)

    • Other local features (sticks, 80% transparent)

  • Only first focus group enabled by default

  • Toggle groups in PyMOL GUI to switch focus

  • Global and local features independently toggleable

  • Script saved as: output_dir/structure_viz_name.pml

  • Putty cartoons: thickness controlled by beta-factor

  • Color gradient: base_color (low B) → white (high B)

  • Stick colors independent of cartoon (beta-factor preserved)

visualize_pymol(structure_viz_name: str, n_top_global: int = 3, n_top_local: int = 3, 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. Supports both global features (averaged across all clusters) and local features (cluster-specific top features).

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_pdb_with_beta_factors)

n_top_globalint, default=3

Number of global top features (averaged across all clusters)

n_top_localint, default=3

Number of local top features per cluster (cluster-specific)

feature_own_colorbool, default=True

If True, features use structure color for local features and distinct colors for global features. If False, uses continuous distinct colors (global 0-N, local N-M).

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_importance.create_pdb_with_beta_factors(
...     "my_viz", "dt_analysis", n_top=10
... )
>>> # Then open in PyMOL (terminal only!)
>>> pipeline.structure_visualization.feature_importance.visualize_pymol(
...     "my_viz", n_top_global=3, n_top_local=3
... )

Notes

  • PyMOL opens with all structures and features visible

  • Toggle groups: enable/disable all_focus_struct_<name>

  • Each focus group shows own structure + features, others transparent

  • Global and local features independently toggleable

  • Putty cartoons: thickness controlled by beta-factor

  • Color gradient: base_color (low B) → white (high B)

  • Script created if not already exists