Trajectory Data

GitHub Link to Code.

Pure MD trajectory data container.

Container for MD trajectory objects with tag annotation support. Does not contain feature computations or analysis data - only trajectory management and tag metadata.

class mdxplain.trajectory.entities.trajectory_data.TrajectoryData

Pure trajectory data container with tag support.

This class serves as a focused container for molecular dynamics trajectories and their associated tag metadata. It provides trajectory management without feature computation or analysis dependencies.

The class supports tag annotation for trajectories, enabling advanced data selection and filtering capabilities through the DataPicker module.

Examples

Basic usage:

>>> traj_data = TrajectoryData()
>>> # Trajectories loaded via TrajectoryManager
>>> print(f"Loaded {len(traj_data.trajectories)} trajectories")

With tag annotation:

>>> traj_data.trajectory_tags = {
...     0: ["system_A", "biased", "high_temp"],
...     1: ["system_A", "unbiased", "high_temp"]
... }
>>> tags = traj_data.get_trajectory_tags(0)
>>> print(tags)  # ["system_A", "biased", "high_temp"]

Attributes

trajectorieslist: List of loaded MD trajectory objects (MDTraj)
trajectory_nameslist: List of trajectory names corresponding to trajectories
trajectory_tagsdict: Dictionary mapping trajectory indices/names to tag lists
res_label_datadict or None: Residue labeling data from nomenclature systems

__init__() → None

Initialize trajectory data container.

Parameters

None

Returns

None: Initializes empty trajectory data container

Examples

>>> traj_data = TrajectoryData()
>>> print(len(traj_data.trajectories))  # 0

get_trajectory_tags(trajectory_id: int | str) → List[str] | None

Get tags for a specific trajectory.

Parameters

trajectory_idint or str: Trajectory index or name

Returns

list or None: List of tags for the trajectory, or None if not found

Examples

>>> traj_data = TrajectoryData()
>>> traj_data.trajectory_tags = {0: ["system_A", "biased"]}
>>> tags = traj_data.get_trajectory_tags(0)
>>> print(tags)  # ["system_A", "biased"]

set_trajectory_tags(trajectory_id: int | str, tags: List[str]) → None

Set tags for a specific trajectory.

Parameters

trajectory_idint or str: Trajectory index or name
tagslist: List of tag strings

Returns

None: Sets tags for the specified trajectory

Examples

>>> traj_data = TrajectoryData()
>>> traj_data.set_trajectory_tags(0, ["system_A", "biased"])
>>> traj_data.set_trajectory_tags("traj1", ["system_B", "unbiased"])

property n_frames_total: int

Get total number of frames across all trajectories.

Returns

int: Total number of frames

get_trajectory_names() → List[str]

Get list of trajectory names.

Returns

list: List of trajectory names

Examples

>>> names = traj_data.get_trajectory_names()
>>> print(names)
['system1_prot_traj1', 'system1_prot_traj2']

print_info() → None

Print information about loaded trajectories.

Parameters

None

Returns

None: Prints trajectory information to console

Examples

>>> traj_data.print_info()
Loaded 3 trajectories:
  [0] system1_prot_traj1: 1000 frames, tags: ['system_A', 'biased']
  [1] system1_prot_traj2: 1500 frames, tags: ['system_A', 'unbiased']
  [2] system2_prot_traj1: 800 frames, tags: ['system_B', 'biased']

save(save_path: str) → None

Save the TrajectoryData object to disk.

Parameters

save_pathstr: Path where to save the TrajectoryData object

Returns

None: Saves the TrajectoryData object to the specified path

Examples

>>> traj_data.save('trajectory_data.pkl')

load(load_path: str) → None

Load a previously saved TrajectoryData object from disk.

Parameters

load_pathstr: Path to the saved TrajectoryData file

Returns

None: Loads the TrajectoryData object from the specified path

Examples

>>> traj_data = TrajectoryData()
>>> traj_data.load('trajectory_data.pkl')

reset() → None

Reset the trajectory data object to empty state.

Parameters

None

Returns

None: Resets all trajectory data and tags

Examples

>>> traj_data.reset()
>>> print(len(traj_data.trajectories))  # 0

get_trajectory_indices(traj_selection: int | str | List[int | str] | all = 'all') → List[int]

Get trajectory indices based on selection criteria.

Central method for trajectory selection supporting indices, names, tags, and combinations thereof. Uses SelectionResolveHelper for consistent trajectory resolution across all modules.

Parameters

traj_selectionint, str, list, or “all”

Selection criteria:

int: trajectory index
str: trajectory name, tag (prefixed with “tag:”) or advanced formats:
- Range: “0-3”, “id 0-3” → [0, 1, 2, 3]
- Comma list: “1,2,4,5”, “id 1,2,4,5” → [1, 2, 4, 5]
- Single number: “7”, “id 7” → [7]
- Pattern: “system_*” → fnmatch pattern matching
list: mix of indices/names/tags/patterns
“all”: all trajectories

Returns

List[int]: List of trajectory indices matching the selection criteria

Examples

>>> # All trajectories
>>> indices = traj_data.get_trajectory_indices("all")

>>> # Single trajectory by index
>>> indices = traj_data.get_trajectory_indices(0)

>>> # Range format
>>> indices = traj_data.get_trajectory_indices("0-3")  # [0, 1, 2, 3]

>>> # Comma list format
>>> indices = traj_data.get_trajectory_indices("1,2,4,5")  # [1, 2, 4, 5]

>>> # Pattern matching
>>> indices = traj_data.get_trajectory_indices("system_*")

>>> # By tag
>>> indices = traj_data.get_trajectory_indices("tag:system_A")

>>> # Mixed selection
>>> indices = traj_data.get_trajectory_indices([0, "traj1", "tag:biased"])