Core

The core module contains the main abstractions used throughout the library.

Chain

class markovpy.chain.Chain(data=None, **attr)[source]

Bases: object

A discrete-time Markov chain.

States are arbitrary hashable python objects. Transitions are stored as adjacency dictionaries with attributes, rather than as a matrix.

This class stores structures only, algorithms are implemented externally.

Parameters:

  • data (Optional[Iterable[str]]) – Optional Iterable data, converted to states.

  • attr – Optional attributes.

add_state(s, **attr)[source]

Add a state to the chain. :type s: :param s: State to add. :type attr: :param attr: Any other attributes.

add_states_from(states, **attr)[source]

Adds multiple states to the chain. :type states: Iterable[str] :param states: Iterable states to add. :type attr: :param attr: Any other attributes.

Parameters:

states (Iterable[str])

add_transition(u, v, p=None, **attr)[source]

Add a transition u -> v to the chain. :type u: :param u: Transition origin state. :type v: :param v: Transition target state. :type p: Union[float, int, None] :param p: Optional probability float. :type attr: :param attr: Any other attributes.

Parameters:

p (float | int | None)

property states

Set of states.

Type:

return

transitions(u=None)[source]

Returns transitions from source u.

If u is none:

iterate over (u, v, attr).

Else:

iterate over (u, v, attr) for fixed u.

Parameters:

u (Optional[str]) – State to return transitions from (Optional).

Yields:

All transitions v -> u.

add_transitions_from(data)[source]

Adds transitions from an iterable.

Each element may be: (u, v) (u, v, p) (u, v, attr) (u, v, p, attr)

Parameters:

data (Iterable[Tuple]) – Iterable Tuples to add data from.

Raises:

ValueError – If not in acceptable form.

successors(u)[source]

Returns all v where u can transition to v.

Parameters:

u (str) – Origin State.

Return type:

set

Returns:

List of States that u can transition to.

predecessors(v)[source]

Returns all u where u can transition to v. :type v: str :param v: Target state to find transitions. :rtype: set :return: List of States that u can transition to.

Parameters:

v (str)

Return type:

set

has_state(s)[source]

Returns true if s is a state. :type s: str :param s: Possible state to check for. :rtype: bool :return: If state exists in chain.

Parameters:

s (str)

Return type:

bool

has_transition(u, v)[source]

returns true if u and v are transitions. :type u: str :param u: Origin of transition to find. :type v: str :param v: Target of transition to find. :rtype: bool :return: If transition exists.

Parameters:

  • u (str)

  • v (str)

Return type:

bool

transition_mass(u, v)[source]

Return the transition probability from state u to state v

If there is no outgoing edge from u to v, returns 0 :type u: str :param u: Origin of the weight to find :type v: str :param v: Target of the weight to find :rtype: float :return:

Parameters:

  • u (str)

  • v (str)

Return type:

float

out_degree(u, weight=None)[source]

Returns the number of outgoing edges if weight is none. Else returns the sum of the weight of outgoing edges. :type u: str :param u: State to count weight. :type weight: Optional[str] :param weight: “p” returns sum. :rtype: float :return: Sum or count of weights of outgoing edges.

Parameters:

  • u (str)

  • weight (str | None)

Return type:

float

in_degree(v, weight=None)[source]

Returns the number of entering edges if weight is none. Else returns the sum of the weight of entering edges. :type v: str :param v: Target state to count weight. :type weight: Optional[str] :param weight: “p” returns sum. :rtype: float :return: Sum or count of weight of entering edges.

Parameters:

  • v (str)

  • weight (str | None)

Return type:

float

is_stochastic(tol=1e-12)[source]

Returns True if the chain is stochastic. :type tol: float :param tol: Optional Tolerance. :rtype: bool :return: True if chain is stochastic.

Parameters:

tol (float)

Return type:

bool

normalise()[source]

Takes the sums of the weights and normalises them to 1

classmethod from_adjacency_matrix(matrix, states=None, normalise=True, validate=True)[source]

Constructs a Markov chain from an adjacency matric

The adjacency matrix is interpreted row-wise

Parameters:

  • matrix (list[list]) – Sequence of Sequences of non-negative numbers

  • states (Optional[Iterable[str]]) – Optional state labels

  • normalise (bool) – Optional, rows of matrix normalised to 1

  • validate (bool) – Optional, validates the matrix for correctness

Returns:

Chain

to_adjacency_matrix(states=None, dense=True)[source]

Converts a chain object to an adjacency matrix. :type states: Optional[list] :param states: Option states. :type dense: bool :param dense: Bool, if True returns dense matrix. :rtype: list[list[float]] | dict[Any, Any] :return: Adjacency matrix.

Parameters:

  • states (list | None)

  • dense (bool)

Return type:

list[list[float]] | dict[Any, Any]

classmethod merge(chain1, chain2, merge_type='add', normalise=True)[source]

Combines Two chains into a new chain :type chain1: :param chain1: First chain to combine. :type chain2: :param chain2: Second chain to combine. :type merge_type: str :param merge_type: :type normalise: bool :param normalise: :return: New merged Chain.

Parameters:

  • merge_type (str)

  • normalise (bool)

stationary_distribution(method='auto', tol=1e-12, max_iter=10000)[source]

Calculates the stationary distribution of the chain. :type method: str :param method: “auto”, “linear” or “power”. :type tol: float :param tol: Optional Tolerance. :type max_iter: int :param max_iter: Optional max iterations of Power Method. :rtype: set :return: set of stationary distribution.

Parameters:

  • method (str)

  • tol (float)

  • max_iter (int)

Return type:

set

Submodules