Label Operation Helper

GitHub Link to Code.

Label operation utilities for trajectory data consistency.

class mdxplain.trajectory.helper.process_helper.label_operation_helper.LabelOperationHelper

Utility class for maintaining label consistency during trajectory operations.

static apply_atom_selection_to_labels(traj_data: TrajectoryData, traj_indices: List[int], original_residue_indices: Dict[int, np.ndarray]) → None

Apply atom selection operations to trajectory labels.

When atoms are selected, the residue structure changes. Labels need to be filtered to only include residues that are still present after atom selection.

Parameters

traj_dataTrajectoryData: Trajectory data object containing labels
traj_indicesList[int]: Indices of trajectories that were modified
original_residue_indicesDict[int, np.ndarray]: Mapping of trajectory index to original residue indices that were kept

Returns

None: Modifies res_label_data in-place to match new residue structure

static combine_stack_labels(traj_data: TrajectoryData, target_idx: int, source_idx: int, target_n_residues: int) → None

Combine and renumber labels from stacked trajectories.

Parameters

traj_dataTrajectoryData: Trajectory data containing labels
target_idxint: Index of target trajectory
source_idxint: Index of source trajectory
target_n_residuesint: Number of residues in target trajectory before stacking

Returns

None: Updates labels in traj_data in-place

static map_residues_to_original_indices(original_residue_info: List[tuple], current_topology: Topology) → ndarray

Map residues by sequential structure matching.

After operations like remove_solvent(), MDTraj may renumber residues, making resSeq-based matching unreliable. We match residues sequentially by name and atom composition, preserving order.

This method uses lightweight residue info (just names and atoms) instead of full trajectory data to avoid memory overhead.

Parameters

original_residue_infoList[tuple]: Original residue structure as list of (name, atoms) tuples where atoms is a tuple of (atom_name, element_symbol) tuples
current_topologymd.Topology: Topology after modification (e.g., after solvent removal)

Returns

np.ndarray: Original residue indices of residues that were kept

Examples

>>> # Prepare lightweight residue info
>>> original_info = [
...     ('ALA', (('CA', 'C'), ('C', 'C'))),
...     ('HOH', (('O', 'O'),)),
...     ('GLY', (('CA', 'C'), ('C', 'C'))),
...     ('HOH', (('O', 'O'),)),
...     ('ALA', (('CA', 'C'), ('C', 'C')))
... ]
>>> # After removal: 3 residues (ALA, GLY, ALA)
>>> # Returns: [0, 2, 4] - original indices of kept residues
>>> kept_indices = LabelOperationHelper.map_residues_to_original_indices(
...     original_info, modified_topology
... )
array([0, 2, 4])