n_leaves_vs_time

mdtools.dtrj.n_leaves_vs_time(dtrj, discard_neg_start=False, discard_all_neg=False, verbose=False)[source]

Calculate the number of compounds that leave their state after a lag time \(\Delta t\) given that they have entered the state at time \(t_0\).

Take a discrete trajectory and calculate the total number of compounds that leave their state at time \(t_0 + \Delta t\) given that they have entered the state at time \(t_0\).

Additionally, calculate the number of compounds that are at risk to leave the state at time \(t_0 + \Delta t\), i.e. the number of compounds that have continuously been in the state from time \(t_0\) to \(t_0 + \Delta t\).

Parameters:

dtrj (array_like) – The discrete trajectory. Array of shape (n, f), where n is the number of compounds and f is the number of frames. The shape can also be (f,), in which case the array is expanded to shape (1, f). The elements of dtrj are interpreted as the indices of the states in which a given compound is at a given frame.
discard_neg_start (bool, optional) – If True, discard all state leavings starting from a negative state. This means compounds in negative states are ignored. They neither increase n_leaves nor n_risk. This is equivalent to discarding the lifetimes of all negative states when calculating state lifetimes with mdtools.dtrj.lifetimes().
discard_all_neg (bool, optional) – If True, discard all state leavings starting from or ending in a negative state. Additionally to ignoring compounds in negative states, transitions from positive to negative states are treated as right-censored. These transitions increase n_risk but not n_leaves. 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().
verbose (bool, optional) – If True print a progress bar.

Returns:

n_leaves (numpy.ndarray) – Array of shape (f,) and dtype numpy.uint32 containing for all possible lag times the number of compounds that leave their state at time \(t_0 + \Delta t\) given that they have entered the state at time \(t_0\).
n_risk (numpy.ndarray) – Array of shape (f,) and dtype numpy.uint32 containing for all possible lag times the number of compounds that are at risk of leaving the state.

See also

mdtools.dtrj.leave_prob(): Calculate the probability that a compound leaves its state after a lag time \(\Delta t\) given that it has entered the state at time \(t_0\)
mdtools.dtrj.kaplan_meier(): Estimate the state survival function using the Kaplan-Meier estimator

Notes

n_leaves / n_risk is the probability that a compound leaves its state at time \(t_0 + \Delta t\) given that it has entered the state at time \(t_0\).

np.cumprod(1 - n_leaves / n_risk) is the Kaplan-Meier estimate of the survival function of the underlying distribution of state lifetimes.[1]

References

Examples

>>> # No detectable leave, two censored lifetimes.
>>> dtrj = np.array([2, 2, 5, 5, 5, 5, 5])
>>> n_leaves, n_risk = mdt.dtrj.n_leaves_vs_time(dtrj)
>>> n_leaves
array([0, 0, 0, 0, 0, 0, 0], dtype=uint32)
>>> n_risk
array([2, 2, 2, 1, 1, 1, 0], dtype=uint32)
>>> # One detectable leave, two censored lifetimes.
>>> dtrj = np.array([2, 2, 3, 3, 3, 2, 2])
>>> n_leaves, n_risk = mdt.dtrj.n_leaves_vs_time(dtrj)
>>> n_leaves
array([0, 0, 0, 1, 0, 0, 0], dtype=uint32)
>>> n_risk
array([3, 3, 3, 1, 0, 0, 0], dtype=uint32)
>>> # Two detectable leaves, two censored lifetimes.
>>> dtrj = np.array([1, 3, 3, 3, 1, 2, 2])
>>> n_leaves, n_risk = mdt.dtrj.n_leaves_vs_time(dtrj)
>>> n_leaves
array([0, 1, 0, 1, 0, 0, 0], dtype=uint32)
>>> n_risk
array([4, 4, 2, 1, 0, 0, 0], dtype=uint32)
>>> dtrj = np.array([1, 3, 3, 3, 2, 2, 1])
>>> n_leaves, n_risk = mdt.dtrj.n_leaves_vs_time(dtrj)
>>> n_leaves
array([0, 0, 1, 1, 0, 0, 0], dtype=uint32)
>>> n_risk
array([4, 4, 2, 1, 0, 0, 0], dtype=uint32)
>>> dtrj = np.array([3, 3, 3, 1, 2, 2, 1])
>>> n_leaves, n_risk = mdt.dtrj.n_leaves_vs_time(dtrj)
>>> n_leaves
array([0, 1, 1, 0, 0, 0, 0], dtype=uint32)
>>> n_risk
array([4, 4, 2, 1, 0, 0, 0], dtype=uint32)

>>> dtrj = np.array([[2, 2, 5, 5, 5, 5, 5],
...                  [2, 2, 3, 3, 3, 2, 2],
...                  [1, 3, 3, 3, 1, 2, 2],
...                  [1, 3, 3, 3, 2, 2, 1],
...                  [3, 3, 3, 1, 2, 2, 1]])
>>> n_leaves, n_risk = mdt.dtrj.n_leaves_vs_time(dtrj)
>>> n_leaves
array([0, 2, 2, 3, 0, 0, 0], dtype=uint32)
>>> n_risk
array([17, 17, 11,  5,  1,  1,  0], dtype=uint32)
>>> 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]])
>>> n_leaves, n_risk = mdt.dtrj.n_leaves_vs_time(dtrj)
>>> n_leaves
array([0, 1, 1, 2, 0, 0], dtype=uint32)
>>> n_risk
array([12, 12,  8,  4,  0,  0], dtype=uint32)

Discarding negative states:

>>> 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]])
>>> n_leaves, n_risk = mdt.dtrj.n_leaves_vs_time(dtrj)
>>> n_leaves
array([0, 1, 1, 2, 1, 0], dtype=uint32)
>>> n_risk
array([15, 15,  9,  5,  1,  0], dtype=uint32)
>>> n_leaves_ns, n_risk_ns = mdt.dtrj.n_leaves_vs_time(
...     dtrj, discard_neg_start=True
... )
>>> n_leaves_ns
array([0, 1, 1, 2, 1, 0], dtype=uint32)
>>> n_risk_ns
array([15, 15,  9,  5,  1,  0], dtype=uint32)
>>> n_leaves_an, n_risk_an = mdt.dtrj.n_leaves_vs_time(
...     dtrj, discard_all_neg=True
... )
>>> n_leaves_an
array([0, 1, 1, 2, 1, 0], dtype=uint32)
>>> n_risk_an
array([15, 15,  9,  5,  1,  0], dtype=uint32)
>>> 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]])
>>> n_leaves, n_risk = mdt.dtrj.n_leaves_vs_time(dtrj)
>>> n_leaves
array([0, 1, 1, 2, 1, 0], dtype=uint32)
>>> n_risk
array([15, 15,  9,  5,  1,  0], dtype=uint32)
>>> n_leaves_ns, n_risk_ns = mdt.dtrj.n_leaves_vs_time(
...     dtrj, discard_neg_start=True
... )
>>> n_leaves_ns
array([0, 1, 0, 2, 1, 0], dtype=uint32)
>>> n_risk_ns
array([10, 10,  5,  5,  1,  0], dtype=uint32)
>>> n_leaves_an, n_risk_an = mdt.dtrj.n_leaves_vs_time(
...     dtrj, discard_all_neg=True
... )
>>> n_leaves_an
array([0, 0, 0, 1, 0, 0], dtype=uint32)
>>> n_risk_ns
array([10, 10,  5,  5,  1,  0], dtype=uint32)
>>> 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]])
>>> n_leaves, n_risk = mdt.dtrj.n_leaves_vs_time(dtrj)
>>> n_leaves
array([0, 1, 1, 2, 1, 0], dtype=uint32)
>>> n_risk
array([17, 17, 11,  7,  3,  2], dtype=uint32)
>>> n_leaves_ns, n_risk_ns = mdt.dtrj.n_leaves_vs_time(
...     dtrj, discard_neg_start=True
... )
>>> n_leaves_ns
array([0, 1, 0, 2, 1, 0], dtype=uint32)
>>> n_risk_ns
array([11, 11,  6,  6,  2,  1], dtype=uint32)
>>> n_leaves_an, n_risk_an = mdt.dtrj.n_leaves_vs_time(
...     dtrj, discard_all_neg=True
... )
>>> n_leaves_an
array([0, 0, 0, 1, 0, 0], dtype=uint32)
>>> n_risk_ns
array([11, 11,  6,  6,  2,  1], dtype=uint32)