boltzkit.utils.molecular.tica

Functions

create_deeptime_tica_model(trajectory, lagtime)

Train a TICA model using the deeptime library.

get_tica_features(trajectory[, ...])

Compute feature vectors for TICA from an MDTraj trajectory.

Classes

TicaModelWithLengthScale

Wrapper around a deeptime TICA model that applies a coordinate length-scale conversion before feature extraction.
boltzkit.utils.molecular.tica.get_tica_features(trajectory: Trajectory, use_dihedrals: bool = True, use_distances: bool = True, selection: str = 'symbol == C or symbol == N or symbol == S')[source]

Compute feature vectors for TICA from an MDTraj trajectory.

Features can include pairwise distances between selected atoms and backbone dihedral angles represented using sine/cosine encoding.

Parameters:

  • trajectory (md.Trajectory) – Input trajectory containing atomic coordinates and topology.

  • use_dihedrals (bool, default=True) – Whether to include backbone dihedral angles (phi, psi, omega) as features.

  • use_distances (bool, default=True) – Whether to include pairwise distances between selected atoms.

  • selection (str, default=SELECTION) – MDTraj atom selection string used to filter atoms before computing features.

Returns:

Feature matrix of shape (n_frames, n_features).

Return type:

np.ndarray

Raises:

ValueError – If both use_dihedrals and use_distances are False.

Notes

  • Distances are computed for all unique atom pairs within the selected atom subset.

  • Dihedral angles are transformed using sine/cosine encoding to avoid discontinuities due to angular periodicity.

boltzkit.utils.molecular.tica.create_deeptime_tica_model(trajectory: Trajectory, lagtime: int, dim: int = 40, use_dihedrals=True, use_distances=True, use_koopman=True)[source]

Train a TICA model using the deeptime library.

Parameters:

  • trajectory (md.Trajectory) – Input molecular dynamics trajectory.

  • lagtime (int) – Lag time (in frames) used for TICA estimation.

  • dim (int, default=40) – Number of TICA components to retain.

  • use_dihedrals (bool, default=True) – Whether to include dihedral-angle features.

  • use_distances (bool, default=True) – Whether to include pairwise distance features.

  • use_koopman (bool, default=True) – If True, apply Koopman reweighting to correct for sampling bias.

Returns:

Fitted TICA model from the deeptime library.

Return type:

dt.decomposition.TransferOperatorModel

Notes

Koopman reweighting can improve estimates when trajectories are not sampled from the equilibrium distribution.

class boltzkit.utils.molecular.tica.TicaModelWithLengthScale[source]

Bases: object

Wrapper around a deeptime TICA model that applies a coordinate length-scale conversion before feature extraction.

This is useful when the TICA model was trained using coordinates in one unit system (e.g., nanometers) but new data is provided in a different unit system (e.g., angstroms).

__init__(model: TransferOperatorModel, length_scale: float = 1.0, **kwargs)[source]
Parameters:

  • model (dt.decomposition.TransferOperatorModel) – A fitted deeptime transfer operator model (e.g., a TICA model).

  • length_scale (float, default=1.0) –

    Multiplicative factor applied to Cartesian coordinates before computing TICA features.

    Example: - Training data in nanometers - Inference data in angstroms → use length_scale=0.1.

Raises:

ValueError – If the provided model is not a deeptime TransferOperatorModel.

project_from_cartesian(pos: ndarray, topology: Topology) → ndarray[source]

Project Cartesian coordinates onto the TICA components.

Parameters:

  • pos (np.ndarray) – Flattened Cartesian coordinates of shape (n_frames, n_atoms * 3) or compatible with reshaping to (n_frames, n_atoms, 3).

  • topology (md.Topology) – MDTraj topology corresponding to the coordinates.

Returns:

TICA projections of shape (n_frames, n_tica_components).

Return type:

np.ndarray

Notes

  • Coordinates are first rescaled using the model’s length_scale.

  • Feature extraction is performed using get_tica_features().

  • Data is processed in batches of 4096 frames to limit memory usage.

classmethod from_path(path: str, length_scale: float)[source]

Load a serialized TICA model and wrap it with a length-scale conversion.

Parameters:

  • path (str) – Path to a pickled deeptime TICA model.

  • length_scale (float) – Coordinate scaling factor applied during projection.

Returns:

Wrapper instance containing the loaded TICA model.

Return type:

TicaModelWithLengthScale