Trajectory Process Helper

GitHub Link to Code.

Trajectory processing utilities.

class mdxplain.trajectory.helper.process_helper.trajectory_process_helper.TrajectoryProcessHelper

Utility class for processing individual trajectory objects.

Apply slicing to trajectories using frames OR DataSelector.

Parameters

pipeline_dataPipelineData: Pipeline data object containing trajectory data
indicesList[int]: List of trajectory indices to process
framesint, slice, list, or None: Frame specification for slicing (ignored if data_selector is used)
data_selectorstr or None: Name of DataSelector to use for frame selection
strideint or None: Stride value for frame subsampling
cutint or None: Frame number after which to cut trajectories
inplacebool, default=True: Whether to perform operation in-place. Note: slicing always returns a new trajectory object (view) which replaces the original in the pipeline.

Returns

None: Modifies trajectories and updates pipeline_data.

Examples

>>> # Using frames parameter
>>> TrajectoryProcessHelper.apply_slicing(
...     pipeline_data, [0, 1, 2], frames=1000, data_selector=None, stride=2, cut=500
... )

static apply_selection_to_new_trajectories(new_trajectories: List[Any], selection: str | None) → List[Any]

Apply atom selection to new trajectories if provided.

Parameters

new_trajectorieslist: List of trajectory objects to process
selectionstr or None: MDTraj selection string to apply

Returns

list: List of trajectories with selection applied

Examples

>>> processed_trajs = TrajectoryProcessHelper.apply_selection_to_new_trajectories(
...     trajectories, "protein"
... )

static execute_removal(traj_data: TrajectoryData, indices_to_remove: List[int]) → None

Remove trajectories and names from trajectory data.

Parameters

traj_data“TrajectoryData”: Trajectory data object
indices_to_removelist: List of trajectory indices to remove (must be sorted in reverse order)

Returns

None: Removes trajectories from traj_data

Examples

>>> # Remove trajectories at indices [3, 1, 0] (reverse sorted)
>>> TrajectoryProcessHelper.execute_removal(traj_data, [3, 1, 0])

static validate_name_mapping(traj_data: TrajectoryData, name_mapping: Dict | List) → None

Validate name mapping input before processing.

Parameters

traj_data“TrajectoryData”: Trajectory data object
name_mappingdict or list: Name mapping to validate

Returns

None: Validation successful

Examples

>>> traj_data = "TrajectoryData"()
>>> # Load some trajectories first
>>> TrajectoryProcessHelper.validate_name_mapping(traj_data, ['new1', 'new2'])
>>> TrajectoryProcessHelper.validate_name_mapping(traj_data, {0: 'renamed_first'})

Raises

ValueError: If trajectories are not loaded or mapping is invalid

static rename_with_list(traj_data: TrajectoryData, name_list: List[str]) → List[str]

Process list-based positional renaming with validation.

Parameters

traj_data“TrajectoryData”: Trajectory data object
name_listlist: List of new names for positional assignment

Returns

list: Validated list of new trajectory names

Examples

>>> traj_data = "TrajectoryData"()
>>> # Assuming 3 trajectories are loaded
>>> new_names = TrajectoryProcessHelper.rename_with_list(
...     traj_data, ['system1', 'system2', 'system3']
... )
>>> print(new_names)
['system1', 'system2', 'system3']

Raises

ValueError: If list length doesn’t match trajectory count

static rename_with_dict(traj_data: TrajectoryData, name_dict: Dict[int | str, str]) → List[str]

Process dict-based selective renaming with validation.

Parameters

traj_data“TrajectoryData”: Trajectory data object
name_dictdict: Dictionary mapping old identifiers to new names

Returns

list: New list of trajectory names with applied changes

Examples

>>> traj_data = "TrajectoryData"()
>>> # Rename specific trajectories by index
>>> new_names = TrajectoryProcessHelper.rename_with_dict(
...     traj_data, {0: 'first_system', 2: 'third_system'}
... )
>>> # Rename by existing name
>>> new_names = TrajectoryProcessHelper.rename_with_dict(
...     traj_data, {'old_name': 'new_name'}
... )

Raises

ValueError: If dictionary keys reference invalid trajectories

Parameters

traj_data“TrajectoryData”: Trajectory data object
name_dictdict: Dictionary mapping old identifiers to new names

Returns

list: New list of trajectory names with applied changes

Raises

ValueError: If dictionary keys reference invalid trajectories