PyDTMC 8.3.0__tar.gz → 8.4.0__tar.gz

PyDTMC-8.4.0/MANIFEST.in

@@ -0,0 +1,8 @@
+# Inclusions
+graft data docs tests
+include README.md LICENSE.md requirements.txt setup.py
+
+# Exclusions
+global-exclude *.dll *.py[cdo] *.so .env .git* __pycache__ *~
+prune .git .github .idea dist docs/build images
+exclude .readthedocs.yaml CODE_OF_CONDUCT.md CONTRIBUTING.md

{PyDTMC-8.3.0 → PyDTMC-8.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: PyDTMC
-Version: 8.3.0
+Version: 8.4.0
 Summary: A full-featured and lightweight library for discrete-time Markov chains analysis.
 Home-page: https://github.com/TommasoBelluzzo/PyDTMC
 Author: Tommaso Belluzzo
@@ -149,6 +149,7 @@ DISCRETE-TIME MARKOV CHAIN
   > APERIODIC:   YES
   > IRREDUCIBLE: NO
  ABSORBING:      YES
+ MONOTONE:       NO
  REGULAR:        NO
  REVERSIBLE:     YES
  SYMMETRIC:      NO

{PyDTMC-8.3.0 → PyDTMC-8.4.0}/PyDTMC.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: PyDTMC
-Version: 8.3.0
+Version: 8.4.0
 Summary: A full-featured and lightweight library for discrete-time Markov chains analysis.
 Home-page: https://github.com/TommasoBelluzzo/PyDTMC
 Author: Tommaso Belluzzo
@@ -149,6 +149,7 @@ DISCRETE-TIME MARKOV CHAIN
   > APERIODIC:   YES
   > IRREDUCIBLE: NO
  ABSORBING:      YES
+ MONOTONE:       NO
  REGULAR:        NO
  REVERSIBLE:     YES
  SYMMETRIC:      NO

PyDTMC-8.4.0/PyDTMC.egg-info/SOURCES.txt

@@ -0,0 +1,42 @@
+LICENSE.md
+MANIFEST.in
+README.md
+requirements.txt
+setup.cfg
+setup.py
+PyDTMC.egg-info/PKG-INFO
+PyDTMC.egg-info/SOURCES.txt
+PyDTMC.egg-info/dependency_links.txt
+PyDTMC.egg-info/requires.txt
+PyDTMC.egg-info/top_level.txt
+pydtmc/__init__.py
+pydtmc/assessments.py
+pydtmc/base_classes.py
+pydtmc/computations.py
+pydtmc/custom_types.py
+pydtmc/decorators.py
+pydtmc/exceptions.py
+pydtmc/files_io.py
+pydtmc/fitting.py
+pydtmc/generators.py
+pydtmc/hidden_markov_model.py
+pydtmc/markov_chain.py
+pydtmc/measures.py
+pydtmc/plotting.py
+pydtmc/simulations.py
+pydtmc/utilities.py
+pydtmc/validation.py
+tests/test_aliases.py
+tests/test_assessments.py
+tests/test_classification.py
+tests/test_conversions.py
+tests/test_fitting.py
+tests/test_generators_instance.py
+tests/test_generators_static.py
+tests/test_hmm.py
+tests/test_measures.py
+tests/test_plotting.py
+tests/test_properties.py
+tests/test_simulations.py
+tests/test_utilities.py
+tests/test_validation.py

{PyDTMC-8.3.0 → PyDTMC-8.4.0}/README.md

@@ -108,6 +108,7 @@ DISCRETE-TIME MARKOV CHAIN
   > APERIODIC:   YES
   > IRREDUCIBLE: NO
  ABSORBING:      YES
+ MONOTONE:       NO
  REGULAR:        NO
  REVERSIBLE:     YES
  SYMMETRIC:      NO

{PyDTMC-8.3.0 → PyDTMC-8.4.0}/pydtmc/__init__.py

@@ -1,14 +1,14 @@
 # -*- coding: utf-8 -*-
 
 __title__ = 'PyDTMC'
-__version__ = '8.3.0'
+__version__ = '8.4.0'
 __author__ = 'Tommaso Belluzzo'
 
 __all__ = [
     'ValidationError',
     'HiddenMarkovModel', 'MarkovChain',
     'assess_first_order', 'assess_homogeneity', 'assess_markov_property', 'assess_stationarity', 'assess_theoretical_compatibility',
-    'plot_comparison', 'plot_eigenvalues', 'plot_graph', 'plot_redistributions', 'plot_sequence', 'plot_trellis'
+    'plot_comparison', 'plot_eigenvalues', 'plot_flow', 'plot_graph', 'plot_redistributions', 'plot_sequence', 'plot_trellis'
 ]
 
 from pydtmc.exceptions import (
@@ -34,6 +34,7 @@ from pydtmc.assessments import (
 from pydtmc.plotting import (
     plot_comparison,
     plot_eigenvalues,
+    plot_flow,
     plot_graph,
     plot_redistributions,
     plot_sequence,

{PyDTMC-8.3.0 → PyDTMC-8.4.0}/pydtmc/custom_types.py

@@ -1,5 +1,7 @@
 # -*- coding: utf-8 -*-
 
+from __future__ import annotations
+
 __all__ = [
     # Base Types
     'tany',
@@ -157,11 +159,11 @@ tstack = _tp.List[_ins.FrameInfo]
 ostack = _tp.Optional[tstack]
 
 # noinspection PyTypeHints
-thmm = _tp.TypeVar('HiddenMarkovModel')
+thmm = _tp.ForwardRef('HiddenMarkovModel')
 ohmm = _tp.Optional[thmm]
 
 # noinspection PyTypeHints
-tmc = _tp.TypeVar('MarkovChain')
+tmc = _tp.ForwardRef('MarkovChain')
 omc = _tp.Optional[tmc]
 
 tmodel = _tp.Union[thmm, tmc]

{PyDTMC-8.3.0 → PyDTMC-8.4.0}/pydtmc/generators.py

@@ -15,6 +15,7 @@ __all__ = [
     'mc_gamblers_ruin',
     'mc_lazy',
     'mc_lump',
+    'mc_population_genetics_model',
     'mc_random',
     'mc_sub',
     'mc_urn_model'
@@ -883,6 +884,52 @@ def mc_lump(p: _tarray, states: _tlist_str, partitions: _tlists_int) -> _tmc_gen
     return p_lump, state_names, None
 
 
+def mc_population_genetics_model(model: str, n: int, s: float, u: float, v: float) -> _tmc_generation:
+
+    size = n + 1
+
+    p = _np.zeros((size, size), dtype=float)
+    p[0, 0] = 1.0
+    p[n, n] = 1.0
+
+    ui = 1.0 - u
+    vi = 1.0 - v
+
+    if model == 'moran':
+
+        r = 1.0 - s
+
+        for i in range(1, n):
+            nmi = n - i
+            ri = r * i
+
+            pm1 = (i / n) * (((ri * v) + (nmi * vi)) / (ri + nmi))
+            pp1 = (nmi / n) * (((ri * ui) + (nmi * v)) / (ri + nmi))
+
+            p[i, i - 1] = pm1
+            p[i, i] = 1.0 - pm1 - pp1
+            p[i, i + 1] = pp1
+
+    else:
+
+        q = _np.arange(0, size)
+
+        for i in range(1, n):
+
+            k = i / n
+
+            pm = (k * ui) + ((1.0 - k) * v)
+            ps = min((pm * (1.0 + s)) / ((pm * (1.0 + s)) - pm + 1.0), 1.0)
+
+            p[i, :] = _np.exp(_sps.binom.logpmf(q, n, ps))
+
+    p /= _np.sum(p, axis=1, keepdims=True)
+
+    state_names = [f'{i:d}' for i in range(1, size + 1)]
+
+    return p, state_names, None
+
+
 # noinspection DuplicatedCode
 def mc_random(rng: _trand, size: int, zeros: int, mask: _tarray) -> _tmc_generation:
 
@@ -968,7 +1015,7 @@ def mc_sub(p: _tarray, states: _tlist_str, adjacency_matrix: _tarray, sub_states
     return p, state_names, None
 
 
-def mc_urn_model(n: int, model: str) -> _tmc_generation:
+def mc_urn_model(model: str, n: int) -> _tmc_generation:
 
     dn = n * 2
     size = dn + 1

{PyDTMC-8.3.0 → PyDTMC-8.4.0}/pydtmc/hidden_markov_model.py

@@ -542,7 +542,8 @@ class HiddenMarkovModel(_Model):
     def to_matrices(self) -> _tpair_array:
 
         """
-        | The method returns a tuple of two items representing the underlying matrices of the hidden Markov model.
+        The method returns a tuple of two items representing the underlying matrices of the hidden Markov model.
+
         | The first item is the transition matrix and the second item is the emission matrix.
         """
 

{PyDTMC-8.3.0 → PyDTMC-8.4.0}/pydtmc/markov_chain.py

@@ -117,6 +117,7 @@ from .generators import (
     mc_gamblers_ruin as _gamblers_ruin,
     mc_lazy as _lazy,
     mc_lump as _lump,
+    mc_population_genetics_model as _population_genetics_model,
     mc_random as _random,
     mc_sub as _sub,
     mc_urn_model as _urn_model
@@ -174,6 +175,7 @@ from .validation import (
     validate_labels_current as _validate_labels_current,
     validate_labels_input as _validate_labels_input,
     validate_mask as _validate_mask,
+    validate_markov_chain as _validate_markov_chain,
     validate_matrix as _validate_matrix,
     validate_partitions as _validate_partitions,
     validate_random_distribution as _validate_random_distribution,
@@ -257,6 +259,7 @@ class MarkovChain(_Model):
         lines.append(f'  > APERIODIC:   {("YES" if self.is_aperiodic else "NO (" + str(self.period) + ")")}')
         lines.append(f'  > IRREDUCIBLE: {("YES" if self.is_irreducible else "NO")}')
         lines.append(f' ABSORBING:      {("YES" if self.is_absorbing else "NO")}')
+        lines.append(f' MONOTONE:       {("YES" if self.is_stochastically_monotone else "NO")}')
         lines.append(f' REGULAR:        {("YES" if self.is_regular else "NO")}')
         lines.append(f' REVERSIBLE:     {("YES" if self.is_reversible else "NO")}')
         lines.append(f' SYMMETRIC:      {("YES" if self.is_symmetric else "NO")}')
@@ -690,6 +693,31 @@ class MarkovChain(_Model):
 
         return result
 
+    @_cached_property
+    @_object_mark(aliases=['is_monotone'])
+    def is_stochastically_monotone(self) -> bool:
+
+        """
+        A property indicating whether the Markov chain is stochastically monotone.
+        """
+
+        result = True
+
+        for m in range(1, self.__size):
+
+            sm = _np.sum(self.__p[:, m:], axis=1)
+
+            for k, l in zip(range(self.__size - 1), range(1, self.__size)):
+
+                sk = sm[k]
+                sl = sm[l]
+
+                if sl < sk:
+                    result = False
+                    break
+
+        return result
+
     @_cached_property
     def is_symmetric(self) -> bool:
 
@@ -1547,6 +1575,36 @@ class MarkovChain(_Model):
 
         return self.__cache['mrt']
 
+    @_object_mark(instance_generator=True)
+    def merge_with(self, other: _tmc, gamma: float) -> _tmc:
+
+        """
+        The method returns a Markov chain whose transition matrix is defined below.
+
+        | :math:`p_{new} = (1 - \gamma) p_{current} + \gamma p_{other}`
+
+        :param other: the other Markov chain to be merged.
+        :param gamma: the merger blending factor.
+        :raises ValidationError: if any input argument is not compliant.
+        """
+
+        try:
+
+            other = _validate_markov_chain(other, self.__size)
+            gamma = _validate_float(gamma, lower_limit=(0.0, True), upper_limit=(1.0, True))
+
+        except Exception as ex:  # pragma: no cover
+            raise _create_validation_error(ex, _ins.trace()) from None
+
+        p_current = self.__p
+        p_other = other.p
+
+        p = ((1.0 - gamma) * p_current) + (gamma * p_other)
+        states = _create_labels(self.__size, 'M')
+        mc = MarkovChain(p, states)
+
+        return mc
+
     @_object_mark(aliases=['mt'])
     def mixing_time(self, initial_distribution: _onumeric = None, jump: int = 1, cutoff_type: str = 'natural') -> _oint:
 
@@ -2050,7 +2108,7 @@ class MarkovChain(_Model):
             sigma = _validate_float(sigma, lower_limit=(0.0, True))
             rho = _validate_float(rho, lower_limit=(-1.0, False), upper_limit=(1.0, False))
 
-            if states is not None:
+            if states is not None:  # pragma: no cover
                 states = _validate_labels_input(states, size)
 
             if approximation_type == 'tauchen':
@@ -2091,7 +2149,7 @@ class MarkovChain(_Model):
             p = _validate_vector(p, 'creation', False)
             q = _validate_vector(q, 'annihilation', False)
 
-            if states is not None:
+            if states is not None:  # pragma: no cover
                 states = _validate_labels_input(states, {p.shape[0], q.shape[0]}.pop())
 
         except Exception as ex:  # pragma: no cover
@@ -2136,7 +2194,7 @@ class MarkovChain(_Model):
             diagonal_bias_factor = None if diagonal_bias_factor is None else _validate_float(diagonal_bias_factor, lower_limit=(0.0, True))
             shift_concentration = _validate_boolean(shift_concentration)
 
-            if states is not None:
+            if states is not None:  # pragma: no cover
                 states = _validate_labels_input(states, size)
 
         except Exception as ex:  # pragma: no cover
@@ -2463,7 +2521,7 @@ class MarkovChain(_Model):
             size = _validate_integer(size, lower_limit=(3, False))
             w = _validate_float(w, lower_limit=(0.0, True), upper_limit=(1.0, True))
 
-            if states is not None:
+            if states is not None:  # pragma: no cover
                 states = _validate_labels_input(states, size)
 
         except Exception as ex:  # pragma: no cover
@@ -2503,6 +2561,50 @@ class MarkovChain(_Model):
 
         return mc
 
+    @staticmethod
+    @_object_mark(instance_generator=True)
+    def population_genetics_model(model: str, n: int, s: float = 0.0, u: float = 1.0e-9, v: float = 1.0e-9, states: _olist_str = None) -> _tmc:
+
+        """
+        The method generates a Markov chain based on the specified population genetics model.
+
+        :param model:
+         - **moran** for the Moran model;
+         - **wright-fisher** for the Wright-Fisher model.
+        :param n: the number of individuals.
+        :param s: the selection intensity.
+        :param u: the backward mutation rate.
+        :param v: the forward mutation rate.
+        :param states: the name of each state (*if omitted, an increasing sequence of integers starting at 1*).
+        :raises ValidationError: if any input argument is not compliant.
+        """
+
+        try:
+
+            model = _validate_enumerator(model, ['moran', 'wright-fisher'])
+            n = _validate_integer(n, lower_limit=(2, False), upper_limit=(500, False))
+            s = _validate_float(s, lower_limit=(-1.0, False))
+            u = _validate_float(u, lower_limit=(0.0, False), upper_limit=(1.0, False))
+            v = _validate_float(v, lower_limit=(0.0, False), upper_limit=(1.0, False))
+
+            if states is not None:  # pragma: no cover
+                states = _validate_labels_input(states, n + 1)
+
+        except Exception as ex:  # pragma: no cover
+            raise _create_validation_error(ex, _ins.trace()) from None
+
+        if model == 'wright-fisher' and (4.0 * n * max(u, v)) > 1.0:
+            raise _ValidationError('The highest mutation rate specified is too high for the Wright-Fisher model.')
+
+        p, states_out, _ = _population_genetics_model(model, n, s, u, v)
+
+        if states is None:
+            states = states_out
+
+        mc = MarkovChain(p, states)
+
+        return mc
+
     # noinspection DuplicatedCode
     @staticmethod
     @_object_mark(instance_generator=True, random_output=True)
@@ -2528,7 +2630,7 @@ class MarkovChain(_Model):
             rng = _create_rng(seed)
             size = _validate_integer(size, lower_limit=(2, False))
 
-            if states is not None:
+            if states is not None:  # pragma: no cover
                 states = _validate_labels_input(states, size)
 
             zeros = _validate_integer(zeros, lower_limit=(0, False))
@@ -2597,31 +2699,31 @@ class MarkovChain(_Model):
 
     @staticmethod
     @_object_mark(instance_generator=True)
-    def urn_model(n: int, model: str, states: _olist_str = None) -> _tmc:
+    def urn_model(model: str, n: int, states: _olist_str = None) -> _tmc:
 
         """
         The method generates a Markov chain of size **2N + 1** based on the specified urn model.
 
-        :param n: the number of elements in each urn.
         :param model:
          - **bernoulli-laplace** for the Bernoulli-Laplace urn model;
          - **ehrenfest** for the Ehrenfest urn model.
+        :param n: the number of elements in each urn.
         :param states: the name of each state (*if omitted, an increasing sequence of integers starting at 1*).
         :raises ValidationError: if any input argument is not compliant.
         """
 
         try:
 
-            n = _validate_integer(n, lower_limit=(1, False))
             model = _validate_enumerator(model, ['bernoulli-laplace', 'ehrenfest'])
+            n = _validate_integer(n, lower_limit=(1, False))
 
-            if states is not None:
+            if states is not None:  # pragma: no cover
                 states = _validate_labels_input(states, (2 * n) + 1)
 
         except Exception as ex:  # pragma: no cover
             raise _create_validation_error(ex, _ins.trace()) from None
 
-        p, states_out, _ = _urn_model(n, model)
+        p, states_out, _ = _urn_model(model, n)
 
         if states is None:
             states = states_out