trans_rate

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

Calculate the transition rate for each compound averaged over all states.

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). This is equivalent to discarding the lifetimes of all negative states when calculating state lifetimes with mdtools.dtrj.lifetimes(). 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). 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().
return_cmp_ix (bool, optional) – If True, return the compound indices associated with the returned transition rates.

Returns:

trans_rates (numpy.ndarray) – 1-dimensional array containing the transition rate for each compound averaged over all states.
cmp_ix (numpy.ndarray) – 1-dimensional array of the same shape as trans_rate containing the corresponding compound indices. Only returned if return_cmp_ix 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_per_state(): Calculate the transition rate for each state averaged over all compounds
mdtools.dtrj.lifetimes(): Calculate the state lifetimes for each compound
mdtools.dtrj.kaplan_meier(): Estimate the state survival function using the Kaplan-Meier estimator
mdtools.dtrj.remain_prob(): 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\)

Notes

Transitions rates are calculated by simply counting the number of valid state transitions for each compound and dividing this number by the number of valid frames.

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()), this method is not biased to lower lifetimes.

Valid and Invalid States

By default, all states in the given discrete trajectory are valid. However, in some cases you might want to treat certain states as invalid, e.g. because you only want to consider specific states. This can be achieved with the arguments discard_neg_start or discard_all_neg which treat negative states (i.e. states with a negative state number/index) as invalid states.

Note

If you want to treat states with index zero as invalid, too, simply subtract one from dtrj. If you want to treat all states below a certain cutoff as invalid, subtract this cutoff from dtrj. If you want to treat certain states as invalid, make these states negative, e.g. by multiplying these states with minus one.

The arguments discard_neg_start and discard_all_neg affect the counting of state transitions and frames.

If both, discard_neg_start and discard_all_neg, are False (the default), all state state transitions are counted and divided by the total number of frames.

If discard_neg_start is True, transitions starting from negative states are discarded and the total number of frames is reduced by the number of frames that a given compound resides in negative states.

If discard_all_neg is True, all negative states are discarded, i.e. transitions starting from or ending in a negative state are discarded. The total number of frames is reduced by the number of frames that a given compound resides in negative states and by the number of frames that a given compound resides in positive states that are followed by negative states.

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]])
>>> rates, cmp_ix = mdt.dtrj.trans_rate(dtrj, return_cmp_ix=True)
>>> rates  # 2 transitions / 6 frames for each compound.
array([0.33333333, 0.33333333, 0.33333333, 0.33333333])
>>> cmp_ix
array([0, 1, 2, 3])
>>> rates, cmp_ix = mdt.dtrj.trans_rate(
...     dtrj, axis=0, return_cmp_ix=True
... )
>>> rates
array([0.75, 0.25, 0.25, 0.5 , 0.25, 0.5 ])
>>> cmp_ix
array([0, 1, 2, 3, 4, 5])

>>> 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]])
>>> rates, cmp_ix = mdt.dtrj.trans_rate(dtrj, return_cmp_ix=True)
>>> rates
array([0.33333333, 0.33333333, 0.33333333, 0.33333333, 0.        ])
>>> cmp_ix
array([0, 1, 2, 3, 4])
>>> rates, cmp_ix = mdt.dtrj.trans_rate(
...     dtrj, axis=0, return_cmp_ix=True
... )
>>> rates
array([0.8, 0.4, 0.4, 0.6, 0.4, 0.6])
>>> cmp_ix
array([0, 1, 2, 3, 4, 5])

>>> 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
>>> rates, cmp_ix = mdt.dtrj.trans_rate(
...     dtrj, axis=ax, return_cmp_ix=True
... )
>>> rates
array([0.33333333, 0.33333333, 0.33333333, 0.33333333, 0.33333333,
       0.        , 0.        ])
>>> cmp_ix
array([0, 1, 2, 3, 4, 5, 6])
>>> rates_start, cmp_ix_start = mdt.dtrj.trans_rate(
...     dtrj, axis=ax, discard_neg_start=True, return_cmp_ix=True
... )
>>> rates_start
array([0.25      , 0.25      , 0.33333333, 0.5       , 0.4       ,
       0.        ])
>>> cmp_ix_start
array([0, 1, 2, 3, 4, 6])
>>> rates_all, cmp_ix_all = mdt.dtrj.trans_rate(
...     dtrj, axis=ax, discard_all_neg=True, return_cmp_ix=True
... )
>>> rates_all
array([0.        , 0.25      , 0.33333333, 1.        , 1.        ,
       0.        ])
>>> cmp_ix_all
array([0, 1, 2, 3, 4, 6])

>>> ax = 0
>>> rates, cmp_ix = mdt.dtrj.trans_rate(
...     dtrj, axis=ax, return_cmp_ix=True
... )
>>> rates
array([0.71428571, 0.57142857, 0.57142857, 0.71428571, 0.71428571,
       0.85714286])
>>> cmp_ix
array([0, 1, 2, 3, 4, 5])
>>> rates_start, cmp_ix_start = mdt.dtrj.trans_rate(
...     dtrj, axis=ax, discard_neg_start=True, return_cmp_ix=True
... )
>>> rates_start
array([0.6       , 0.5       , 0.4       , 0.66666667, 0.6       ,
       0.75      ])
>>> cmp_ix_start
array([0, 1, 2, 3, 4, 5])
>>> rates_all, cmp_ix_all = mdt.dtrj.trans_rate(
...     dtrj, axis=ax, discard_all_neg=True, return_cmp_ix=True
... )
>>> rates_all
array([0.5       , 0.33333333, 0.25      , 0.6       , 0.33333333,
       0.66666667])
>>> cmp_ix_all
array([0, 1, 2, 3, 4, 5])