lifetimes_per_state

mdtools.dtrj.lifetimes_per_state(dtrj, axis=-1, uncensored=False, discard_neg_start=False, discard_all_neg=False, return_states=False, return_cmp_ix=False, return_avg=False, kwargs_avg=None, return_std=False, kwargs_std=None)

Calculate the state lifetimes for each state.

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.

• uncensored (bool, optional) – If True only take into account uncensored states, i.e. states whose start and end lie within the trajectory. In other words, discard the truncated (censored) states at the beginning and end of the trajectory. For these states the start/end time is unknown.

• discard_neg_start (bool, optional) – If True, discard the lifetimes of all negative states (see notes of mdtools.dtrj.lifetimes()). This is equivalent to discarding all transitions starting from a negative state when calculating transition rates with mdtools.dtrj.trans_rate_per_state() or remain probabilities with mdtools.dtrj.remain_prob_discrete(). Has no effect if discard_all_neg is True.

• discard_all_neg (bool, optional) – If True, discard the lifetimes of all negative states and of all states that are followed by a negative state (see notes of mdtools.dtrj.lifetimes()). This is equivalent to discarding all transitions starting from or ending in a negative state when calculating transition rates with mdtools.dtrj.trans_rate_per_state() or remain probabilities with mdtools.dtrj.remain_prob_discrete().

• return_states (bool, optional) – If True, return the state indices associated with the returned lifetimes.

• return_cmp_ix (bool, optional) – If True, return the compound indices associated with the returned lifetimes.

• return_avg (bool, optional) – If True, return the average lifetime of each state.

• kwargs_avg (dict, optional) – Keyword arguments to parse to numpy.mean() for calculating the average lifetimes. See there for possible options.

• return_std (bool, optional) – If True, return the standard deviation of the lifetimes of each state.

• kwargs_std (dict, optional) – Keyword arguments to parse to numpy.std() for calculating the standard deviation of the lifetimes. See there for possible options.

Returns:

• lt (list of 1D numpy.ndarray) – List of 1-dimensional arrays. Each array contains the lifetimes of one state.

• states (numpy.ndarray) – 1-dimensional array of shape (len(lt),) containing the corresponding state indices for each lifetime array in lt. Only returned if return_states is True.

• cmp_ix (list of 1D numpy.ndarray) – List of 1-dimensional arrays of the same shape as lt. Each array contains the corresponding compound indices. Only returned if return_cmp_ix is True.

• lt_avg (numpy.ndarray) – 1-dimensional array of shape (len(lt),) containing the average lifetime of each state. Only returned if return_avg is True.

• lt_std (numpy.ndarray) – 1-dimensional array of shape (len(lt),) containing the standard deviation of the lifetimes of each state. Only returned if return_std is True.

See also

mdtools.dtrj.lifetimes()

Calculate the state lifetimes for each compound

mdtools.dtrj.trans_rate_per_state()

Calculate the transition rate for each state averaged over all compounds

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

Notes

See mdtools.dtrj.lifetimes() for details about how state lifetimes are calculated and 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],
...                  [6, 6, 6, 1, 4, 4],
...                  [1, 6, 6, 6, 4, 4]])
>>> lt, states, cmp_ix, lt_avg, lt_std = mdt.dtrj.lifetimes_per_state(
...     dtrj,
...     return_states=True,
...     return_cmp_ix=True,
...     return_avg=True,
...     return_std=True,
... )
>>> lt
[array([1, 1, 1, 1]), array([2, 2]), array([3, 3]), array([2, 2]), array([3, 3])]
>>> states
array([1, 2, 3, 4, 6])
>>> cmp_ix
[array([0, 1, 2, 3]), array([0, 1]), array([0, 1]), array([2, 3]), array([2, 3])]
>>> lt_avg
array([1., 2., 3., 2., 3.])
>>> lt_std
array([0., 0., 0., 0., 0.])
>>> lt, states, cmp_ix, lt_avg, lt_std = mdt.dtrj.lifetimes_per_state(
...     dtrj,
...     axis=0,
...     return_states=True,
...     return_cmp_ix=True,
...     return_avg=True,
...     return_std=True,
... )
>>> lt
[array([1, 1, 1, 1]), array([1, 2, 1]), array([1, 2, 2, 1]), array([2, 2]), array([1, 2, 2, 1])]
>>> states
array([1, 2, 3, 4, 6])
>>> cmp_ix
[array([0, 0, 3, 5]), array([0, 1, 2]), array([2, 3, 4, 5]), array([4, 5]), array([0, 1, 2, 3])]
>>> lt_avg
array([1.        , 1.33333333, 1.5       , 2.        , 1.5       ])
>>> lt_std
array([0.        , 0.47140452, 0.5       , 0.        , 0.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]])
>>> lt, states, cmp_ix, lt_avg, lt_std = mdt.dtrj.lifetimes_per_state(
...     dtrj,
...     return_states=True,
...     return_cmp_ix=True,
...     return_avg=True,
...     return_std=True,
... )
>>> lt
[array([1, 1, 1, 1]), array([2, 2, 2, 2]), array([3, 3, 3, 3])]
>>> states
array([1, 2, 3])
>>> cmp_ix
[array([0, 1, 2, 3]), array([0, 1, 2, 3]), array([0, 1, 2, 3])]
>>> lt_avg
array([1., 2., 3.])
>>> lt_std
array([0., 0., 0.])
>>> lt_unc, states_unc, cmp_ix_unc, lt_avg_unc, lt_std_unc = mdt.dtrj.lifetimes_per_state(
...     dtrj,
...     uncensored=True,
...     return_states=True,
...     return_cmp_ix=True,
...     return_avg=True,
...     return_std=True,
... )
>>> lt_unc
[array([1]), array([2]), array([3, 3])]
>>> states_unc
array([1, 2, 3])
>>> cmp_ix_unc
[array([2]), array([0]), array([1, 3])]
>>> lt_avg_unc
array([1., 2., 3.])
>>> lt_std_unc
array([0., 0., 0.])
>>> lt, states, cmp_ix, lt_avg, lt_std = mdt.dtrj.lifetimes_per_state(
...     dtrj,
...     axis=0,
...     return_states=True,
...     return_cmp_ix=True,
...     return_avg=True,
...     return_std=True,
... )
>>> lt
[array([1, 1, 1, 1]), array([1, 2, 1, 2, 2]), array([1, 2, 3, 2, 1, 2, 1])]
>>> states
array([1, 2, 3])
>>> cmp_ix
[array([0, 0, 3, 5]), array([0, 1, 2, 4, 5]), array([0, 1, 2, 3, 3, 4, 5])]
>>> lt_avg
array([1.        , 1.6       , 1.71428571])
>>> lt_std
array([0.        , 0.48989795, 0.69985421])
>>> lt_unc, states_unc, cmp_ix_unc, lt_avg_unc, lt_std_unc = mdt.dtrj.lifetimes_per_state(
...     dtrj,
...     axis=0,
...     uncensored=True,
...     return_states=True,
...     return_cmp_ix=True,
...     return_avg=True,
...     return_std=True,
... )
>>> lt_unc
[array([1, 1]), array([1]), array([1])]
>>> states_unc
array([1, 2, 3])
>>> cmp_ix_unc
[array([3, 5]), array([0]), array([0])]
>>> lt_avg_unc
array([1., 1., 1.])
>>> lt_std_unc
array([0., 0., 0.])

>>> dtrj = np.array([[ 1,  2,  2,  1,  1,  1],
...                  [ 2,  2,  3,  3,  3,  2],
...                  [-3, -3, -3, -1,  2,  2],
...                  [ 2,  3,  3,  3, -2, -2]])
>>> lt, states, cmp_ix, lt_avg, lt_std = mdt.dtrj.lifetimes_per_state(
...     dtrj,
...     return_states=True,
...     return_cmp_ix=True,
...     return_avg=True,
...     return_std=True,
... )
>>> lt
[array([3]), array([2]), array([1]), array([1, 3]), array([2, 2, 1, 2, 1]), array([3, 3])]
>>> states
array([-3, -2, -1,  1,  2,  3])
>>> cmp_ix
[array([2]), array([3]), array([2]), array([0, 0]), array([0, 1, 1, 2, 3]), array([1, 3])]
>>> lt_avg
array([3. , 2. , 1. , 2. , 1.6, 3. ])
>>> lt_std
array([0.        , 0.        , 0.        , 1.        , 0.48989795,
       0.        ])
>>> lt, states, cmp_ix, lt_avg, lt_std = mdt.dtrj.lifetimes_per_state(
...     dtrj,
...     discard_neg_start=True,
...     return_states=True,
...     return_cmp_ix=True,
...     return_avg=True,
...     return_std=True,
... )
>>> lt
[array([1, 3]), array([2, 2, 1, 2, 1]), array([3, 3])]
>>> states
array([1, 2, 3])
>>> cmp_ix
[array([0, 0]), array([0, 1, 1, 2, 3]), array([1, 3])]
>>> lt_avg
array([2. , 1.6, 3. ])
>>> lt_std
array([1.        , 0.48989795, 0.        ])
>>> lt, states, cmp_ix, lt_avg, lt_std = mdt.dtrj.lifetimes_per_state(
...     dtrj,
...     discard_all_neg=True,
...     return_states=True,
...     return_cmp_ix=True,
...     return_avg=True,
...     return_std=True,
... )
>>> lt
[array([1, 3]), array([2, 2, 1, 2, 1]), array([3])]
>>> states
array([1, 2, 3])
>>> cmp_ix
[array([0, 0]), array([0, 1, 1, 2, 3]), array([1])]
>>> lt_avg
array([2. , 1.6, 3. ])
>>> lt_std
array([1.        , 0.48989795, 0.        ])
>>> ax = 0
>>> lt, states, cmp_ix, lt_avg, lt_std = mdt.dtrj.lifetimes_per_state(
...     dtrj,
...     axis=ax,
...     return_states=True,
...     return_cmp_ix=True,
...     return_avg=True,
...     return_std=True,
... )
>>> lt
[array([1, 1, 1]), array([1, 1]), array([1]), array([1, 1, 1, 1]), array([1, 1, 2, 1, 1, 2]), array([1, 1, 1, 1, 1, 1])]
>>> states
array([-3, -2, -1,  1,  2,  3])
>>> cmp_ix
[array([0, 1, 2]), array([4, 5]), array([3]), array([0, 3, 4, 5]), array([0, 0, 1, 2, 4, 5]), array([1, 2, 2, 3, 3, 4])]
>>> lt_avg
array([1.        , 1.        , 1.        , 1.        , 1.33333333,
       1.        ])
>>> lt_std
array([0.        , 0.        , 0.        , 0.        , 0.47140452,
       0.        ])
>>> lt, states, cmp_ix, lt_avg, lt_std = mdt.dtrj.lifetimes_per_state(
...     dtrj,
...     axis=ax,
...     discard_neg_start=True,
...     return_states=True,
...     return_cmp_ix=True,
...     return_avg=True,
...     return_std=True,
... )
>>> lt
[array([1, 1, 1, 1]), array([1, 1, 2, 1, 1, 2]), array([1, 1, 1, 1, 1, 1])]
>>> states
array([1, 2, 3])
>>> cmp_ix
[array([0, 3, 4, 5]), array([0, 0, 1, 2, 4, 5]), array([1, 2, 2, 3, 3, 4])]
>>> lt_avg
array([1.        , 1.33333333, 1.        ])
>>> lt_std
array([0.        , 0.47140452, 0.        ])
>>> lt, states, cmp_ix, lt_avg, lt_std = mdt.dtrj.lifetimes_per_state(
...     dtrj,
...     axis=ax,
...     discard_all_neg=True,
...     return_states=True,
...     return_cmp_ix=True,
...     return_avg=True,
...     return_std=True,
... )
>>> lt
[array([1, 1, 1, 1]), array([1, 1]), array([1, 1, 1, 1])]
>>> states
array([1, 2, 3])
>>> cmp_ix
[array([0, 3, 4, 5]), array([0, 2]), array([1, 2, 3, 4])]
>>> lt_avg
array([1., 1., 1.])
>>> lt_std
array([0., 0., 0.])

>>> 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]])
>>> lt, states, cmp_ix, lt_avg, lt_std = mdt.dtrj.lifetimes_per_state(
...     dtrj,
...     return_states=True,
...     return_cmp_ix=True,
...     return_avg=True,
...     return_std=True,
... )
>>> lt
[array([2, 2, 2, 2]), array([1]), array([1, 1, 1, 1, 1]), array([3, 3, 3, 3]), array([4])]
>>> states
array([-2, -1,  1,  3,  4])
>>> cmp_ix
[array([0, 1, 2, 3]), array([4]), array([0, 1, 2, 3, 4]), array([0, 1, 2, 3]), array([4])]
>>> lt_avg
array([2., 1., 1., 3., 4.])
>>> lt_std
array([0., 0., 0., 0., 0.])
>>> lt, states, cmp_ix, lt_avg, lt_std = mdt.dtrj.lifetimes_per_state(
...     dtrj,
...     discard_neg_start=True,
...     return_states=True,
...     return_cmp_ix=True,
...     return_avg=True,
...     return_std=True,
... )
>>> lt
[array([1, 1, 1, 1, 1]), array([3, 3, 3, 3]), array([4])]
>>> states
array([1, 3, 4])
>>> cmp_ix
[array([0, 1, 2, 3, 4]), array([0, 1, 2, 3]), array([4])]
>>> lt_avg
array([1., 3., 4.])
>>> lt_std
array([0., 0., 0.])
>>> lt, states, cmp_ix, lt_avg, lt_std = mdt.dtrj.lifetimes_per_state(
...     dtrj,
...     discard_all_neg=True,
...     return_states=True,
...     return_cmp_ix=True,
...     return_avg=True,
...     return_std=True,
... )
>>> lt
[array([1, 1, 1]), array([3, 3, 3])]
>>> states
array([1, 3])
>>> cmp_ix
[array([1, 3, 4]), array([0, 1, 2])]
>>> lt_avg
array([1., 3.])
>>> lt_std
array([0., 0.])
>>> ax = 0
>>> lt, states, cmp_ix, lt_avg, lt_std = mdt.dtrj.lifetimes_per_state(
...     dtrj,
...     axis=ax,
...     return_states=True,
...     return_cmp_ix=True,
...     return_avg=True,
...     return_std=True,
... )
>>> lt
[array([1, 2, 1, 2, 2]), array([1]), array([1, 2, 1, 1]), array([1, 2, 3, 2, 1, 2, 1]), array([1, 1, 1, 1])]
>>> states
array([-2, -1,  1,  3,  4])
>>> cmp_ix
[array([0, 1, 2, 4, 5]), array([5]), array([0, 0, 3, 5]), array([0, 1, 2, 3, 3, 4, 5]), array([1, 2, 3, 4])]
>>> lt_avg
array([1.6       , 1.        , 1.25      , 1.71428571, 1.        ])
>>> lt_std
array([0.48989795, 0.        , 0.4330127 , 0.69985421, 0.        ])
>>> lt, states, cmp_ix, lt_avg, lt_std = mdt.dtrj.lifetimes_per_state(
...     dtrj,
...     axis=ax,
...     discard_neg_start=True,
...     return_states=True,
...     return_cmp_ix=True,
...     return_avg=True,
...     return_std=True,
... )
>>> lt
[array([1, 2, 1, 1]), array([1, 2, 3, 2, 1, 2, 1]), array([1, 1, 1, 1])]
>>> states
array([1, 3, 4])
>>> cmp_ix
[array([0, 0, 3, 5]), array([0, 1, 2, 3, 3, 4, 5]), array([1, 2, 3, 4])]
>>> lt_avg
array([1.25      , 1.71428571, 1.        ])
>>> lt_std
array([0.4330127 , 0.69985421, 0.        ])
>>> lt, states, cmp_ix, lt_avg, lt_std = mdt.dtrj.lifetimes_per_state(
...     dtrj,
...     axis=ax,
...     discard_all_neg=True,
...     return_states=True,
...     return_cmp_ix=True,
...     return_avg=True,
...     return_std=True,
... )
>>> lt
[array([2, 1]), array([1, 2, 3, 2, 1, 1]), array([1, 1, 1, 1])]
>>> states
array([1, 3, 4])
>>> cmp_ix
[array([0, 3]), array([0, 1, 2, 3, 3, 5]), array([1, 2, 3, 4])]
>>> lt_avg
array([1.5       , 1.66666667, 1.        ])
>>> lt_std
array([0.5       , 0.74535599, 0.        ])

>>> dtrj = np.array([[1, 2, 2],
...                  [3, 3, 3]])
>>> lt_unc, states_unc, cmp_ix_unc, lt_avg_unc, lt_std_unc = mdt.dtrj.lifetimes_per_state(
...     dtrj,
...     uncensored=True,
...     return_states=True,
...     return_cmp_ix=True,
...     return_avg=True,
...     return_std=True,
... )
>>> lt_unc
[array([], dtype=int64)]
>>> states_unc
array([], dtype=int64)
>>> cmp_ix_unc
[array([], dtype=int64)]
>>> lt_avg_unc
array([nan])
>>> lt_std_unc
array([nan])
>>> lt_unc, states_unc, cmp_ix_unc, lt_avg_unc, lt_std_unc = mdt.dtrj.lifetimes_per_state(
...     dtrj,
...     axis=0,
...     uncensored=True,
...     return_states=True,
...     return_cmp_ix=True,
...     return_avg=True,
...     return_std=True,
... )
>>> lt_unc
[array([], dtype=int64)]
>>> states_unc
array([], dtype=int64)
>>> cmp_ix_unc
[array([], dtype=int64)]
>>> lt_avg_unc
array([nan])
>>> lt_std_unc
array([nan])