trans_rate_per_state

mdtools.dtrj.trans_rate_per_state(dtrj, axis=-1, discard_neg_start=False, discard_all_neg=False, return_states=False)[source]

Calculate the transition rate for each state averaged over all compounds.

Parameters:

dtrj (array_like) – Array containing the discrete trajectory.
axis (int, optional) – The axis along which to search for state transitions. For ordinary discrete trajectories with shape (n, f) or (f,), where n is the number of compounds and f is the number of frames, set axis to -1. If you parse a transposed discrete trajectory of shape (f, n), set axis to 0.
discard_neg_start (bool, optional) – If True, discard all transitions starting from a negative state (see notes of mdtools.dtrj.trans_rate()). This is equivalent to discarding the lifetimes of all negative states when calculating state lifetimes with mdtools.dtrj.lifetimes_per_state(). Has no effect if discard_all_neg is True.
discard_all_neg (bool, optional) – If True, discard all transitions starting from or ending in a negative state (see notes mdtools.dtrj.trans_rate()). This is equivalent to discarding the lifetimes of all negative states and of all states that are followed by a negative state when calculating state lifetimes with mdtools.dtrj.lifetimes_per_state().
return_states (bool, optional) – If True, return the state indices associated with the returned transition rates.

Returns:

trans_rates (numpy.ndarray) – 1-dimensional array containing the transition rates for each valid state.
states (numpy.ndarray) – 1-dimensional array of the same shape as trans_rates containing the corresponding state indices. Only returned if return_states is True.

See also

mdtools.dtrj.trans_rate_tot(): Calculate the transition rate averaged over all compounds and over all states
mdtools.dtrj.trans_rate(): Calculate the transition rate for each compound averaged over all states
mdtools.dtrj.kaplan_meier_discrete(): Estimate the state survival function using the Kaplan-Meier estimator resolved with respect to the states in a second discrete trajectory
mdtools.dtrj.remain_prob_discrete(): Calculate the probability that a compound is still (or again) in the same state as at time \(t_0\) after a lag time \(\Delta t\) resolved with respect to the states in second discrete trajectory
mdtools.dtrj.lifetimes_per_state(): Calculate the state lifetimes for each state

Notes

Transitions rates are calculated for a given valid state by simply counting the number of valid transitions out of this state and dividing this number by the number of valid frames that compounds have spent in this state.

To calculate the transition rate averaged over all states and all compounds simply do:

n_trans_tot = np.count_nonzero(mdt.dtrj.locate_trans(dtrj))
n_frames_tot = dtrj.size
trans_rate = n_trans_tot / n_frames_tot

The inverse of the transition rate gives an estimate for the average state lifetime. In contrast to calculating the average lifetime by simply counting how many frames a given compound stays in a given state (as done by mdtools.dtrj.lifetimes_per_state()), this method is not biased to lower lifetimes.

See mdtools.dtrj.trans_rate() for details about valid and invalid states (discard_neg_start and discard_all_neg).

Examples

>>> dtrj = np.array([[1, 2, 2, 3, 3, 3],
...                  [2, 2, 3, 3, 3, 1],
...                  [3, 3, 3, 1, 2, 2],
...                  [1, 3, 3, 3, 2, 2]])
>>> trans_rates, states = mdt.dtrj.trans_rate_per_state(
...     dtrj, return_states=True
... )
>>> trans_rates
array([0.75, 0.25, 0.25])
>>> states
array([1, 2, 3])
>>> trans_rates, states = mdt.dtrj.trans_rate_per_state(
...     dtrj, axis=0, return_states=True
... )
>>> trans_rates
array([0.75      , 0.375     , 0.33333333])
>>> states
array([1, 2, 3])

>>> dtrj = np.array([[1, 2, 2, 3, 3, 3],
...                  [2, 2, 3, 3, 3, 1],
...                  [3, 3, 3, 1, 2, 2],
...                  [1, 3, 3, 3, 2, 2],
...                  [6, 6, 6, 6, 6, 6]])
>>> trans_rates, states = mdt.dtrj.trans_rate_per_state(
...     dtrj, return_states=True
... )
>>> trans_rates
array([0.75, 0.25, 0.25, 0.  ])
>>> states
array([1, 2, 3, 6])
>>> trans_rates, states = mdt.dtrj.trans_rate_per_state(
...     dtrj, axis=0, return_states=True
... )
>>> trans_rates
array([1.        , 0.625     , 0.58333333, 0.        ])
>>> states
array([1, 2, 3, 6])

>>> dtrj = np.array([[ 1, -2, -2,  3,  3,  3],
...                  [-2, -2,  3,  3,  3,  1],
...                  [ 3,  3,  3,  1,  2,  2],
...                  [ 1,  3,  3,  3, -2, -2],
...                  [ 1,  4,  4,  4,  4, -1],
...                  [-6, -6, -6, -6, -6, -6],
...                  [ 6,  6,  6,  6,  6,  6]])
>>> ax = -1
>>> trans_rates, states = mdt.dtrj.trans_rate_per_state(
...     dtrj, axis=ax, return_states=True
... )
>>> trans_rates
array([0.        , 0.33333333, 0.        , 0.8       , 0.        ,
       0.25      , 0.25      , 0.        ])
>>> states
array([-6, -2, -1,  1,  2,  3,  4,  6])
>>> trans_rates_start, states_start = mdt.dtrj.trans_rate_per_state(
...     dtrj, axis=ax, discard_neg_start=True, return_states=True
... )
>>> trans_rates_start
array([0.8 , 0.  , 0.25, 0.25, 0.  ])
>>> states_start
array([1, 2, 3, 4, 6])
>>> trans_rates_all, states_all = mdt.dtrj.trans_rate_per_state(
...     dtrj, axis=ax, discard_all_neg=True, return_states=True
... )
>>> trans_rates_all
array([0.75      , 0.        , 0.22222222, 0.        ])
>>> states_all
array([1, 2, 3, 6])

>>> ax = 0
>>> trans_rates, states = mdt.dtrj.trans_rate_per_state(
...     dtrj, axis=ax, return_states=True
... )
>>> trans_rates
array([1.        , 0.83333333, 1.        , 0.8       , 1.        ,
       0.58333333, 1.        , 0.        ])
>>> states
array([-6, -2, -1,  1,  2,  3,  4,  6])
>>> trans_rates_start, states_start = mdt.dtrj.trans_rate_per_state(
...     dtrj, axis=ax, discard_neg_start=True, return_states=True
... )
>>> trans_rates_start
array([0.8       , 1.        , 0.58333333, 1.        , 0.        ])
>>> states_start
array([1, 2, 3, 4, 6])

>>> trans_rates_all, states_all = mdt.dtrj.trans_rate_per_state(
...     dtrj, axis=ax, discard_all_neg=True, return_states=True
... )
>>> trans_rates_all
array([1.        , 0.58333333, 0.        ])
>>> states_all
array([1, 3, 6])