class DrunkardsWalk¶

class deeptime.data.DrunkardsWalk(grid_size: Tuple[int, int], bar_location: List[Tuple[int, int]], home_location: List[Tuple[int, int]], barriers=None)¶

This example dataset simulates the steps a drunkard living in a two-dimensional plane takes finding either the bar or the home as two absorbing states.

The drunkard can take steps in a 3x3 stencil with uniform probability (as possible, in the corners the only possibilities are the ones that do not lead out of the grid). The transition matrix $P\in\mathbb{R}^{nm\times nm}$ possesses one absorbing state for home and bar, respectively, and uniform two-dimensional jump probabilities in between. The grid is of size $n\times m$ and a point $(i,j)$ is identified with state $i+nj$ in the transition matrix.

Parameters:

grid_size (tuple) – The grid size, must be tuple of length two.
bar_location (tuple) – The bar location, must be valid coordinate and tuple of length two.
home_location (tuple) – The home location, must be valid coordinate and tuple of length two.
barriers (List of tuple of two integers or None, default=None) – Initial barrier locations. Can also be added post-hoc by calling add_barrier().

Attributes

msm

Yields a MSM which is parameterized with a transition matrix corresponding to this setup.

Methods

`add_barrier`(begin, end[, weight])	Adds a barrier to the grid by assigning probabilities
`coordinate_to_state`(coord)	Transforms a two-dimensional grid point (i, j) to a one-dimensional state.
`is_valid_coordinate`(coord)	Validates if a coordinate is within bounds.
`plot_2d_map`(ax[, barriers, barrier_mode])	Plots the drunkard's map onto an already existing matplotlib axis.
`plot_network`(ax, F[, cmap, connection_threshold])	Plots a flux network onto a matplotlib axis assuming that the states are ordered according to a iota range (i.e., {0, 1, ..., n_states-1}) on the grid.
`plot_path`(ax, path[, intermediates, color_lerp])	Plots a path onto a drunkard's walk map.
`state_to_coordinate`(state)	Inverse operation to `coordinate_to_state()`.
`walk`(start, n_steps[, stop, return_states, seed])	Simulates a random walk on the grid.

add_barrier(begin: Tuple[int, int], end: Tuple[int, int], weight: Optional[float] = None)¶

Adds a barrier to the grid by assigning probabilities

P_{ij} = \mathbb{P}(X_{n+1} = j\in\mathrm{barriers} : X_n=i\text{ next to barrier}) = 0.

The barrier is interpreted as a straight line between begin and end, discretized onto states using Bresenham’s line algorithm [1].

Parameters:

begin (tuple of two integers) – Begin coordinate of the barrier.
end (tuple of two integers) – End coordinate of the barrier.
weight (float or None, default=None) – If not None, the probability of jumping onto the barrier is set to $1/w$ before row-normalization.

References

coordinate_to_state(coord: Tuple[int, int]) → int¶

Transforms a two-dimensional grid point (i, j) to a one-dimensional state.

Parameters:: coord ((i, j) tuple) – The grid point.
Returns:: state – The state corresponding to the grid point.
Return type:: int

is_valid_coordinate(coord: Tuple[int, int]) → bool¶

Validates if a coordinate is within bounds.

Parameters:: coord ((i, j) tuple) – The coordinate.
Returns:: is_valid – Whether the coordinate is within bounds.
Return type:: bool

plot_2d_map(ax, barriers: bool = True, barrier_mode: str = 'filled')¶

Plots the drunkard’s map onto an already existing matplotlib axis. One can select whether to draw barriers and if barriers should be drawn, whether they have a ‘filled’ face or be ‘hollow’ with just the border being colored.

Parameters:

ax (matplotlib axis) – The axis.
barriers (bool, default=True) – Whether to draw the barriers.
barrier_mode (str, default='filled') – How to draw barriers - can be one of ‘filled’ and ‘hollow’.

Returns:

Handles and labels for a matplotlib legend.

Return type:

handles, labels

plot_network(ax, F, cmap=None, connection_threshold: float = 0.0)¶

Plots a flux network onto a matplotlib axis assuming that the states are ordered according to a iota range (i.e., {0, 1, …, n_states-1}) on the grid.

Parameters:

ax (matplotlib axis) – The axis to plot onto.
F ((n_states, n_states) ndarray) – The flux network, assigning to a state tuple F[i,j] a current.
cmap (matplotlib colormap, default=None) – A colormap to use for the edges.
connection_threshold (float, default=0) – A connection threshold in terms of minimal current to exceed to draw an edge.

Returns:

edge_colors – List of edge colors.

Return type:

list

static plot_path(ax, path, intermediates: bool = True, color_lerp: bool = True, **plot_kw)¶

Plots a path onto a drunkard’s walk map. The path is interpolated with splines and, if desired, has a linearly interpolated color along its path.

Parameters:

ax (matplotlib axis) – The axis to plot onto.
path ((N, 2) ndarray) – The path in terms of 2-dimensional coordinates.
intermediates (bool, default=True) – Whether to scatterplot the states that were visited in the path.
color_lerp (bool, default=True) – Whether to perform a linear interpolation along a colormap while the path progresses through the map.
plot_kw – Additional args that go into either a ax.plot call (lerp=False) or into a LineCollection(…) call (lerp=True).

state_to_coordinate(state: int) → Tuple[int, int]¶

Inverse operation to coordinate_to_state(). Transforms state to corresponding coordinate (i,j).

Parameters:: state (int) – The state.
Returns:: coordinate – The corresponding coordinate.
Return type:: (i, j) tuple

walk(start: Tuple[int, int], n_steps: int, stop: bool = True, return_states: bool = False, seed: int = -1)¶

Simulates a random walk on the grid.

Parameters:

start ((i, j) tuple) – Start coordinate on the grid.
n_steps (int) – Maximum number of steps to simulate.
stop (bool, default=False) – Whether to stop the simulation once home or bar have been reached
return_states (bool, default=False) – Whether to return states instead of coordinates. Default is False.
seed (int, default=-1) – Random seed.

Returns:

random_walk – A random walk in coordinate space.

Return type:

(n_steps, 2) ndarray

property msm¶

Yields a MSM which is parameterized with a transition matrix corresponding to this setup.

Returns:: msm – The corresponding Markov state model.
Return type:: deeptime.markov.msm.MarkovStateModel