Residue Importance Calculator

GitHub Link to Code.

Residue importance calculator for feature importance visualization.

This module calculates importance scores for each residue based on their occurrence in top important features, weighted by feature importance scores.

class mdxplain.structure_visualization.helper.residue_importance_calculator.ResidueImportanceCalculator

Calculator for residue importance scores.

Computes importance scores for residues based on their occurrence in top important features, weighted by feature importance scores.

Examples

>>> # Calculate residue importance from top features
>>> top_features = [
...     {"residue_indices": [5, 10], "importance_score": 0.85},
...     {"residue_indices": [5], "importance_score": 0.72}
... ]
>>> importance = ResidueImportanceCalculator.calculate_residue_importance(
...     top_features
... )
>>> print(importance[5])  # 1.57 (0.85 + 0.72)

static calculate_residue_importance(top_features: List[Dict[str, Any]]) → Dict[int, float]

Calculate importance score for each residue.

Computes weighted importance scores based on occurrence in top features, where each occurrence is weighted by the feature’s importance score.

Parameters

top_featuresList[Dict[str, Any]]

List of top feature dictionaries with keys:

“residue_indices”: List[int]
“importance_score”: float

Returns

Dict[int, float]: Mapping from residue index to importance score

Examples

>>> top_features = [
...     {"residue_indices": [5, 10], "importance_score": 0.85},
...     {"residue_indices": [10], "importance_score": 0.60}
... ]
>>> importance = ResidueImportanceCalculator.calculate_residue_importance(
...     top_features
... )
>>> # Residue 5: 0.85, Residue 10: 0.85 + 0.60 = 1.45

Notes

Each residue occurrence is weighted by feature importance
Residues in multiple features accumulate scores
Only residues in top features receive non-zero scores
Uses residue_indices from feature metadata (no string parsing)

static importance_to_beta_factors(residue_importance: Dict[int, float], topology: Topology) → ndarray

Convert residue importance scores to beta factors.

Normalizes importance scores to 0-1 range and expands to per-atom beta factors (all atoms in a residue get the same beta factor).

Parameters

residue_importanceDict[int, float]: Mapping from residue index to importance score
topologymdtraj.Topology: Topology object for atom-residue mapping

Returns

np.ndarray: Array of beta factors for all atoms, shape (n_atoms,)

Examples

>>> residue_importance = {5: 1.57, 10: 1.45, 15: 0.92}
>>> topology = md.load("structure.pdb").topology
>>> beta_factors = ResidueImportanceCalculator.importance_to_beta_factors(
...     residue_importance, topology
... )
>>> print(beta_factors.shape)  # (n_atoms,)
>>> print(beta_factors.max())  # 1.0

Notes

Scores are normalized to 0-1 range for nglview visualization
All atoms in a residue receive the same beta factor
Residues not in importance dict receive beta factor 0.0

static calculate_beta_factors_from_features(top_features: List[Dict[str, Any]], topology: Topology) → ndarray

Calculate beta factors directly from top features.

Convenience method that combines calculate_residue_importance and importance_to_beta_factors in one call.

Parameters

top_featuresList[Dict[str, Any]]: List of top feature dictionaries
topologymdtraj.Topology: Topology object

Returns

np.ndarray: Array of beta factors for all atoms

Examples

>>> top_features = pipeline.feature_importance.get_top_features(
...     "dt_analysis", "cluster_0_vs_rest", n=10
... )
>>> topology = pipeline.data.trajectory_data.get_topology()
>>> beta_factors = ResidueImportanceCalculator.calculate_beta_factors_from_features(
...     top_features, topology
... )