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
Yields a
MSMwhich 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