statetraj

Classes for handling discrete state trajectories.

• StateTraj is a fast implementation of a state trajectory and should be used for microstate dynamics.

• LumpedStateTraj is an implementation of the Hummer-Szabo projection¹ and allows to reproduce the microstates dynamics on the macrostates space.

Note

One should also mention that for bad coarse-graining one can get negative entries in the transition matrix \(T_{ij} < 0\). To prevent this, one can explicitly force \(T_{ij} \ge 0\) by setting the flag positive=True.

---

1. Hummer and Szabo, Optimal Dimensionality Reduction of Multistate Kinetic and Markov-State Models, J. Phys. Chem. B, 119 (29), 9029-9037 (2015), doi: 10.1021/jp508375q ↩

StateTraj(trajs)

Class for handling discrete state trajectories.

Initialize StateTraj and convert to index trajectories.

If called with StateTraj instance, it will be returned instead.

Parameters:

• trajs (list or ndarray or list of ndarray) –

  State trajectory/trajectories. The states need to be integers.

Source code in src/msmhelper/statetraj.py

def __init__(self, trajs):
    """Initialize StateTraj and convert to index trajectories.

    If called with StateTraj instance, it will be returned instead.

    Parameters
    ----------
    trajs : list or ndarray or list of ndarray
        State trajectory/trajectories. The states need to be integers.

    """
    if isinstance(trajs, StateTraj):
        return

    self._trajs = mh.utils.format_state_traj(trajs)

    # get number of states
    self._states = mh.utils.unique(self._trajs)

    # enforce true copy of trajs
    if np.array_equal(self._states, np.arange(self.nstates)):
        self._trajs = [traj.copy() for traj in self._trajs]
    # shift to indices
    elif np.array_equal(self._states, np.arange(1, self.nstates + 1)):
        self._states = np.arange(1, self.nstates + 1)
        self._trajs = [traj - 1 for traj in self._trajs]
    else:  # not np.array_equal(self._states, np.arange(self.nstates)):
        self._trajs, self._states = mh.utils.rename_by_index(
            self._trajs,
            return_permutation=True,
        )

states property

Return active set of states.

Returns:

• states ( ndarray ) –

  Numpy array holding active set of states.

nstates property

Return number of states.

Returns:

• nstates ( int ) –

  Number of states.

ntrajs property

Return number of trajectories.

Returns:

• ntrajs ( int ) –

  Number of trajectories.

nframes property

Return cumulative length of all trajectories.

Returns:

• nframes ( int ) –

  Number of frames of all trajectories.

trajs property

Return state trajectory.

Returns:

• trajs ( list of ndarrays ) –

  List of ndarrays holding the input data.

trajs_flatten property

Return flattened state trajectory.

Returns:

• trajs ( ndarray ) –

  1D ndarray representation of state trajectories.

index_trajs property

Return index trajectory.

Returns:

• trajs ( list of ndarrays ) –

  List of ndarrays holding the input data.

index_trajs_flatten property

Return flattened index trajectory.

Returns:

• trajs ( ndarray ) –

  1D ndarray representation of index trajectories.

estimate_markov_model(lagtime)

Estimates Markov State Model.

This method estimates the MSM based on the transition count matrix.

Parameters:

• lagtime (int) –

  Lag time for estimating the markov model given in [frames].

Returns:

• T ( ndarray ) –

  Transition probability matrix \(T_{ij}\), containing the transition probability transition from state \(i o j\).

• states ( ndarray ) –

  Array holding states corresponding to the columns of \(T_{ij}\).

Source code in src/msmhelper/statetraj.py

def estimate_markov_model(self, lagtime):
    """Estimates Markov State Model.

    This method estimates the MSM based on the transition count matrix.

    Parameters
    ----------
    lagtime : int
        Lag time for estimating the markov model given in [frames].

    Returns
    -------
    T : ndarray
        Transition probability matrix $T_{ij}$, containing the transition
        probability transition from state $i\to j$.
    states : ndarray
        Array holding states corresponding to the columns of $T_{ij}$.

    """
    return mh.msm.msm._estimate_markov_model(
        self.index_trajs,
        lagtime,
        self.nstates,
        self.states,
    )

state_to_idx(state)

Get idx corresponding to state.

Parameters:

• state (int) –

  State to get idx of.

Returns:

• idx ( int ) –

  Idx corresponding to state.

Source code in src/msmhelper/statetraj.py

def state_to_idx(self, state):
    """Get idx corresponding to state.

    Parameters
    ----------
    state : int
        State to get idx of.

    Returns
    -------
    idx : int
        Idx corresponding to state.

    """
    idx = np.where(self.states == state)[0]
    if not idx.size:
        raise ValueError(
            'State "{state}" does not exists in trajectory.'.format(
                state=state,
            ),
        )
    return idx[0]

LumpedStateTraj(macrotrajs, microtrajs=None, positive=False)

Bases: StateTraj

Class for using the Hummer-Szabo projection with state trajectories.

Initialize LumpedStateTraj.

If called with LumpedStateTraj instance, it will be returned instead. This class is an implementation of the Hummer-Szabo projection¹.

---

1. Hummer and Szabo, Optimal Dimensionality Reduction of Multistate Kinetic and Markov-State Models, J. Phys. Chem. B, 119 (29), 9029-9037 (2015), doi: 10.1021/jp508375q ↩

Parameters:

• macrotrajs (list or ndarray or list of ndarray) –

  Lumped state trajectory/trajectories. The states need to be integers and all states needs to correspond to union of microstates.

• microtrajs (list or ndarray or list of ndarray, default: None ) –

  State trajectory/trajectories. EaThe states should start from zero and need to be integers.

• positive (bool, default: False ) –

  If True \(T_ij\ge0\) will be enforced, else small negative values are possible.

Source code in src/msmhelper/statetraj.py

def __init__(self, macrotrajs, microtrajs=None, positive=False):
    r"""Initialize LumpedStateTraj.

    If called with LumpedStateTraj instance, it will be returned instead.
    This class is an implementation of the Hummer-Szabo projection[^1].

    [^1]: Hummer and Szabo, **Optimal Dimensionality Reduction of
          Multistate Kinetic and Markov-State Models**, *J. Phys. Chem. B*,
          119 (29), 9029-9037 (2015),
          doi: [10.1021/jp508375q](https://doi.org/10.1021/jp508375q)

    Parameters
    ----------
    macrotrajs : list or ndarray or list of ndarray
        Lumped state trajectory/trajectories. The states need to be
        integers and all states needs to correspond to union of
        microstates.
    microtrajs : list or ndarray or list of ndarray
        State trajectory/trajectories. EaThe states should start from zero
        and need to be integers.
    positive : bool
        If `True` $T_ij\ge0$ will be enforced, else small negative values
        are possible.

    """
    if isinstance(macrotrajs, LumpedStateTraj):
        return

    if microtrajs is None:
        raise TypeError(
            'microtrajs may only be None when macrotrajs is of type ' +
            'LumpedStateTraj.',
        )

    self.positive = positive

    # parse macrotraj
    macrotrajs = mh.utils.format_state_traj(macrotrajs)
    self._macrostates = mh.utils.unique(macrotrajs)

    # init microstate trajectories
    super().__init__(microtrajs)

    # cache flattened trajectories to speed up code for many states
    macrotrajs_flatten = np.concatenate(macrotrajs)
    microtrajs_flatten = self.microstate_trajs_flatten

    self._state_assignment = np.zeros(self.nmicrostates, dtype=np.int64)
    for idx, microstate in enumerate(self.microstates):
        idx_first = mh.utils.find_first(microstate, microtrajs_flatten)
        self._state_assignment[idx] = macrotrajs_flatten[idx_first]

states property

Return active set of macrostates.

Returns:

• states ( ndarray ) –

  Numpy array holding active set of states.

nstates property

Return number of macrostates.

Returns:

• nstates ( int ) –

  Number of states.

microstate_trajs property

Return microstate trajectory.

Returns:

• trajs ( list of ndarrays ) –

  List of ndarrays holding the input data.

microstate_trajs_flatten property

Return flattened state trajectory.

Returns:

• trajs ( ndarray ) –

  1D ndarrays representation of state trajectories.

microstate_index_trajs property

Return microstate index trajectory.

Returns:

• trajs ( list of ndarrays ) –

  List of ndarrays holding the microstate index trajectory.

microstate_index_trajs_flatten property

Return flattened microstate index trajectory.

Returns:

• trajs ( ndarray ) –

  1D ndarrays representation of microstate index trajectories.

trajs property

Return macrostate trajectory.

Returns:

• trajs ( list of ndarrays ) –

  List of ndarrays holding the input macrostate data.

index_trajs property

Return index trajectory.

Returns:

• trajs ( list of ndarrays ) –

  List of ndarrays holding the input data.

microstates property

Return active set of microstates.

Returns:

• states ( ndarray ) –

  Numpy array holding active set of states.

nmicrostates property

Return number of active set of states.

Returns:

• states ( ndarray ) –

  Numpy array holding active set of states.

state_assignment property

Return micro to macrostate assignment vector.

Returns:

• state_assignment ( ndarray ) –

  Micro to macrostate assignment vector.

estimate_markov_model(lagtime)

Estimates Markov State Model.

This method estimates the microstate MSM based on the transition count matrix, followed by Szabo-Hummer projection¹ formalism to macrostates.

---

1. Hummer and Szabo, Optimal Dimensionality Reduction of Multistate Kinetic and Markov-State Models, J. Phys. Chem. B, 119 (29), 9029-9037 (2015), doi: 10.1021/jp508375q ↩

Parameters:

• lagtime (int) –

  Lag time for estimating the markov model given in [frames].

Returns:

• T ( ndarray ) –

  Transition probability matrix \(T_{ij}\), containing the transition probability transition from state \(i\to j\).

• states ( ndarray ) –

  Array holding states corresponding to the columns of \(T_{ij}\).

Source code in src/msmhelper/statetraj.py

def estimate_markov_model(self, lagtime):
    r"""Estimates Markov State Model.

    This method estimates the microstate MSM based on the transition count
    matrix, followed by Szabo-Hummer projection[^1] formalism to
    macrostates.

    [^1]: Hummer and Szabo, **Optimal Dimensionality Reduction of
          Multistate Kinetic and Markov-State Models**, *J. Phys. Chem. B*,
          119 (29), 9029-9037 (2015),
          doi: [10.1021/jp508375q](https://doi.org/10.1021/jp508375q)

    Parameters
    ----------
    lagtime : int
        Lag time for estimating the markov model given in [frames].

    Returns
    -------
    T : ndarray
        Transition probability matrix $T_{ij}$, containing the transition
        probability transition from state $i\to j$.
    states : ndarray
        Array holding states corresponding to the columns of $T_{ij}$.

    """
    # in the following corresponds 'i' to micro and 'a' to macro
    msm_i, _ = mh.msm.msm._estimate_markov_model(
        self.microstate_index_trajs,
        lagtime,
        self.nmicrostates,
        self.microstates,
    )
    if not mh.utils.tests.is_ergodic(msm_i):
        raise TypeError('tmat needs to be ergodic transition matrix.')
    return (self._estimate_markov_model(msm_i), self.states)