locate_trans

mdtools.dtrj.locate_trans(dtrj, axis=-1, pin='end', discard_neg=None, trans_type=None, wrap=False, tfft=False, tlft=False, mic=False, min_state=None, max_state=None)[source]

Locate the frames of state transitions inside a discrete trajectory.

Get a boolean array of the same shape as dtrj that indicates at which positions in dtrj state transitions occur.

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.
pin ({"end", "start", "both"}) – Whether to return the "start" (last frame where a given compound is in the previous state) or "end" (first frame where a given compound is in the next state) of the state transitions. If set to "both", two output arrays will be returned, one for "start" and one for "end".
discard_neg ({None, "start", "end", "both"}, optional) – Whether to locate all state transitions (None) or whether to discard state transitions starting from a negative state ("start") or ending in a negative state ("end"). If set to "both", all state transitions starting from or ending in a negative state will be discarded.
trans_type ({None, "higher", "lower", "both"} or int or iterable of ints, optional) – Whether to locate all state transitions without discriminating between different transition types (None) or whether to locate only state transitions into higher states ("higher") or into lower states ("lower"). If set to "both", two output arrays will be returned, one for "higher" and one for "lower". If pin is set to "both", too, a 2x2 tuple will be returned. The first index addresses pin, the second index addresses trans_type. If trans_type is an integer, locate only state transitions where the difference between the final and first state is equal to the given integer value. If trans_type is an iterable of integers, one output array for each given integer will be returned.
wrap (bool, optional) – If True, dtrj is assumed to be continued after the last frame by dtrj itself, like when using periodic boundary conditions. Consequently, if the first and last state in the trajectory do not match, this is interpreted as state transition. The start of this transition is the last frame of the trajectory and the end is the first frame.
tfft (bool, optional) – Treat First Frame as Transition. If True, treat the first frame as the end of a state transition. Has no effect if pin is set to "start". Must not be used together with discard_neg, trans_type, wrap or mic.
tlft (bool, optional) – Treat Last Frame as Transition. If True, treat the last frame as the start of a state transition. Has no effect if pin is set to "end". Must not be used together with discard_neg, trans_type, wrap or mic.
mic (bool, optional) – If True, respect the Minimum Image Convention when evaluating the transition type, i.e. when evaluating whether the transition was in positive direction (to a higher state) or in negative direction (to a lower state). Has no effect if trans_type is None. This option could be useful, when the states have periodic boundary conditions, for instance because the states are position bins along a box dimension with periodic boundary conditions. In this case, the states should result from an equidistant binning, otherwise the MIC algorithm will give wrong results, because it only considers the state indices.
min_state, max_state (scalar or array_like, optional) – The lower and upper bound(s) for the minimum image convention. Has no effect if mic is False or trans_type is None. If None, the minium and maximum value of dtrj is taken, respectively. min_state must be smaller than max_state. If the transition between two states is larger than 0.5 * (max_state - min_state), it is wrapped back to lie within that range. See also mdtools.numpy_helper_functions.diff_mic().

Returns:

trans_start (numpy.ndarray) – Boolean array of the same shape as dtrj. Elements that evaluate to True indicate frames in dtrj where a given compound is the last time in a given state before it will be in another state in the next frame. Can be used to index dtrj and get the states right before a state transition. Is not returned if pin is "end".
trans_end (numpy.ndarray) – Boolean array of the same shape as dtrj. Elements that evaluate to True indicate frames in dtrj where a given compound is the first time in a new state after it was in another state one frame before. Can be used to index dtrj and get the states right after a state transition. Is not returned if pin is "start".

See also

mdtools.numpy_helper_functions.locate_item_change(): Locate the positions of item changes in arbitrary arrays
mdtools.dtrj.trans_ix(): Get the frame indices of state transitions in a discrete trajectory

Notes

This function only checks if the input array is a discrete trajectory using mdtools.check.dtrj() and then calls mdtools.numpy_helper_functions.locate_item_change().

To get the frame indices of the state transitions for each compound, apply numpy.nonzero() to the output array(s) of this function. If you are only interested in the frame indices but not in the boolean arrays returned by this function, you can use mdtools.dtrj.trans_ix() instead.

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]])
>>> start, end = mdt.dtrj.locate_trans(dtrj, pin="both")
>>> start
array([[ True, False,  True, False, False, False],
       [False,  True, False, False,  True, False],
       [False, False,  True,  True, False, False],
       [ True, False, False,  True, False, False]])
>>> end
array([[False,  True, False,  True, False, False],
       [False, False,  True, False, False,  True],
       [False, False, False,  True,  True, False],
       [False,  True, False, False,  True, False]])