chainopy package

Subpackages

Submodules

chainopy._caching module

chainopy._exceptions module

chainopy._fileio module

chainopy._visualizations module

chainopy.markov_chain module

class chainopy.markov_chain.MarkovChain(p=None, states=None)

Bases: object

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)

absorbing_states()

Returns all absorbing states.

Return type:

List[str]

Returns:

List[str]: Absorbing states.

absorption_probabilities()

Returns the absorption probabilities matrix for each state.

Return type:

ndarray

Returns:

ndarray: Absorption probabilities matrix.

adjacency_matrix()

Return type:

ndarray

Returns:

ndarray: Adjacency matrix of the chain.

eigendecom

eigenvalues

eigenvectors

epsilon

expected_hitting_time(state)

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()

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

Return type:

ndarray

Returns:

ndarray: Expected number of visits.

expected_time_to_absorption()

Returns the expected time to absorption for each state.

Return type:

ndarray

Returns:

ndarray: Expected time to absorption.

fit(data, epsilon=1e-16)

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)

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()

Returns the fundamental matrix.

Return type:

Optional[ndarray]

Returns:

Union[ndarray, None]: Fundamental matrix.

is_absorbing()

Checks if the Markov chain is absorbing.

Return type:

bool

Returns:

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

is_aperiodic()

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)

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()

Checks if the Markov chain is ergodic.

Return type:

bool

Returns:

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

is_irreducible()

Checks if the Markov chain is irreducible.

Return type:

bool

Returns:

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

is_recurrent(state)

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()

Checks if the Markov chain is symmetric.

Return type:

bool

Returns:

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

is_transient(state)

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)

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)

Parameters:

state (str) – State for which to calculate the marginal distribution

Returns:

marginal distribution of a state

Return type:

float

nstep_distribution(n_steps)

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()

Returns the period of the Markov chain.

Return type:

int

Returns:

int: Period of the Markov chain.

predict(initial_state)

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)

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)

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()

Returns the stationary distribution of the Markov chain.

Return type:

ndarray

Returns:

ndarray: Stationary distribution.

tpm

visualize_chain()

Visualize the Markov Chain

visualize_transition_matrix()

Visualize the Transition Matrix

chainopy.markov_switching module

class chainopy.markov_switching.MarkovSwitchingModel

Bases: object

MarkovSwitchingModel estimates 1D target values given the current regime. The regimes follow a first-order Markov process.

regimes

List of regimes identified in the training data.

Type:

list

num_regimes

Number of unique regimes.

Type:

int

models

Dictionary mapping regimes to their respective AutoReg models.

Type:

dict

num_models

Number of models, corresponding to the number of unique regimes.

Type:

int

__init__()

evaluate(ts_test, ts_pred)

Evaluates the accuracy of the model using the mean squared error metric.

Parameters:

• ts_test (ndarray) – Real target values of the Time Series

• ts_pred (ndarray) – Predicted target values of the Time Series

Returns:

float

Return type:

mean square error between ts_test and ts_pred

fit(ts_data, regime_sequence, lags=1)

Trains and sets the models self.models and self._markov_chain attributes

Parameters:

• ts_data (ndarray) – 1D Target values at different timepoints

• regime_sequence (list) – Training data consisting of Regimes in chronological Order.

• lags (int,) – Time lags to consider during autoregression

predict(start_regime, steps=1)

Predicts the target values for a given number of steps into the future.

Parameters:

• start_regime (str) – Regime at the start of the prediction.

• steps (int, optional) – Number of steps into the future to predict, by default 1.

Return type:

Tuple[ndarray, ndarray]

Returns:

• Tuple[np.ndarray, np.ndarray] (Tuple containing the array of predicted)

• target values and the predicted regime sequence.

chainopy.nn module

class chainopy.nn.MarkovChainNeuralNetwork(markov_chain, num_layers)

Bases: Module

Neural network for simulating Markov chain behavior.

Parameters:

• markov_chain (chainopy.MarkovChain) – Markov chain object.

• num_layers (int) – Number of layers in the neural network.

input_dim

Input shape of the neural network. Calculated using the transition matrix.

Type:

tuple

output_dim

Output shape of the neural network. Calculated using the transition matrix.

Type:

tuple

Raises:

ValueError – If markov_chain is not of type MarkovChain.:

__init__(markov_chain, num_layers)

Initialize internal Module state, shared by both nn.Module and ScriptModule.

forward(x)

Forward pass of the neural network.

Parameters:

x (torch.tensor) – Input data.

Returns:

torch.Tensor: Output data after passing through the network.

get_weights()

Returns the weights of the model.

Returns:

dict: Dictionary containing layer names and corresponding weights.

simulate_random_walk(start_state, steps)

Simulates a random walk based on the trained model.

Parameters:

• start_state (int) – Starting state for the random walk.

• steps (int) – Number of steps to simulate.

Returns:

list: List of states representing the random walk.

train_model(num_samples, epochs, learning_rate, momentum=0.9, verbose=True, patience=500, factor=0.5)

Trains the neural network model.

Parameters:

• num_samples (int) – Number of training samples.

• epochs (int) – Number of training epochs.

• learning_rate (float) – Learning rate for optimization.

• momentum (float) – Momentum factor (default is 0.9).

• verbose (bool, optional) – If True, prints training progress (default is True).

• patience (int, optional) – Patience parameter for learning rate scheduler (default is 500).

• factor (float, optional) – Factor by which the learning rate will be reduced (default is 0.5).

chainopy.nn.divergance_analysis(mc, nn)

KL Divergance between MarkovChain.tpm and MarkovChain().fit(MarkovChainNeuralNetwork.simulate_random_walk).tpm.

Parameters:

• mc (MarkovChain) – Original Markov Chain that is used to fit the MarkovChainNeuralNetwork.

• nn (MarkovChainNeuralNetwork) – The fitted MarkovChainNeuralNetwork.

Return type:

float

Returns:

float: KL-Divergance

Lower the KL-Divergance, better the fit.

Notes

KL-Divergance<https://en.wikipedia.org/wiki/Kullback%E2%80%93Leibler_divergence>_.

Module contents

class chainopy.MarkovChain(p=None, states=None)

Bases: object

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)

absorbing_states()

Returns all absorbing states.

Return type:

List[str]

Returns:

List[str]: Absorbing states.

absorption_probabilities()

Returns the absorption probabilities matrix for each state.

Return type:

ndarray

Returns:

ndarray: Absorption probabilities matrix.

adjacency_matrix()

Return type:

ndarray

Returns:

ndarray: Adjacency matrix of the chain.

eigendecom

eigenvalues

eigenvectors

epsilon

expected_hitting_time(state)

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()

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

Return type:

ndarray

Returns:

ndarray: Expected number of visits.

expected_time_to_absorption()

Returns the expected time to absorption for each state.

Return type:

ndarray

Returns:

ndarray: Expected time to absorption.

fit(data, epsilon=1e-16)

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)

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()

Returns the fundamental matrix.

Return type:

Optional[ndarray]

Returns:

Union[ndarray, None]: Fundamental matrix.

is_absorbing()

Checks if the Markov chain is absorbing.

Return type:

bool

Returns:

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

is_aperiodic()

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)

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()

Checks if the Markov chain is ergodic.

Return type:

bool

Returns:

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

is_irreducible()

Checks if the Markov chain is irreducible.

Return type:

bool

Returns:

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

is_recurrent(state)

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()

Checks if the Markov chain is symmetric.

Return type:

bool

Returns:

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

is_transient(state)

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)

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)

Parameters:

state (str) – State for which to calculate the marginal distribution

Returns:

marginal distribution of a state

Return type:

float

nstep_distribution(n_steps)

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()

Returns the period of the Markov chain.

Return type:

int

Returns:

int: Period of the Markov chain.

predict(initial_state)

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)

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)

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()

Returns the stationary distribution of the Markov chain.

Return type:

ndarray

Returns:

ndarray: Stationary distribution.

tpm

visualize_chain()

Visualize the Markov Chain

visualize_transition_matrix()

Visualize the Transition Matrix

class chainopy.MarkovChainNeuralNetwork(markov_chain, num_layers)

Bases: Module

Neural network for simulating Markov chain behavior.

Parameters:

• markov_chain (chainopy.MarkovChain) – Markov chain object.

• num_layers (int) – Number of layers in the neural network.

input_dim

Input shape of the neural network. Calculated using the transition matrix.

Type:

tuple

output_dim

Output shape of the neural network. Calculated using the transition matrix.

Type:

tuple

Raises:

ValueError – If markov_chain is not of type MarkovChain.:

__init__(markov_chain, num_layers)

Initialize internal Module state, shared by both nn.Module and ScriptModule.

forward(x)

Forward pass of the neural network.

Parameters:

x (torch.tensor) – Input data.

Returns:

torch.Tensor: Output data after passing through the network.

get_weights()

Returns the weights of the model.

Returns:

dict: Dictionary containing layer names and corresponding weights.

simulate_random_walk(start_state, steps)

Simulates a random walk based on the trained model.

Parameters:

• start_state (int) – Starting state for the random walk.

• steps (int) – Number of steps to simulate.

Returns:

list: List of states representing the random walk.

train_model(num_samples, epochs, learning_rate, momentum=0.9, verbose=True, patience=500, factor=0.5)

Trains the neural network model.

Parameters:

• num_samples (int) – Number of training samples.

• epochs (int) – Number of training epochs.

• learning_rate (float) – Learning rate for optimization.

• momentum (float) – Momentum factor (default is 0.9).

• verbose (bool, optional) – If True, prints training progress (default is True).

• patience (int, optional) – Patience parameter for learning rate scheduler (default is 500).

• factor (float, optional) – Factor by which the learning rate will be reduced (default is 0.5).

class chainopy.MarkovSwitchingModel

Bases: object

MarkovSwitchingModel estimates 1D target values given the current regime. The regimes follow a first-order Markov process.

regimes

List of regimes identified in the training data.

Type:

list

num_regimes

Number of unique regimes.

Type:

int

models

Dictionary mapping regimes to their respective AutoReg models.

Type:

dict

num_models

Number of models, corresponding to the number of unique regimes.

Type:

int

__init__()

evaluate(ts_test, ts_pred)

Evaluates the accuracy of the model using the mean squared error metric.

Parameters:

• ts_test (ndarray) – Real target values of the Time Series

• ts_pred (ndarray) – Predicted target values of the Time Series

Returns:

float

Return type:

mean square error between ts_test and ts_pred

fit(ts_data, regime_sequence, lags=1)

Trains and sets the models self.models and self._markov_chain attributes

Parameters:

• ts_data (ndarray) – 1D Target values at different timepoints

• regime_sequence (list) – Training data consisting of Regimes in chronological Order.

• lags (int,) – Time lags to consider during autoregression

predict(start_regime, steps=1)

Predicts the target values for a given number of steps into the future.

Parameters:

• start_regime (str) – Regime at the start of the prediction.

• steps (int, optional) – Number of steps into the future to predict, by default 1.

Return type:

Tuple[ndarray, ndarray]

Returns:

• Tuple[np.ndarray, np.ndarray] (Tuple containing the array of predicted)

• target values and the predicted regime sequence.

chainopy.divergance_analysis(mc, nn)

KL Divergance between MarkovChain.tpm and MarkovChain().fit(MarkovChainNeuralNetwork.simulate_random_walk).tpm.

Parameters:

• mc (MarkovChain) – Original Markov Chain that is used to fit the MarkovChainNeuralNetwork.

• nn (MarkovChainNeuralNetwork) – The fitted MarkovChainNeuralNetwork.

Return type:

float

Returns:

float: KL-Divergance

Lower the KL-Divergance, better the fit.

Notes

KL-Divergance<https://en.wikipedia.org/wiki/Kullback%E2%80%93Leibler_divergence>_.