timescales

Set of functions for analyzing the MD trajectory.

This submodule contains methods for estimating various timescales based on a Markov model.

implied_timescales(trajs, lagtimes, ntimescales=None, reversible=False)

Calculate the implied timescales.

Calculate the implied timescales, which are defined by

\[t_i = - \frac{t_\text{lag}}{\log\lambda_i}\]

the \(i\)-th eigenvalue \(\lambda_i\).

Note

It is not checked if for higher lagtimes the dimensionality changes.

Parameters:

• trajs (StateTraj or list or ndarray or list of ndarray) –

  State trajectory/trajectories. The states should start from zero and need to be integers.

• lagtimes (list or ndarray int) –

  Lagtimes for estimating the markov model given in [frames]. This is not implemented yet!

• ntimescales (int, default: None ) –

  Number of returned lagtimes.

• reversible (bool, default: False ) –

  If reversibility should be enforced for the markov state model.

Returns:

• ts ( ndarray ) –

  Matrix containing the implied Timescales.

Source code in src/msmhelper/msm/timescales.py

def implied_timescales(trajs, lagtimes, ntimescales=None, reversible=False):
    r"""Calculate the implied timescales.

    Calculate the implied timescales, which are defined by

    $$t_i = - \frac{t_\text{lag}}{\log\lambda_i}$$

    the $i$-th eigenvalue $\lambda_i$.

    !!! note
        It is not checked if for higher lagtimes the dimensionality changes.

    Parameters
    ----------
    trajs : StateTraj or list or ndarray or list of ndarray
        State trajectory/trajectories. The states should start from zero and
        need to be integers.
    lagtimes : list or ndarray int
        Lagtimes for estimating the markov model given in [frames].
        This is not implemented yet!
    ntimescales : int, optional
        Number of returned lagtimes.
    reversible : bool
        If reversibility should be enforced for the markov state model.

    Returns
    -------
    ts : ndarray
        Matrix containing the implied Timescales.

    """
    # format input
    trajs = StateTraj(trajs)
    lagtimes = np.atleast_1d(lagtimes)

    # check that lag times are array of integers
    if not np.issubdtype(lagtimes.dtype, np.integer):
        raise TypeError(
            'Lagtimes needs to be integers but are {0}'.format(lagtimes.dtype),
        )
    if not (lagtimes > 0).all():
        raise TypeError('Lagtimes needs to be positive integers')
    if reversible:
        raise NotImplementedError(
            'Reversible matrices are not anymore supported.'
        )

    if ntimescales is None:
        ntimescales = trajs.nstates - 1

    # initialize result
    impl_timescales = np.zeros((len(lagtimes), ntimescales))

    for idx, lagtime in enumerate(lagtimes):
        transmat, _ = trajs.estimate_markov_model(lagtime)
        impl_timescales[idx] = _implied_timescales(
            transmat, lagtime, ntimescales=ntimescales,
        )

    return impl_timescales

estimate_waiting_times(*, trajs, lagtime, start, final, steps, return_list=False)

Estimates waiting times between stated states.

The stated states (from/to) will be treated as a basin. The function calculates all transitions from first entering the start-basin until first reaching the final-basin.

Parameters:

• trajs (statetraj or list or ndarray or list of ndarray) –

  State trajectory/trajectories. The states should start from zero and need to be integers.

• lagtime (int) –

  Lag time for estimating the markov model given in [frames].

• start (int or list of) –

  States to start counting.

• final (int or list of) –

  States to start counting.

• steps (int) –

  Number of MCMC propagation steps of MCMC run.

• return_list (bool, default: False ) –

  If true a list of all events is returned, else the probability density together with the edges is returned.

Returns:

• ts ( ndarray ) –

  Density probability of the time distribution. If return_list=True, return a sorted (!) list containing all times.

• edges ( ndarray ) –

  Array containing the edges corresponding to the probability, given in frames. Only for return_list=False.

Source code in src/msmhelper/msm/timescales.py

@decorit.alias('estimate_wt')
def estimate_waiting_times(
    *,
    trajs,
    lagtime,
    start,
    final,
    steps,
    return_list=False,
):
    """Estimates waiting times between stated states.

    The stated states (from/to) will be treated as a basin. The function
    calculates all transitions from first entering the start-basin until first
    reaching the final-basin.

    Parameters
    ----------
    trajs : statetraj or list or ndarray or list of ndarray
        State trajectory/trajectories. The states should start from zero and
        need to be integers.
    lagtime : int
        Lag time for estimating the markov model given in [frames].
    start : int or list of
        States to start counting.
    final : int or list of
        States to start counting.
    steps : int
        Number of MCMC propagation steps of MCMC run.
    return_list : bool
        If true a list of all events is returned, else the probability density
        together with the edges is returned.

    Returns
    -------
    ts : ndarray
        Density probability of the time distribution. If `return_list=True`,
        return a sorted (!) list containing all times.
    edges : ndarray
        Array containing the edges corresponding to the probability, given in
        frames. Only for `return_list=False`.

    """
    return _estimate_times(
        trajs=trajs,
        lagtime=lagtime,
        start=start,
        final=final,
        steps=steps,
        estimator=_estimate_waiting_times,
        return_list=return_list,
    )

estimate_transition_times(*, trajs, lagtime, start, final, steps, return_list=False)

Estimates transition times between stated states.

The stated states (from/to) will be treated as a basin. The function calculates all transitions from leaving the start-basin until first reaching the final-basin.

Parameters:

• trajs (statetraj or list or ndarray or list of ndarray) –

  State trajectory/trajectories. The states should start from zero and need to be integers.

• lagtime (int) –

  Lag time for estimating the markov model given in [frames].

• start (int or list of) –

  States to start counting.

• final (int or list of) –

  States to start counting.

• steps (int) –

  Number of MCMC propagation steps of MCMC run.

• return_list (bool, default: False ) –

  If true a list of all events is returned, else the probability density together with the edges is returned.

Returns:

• ts ( ndarray ) –

  Density probability of the time distribution. If return_list=True, return a sorted (!) list containing all times.

• edges ( ndarray ) –

  Array containing the edges corresponding to the probability, given in frames. Only for return_list=False.

Source code in src/msmhelper/msm/timescales.py

@decorit.alias('estimate_tt')
def estimate_transition_times(
    *,
    trajs,
    lagtime,
    start,
    final,
    steps,
    return_list=False,
):
    """Estimates transition times between stated states.

    The stated states (from/to) will be treated as a basin. The function
    calculates all transitions from leaving the start-basin until first
    reaching the final-basin.

    Parameters
    ----------
    trajs : statetraj or list or ndarray or list of ndarray
        State trajectory/trajectories. The states should start from zero and
        need to be integers.
    lagtime : int
        Lag time for estimating the markov model given in [frames].
    start : int or list of
        States to start counting.
    final : int or list of
        States to start counting.
    steps : int
        Number of MCMC propagation steps of MCMC run.
    return_list : bool
        If true a list of all events is returned, else the probability density
        together with the edges is returned.

    Returns
    -------
    ts : ndarray
        Density probability of the time distribution. If `return_list=True`,
        return a sorted (!) list containing all times.
    edges : ndarray
        Array containing the edges corresponding to the probability, given in
        frames. Only for `return_list=False`.

    """
    return _estimate_times(
        trajs=trajs,
        lagtime=lagtime,
        start=start,
        final=final,
        steps=steps,
        estimator=_estimate_transition_times,
        return_list=return_list,
    )

estimate_paths(*, trajs, lagtime, start, final, steps)

Estimates paths and waiting times between stated states.

The stated states (from/to) will be treated as a basin. The function estimates transitions from first entering the start-basin until first reaching the final-basin. The results will be listed by the corresponding pathways, where loops are removed occuring first.

Note

This function is a simple wrapper and in contrast to estimate_wt it stores the whole MCMC trajectory in memory. Hence, it memory-hungry.

Parameters:

• trajs (statetraj or list or ndarray or list of ndarray) –

  State trajectory/trajectories. The states should start from zero and need to be integers.

• lagtime (int) –

  Lag time for estimating the markov model given in [frames].

• start (int or list of) –

  States to start counting.

• final (int or list of) –

  States to start counting.

• steps (int) –

  Number of MCMC propagation steps of MCMC run.

Returns:

• paths ( dict ) –

  Dictionary containing the the paths as keys and and an array holding the times of all paths as value.

Source code in src/msmhelper/msm/timescales.py

def estimate_paths(
    *,
    trajs,
    lagtime,
    start,
    final,
    steps,
):
    """Estimates paths and waiting times between stated states.

    The stated states (from/to) will be treated as a basin. The function
    estimates transitions from first entering the start-basin until first
    reaching the final-basin. The results will be listed by the corresponding
    pathways, where loops are removed occuring first.

    !!! note
        This function is a simple wrapper and in contrast to
        [estimate_wt][msmhelper.msm.estimate_waiting_times] it stores the whole
        MCMC trajectory in memory. Hence, it memory-hungry.

    Parameters
    ----------
    trajs : statetraj or list or ndarray or list of ndarray
        State trajectory/trajectories. The states should start from zero and
        need to be integers.
    lagtime : int
        Lag time for estimating the markov model given in [frames].
    start : int or list of
        States to start counting.
    final : int or list of
        States to start counting.
    steps : int
        Number of MCMC propagation steps of MCMC run.

    Returns
    -------
    paths : dict
        Dictionary containing the the paths as keys and and an array holding
        the times of all paths as value.

    """
    # check correct input format
    trajs = StateTraj(trajs)

    states_start, states_final = np.unique(start), np.unique(final)

    if intersect(states_start, states_final):
        raise ValueError('States `start` and `final` do overlap.')

    # check that all states exist in trajectory
    for states in (states_start, states_final):
        if intersect(states, trajs.states) != len(states):
            raise ValueError(
                'Selected states does not exist in state trajectory.',
            )

    return md_estimate_paths(
        propagate_MCMC(trajs, lagtime, steps),
        start,
        final,
    )

propagate_MCMC(trajs, lagtime, steps, start=-1)

Propagate Monte Carlo Markov chain.

Parameters:

• trajs (statetraj or list or ndarray or list of ndarray) –

  State trajectory/trajectories. The states should start from zero and need to be integers.

• lagtime (int) –

  Lag time for estimating the markov model given in [frames].

• steps (int) –

  Number of MCMC propagation steps.

• start (int or list of, default: -1 ) –

  State to start propagating. Default (-1) is random state.

Returns:

• mcmc ( ndarray ) –

  Monte Carlo Markov chain state trajectory.

Source code in src/msmhelper/msm/timescales.py

def propagate_MCMC(
    trajs,
    lagtime,
    steps,
    start=-1,
):
    """Propagate Monte Carlo Markov chain.

    Parameters
    ----------
    trajs : statetraj or list or ndarray or list of ndarray
        State trajectory/trajectories. The states should start from zero and
        need to be integers.
    lagtime : int
        Lag time for estimating the markov model given in [frames].
    steps : int
        Number of MCMC propagation steps.
    start : int or list of, optional
        State to start propagating. Default (-1) is random state.

    Returns
    -------
    mcmc : ndarray
        Monte Carlo Markov chain state trajectory.

    """
    # check correct input format
    trajs = StateTraj(trajs)

    # check that all states exist in trajectory
    if start == -1:
        start = np.random.choice(trajs.states)
    elif start not in trajs.states:
        raise ValueError(
            'Selected starting state does not exist in state trajectory.',
        )

    # convert states to idx
    idx_start = trajs.state_to_idx(start)

    # estimate permuted cumulative transition matrix
    cummat = _get_cummat(trajs=trajs, lagtime=lagtime)

    # do not convert for pytest coverage
    return shift_data(
        _propagate_MCMC(  # pragma: no cover
            cummat=cummat,
            start=idx_start,
            steps=steps,
        ),
        np.arange(trajs.nstates),
        trajs.states,
    )

estimate_waiting_time_dist(trajs, max_lagtime, start, final, steps, n_lagtimes=50)

Estimate waiting time distribution.

Parameters:

• trajs (statetraj or list or ndarray or list of ndarray) –

  State trajectory/trajectories. The states should start from zero and need to be integers.

• max_lagtime (int) –

  Maximal lag time for estimating the markov model given in [frames].

• start (int or list of) –

  States to start counting.

• final (int or list of) –

  States to start counting.

• steps (int) –

  Number of MCMC propagation steps of MCMC run.

Returns:

• wtd ( dict ) –

  Dictionary containing waiting time distribution.

Source code in src/msmhelper/msm/timescales.py

@decorit.alias('estimate_wtd')
def estimate_waiting_time_dist(
    trajs,
    max_lagtime,
    start,
    final,
    steps,
    n_lagtimes=50,
):
    """Estimate waiting time distribution.

    Parameters
    ----------
    trajs : statetraj or list or ndarray or list of ndarray
        State trajectory/trajectories. The states should start from zero and
        need to be integers.
    max_lagtime : int
        Maximal lag time for estimating the markov model given in [frames].
    start : int or list of
        States to start counting.
    final : int or list of
        States to start counting.
    steps : int
        Number of MCMC propagation steps of MCMC run.

    Returns
    -------
    wtd : dict
        Dictionary containing waiting time distribution.

    """
    lagtimes = np.unique(
        np.linspace(1, max_lagtime, num=n_lagtimes, dtype=int),
    )

    # get stats
    wtd = {
        lagtime: boxplot_stats(
            estimate_waiting_times(
                trajs=trajs,
                lagtime=lagtime,
                start=start,
                final=final,
                steps=steps,
                return_list=True,
            ),
        )[0]
        for lagtime in lagtimes
    }

    # include MD
    wtd['MD'] = boxplot_stats(
        md_estimate_wt(
            trajs=trajs,
            start=start,
            final=final,
        ),
    )
    return wtd