Decomposition Entities

GitHub Link to Code.

Decomposition data container for computed dimensionality reduction results.

Container for decomposition results (PCA, KernelPCA) with associated metadata and hyperparameters. Stores decomposed data with transformation information.

class mdxplain.decomposition.entities.decomposition_data.DecompositionData(decomposition_type: str, use_memmap: bool = False, cache_path: str = './cache')

Container for decomposition results with metadata and hyperparameters.

Stores results from dimensionality reduction methods (PCA, KernelPCA) along with transformation metadata and hyperparameters used for computation.

Attributes

decomposition_typestr: Type of decomposition used (e.g., “pca”, “kernel_pca”)
use_memmapbool: Whether memory mapping is used for large datasets
cache_pathstr: Path for memory-mapped cache files
datanp.ndarray or None: Decomposed data array
metadatadict or None: Metadata including explained variance, hyperparameters, etc.
frame_mappingdict or None: Mapping from global_frame_index to (trajectory_index, local_frame_index) for tracking frame origins across multiple trajectories

__init__(decomposition_type: str, use_memmap: bool = False, cache_path: str = './cache') → None

Initialize decomposition data container.

Parameters

decomposition_typestr: Type of decomposition used (e.g., “pca”, “kernel_pca”)
use_memmapbool, default=False: Whether to use memory mapping for large datasets
cache_pathstr, optional: Path for memory-mapped cache files

Returns

None: Initializes decomposition data container

Examples

>>> # Basic initialization
>>> decomp_data = DecompositionData("pca")

>>> # With memory mapping
>>> decomp_data = DecompositionData(
...     "kernel_pca",
...     use_memmap=True,
...     cache_path="./cache/kernel_pca.dat"
... )

get_frame_mapping()

Get frame mapping from global frame indices to trajectory origins.

Returns

dict or None: Mapping from global_frame_index to (trajectory_index, local_frame_index), or None if decomposition has not been computed or mapping is not available

Examples

>>> decomp_data = DecompositionData("pca")
>>> frame_mapping = decomp_data.get_frame_mapping()
>>> if frame_mapping is not None:
...     print(f"Frame 0 comes from: {frame_mapping[0]}")  # (traj_idx, local_frame_idx)

set_frame_mapping(frame_mapping: Dict[int, int]) → None

Set frame mapping from global frame indices to trajectory origins.

Parameters

frame_mappingdict: Mapping from global_frame_index to (trajectory_index, local_frame_index)

Returns

None: Sets the frame mapping for trajectory tracking

Examples

>>> decomp_data = DecompositionData("pca")
>>> mapping = {0: (0, 10), 1: (0, 11), 2: (1, 5)}  # global -> (traj, local)
>>> decomp_data.set_frame_mapping(mapping)

save(save_path: str) → None

Save DecompositionData object to disk.

Parameters

save_pathstr: Path where to save the DecompositionData object

Returns

None: Saves the DecompositionData object to the specified path

Examples

>>> decomposition_data.save('analysis_results/pca_decomposition.pkl')

load(load_path: str) → None

Load DecompositionData object from disk.

Parameters

load_pathstr: Path to the saved DecompositionData file

Returns

None: Loads the DecompositionData object from the specified path

Examples

>>> decomposition_data.load('analysis_results/pca_decomposition.pkl')

print_info() → None

Print comprehensive decomposition information.

Parameters

None

Returns

None: Prints decomposition information to console

Examples

>>> decomposition_data.print_info()
=== DecompositionData ===
Decomposition Type: PCA
Transformed Data: 1000 frames x 10 components
Explained Variance Ratio: [0.45, 0.23, 0.12, 0.08, ...]