Criteria Builder Helper

GitHub Link to Code.

Criteria builder helper for data selector operations.

This module provides helper methods for building selection criteria dictionaries that describe how frame selections were created.

class mdxplain.data_selector.helper.criteria_builder_helper.CriteriaBuilderHelper

Helper class for building selection criteria dictionaries.

Provides static methods for creating standardized criteria dictionaries that describe how frame selections were created. These dictionaries are stored in DataSelectorData objects for documentation and debugging.

static build_tag_criteria(tags: List[str], match_all: bool, n_matches: int) → Dict[str, Any]

Build criteria dictionary for tag-based selection.

Creates a standardized criteria dictionary that documents how a tag-based frame selection was performed.

Parameters

tagsList[str]: List of tags used for selection
match_allbool: Whether all tags were required (True) or any tag (False)
n_matchesint: Number of frames that matched the criteria

Returns

Dict[str, Any]: Criteria dictionary with selection documentation

Examples

>>> criteria = CriteriaBuilderHelper.build_tag_criteria(
...     ["system_A", "biased"], True, 150
... )
>>> print(criteria["type"])  # "tags"
>>> print(criteria["n_matches"])  # 150

static build_cluster_criteria(clustering_name: str, cluster_ids: List[int | str], resolved_cluster_ids: List[int], n_matches: int) → Dict[str, Any]

Build criteria dictionary for cluster-based selection.

Creates a standardized criteria dictionary that documents how a cluster-based frame selection was performed, including both original and resolved cluster IDs.

Parameters

clustering_namestr: Name of the clustering used for selection
cluster_idsList[Union[int, str]]: Original cluster identifiers (may include names)
resolved_cluster_idsList[int]: Numeric cluster IDs after name resolution
n_matchesint: Number of frames that matched the criteria

Returns

Dict[str, Any]: Criteria dictionary with selection documentation

Examples

>>> criteria = CriteriaBuilderHelper.build_cluster_criteria(
...     "conformations", ["folded", 1], [0, 1], 300
... )
>>> print(criteria["type"])  # "cluster"
>>> print(criteria["clustering_name"])  # "conformations"

static build_indices_criteria(trajectory_frames: Dict[int, List[int]], n_matches: int) → Dict[str, Any]

Build criteria dictionary for trajectory-specific explicit indices selection.

Creates a standardized criteria dictionary that documents how a trajectory-specific explicit indices-based frame selection was performed.

Parameters

trajectory_framesDict[int, List[int]]: Dictionary mapping trajectory indices to their selected frame indices
n_matchesint: Number of frames selected

Returns

Dict[str, Any]: Criteria dictionary with selection documentation

Examples

>>> trajectory_frames = {0: [0, 10, 20], 1: [100, 200]}
>>> criteria = CriteriaBuilderHelper.build_indices_criteria(trajectory_frames, 5)
>>> print(criteria["type"])  # "indices"
>>> print(criteria["n_matches"])  # 5
>>> print(criteria["n_trajectories"])  # 2

static build_combination_criteria(source_selectors: List[str], combination_mode: str, n_matches: int) → Dict[str, Any]

Build criteria dictionary for combination-based selection.

Creates a standardized criteria dictionary that documents how a combination of multiple selectors was performed.

Parameters

source_selectorsList[str]: Names of the source selectors that were combined
combination_modestr: Mode used for combination (“union”, “intersection”, “difference”)
n_matchesint: Number of frames in the final combined selection

Returns

Dict[str, Any]: Criteria dictionary with selection documentation

Examples

>>> criteria = CriteriaBuilderHelper.build_combination_criteria(
...     ["folded_frames", "biased_frames"], "intersection", 75
... )
>>> print(criteria["type"])  # "combination"
>>> print(criteria["combination_mode"])  # "intersection"