Static Methods
- class pydtmc.MarkovChain[source]
- 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: