Structure Visualization Entities

GitHub Link to Code.

Structure visualization data entity for storing PDB paths.

This module contains the StructureVisualizationData class that stores PDB file paths generated for structure visualization. Each instance represents a named visualization session with PDBs for different structures (from FI sub-comparisons or data selectors).

class mdxplain.structure_visualization.entities.structure_visualization_data.StructureVisualizationData(name: str, feature_importance_name: str = None, selector_centroid: str = None, selector_features: str = None)

Data entity for storing structure visualization PDB paths.

Stores paths to generated PDB files for structure visualization, organized by structure identifiers. Supports two source types:

“feature_importance”: From FI analysis sub-comparisons
“feature”: From feature/data selectors

Attributes

namestr: Name identifier for this visualization session
source_typestr: Source type: “feature_importance” or “feature”
feature_importance_namestr | None: Name of FI analysis (for FI source type)
selector_centroidstr | None: Feature selector for centroids (for feature source type)
selector_featuresstr | None: Feature selector for highlights (for feature source type)
pdb_pathsDict[str, str]: Mapping from structure identifier to PDB file path
feature_infoList[Dict[str, Any]]: List of feature dicts with metadata for visualization

Examples

>>> # Feature importance mode
>>> viz_data = StructureVisualizationData("my_viz", "dt_analysis")
>>> viz_data.add_pdb("cluster_0_vs_rest", "/path/to/structure.pdb")

>>> # Feature mode
>>> viz_data = StructureVisualizationData.from_selectors(
...     "my_viz", "coords_all", "distances"
... )
>>> viz_data.add_pdb("cluster_0", "/path/to/c0.pdb")

__init__(name: str, feature_importance_name: str = None, selector_centroid: str = None, selector_features: str = None)

Initialize structure visualization data.

Use either feature_importance_name (FI mode) OR selector_centroid (feature mode), not both.

Parameters

namestr: Name identifier for this visualization session
feature_importance_namestr, optional: Name of FI analysis (for FI source type)
selector_centroidstr, optional: Feature selector for centroids (for feature source type)
selector_featuresstr, optional: Feature selector for highlights (for feature source type)

Returns

None: Initializes StructureVisualizationData with empty PDB paths

Examples

>>> # Feature importance mode
>>> viz_data = StructureVisualizationData("my_viz", "dt_analysis")

>>> # Feature mode with features
>>> viz_data = StructureVisualizationData(
...     "my_viz",
...     selector_centroid="coords_all",
...     selector_features="distances"
... )

>>> # Feature mode without features
>>> viz_data = StructureVisualizationData(
...     "my_viz",
...     selector_centroid="coords_all"
... )

add_pdb(sub_comparison: str, pdb_path: str) → None

Add PDB path for a sub-comparison.

Parameters

sub_comparisonstr: Sub-comparison identifier
pdb_pathstr: Path to PDB file

Returns

None: Adds PDB path to internal storage

Examples

>>> viz_data = StructureVisualizationData("my_viz")
>>> viz_data.add_pdb("cluster_0_vs_rest", "/path/to/structure.pdb")

get_pdb(sub_comparison: str) → str | None

Get PDB path for a sub-comparison.

Parameters

sub_comparisonstr: Sub-comparison identifier

Returns

Optional[str]: PDB file path, or None if not found

Examples

>>> viz_data = StructureVisualizationData("my_viz")
>>> viz_data.add_pdb("cluster_0_vs_rest", "/path/to/structure.pdb")
>>> path = viz_data.get_pdb("cluster_0_vs_rest")
>>> print(path)
'/path/to/structure.pdb'

get_all_pdbs() → Dict[str, str]

Get all PDB paths.

Returns

Dict[str, str]: Dictionary mapping sub-comparison to PDB path

Examples

>>> viz_data = StructureVisualizationData("my_viz")
>>> viz_data.add_pdb("cluster_0", "/path/to/c0.pdb")
>>> viz_data.add_pdb("cluster_1", "/path/to/c1.pdb")
>>> all_paths = viz_data.get_all_pdbs()
>>> print(len(all_paths))
2

has_pdb(sub_comparison: str) → bool

Check if PDB exists for sub-comparison.

Parameters

sub_comparisonstr: Sub-comparison identifier

Returns

bool: True if PDB path exists, False otherwise

Examples

>>> viz_data = StructureVisualizationData("my_viz")
>>> viz_data.add_pdb("cluster_0", "/path/to/c0.pdb")
>>> viz_data.has_pdb("cluster_0")
True
>>> viz_data.has_pdb("cluster_1")
False

add_feature_info(features: List[Dict[str, Any]]) → None

Add feature information for visualization.

Parameters

featuresList[Dict[str, Any]]: List of feature dictionaries with metadata

Returns

None: Stores feature info for later visualization

Examples

>>> viz_data = StructureVisualizationData(
...     "my_viz", selector_centroid="coords_all"
... )
>>> features = [
...     {"feature_name": "ALA_5_CA-GLU_10_CA", "residue_seqids": [5, 10]},
...     {"feature_name": "GLY_3_phi", "residue_seqids": [3]}
... ]
>>> viz_data.add_feature_info(features)

get_feature_info() → List[Dict[str, Any]]

Get stored feature information.

Returns

List[Dict[str, Any]]: List of feature dictionaries with metadata

Examples

>>> viz_data = StructureVisualizationData(
...     "my_viz", selector_centroid="coords_all"
... )
>>> viz_data.add_feature_info([{"feature_name": "test"}])
>>> features = viz_data.get_feature_info()
>>> len(features)
1