chainopy.markov_chain¶

Classes

MarkovChain([p, states])

A class containing Fundamental Functions for Discrete Time Markov Chains.

class chainopy.markov_chain.MarkovChain(p=None, states=None)[source]¶

A class containing Fundamental Functions for Discrete Time Markov Chains.

This class provides a comprehensive suite of methods for working with discrete-time Markov chains (DTMCs), including validation, simulation, and analysis functionalities. It supports learning transition probability matrices (TPMs) from data, checking various properties of the Markov chain (e.g., ergodicity, aperiodicity, symmetry), and computing distributions and probabilities related to the chain’s behavior over time.

tpm¶

Transition probability matrix (TPM) representing the Markov chain.

Type:: np.ndarray

states¶

List of state names corresponding to the TPM.

Type:: List[str]

eigendecom¶

Flag indicating if the TPM is eigendecomposable.

Type:: bool

eigenvalues¶

Eigenvalues of the TPM.

Type:: np.ndarray

eigenvectors¶

Eigenvectors of the TPM.

Type:: np.ndarray

epsilon¶

Small value to avoid numerical issues in calculations.

Type:: float

__init__(p=None, states=None)[source]¶

absorbing_states()[source]¶

Returns all absorbing states.

Return type:: List[str]
Returns:: List[str]: Absorbing states.

absorption_probabilities()[source]¶

Returns the absorption probabilities matrix for each state.

Return type:: ndarray
Returns:: ndarray: Absorption probabilities matrix.

adjacency_matrix()[source]¶

Return type:: ndarray
Returns:: ndarray: Adjacency matrix of the chain.

eigendecom¶

eigenvalues¶

eigenvectors¶

epsilon¶

expected_hitting_time(state)[source]¶

Returns the expected hitting time to reach the given absorbing state.

Parameters:: state (str) – Absorbing state.
Return type:: Optional[float]
Returns:: Union[float, None]: Expected hitting time.

expected_number_of_visits()[source]¶

Returns the expected number of visits to each state before absorption.

Return type:: ndarray
Returns:: ndarray: Expected number of visits.

expected_time_to_absorption()[source]¶

Returns the expected time to absorption for each state.

Return type:: ndarray
Returns:: ndarray: Expected time to absorption.

fit(data, epsilon=1e-16)[source]¶

Learn Transition Matrix from Sequence (list or str) of Data. Each Unique Word is considered a State. It will override the current transition-matrix.

Parameters:

data (Union[str, list]) – Data on which the MarkovChain model must be fitted.
epsilon (float) – Small dummy value to avoid zeros in the Transition-Matrix

Return type:

ndarray

Returns:

ndarray: Transition - Matrix based on data
Usage
—– – >>> chainopy.MarkovChain().fit(“My name is John.”)

fit_from_file(path, epsilon=1e-16)[source]¶

Parameters:

path (str) – path to the text file
epsilon (float) – small value to avoid zero division

Returns:

Transition Matrix trained from the text file. If self.tpm is None. Then this sets self.tpm to the new transition-matrix.

Return type:

ndarray

fundamental_matrix()[source]¶

Returns the fundamental matrix.

Return type:: Optional[ndarray]
Returns:: Union[ndarray, None]: Fundamental matrix.

is_absorbing()[source]¶

Checks if the Markov chain is absorbing.

Return type:: bool
Returns:: bool: True if the Markov chain is absorbing, False otherwise.

is_aperiodic()[source]¶

Checks if the Markov chain is aperiodic.

Return type:: bool
Returns:: bool: True if the Markov chain is aperiodic, False otherwise.

is_communicating(state1, state2, threshold=1000)[source]¶

Checks if two states are communicating.

Parameters:

state1 (str) – First state.
state2 (str) – Second state.
threshold (int, optional) – Threshold for convergence. Defaults to 1000.

Return type:

bool

Returns:

bool: True if the states are communicating, False otherwise.

is_ergodic()[source]¶

Checks if the Markov chain is ergodic.

Return type:: bool
Returns:: bool: True if the Markov chain is ergodic, False otherwise.

is_irreducible()[source]¶

Checks if the Markov chain is irreducible.

Return type:: bool
Returns:: bool: True if the Markov chain is irreducible, False otherwise.

is_recurrent(state)[source]¶

Checks if a state is recurrent.

Parameters:: state (str) – State to check.
Return type:: bool
Returns:: bool: True if the state is recurrent, False otherwise.

is_symmetric()[source]¶

Checks if the Markov chain is symmetric.

Return type:: bool
Returns:: bool: True if the Markov chain is symmetric, False otherwise.

is_transient(state)[source]¶

Checks if a state is transient.

Parameters:: state (str) – State to check.
Return type:: bool
Returns:: bool: True if the state is transient, False otherwise.

load_model(path)[source]¶

Load a ChainoPy Model stored as a JSON Object and return as a MarkovChain object.

Parameters:: path (str) – Path to the file.

Raises:¶

ValueError: If the file cannot be loaded.

marginal_dist(state)[source]¶

Parameters:: state (str) – State for which to calculate the marginal distribution
Returns:: marginal distribution of a state
Return type:: float

nstep_distribution(n_steps)[source]¶

Calculates the distribution of the Markov Chain after n-steps.

Parameters:: n_steps (int) – Number of steps.
Return type:: ndarray
Returns:: ndarray: Distribution of the Markov Chain.

period()[source]¶

Returns the period of the Markov chain.

Return type:: int
Returns:: int: Period of the Markov chain.

predict(initial_state)[source]¶

Return the next most likely states.

Parameters:: initial_state (str) – Initial state.
Return type:: str
Returns:: str: Next most likely state.

save_model(filename, epsilon=1e-16)[source]¶

Save Model as a JSON Object. If tpm is sparsifyable, it stores tpm as a sparse matrix.

Parameters:

filename (str) – Name of the file to save.
epsilon (float) – Small dummy value to avoid zeros in the Transition-Matrix

simulate(initial_state, n_steps)[source]¶

Simulate the Markov Chain for n_steps steps.

Parameters:

initial_state (str) – State from which the simulation starts
n_steps (int) – Number of steps to simulate the chain for

Return type:

List[str]

Returns:

list: Contains states attained during simulation

states¶

stationary_dist()[source]¶

Returns the stationary distribution of the Markov chain.

Return type:: ndarray
Returns:: ndarray: Stationary distribution.

tpm¶

visualize_chain()[source]¶: Visualize the Markov Chain

visualize_transition_matrix()[source]¶: Visualize the Transition Matrix