I/O

loader

Feature loading and dataset validation.

FEATURE_EXTENSIONS module-attribute

FEATURE_EXTENSIONS = ('.npy', '.pkl')

list_feature_files

list_feature_files(features_dir: Path) -> List[Path]

List *.npy and *.pkl feature files in a directory, sorted by stem.

Parameters:

Name	Type	Description	Default
features_dir	Path	Directory containing feature arrays.	required

Returns:

Type	Description
list of Path	Sorted paths to feature files (one file per trajectory stem).

Raises:

Type	Description
FileNotFoundError	If the directory does not exist.
ValueError	If no supported feature files are found or duplicate stems exist.

load_feature_array

load_feature_array(path: Path) -> np.ndarray

Load a feature array from a .npy or .pkl file.

Parameters:

Name	Type	Description	Default
path	Path	Path to a feature file.	required

Returns:

Type	Description
ndarray	Loaded feature array.

Raises:

Type	Description
ValueError	If the file extension is unsupported or the loaded object cannot be converted to an array.

load_features

load_features(features_dir: Path) -> Dataset

Load feature arrays from disk and build a :class:Dataset.

Each *.npy or *.pkl file must have shape (n_frames, n_features). Per-frame FrameRecord objects are created while preserving trajectory identity.

Parameters:

Name	Type	Description	Default
features_dir	Path	Directory containing feature files.	required

Returns:

Type	Description
Dataset	Loaded dataset with concatenated feature matrix and frame records.

Raises:

Type	Description
ValueError	If feature arrays have inconsistent dimensionality.

validate_dataset

validate_dataset(dataset: Dataset, trajectory_files: Optional[List[Path]] = None) -> None

Run consistency checks on a loaded dataset.

Parameters:

Name	Type	Description	Default
dataset	Dataset	Dataset to validate.	required
trajectory_files	list of Path or None	Optional trajectory files for cross-validation.	None

Raises:

Type	Description
ValueError	If internal consistency checks fail.

validate_feature_trajectory_mapping

validate_feature_trajectory_mapping(feature_files: List[Path], trajectory_files: Optional[List[Path]] = None) -> None

Ensure feature and trajectory filenames match one-to-one.

Parameters:

Name	Type	Description	Default
feature_files	list of Path	Feature .npy or .pkl file paths.	required
trajectory_files	list of Path or None	Optional coordinate trajectory file paths.	None

Raises:

Type	Description
ValueError	If stems do not match exactly between features and trajectories.

list_trajectory_files

list_trajectory_files(trajectories_dir: Path) -> List[Path]

List coordinate trajectory files supported by mdtraj.

Parameters:

Name	Type	Description	Default
trajectories_dir	Path	Directory containing trajectory files.	required

Returns:

Type	Description
list of Path	Sorted paths to trajectory files (.xtc, .dcd, .trr).

Raises:

Type	Description
FileNotFoundError	If the directory does not exist.
ValueError	If no supported trajectory files are found.

trajectory

Coordinate trajectory loading and frame extraction via mdtraj.

build_trajectory_map

build_trajectory_map(trajectories_dir: Path, traj_names: List[str]) -> Dict[int, Path]

Map trajectory IDs to coordinate file paths by matching stems.

Parameters:

Name	Type	Description	Default
trajectories_dir	Path	Directory containing coordinate trajectories.	required
traj_names	list of str	Basenames corresponding to feature files (e.g. traj_0).	required

Returns:

Type	Description
dict	Mapping from traj_id to trajectory file path.

Raises:

Type	Description
ValueError	If a trajectory file cannot be found for any traj_name.

load_trajectory

load_trajectory(topology: Path, trajectory_path: Path) -> md.Trajectory

Load a single trajectory using mdtraj.

Parameters:

Name	Type	Description	Default
topology	Path	Topology file (PDB, parm7, etc.).	required
trajectory_path	Path	Coordinate trajectory file.	required

Returns:

Type	Description
Trajectory	Loaded trajectory object.

extract_frame

extract_frame(topology: Path, trajectory_path: Path, frame_id: int) -> md.Trajectory

Load a trajectory and return a single-frame subset.

Parameters:

Name	Type	Description	Default
topology	Path	Topology file path.	required
trajectory_path	Path	Coordinate trajectory file path.	required
frame_id	int	Zero-based frame index to extract.	required

Returns:

Type	Description
Trajectory	Single-frame trajectory suitable for PDB export.

validate_trajectory_frame_counts

validate_trajectory_frame_counts(topology: Path, trajectory_map: Dict[int, Path], expected_counts: Dict[int, int]) -> None

Verify trajectory frame counts match feature frame counts.

Parameters:

Name	Type	Description	Default
topology	Path	Topology file path.	required
trajectory_map	dict	Mapping from traj_id to trajectory file.	required
expected_counts	dict	Expected frame count per traj_id from features.	required

Raises:

Type	Description
ValueError	If any trajectory has a different number of frames than its features.