Contact to Distances Converter

GitHub Link to Code.

Helper class for converting contact-based feature selectors to distance-based.

Contact features are boolean (0/1) indicating presence/absence of contacts, which are not suitable for violin plots. This helper creates equivalent distance-based feature selectors for the same atom pairs, enabling continuous value visualization.

class mdxplain.plots.helper.contact_to_distances_converter.ContactToDistancesConverter

Helper class for converting contact features to distances.

Contacts are boolean features (0/1) that indicate whether atoms are within a cutoff distance. These are not suitable for violin plots which require continuous values. This helper creates a new feature selector with distances for the same atom pairs.

The conversion preserves:

Exact same atom pairs
Same feature ordering
Same trajectory coverage

Examples

>>> # Ensure feature selector uses continuous values
>>> continuous_selector = ContactToDistancesConverter.convert_contacts_to_distances(
...     pipeline_data, "important_contacts"
... )
>>> # Returns "important_contacts_distances" if conversion needed
>>> # Returns "important_contacts" if already continuous

static convert_contacts_to_distances(pipeline_data: PipelineData, feature_selector_name: str) → Tuple[str, bool, float | None]

Ensure feature selector uses continuous distance features.

If the selector contains ‘contacts’ (boolean features), creates a new selector ‘{name}_distances’ with distances for the same atom pairs. If selector already uses continuous features, returns original name unchanged.

Parameters

pipeline_dataPipelineData: Pipeline data container with feature selectors
feature_selector_namestr: Name of the feature selector to check/convert

Returns

Tuple[str, bool, Optional[float]]

Tuple of (selector_name, is_temporary, contact_cutoff)

selector_name: Name of continuous feature selector
is_temporary: True if temporary selector was created, False otherwise
contact_cutoff: Contact cutoff value if converted from contacts, None otherwise

Raises

ValueError: If feature selector not found or conversion fails

Examples

>>> # Selector with contacts - creates new distances selector
>>> new_name = ContactToDistancesConverter.convert_contacts_to_distances(
...     pipeline_data, "key_contacts"
... )
>>> print(new_name)  # "key_contacts_distances"

>>> # Selector already with distances - returns original
>>> name = ContactToDistancesConverter.convert_contacts_to_distances(
...     pipeline_data, "key_distances"
... )
>>> print(name)  # "key_distances"

Notes

Boolean contact features cannot be meaningfully visualized in violin plots. This method automatically creates a distances-based version for visualization while preserving the original selector for analysis purposes.

The new selector name follows the pattern: “{original}_distances”

static cleanup_temporary_selector(pipeline_data: PipelineData, selector_name: str) → None

Remove temporary distance selector.

Silently removes a feature selector that was created temporarily for visualization purposes.

Parameters

pipeline_dataPipelineData: Pipeline data container
selector_namestr: Name of selector to remove

Returns

None: Removes selector from pipeline_data

Examples

>>> # After creating temporary selector
>>> selector, is_temp = ContactToDistancesConverter.convert_contacts_to_distances(
...     pipeline_data, "contacts_only"
... )
>>> # Use selector...
>>> if is_temp:
...     ContactToDistancesConverter.cleanup_temporary_selector(
...         pipeline_data, selector
...     )

Notes

Only removes selectors that actually exist in pipeline_data. Silently does nothing if selector doesn’t exist.