PyDTMC
Markov Chain
Properties
- class pydtmc.MarkovChain(p, states=None)[source]
Defines a Markov chain with the given transition matrix.
- Parameters:
- Raises:
ValidationError– if any input argument is not compliant.
- absorbing_states: List[List[str]][source]
A property representing the absorbing states of the Markov chain.
- accessibility_matrix: ndarray[source]
A property representing the accessibility matrix of the Markov chain.
- communicating_classes: List[List[str]][source]
A property representing the communicating classes of the Markov chain.
- communication_matrix: ndarray[source]
A property representing the communication matrix of the Markov chain.
- cyclic_classes: List[List[str]][source]
A property representing the cyclic classes of the Markov chain.
- cyclic_states: List[List[str]][source]
A property representing the cyclic states of the Markov chain.
- density: float[source]
A property representing the density of the transition matrix of the Markov chain.
- determinant: float[source]
A property representing the determinant of the transition matrix of the Markov chain.
- entropy_rate: float | None[source]
- A property representing the entropy rate of the Markov chain.If the Markov chain has multiple stationary distributions, then
Noneis returned.
- entropy_rate_normalized: float | None[source]
- A property representing the entropy rate, normalized between 0 and 1, of the Markov chain.If the Markov chain has multiple stationary distributions, then
Noneis returned.
- fundamental_matrix: ndarray | None[source]
- A property representing the fundamental matrix of the Markov chain.If the Markov chain is not absorbing or has no transient states, then
Noneis returned.
- implied_timescales: ndarray | None[source]
- A property representing the implied timescales of the Markov chain.If the Markov chain is not ergodic, then
Noneis returned.
- is_doubly_stochastic: bool[source]
A property indicating whether the Markov chain is doubly stochastic.
- is_stochastically_monotone: bool[source]
A property indicating whether the Markov chain is stochastically monotone.
- kemeny_constant: float | None[source]
- A property representing the Kemeny’s constant of the fundamental matrix of the Markov chain.If the Markov chain is not absorbing or has no transient states, then
Noneis returned.
- lumping_partitions: List[List[List[int]] | List[List[str]]][source]
A property representing all the partitions of the Markov chain that satisfy the ordinary lumpability criterion.
- mixing_rate: float | None[source]
- A property representing the mixing rate of the Markov chain.If the Markov chain is not ergodic or the SLEM (second largest eigenvalue modulus) cannot be computed, then
Noneis returned.
- n: int
A property representing the size of the Markov chain state space.
- p: ndarray
A property representing the transition matrix of the Markov chain.
- periods: List[int][source]
A property representing the period of each communicating class defined by the Markov chain.
- pi: List[ndarray][source]
- A property representing the stationary distributions of the Markov chain.Aliases: stationary_distributions, steady_states
- recurrent_classes: List[List[str]][source]
A property representing the recurrent classes defined by the Markov chain.
- recurrent_states: List[List[str]][source]
A property representing the recurrent states of the Markov chain.
- relaxation_rate: float | None[source]
- A property representing the relaxation rate of the Markov chain.If the Markov chain is not ergodic or the SLEM (second largest eigenvalue modulus) cannot be computed, then
Noneis returned.
- size: int
A property representing the size of the Markov chain.
- spectral_gap: float | None[source]
- A property representing the spectral gap of the Markov chain.If the Markov chain is not ergodic or the SLEM (second largest eigenvalue modulus) cannot be computed, then
Noneis returned.
- topological_entropy: float[source]
A property representing the topological entropy of the Markov chain.
Instance Methods
- class pydtmc.MarkovChain(p, states=None)[source]
Defines a Markov chain with the given transition matrix.
- Parameters:
- Raises:
ValidationError– if any input argument is not compliant.
- absorption_probabilities()[source]
The method computes the absorption probabilities of the Markov chain.
Notes:If the Markov chain has no transient states, then
Noneis returned.
- aggregate(s, method='adaptive')[source]
The method attempts to reduce the state space of the Markov chain to the given number of states through a Kullback-Leibler divergence minimization approach.
Notes:The spectral theory based aggregation is described in Optimal Kullback-Leibler Aggregation via Spectral Theory of Markov Chains (Deng et al., 2011).
- Parameters:
s (
int) – the number of states of the reduced Markov chain.method (
str)spectral-bottom-up for a spectral theory based aggregation, bottom-up (more suitable for reducing a large number of states).
spectral-top-down for a spectral theory based aggregation, top-down (more suitable for reducing a small number of states).
adaptive for automatically selecting the best aggregation method.
- Raises:
ValidationError– if any input argument is not compliant.ValueError– if the Markov chain defines only two states or is not ergodic.
- Return Type:
- are_communicating(state1, state2)[source]
The method verifies whether the given states of the Markov chain are communicating.
- closest_reversible(initial_distribution=None, weighted=False)[source]
The method computes the closest reversible of the Markov chain.
Notes:The algorithm is described in Computing the Nearest Reversible Markov chain (Nielsen & Weber, 2015).
- Parameters:
- Raises:
ValidationError– if any input argument is not compliant.ValueError– if the closest reversible could not be computed.
- Return Type:
- committor_probabilities(committor_type, states1, states2)[source]
The method computes the committor probabilities between the given subsets of the state space defined by the Markov chain.
Notes:If the Markov chain is not ergodic, then
Noneis returned.The method can be accessed through the following aliases: crp.
- Parameters:
- Raises:
ValidationError– if any input argument is not compliant.- Return Type:
- conditional_probabilities(state)[source]
The method computes the probabilities, for all the states of the Markov chain, conditioned on the process being at the given state.
Notes:The method can be accessed through the following aliases: conditional_distribution, cd, cp.
- Parameters:
- Raises:
ValidationError– if any input argument is not compliant.- Return Type:
- expected_rewards(steps, rewards)[source]
The method computes the expected rewards of the Markov chain after N steps, given the reward value of each state.
Notes:The method can be accessed through the following aliases: er.
- expected_transitions(steps, initial_distribution=None)[source]
The method computes the expected number of transitions performed by the Markov chain after N steps, given the initial distribution of the states.
Notes:The method can be accessed through the following aliases: et.
- first_passage_probabilities(steps, initial_state, first_passage_states=None)[source]
The method computes the first passage probabilities of the Markov chain after N steps, given the initial state and, optionally, the first passage states.
Notes:The method can be accessed through the following aliases: fpp.
- first_passage_reward(steps, initial_state, first_passage_states, rewards)[source]
The method computes the first passage reward of the Markov chain after N steps, given the reward value of each state, the initial state and the first passage states.
Notes:The method can be accessed through the following aliases: fpr.
- Parameters:
- Raises:
ValidationError– if any input argument is not compliant.ValueError– if the Markov chain defines only two states.
- Return Type:
- hitting_probabilities(targets=None)[source]
The method computes the hitting probability, for the states of the Markov chain, to the given set of states.
Notes:The method can be accessed through the following aliases: hp.
- hitting_times(targets=None)[source]
The method computes the hitting times, for all the states of the Markov chain, to the given set of states.
Notes:The method can be accessed through the following aliases: ht.
- is_absorbing_state(state)[source]
The method verifies whether the given state of the Markov chain is absorbing.
- Parameters:
- Raises:
ValidationError– if any input argument is not compliant.- Return Type:
- is_accessible(state_target, state_origin)[source]
The method verifies whether the given target state is reachable from the given origin state.
- is_cyclic_state(state)[source]
The method verifies whether the given state is cyclic.
- Parameters:
- Raises:
ValidationError– if any input argument is not compliant.- Return Type:
- is_recurrent_state(state)[source]
The method verifies whether the given state is recurrent.
- Parameters:
- Raises:
ValidationError– if any input argument is not compliant.- Return Type:
- is_transient_state(state)[source]
The method verifies whether the given state is transient.
- Parameters:
- Raises:
ValidationError– if any input argument is not compliant.- Return Type:
- lump(partitions)[source]
The method attempts to reduce the state space of the Markov chain with respect to the given partitions following the ordinary lumpability criterion.
- Parameters:
partitions (
Union[List[List[int]],List[List[str]]]) – the partitions of the state space.- Raises:
ValidationError– if any input argument is not compliant.ValueError– if the Markov chain defines only two states or is not lumpable with respect to the given partitions.
- Return Type:
- mean_absorption_times()[source]
The method computes the mean absorption times of the Markov chain.
Notes:If the Markov chain is not absorbing or has no transient states, then
Noneis returned.The method can be accessed through the following aliases: mat.
- mean_first_passage_times_between(origins, targets)[source]
The method computes the mean first passage times between the given subsets of the state space.
Notes:If the Markov chain is not ergodic, then
Noneis returned.The method can be accessed through the following aliases: mfpt_between, mfptb.
- mean_first_passage_times_to(targets=None)[source]
The method computes the mean first passage times, for all the states, to the given set of states.
Notes:If the Markov chain is not ergodic, then
Noneis returned.The method can be accessed through the following aliases: mfpt_to, mfptt.
- mean_number_visits()[source]
The method computes the mean number of visits of the Markov chain.
Notes:The method can be accessed through the following aliases: mnv.
- mean_recurrence_times()[source]
The method computes the mean recurrence times of the Markov chain.
Notes:If the Markov chain is not ergodic, then
Noneis returned.The method can be accessed through the following aliases: mrt.
- merge_with(other, gamma)[source]
The method returns a Markov chain whose transition matrix is defined below.
\(p_{new} = (1 - \gamma) p_{current} + \gamma p_{other}\)- Parameters:
other (
MarkovChain) – the other Markov chain to be merged.gamma (
float) – the merger blending factor.
- Raises:
ValidationError– if any input argument is not compliant.- Return Type:
- mixing_time(initial_distribution=None, jump=1, cutoff_type='natural')[source]
The method computes the mixing time of the Markov chain, given the initial distribution of the states.
Notes:If the Markov chain is not ergodic, then
Noneis returned.The method can be accessed through the following aliases: mt.
- Parameters:
initial_distribution (
Optional[Union[ndarray,spmatrix]]) – the initial distribution of the states (if omitted, the states are assumed to be uniformly distributed).jump (
int) – the number of steps in each iteration.cutoff_type (
str)natural for the natural cutoff;
traditional for the traditional cutoff.
- Raises:
ValidationError– if any input argument is not compliant.- Return Type:
- next(initial_state, output_index=False, seed=None)[source]
The method simulates a single step in a random walk.
- Parameters:
- Raises:
ValidationError– if any input argument is not compliant.- Return Type:
- predict(steps, initial_state, output_indices=False)[source]
The method computes the most probable sequence of states produced by a random walk of N steps, given the initial state.
Notes:In presence of probability ties
Noneis returned.
- redistribute(steps, initial_status=None, output_last=True)[source]
The method performs a redistribution of states of N steps.
- Parameters:
steps (
int) – the number of steps.initial_status (
Optional[Union[int,str,ndarray,spmatrix]]) – the initial state or the initial distribution of the states (if omitted, the states are assumed to be uniformly distributed).output_last (
bool) – a boolean indicating whether to output only the last distributions.
- Raises:
ValidationError– if any input argument is not compliant.- Return Type:
- sensitivity(state)[source]
The method computes the sensitivity matrix of the stationary distribution with respect to a given state.
Notes:If the Markov chain is not irreducible, then
Noneis returned.
- sequence_probability(sequence)[source]
The method computes the probability of a given sequence of states.
- simulate(steps, initial_state=None, final_state=None, output_indices=False, seed=None)[source]
The method simulates a random walk of the given number of steps.
- Parameters:
steps (
int) – the number of steps.initial_state (
Optional[Union[int,str]]) – the initial state (if omitted, it is chosen uniformly at random).final_state (
Optional[Union[int,str]]) – the final state of the walk (if specified, the simulation stops as soon as it is reached even if not all the steps have been performed).output_indices (
bool) – a boolean indicating whether to output the state indices.seed (
Optional[int]) – a seed to be used as RNG initializer for reproducibility purposes.
- Raises:
ValidationError– if any input argument is not compliant.- Return Type:
- time_correlations(sequence1, sequence2=None, time_points=1)[source]
The method computes the time autocorrelations of a single observed sequence of states or the time cross-correlations of two observed sequences of states.
Notes:If the Markov chain has multiple stationary distributions, then
Noneis returned.If a single time point is provided, then a
floatis returned.The method can be accessed through the following aliases: tc.
- Parameters:
- Raises:
ValidationError– if any input argument is not compliant.- Return Type:
- time_relaxations(sequence, initial_distribution=None, time_points=1)[source]
The method computes the time relaxations of an observed sequence of states with respect to the given initial distribution of the states.
Notes:If the Markov chain has multiple stationary distributions, then
Noneis returned.If a single time point is provided, then a
floatis returned.The method can be accessed through the following aliases: tr.
- Parameters:
sequence (
Union[List[int],List[str]]) – the observed sequence of states.initial_distribution (
Optional[Union[ndarray,spmatrix]]) – the initial distribution of the states (if omitted, the states are assumed to be uniformly distributed).time_points (
Union[int,List[int]]) – the time point or a list of time points at which the computation is performed.
- Raises:
ValidationError– if any input argument is not compliant.- Return Type:
- to_bounded_chain(boundary_condition)[source]
The method returns a bounded Markov chain by adjusting the transition matrix of the original process using the specified boundary condition.
Notes:The method can be accessed through the following aliases: to_bounded.
- Parameters:
boundary_condition (
Union[float,int,str])a number representing the first probability of the semi-reflecting condition;
a string representing the boundary condition type (either absorbing or reflecting).
- Raises:
ValidationError– if any input argument is not compliant.- Return Type:
- to_canonical_form()[source]
The method returns the canonical form of the Markov chain.
Notes:The method can be accessed through the following aliases: to_canonical.
- Return Type:
- to_dictionary()[source]
The method returns a dictionary representing the Markov chain.
- to_file(file_path)[source]
The method writes a Markov chain to the given file.
Only csv, json, txt and xml files are supported; data format is inferred from the file extension.- Parameters:
file_path (
Union[str,Path]) – the location of the file in which the Markov chain must be written.- Raises:
OSError– if the file cannot be written.ValidationError– if any input argument is not compliant.
- to_graph()[source]
The method returns a directed graph representing the Markov chain.
- Return Type:
- to_lazy_chain(inertial_weights=0.5)[source]
The method returns a lazy Markov chain by adjusting the state inertia of the original process.
Notes:The method can be accessed through the following aliases: to_lazy.
- to_matrix()[source]
The method returns the transition matrix of the Markov chain.
- Return Type:
- to_subchain(states)[source]
The method returns a subchain containing all the given states plus all the states reachable from them.
Notes:The method can be accessed through the following aliases: to_sub.
- Parameters:
states (
Union[int,str,List[int],List[str]]) – the states to include in the subchain.- Raises:
ValidationError– if any input argument is not compliant.ValueError– if the subchain is not a valid Markov chain.
- Return Type:
- transition_probability(state_target, state_origin)[source]
The method computes the probability of a given state, conditioned on the process being at a given state.
Static Methods
- class pydtmc.MarkovChain(p, states=None)[source]
Defines a Markov chain with the given transition matrix.
- Parameters:
- Raises:
ValidationError– if any input argument is not compliant.
- approximation(size, approximation_type, alpha, sigma, rho, states=None, k=None)[source]
The method approximates the Markov chain associated with the discretized version of the first-order autoregressive process defined below.
\(y_t = (1 - \rho) \alpha + \rho y_{t-1} + \varepsilon_t\)with \(\varepsilon_t \overset{i.i.d}{\sim} \mathcal{N}(0, \sigma_{\varepsilon}^{2})\)- Parameters:
size (
int) – the size of the Markov chain.approximation_type (
str)adda-cooper for the Adda-Cooper approximation;
rouwenhorst for the Rouwenhorst approximation;
tauchen for the Tauchen approximation;
tauchen-hussey for the Tauchen-Hussey approximation.
alpha (
float) – the constant term \(\alpha\), representing the unconditional mean of the process.sigma (
float) – the standard deviation of the innovation term \(\varepsilon\).rho (
float) – the autocorrelation coefficient \(\rho\), representing the persistence of the process across periods.In the Tauchen approximation, the number of standard deviations to approximate out to (if omitted, the value is set to 3).
In the Tauchen-Hussey approximation, the standard deviation used for the gaussian quadrature (if omitted, the value is set to an optimal default).
states (
Optional[List[str]]) – the name of each state (if omitted, an increasing sequence of integers starting at 1).
- Raises:
ValidationError– if any input argument is not compliant.ValueError– if the gaussian quadrature fails to converge in the Tauchen-Hussey approximation.
- Return Type:
- birth_death(p, q, states=None)[source]
The method generates a birth-death Markov chain of given size and from given probabilities.
- Parameters:
- Raises:
ValidationError– if any input argument is not compliant.- Return Type:
- dirichlet_process(size, diffusion_factor, states=None, diagonal_bias_factor=None, shift_concentration=False, seed=None)[source]
The method generates a Markov chain of given size using a parametrized Dirichlet process.
- Parameters:
size (
int) – the size of the Markov chain.diffusion_factor (
int) – the diffusion factor of the Dirichlet process.states (
Optional[List[str]]) – the name of each state (if omitted, an increasing sequence of integers starting at 1).diagonal_bias_factor (
Optional[float]) – the bias factor applied to the diagonal of the transition matrix (if omitted, no inside-state stability is enforced).shift_concentration (
bool) – a boolean indicating whether to shift the concentration of the Dirichlet process to the rightmost states.seed (
Optional[int]) – a seed to be used as RNG initializer for reproducibility purposes.
- Raises:
ValidationError– if any input argument is not compliant.- Return Type:
- fit_function(quadrature_type, possible_states, f, quadrature_interval=None)[source]
The method fits a Markov chain using the given transition function and the given quadrature type for the computation of nodes and weights.
Notes:The transition function takes the four input arguments below and returns a numeric value:
x_index an integer value representing the index of the i-th quadrature node;
x_value a float value representing the value of the i-th quadrature node;
y_index an integer value representing the index of the j-th quadrature node;
y_value a float value representing the value of the j-th quadrature node.
- Parameters:
quadrature_type (
str)gauss-chebyshev for the Gauss-Chebyshev quadrature;
gauss-legendre for the Gauss-Legendre quadrature;
niederreiter for the Niederreiter equidistributed sequence;
newton-cotes for the Newton-Cotes quadrature;
simpson-rule for the Simpson rule;
trapezoid-rule for the Trapezoid rule.
possible_states (
List[str]) – the possible states of the process.f (
Callable[[int,float,int,float],float]) – the transition function of the process.quadrature_interval (
Optional[Tuple[Union[float,int],Union[float,int]]]) – the quadrature interval to use for the computation of nodes and weights (if omitted, the interval [0, 1] is used).
- Raises:
ValidationError– if any input argument is not compliant.ValueError– if the Gauss-Legendre quadrature fails to converge.
- Return Type:
- fit_sequence(fitting_type, possible_states, sequence, fitting_param=None)[source]
The method fits a Markov chain from an observed sequence of states using the specified fitting approach.
- Parameters:
fitting_type (
str)map for the maximum a posteriori fitting;
mle for the maximum likelihood fitting.
possible_states (
List[str]) – the possible states of the process.sequence (
Union[List[int],List[str]]) – the observed sequence of states.fitting_param (
Any) –- In the maximum a posteriori fitting, the matrix for the a priori distribution (if omitted, a default value of 1 is assigned to each matrix element).- In the maximum likelihood fitting, a boolean indicating whether to apply a Laplace smoothing to compensate for the unseen transition combinations (if omitted, the value is set to True).
- Raises:
ValidationError– if any input argument is not compliant.- Return Type:
- from_dictionary(d)[source]
The method generates a Markov chain from the given dictionary, whose keys represent state pairs and whose values represent transition probabilities.
- Parameters:
d (
Dict[Tuple[str,str],Union[float,int]]) – the dictionary to transform into the transition matrix.- Raises:
ValidationError– if any input argument is not compliant.ValueError– if the transition matrix defined by the dictionary is not valid.
- Return Type:
- from_file(file_path)[source]
The method reads a Markov chain from the given file.
Only csv, json, txt and xml files are supported; data format is inferred from the file extension.In csv files, data must be structured as follows:Delimiter: comma
Quoting: minimal
Quote Character: double quote
Header Row: state names
Data Rows: probabilities
In json files, data must be structured as an array of objects with the following properties:state_from (string)
state_to (string)
probability (float or int)
In txt files, every line of the file must have the following format:<state_from> <state_to> <probability>
In xml files, the structure must be defined as follows:Root Element: MarkovChain
Child Elements: Item, with attributes:
state_from (string)
state_to (string)
probability (float or int)
- Parameters:
file_path (
Union[str,Path]) – the location of the file that defines the Markov chain.- Raises:
FileNotFoundError– if the file does not exist.OSError– if the file cannot be read or is empty.ValidationError– if any input argument is not compliant.ValueError– if the file contains invalid data.
- Return Type:
- from_graph(graph)[source]
The method generates a Markov chain from the given directed graph, whose transition matrix is obtained through the normalization of edge weights.
- Raises:
ValidationError– if any input argument is not compliant.- Return Type:
- from_matrix(m, states=None)[source]
The method generates a Markov chain whose transition matrix is obtained through the normalization of the given matrix.
- Parameters:
- Raises:
ValidationError– if any input argument is not compliant.- Return Type:
- gamblers_ruin(size, w, states=None)[source]
The method generates a gambler’s ruin Markov chain of given size and win probability.
- Parameters:
- Raises:
ValidationError– if any input argument is not compliant.- Return Type:
- identity(size, states=None)[source]
The method generates a Markov chain of given size based on an identity transition matrix.
- Parameters:
- Raises:
ValidationError– if any input argument is not compliant.- Return Type:
- population_genetics_model(model, n, s=0.0, u=1e-09, v=1e-09, states=None)[source]
The method generates a Markov chain based on the specified population genetics model.
- Parameters:
model (
str)moran for the Moran model;
wright-fisher for the Wright-Fisher model.
n (
int) – the number of individuals.s (
float) – the selection intensity.u (
float) – the backward mutation rate.v (
float) – the forward mutation rate.states (
Optional[List[str]]) – the name of each state (if omitted, an increasing sequence of integers starting at 1).
- Raises:
ValidationError– if any input argument is not compliant.- Return Type:
- random(size, states=None, zeros=0, mask=None, seed=None)[source]
The method generates a Markov chain of given size with random transition probabilities.
Notes:In the mask parameter, undefined transition probabilities are represented by NaN values.
- Parameters:
size (
int) – the size of the Markov chain.states (
Optional[List[str]]) – the name of each state (if omitted, an increasing sequence of integers starting at 1).zeros (
int) – the number of null transition probabilities.mask (
Optional[Union[ndarray,spmatrix]]) – a matrix representing locations and values of fixed transition probabilities.seed (
Optional[int]) – a seed to be used as RNG initializer for reproducibility purposes.
- Raises:
ValidationError– if any input argument is not compliant.- Return Type:
- random_distribution(size, f, states=None, seed=None, **kwargs)[source]
The method generates a Markov chain of given size using draws from a Numpy random distribution function.
Notes:NaN values are replaced with zeros
Infinite values are replaced with finite numbers.
Negative values are clipped to zero.
In transition matrix rows with no positive values the states are assumed to be uniformly distributed.
In light of the above points, random distribution functions must be carefully parametrized.
- Parameters:
size (
int) – the size of the Markov chain.f (
Union[Callable,str]) – the Numpy random distribution function or the name of the Numpy random distribution function.states (
Optional[List[str]]) – the name of each state (if omitted, an increasing sequence of integers starting at 1).seed (
Optional[int]) – a seed to be used as RNG initializer for reproducibility purposes.**kwargs – additional arguments passed to the random distribution function.
- Raises:
ValidationError– if any input argument is not compliant.- Return Type:
- urn_model(model, n, states=None)[source]
The method generates a Markov chain of size 2N + 1 based on the specified urn model.
- Parameters:
- Raises:
ValidationError– if any input argument is not compliant.- Return Type:
Assessment Functions
- pydtmc.assess_first_order(possible_states, sequence, significance=0.05)[source]
The function verifies whether the given sequence can be associated to a first-order Markov process.
- Parameters:
- Raises:
ValidationError– if any input argument is not compliant.- Return Type:
- pydtmc.assess_homogeneity(possible_states, sequences, significance=0.05)[source]
The function verifies whether the given sequences belong to the same Markov process.
- Parameters:
- Raises:
ValidationError– if any input argument is not compliant.- Return Type:
- pydtmc.assess_markov_property(possible_states, sequence, significance=0.05)[source]
The function verifies whether the given sequence holds the Markov property.
- Parameters:
- Raises:
ValidationError– if any input argument is not compliant.- Return Type:
- pydtmc.assess_stationarity(possible_states, sequence, blocks=1, significance=0.05)[source]
The function verifies whether the given sequence is stationary.
- Parameters:
possible_states (
List[str]) – the possible states of the process.sequence (
Union[List[int],List[str]]) – the observed sequence of states.blocks (
int) – the number of blocks in which the sequence is divided.significance (
float) – the p-value significance threshold below which to accept the alternative hypothesis.
- Raises:
ValidationError– if any input argument is not compliant.- Return Type:
- pydtmc.assess_theoretical_compatibility(mc, sequence, significance=0.05)[source]
The function verifies whether the given empirical sequence is statistically compatible with the given theoretical Markov process.
- Parameters:
- Raises:
ValidationError– if any input argument is not compliant.- Return Type:
Plotting Functions
- pydtmc.plot_comparison(models, underlying_matrices='transition', names=None, dpi=100)[source]
The function plots the underlying matrices of the given models in the form of a heatmap.
Notes:If Matplotlib is in interactive mode, the plot is immediately displayed and the function does not return the plot handles.
- Parameters:
models (
List[Union[HiddenMarkovModel,MarkovChain]]) – the models.underlying_matrices (
str)emission for comparing the emission matrices;
transition for comparing the transition matrices.
names (
Optional[List[str]]) – the name of each model subplot (if omitted, a standard name is given to each subplot).dpi (
int) – the resolution of the plot expressed in dots per inch.
- Raises:
ValidationError– if any input argument is not compliant.- Return Type:
- pydtmc.plot_eigenvalues(model, dpi=100)[source]
The function plots the eigenvalues of the transition matrix of the given model on the complex plane.
Notes:If Matplotlib is in interactive mode, the plot is immediately displayed and the function does not return the plot handles.
- Parameters:
model (
Union[HiddenMarkovModel,MarkovChain]) – the model.dpi (
int) – the resolution of the plot expressed in dots per inch.
- Raises:
ValidationError– if any input argument is not compliant.- Return Type:
- pydtmc.plot_flow(model, steps, interval, initial_status=None, palette='viridis', dpi=100)[source]
The function produces an alluvial diagram of the given model.
Notes:If Matplotlib is in interactive mode, the plot is immediately displayed and the function does not return the plot handles.
- Parameters:
model (
Union[HiddenMarkovModel,MarkovChain]) – the model.steps (
int) – the number of steps.interval (
int) – the interval between each step.initial_status (
Optional[Union[int,str,ndarray,spmatrix]]) – the initial state or the initial distribution of the states (if omitted, the states are assumed to be uniformly distributed).palette (
str) – the palette of the plot.dpi (
int) – the resolution of the plot expressed in dots per inch.
- Raises:
ValidationError– if any input argument is not compliant.- Return Type:
- pydtmc.plot_graph(model, nodes_color=True, nodes_shape=True, edges_label=True, force_standard=False, dpi=100)[source]
The function plots the directed graph of the given model.
Notes:If Matplotlib is in interactive mode, the plot is immediately displayed and the function does not return the plot handles.
Graphviz and pydot are not required, but they provide access to extended mode with improved rendering and additional features.
The rendering, especially in standard mode or for big graphs, is not granted to be high-quality.
For Markov chains, the color of nodes is based on communicating classes; for hidden Markov models, every state node has a different color and symbol nodes are gray.
For Markov chains, recurrent nodes have an elliptical shape and transient nodes have a rectangular shape; for hidden Markov models, state nodes have an elliptical shape and symbol nodes have a hexagonal shape.
- Parameters:
model (
Union[HiddenMarkovModel,MarkovChain]) – the model.nodes_color (
bool) – a boolean indicating whether to use a different color for every type of node.nodes_shape (
bool) – a boolean indicating whether to use a different shape for every type of node.edges_label (
bool) – a boolean indicating whether to display the probability of every edge as text.force_standard (
bool) – a boolean indicating whether to use standard mode even if extended mode is available.dpi (
int) – the resolution of the plot expressed in dots per inch.
- Raises:
ValidationError– if any input argument is not compliant.- Return Type:
- pydtmc.plot_redistributions(model, redistributions, initial_status=None, plot_type='projection', dpi=100)[source]
The function plots a redistribution of states on the given model.
Notes:If Matplotlib is in interactive mode, the plot is immediately displayed and the function does not return the plot handles.
- Parameters:
model (
Union[HiddenMarkovModel,MarkovChain]) – the model to be converted into a graph.redistributions (
int) – the number of redistributions to perform.initial_status (
Optional[Union[int,str,ndarray,spmatrix]]) – the initial state or the initial distribution of the states (if omitted, the states are assumed to be uniformly distributed).plot_type (
str)heatmap for displaying a heatmap plot;
projection for displaying a projection plot.
dpi (
int) – the resolution of the plot expressed in dots per inch.
- Raises:
ValidationError– if any input argument is not compliant.ValueError– if the “distributions” parameter represents a sequence of redistributions and the “initial_status” parameter does not match its first element.
- Return Type:
- pydtmc.plot_sequence(model, steps, initial_state=None, plot_type='histogram', seed=None, dpi=100)[source]
The function plots a random walk on the given model.
Notes:If Matplotlib is in interactive mode, the plot is immediately displayed and the function does not return the plot handles.
- Parameters:
model (
Union[HiddenMarkovModel,MarkovChain]) – the model.steps (
int) – the number of steps.initial_state (
Optional[Union[int,str]]) – the initial state of the random walk (if omitted, it is chosen uniformly at random).plot_type (
str)heatmap for displaying heatmap-like plots;
histogram for displaying a histogram plots;
matrix for displaying matrix plots.
seed (
Optional[int]) – a seed to be used as RNG initializer for reproducibility purposes.dpi (
int) – the resolution of the plot expressed in dots per inch.
- Raises:
ValidationError– if any input argument is not compliant.- Return Type: