Validation Helper

GitHub Link to Code.

Helper class for input validation in plots module.

Provides validation for plot parameters to ensure data consistency and proper error messages before plot generation.

class mdxplain.plots.helper.validation_helper.ValidationHelper

Helper class for atomic input validation in plots.

Provides static methods for validating individual plot parameters. Each method validates ONE specific aspect and can be composed together.

Examples

>>> # Validate decomposition exists
>>> decomp = ValidationHelper.validate_decomposition_exists(
...     pipeline_data, "pca"
... )

>>> # Validate dimensions
>>> ValidationHelper.validate_dimensions_list([0, 1], "pca", 10)

>>> # Validate clustering exists
>>> cluster = ValidationHelper.validate_clustering_exists(
...     pipeline_data, "dbscan"
... )

>>> # Validate trajectory selection
>>> indices = ValidationHelper.validate_trajectory_selection(
...     pipeline_data, "all"
... )

>>> # Validate dimension layout for grid
>>> ValidationHelper.validate_dimensions_for_layout([0, 1, 2, 3])

static validate_decomposition_exists(pipeline_data: PipelineData, decomposition_name: str)

Validate that decomposition exists in pipeline data.

Parameters

pipeline_dataPipelineData: Pipeline data container
decomposition_namestr: Name of decomposition to validate

Returns

DecompositionData: Decomposition object if found

Raises

ValueError: If decomposition not found

Examples

>>> decomp = ValidationHelper.validate_decomposition_exists(
...     pipeline_data, "pca"
... )

static validate_dimensions_list(dimensions: List[int], decomposition_name: str, n_components: int) → None

Validate dimensions list format, type, range, and uniqueness.

Parameters

dimensionsList[int]: Dimension indices to validate
decomposition_namestr: Name of decomposition (for error messages)
n_componentsint: Number of available components in decomposition

Returns

None

Raises

ValueError: If dimensions empty, wrong type, out of range, or duplicates

Examples

>>> ValidationHelper.validate_dimensions_list([0, 1], "pca", 10)  # OK
>>> ValidationHelper.validate_dimensions_list([0, 15], "pca", 10)  # ValueError

static validate_show_centers_requirement(show_centers: bool, clustering_name: str | None) → None

Validate show_centers requires clustering_name.

Parameters

show_centersbool: Whether cluster centers should be shown
clustering_nameOptional[str]: Name of clustering

Returns

None

Raises

ValueError: If show_centers=True but clustering_name not specified

Examples

>>> ValidationHelper.validate_show_centers_requirement(True, "dbscan")  # OK
>>> ValidationHelper.validate_show_centers_requirement(True, None)  # ValueError

static validate_clustering_compatibility(pipeline_data: PipelineData, clustering_name: str, decomposition_name: str, n_frames_decomp: int) → None

Validate clustering exists and matches decomposition frame count.

Parameters

pipeline_dataPipelineData: Pipeline data container
clustering_namestr: Name of clustering to validate
decomposition_namestr: Name of decomposition (for error messages)
n_frames_decompint: Number of frames in decomposition

Returns

None

Raises

ValueError: If clustering not found or frame count mismatch

Examples

>>> ValidationHelper.validate_clustering_compatibility(
...     pipeline_data, "dbscan", "pca", 1000
... )

static validate_clustering_exists(pipeline_data: PipelineData, clustering_name: str)

Validate that clustering exists in pipeline data.

Parameters

pipeline_dataPipelineData: Pipeline data container
clustering_namestr: Name of clustering to validate

Returns

ClusterData: Clustering object if found

Raises

ValueError: If clustering not found

Examples

>>> cluster = ValidationHelper.validate_clustering_exists(
...     pipeline_data, "dbscan"
... )

static validate_trajectory_selection(pipeline_data: PipelineData, traj_selection)

Validate trajectory selection and return indices.

Parameters

pipeline_dataPipelineData: Pipeline data container
traj_selectionint, str, list, or “all”: Trajectory selection to validate

Returns

List[int]: List of trajectory indices

Raises

ValueError: If no trajectories match selection

Examples

>>> indices = ValidationHelper.validate_trajectory_selection(
...     pipeline_data, "all"
... )
>>> indices = ValidationHelper.validate_trajectory_selection(
...     pipeline_data, [0, 1, 2]
... )

static validate_dimensions_for_layout(dimensions: List[int]) → None

Validate that dimensions list is suitable for grid layout.

For landscape plots, dimensions are paired consecutively. An even number of dimensions is required for proper grid layout.

Parameters

dimensionsList[int]: Dimension indices to plot

Returns

None: Raises ValueError if validation fails

Raises

ValueError: If odd number of dimensions provided

Examples

>>> # Valid - even number
>>> ValidationHelper.validate_dimensions_for_layout([0, 1, 2, 3])

>>> # Invalid - odd number
>>> ValidationHelper.validate_dimensions_for_layout([0, 1, 2])
ValueError: Odd number of dimensions (3) provided. Landscape plots require
consecutive dimension pairs. Please provide an even number of dimensions.

Notes

Dimensions are paired consecutively: [0,1,2,3] becomes [(0,1), (2,3)] for a 2x1 grid layout.

static validate_feature_importance_exists(pipeline_data: PipelineData, fi_name: str)

Validate that feature importance analysis exists in pipeline data.

Parameters

pipeline_dataPipelineData: Pipeline data container
fi_namestr: Name of feature importance analysis to validate

Returns

FeatureImportanceData: Feature importance data object if found

Raises

ValueError: If feature importance analysis not found

Examples

>>> fi_data = ValidationHelper.validate_feature_importance_exists(
...     pipeline_data, "tree_analysis"
... )

static validate_positive_integer(value: int, param_name: str) → None

Validate that parameter is a positive integer.

Parameters

valueint: Value to validate
param_namestr: Name of parameter for error messages

Returns

None: Raises ValueError if validation fails

Raises

ValueError: If value is not positive integer

Examples

>>> ValidationHelper.validate_positive_integer(10, "n_top")  # OK
>>> ValidationHelper.validate_positive_integer(0, "n_top")  # ValueError
>>> ValidationHelper.validate_positive_integer(-5, "n_top")  # ValueError

static validate_feature_selector_exists(pipeline_data: PipelineData, feature_selector_name: str)

Validate that feature selector exists in pipeline data.

Parameters

pipeline_dataPipelineData: Pipeline data container
feature_selector_namestr: Name of feature selector to validate

Returns

None

Raises

ValueError: If feature selector not found

Examples

>>> ValidationHelper.validate_feature_selector_exists(
...     pipeline_data, "my_selector"
... )

static has_discrete_features(all_features: List[tuple], metadata_map: dict) → bool

Check if any feature in the list is discrete.

Examines visualization metadata of all features to determine if at least one discrete feature is present. Used to adjust plot spacing for discrete feature labels.

Parameters

all_featuresList[tuple]: List of (feature_type, feature_name) tuples
metadata_mapdict: Nested dict structure: {feat_type: {feat_name: metadata}}

Returns

bool: True if at least one discrete feature found, False otherwise

Examples

>>> features = [("distances", "ALA1-VAL2"), ("contacts", "GLU3-ARG4")]
>>> metadata = {
...     "distances": {
...         "ALA1-VAL2": {"type_metadata": {"visualization": {"is_discrete": False}}}
...     },
...     "contacts": {
...         "GLU3-ARG4": {"type_metadata": {"visualization": {"is_discrete": True}}}
...     }
... }
>>> ValidationHelper.has_discrete_features(features, metadata)
True

Notes

Returns False if no features provided or if visualization metadata is missing/incomplete for all features.