python-hiddenmarkov 0.1.3__tar.gz → 0.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (24) hide show
  1. {python-hiddenmarkov-0.1.3 → python_hiddenmarkov-0.3.0}/PKG-INFO +15 -11
  2. {python-hiddenmarkov-0.1.3 → python_hiddenmarkov-0.3.0}/README.md +5 -3
  3. {python-hiddenmarkov-0.1.3 → python_hiddenmarkov-0.3.0}/hiddenmarkov/__init__.py +238 -122
  4. python_hiddenmarkov-0.3.0/hiddenmarkov/_hmm.c +33835 -0
  5. python_hiddenmarkov-0.3.0/hiddenmarkov/_hmm.pyi +10 -0
  6. python_hiddenmarkov-0.3.0/hiddenmarkov/_hmm.pyx +90 -0
  7. python_hiddenmarkov-0.3.0/hiddenmarkov/py.typed +0 -0
  8. python_hiddenmarkov-0.3.0/hiddenmarkov/utils.py +55 -0
  9. python_hiddenmarkov-0.3.0/pyproject.toml +46 -0
  10. {python-hiddenmarkov-0.1.3 → python_hiddenmarkov-0.3.0}/python_hiddenmarkov.egg-info/PKG-INFO +15 -11
  11. {python-hiddenmarkov-0.1.3 → python_hiddenmarkov-0.3.0}/python_hiddenmarkov.egg-info/SOURCES.txt +10 -1
  12. python_hiddenmarkov-0.3.0/python_hiddenmarkov.egg-info/requires.txt +2 -0
  13. {python-hiddenmarkov-0.1.3 → python_hiddenmarkov-0.3.0}/python_hiddenmarkov.egg-info/top_level.txt +1 -0
  14. python_hiddenmarkov-0.3.0/setup.py +85 -0
  15. python_hiddenmarkov-0.3.0/tests/test_algorithms.py +313 -0
  16. python_hiddenmarkov-0.3.0/tests/test_forward_optimized.py +179 -0
  17. python_hiddenmarkov-0.3.0/tests/test_models.py +252 -0
  18. python_hiddenmarkov-0.3.0/tests/test_utils.py +66 -0
  19. python-hiddenmarkov-0.1.3/hiddenmarkov/utils.py +0 -57
  20. python-hiddenmarkov-0.1.3/python_hiddenmarkov.egg-info/requires.txt +0 -1
  21. python-hiddenmarkov-0.1.3/setup.py +0 -74
  22. {python-hiddenmarkov-0.1.3 → python_hiddenmarkov-0.3.0}/LICENSE +0 -0
  23. {python-hiddenmarkov-0.1.3 → python_hiddenmarkov-0.3.0}/python_hiddenmarkov.egg-info/dependency_links.txt +0 -0
  24. {python-hiddenmarkov-0.1.3 → python_hiddenmarkov-0.3.0}/setup.cfg +0 -0
@@ -1,25 +1,29 @@
1
- Metadata-Version: 2.1
1
+ Metadata-Version: 2.4
2
2
  Name: python-hiddenmarkov
3
- Version: 0.1.3
3
+ Version: 0.3.0
4
4
  Summary: A simple Python package for Hidden Markov Models
5
- Home-page: https://github.com/neosatrapahereje/hiddenmarkov
6
- Author: Carlos Cancino-Chacón, Silvan Peter
7
- Author-email: carloscancinochacon@gmail.com
5
+ Author: Silvan Peter
6
+ Author-email: Carlos Cancino-Chacón <carloscancinochacon@gmail.com>
8
7
  License: MIT
9
- Keywords: hmm hidden_Markov_models
8
+ Project-URL: Homepage, https://github.com/CarlosCancino-Chacon/hiddenmarkov
9
+ Keywords: hmm,hidden_markov_models
10
10
  Classifier: License :: OSI Approved :: MIT License
11
11
  Classifier: Programming Language :: Python
12
12
  Classifier: Programming Language :: Python :: 3
13
13
  Classifier: Programming Language :: Python :: Implementation :: CPython
14
14
  Classifier: Programming Language :: Python :: Implementation :: PyPy
15
- Requires-Python: >=3.6
15
+ Requires-Python: >=3.10
16
16
  Description-Content-Type: text/markdown
17
17
  License-File: LICENSE
18
-
18
+ Requires-Dist: numpy>=1.24
19
+ Requires-Dist: scipy>=1.7
20
+ Dynamic: license-file
19
21
 
20
22
  # hiddenmarkov
21
23
 
22
- [![PyPI version](https://badge.fury.io/py/python-hiddenmarkov.svg)](https://badge.fury.io/py/python-hiddenmarkov)
24
+ [![PyPI](https://img.shields.io/pypi/v/python-hiddenmarkov)](https://pypi.org/project/python-hiddenmarkov/)
25
+ [![CI](https://github.com/CarlosCancino-Chacon/hiddenmarkov/actions/workflows/ci.yml/badge.svg)](https://github.com/CarlosCancino-Chacon/hiddenmarkov/actions/workflows/ci.yml)
26
+ [![codecov](https://codecov.io/gh/CarlosCancino-Chacon/hiddenmarkov/branch/main/graph/badge.svg)](https://codecov.io/gh/CarlosCancino-Chacon/hiddenmarkov)
23
27
 
24
28
  A simple Python library for Hidden Markov Models.
25
29
 
@@ -35,7 +39,7 @@ pip install python-hiddenmarkov
35
39
 
36
40
  Develop version
37
41
  ```bash
38
- git clone https://github.com/neosatrapahereje/hiddenmarkov.git
42
+ git clone https://github.com/CarlosCancino-Chacon/hiddenmarkov.git
39
43
  cd hiddenmarkov
40
44
  pip install -e .
41
45
  ```
@@ -77,4 +81,4 @@ print("Expected probability", 0.01512)
77
81
  ## Licence
78
82
 
79
83
  The code in this package is licensed under the MIT Licence. For details,
80
- please see the [LICENSE](https://github.com/neosatrapahereje/hiddenmarkov/blob/main/LICENSE) file.
84
+ please see the [LICENSE](https://github.com/CarlosCancino-Chacon/hiddenmarkov/blob/main/LICENSE) file.
@@ -1,6 +1,8 @@
1
1
  # hiddenmarkov
2
2
 
3
- [![PyPI version](https://badge.fury.io/py/python-hiddenmarkov.svg)](https://badge.fury.io/py/python-hiddenmarkov)
3
+ [![PyPI](https://img.shields.io/pypi/v/python-hiddenmarkov)](https://pypi.org/project/python-hiddenmarkov/)
4
+ [![CI](https://github.com/CarlosCancino-Chacon/hiddenmarkov/actions/workflows/ci.yml/badge.svg)](https://github.com/CarlosCancino-Chacon/hiddenmarkov/actions/workflows/ci.yml)
5
+ [![codecov](https://codecov.io/gh/CarlosCancino-Chacon/hiddenmarkov/branch/main/graph/badge.svg)](https://codecov.io/gh/CarlosCancino-Chacon/hiddenmarkov)
4
6
 
5
7
  A simple Python library for Hidden Markov Models.
6
8
 
@@ -16,7 +18,7 @@ pip install python-hiddenmarkov
16
18
 
17
19
  Develop version
18
20
  ```bash
19
- git clone https://github.com/neosatrapahereje/hiddenmarkov.git
21
+ git clone https://github.com/CarlosCancino-Chacon/hiddenmarkov.git
20
22
  cd hiddenmarkov
21
23
  pip install -e .
22
24
  ```
@@ -58,4 +60,4 @@ print("Expected probability", 0.01512)
58
60
  ## Licence
59
61
 
60
62
  The code in this package is licensed under the MIT Licence. For details,
61
- please see the [LICENSE](https://github.com/neosatrapahereje/hiddenmarkov/blob/main/LICENSE) file.
63
+ please see the [LICENSE](https://github.com/CarlosCancino-Chacon/hiddenmarkov/blob/main/LICENSE) file.
@@ -5,23 +5,35 @@ Hidden Markov Models
5
5
 
6
6
  This module contains case classes to define Hidden Markov Models.
7
7
  """
8
- import pkg_resources
9
- import warnings
8
+ from __future__ import annotations
9
+
10
10
  import numpy as np
11
+ from importlib.metadata import version, PackageNotFoundError
11
12
 
12
13
  from collections import defaultdict
13
- from typing import Any, Iterable, Optional, Tuple, ClassVar, List
14
+ from typing import Any, Callable, ClassVar, Iterable, List, Optional, Tuple
14
15
 
15
16
  from scipy.special import logsumexp
16
17
 
17
18
  from .utils import inverted_softmax, softmax
18
19
 
20
+ try:
21
+ from ._hmm import viterbi_loop as _viterbi_loop
22
+ _HAS_CYTHON = True
23
+ except ImportError: # pragma: no cover
24
+ _HAS_CYTHON = False
25
+
26
+ # Type alias for a single windowed probability model entry.
27
+ _ProbModelEntry = Tuple[Callable[..., Any], int]
19
28
 
20
29
  # define a version variable
21
- __version__ = pkg_resources.get_distribution("python-hiddenmarkov").version
30
+ try:
31
+ __version__ = version("python-hiddenmarkov")
32
+ except PackageNotFoundError: # pragma: no cover
33
+ __version__ = "unknown"
22
34
 
23
35
 
24
- class TransitionModel(object):
36
+ class TransitionModel:
25
37
  """
26
38
  Base class for implementing a Transition Model
27
39
  """
@@ -36,25 +48,25 @@ class TransitionModel(object):
36
48
  self,
37
49
  i: Optional[int] = None,
38
50
  j: Optional[int] = None,
39
- *args,
40
- **kwargs,
51
+ *args: Any,
52
+ **kwargs: Any,
41
53
  ) -> np.ndarray:
42
54
  raise NotImplementedError
43
55
 
44
56
 
45
- class ObservationModel(object):
57
+ class ObservationModel:
46
58
  """
47
59
  Base class for implementing an Observation Model
48
60
  """
49
61
 
50
62
  def __init__(self, use_log_probabilities: bool = True) -> None:
51
- self.use_log_probabilities = use_log_probabilities
63
+ self.use_log_probabilities: bool = use_log_probabilities
52
64
 
53
- def __call__(self, observation: Any, *args, **kwargs) -> np.ndarray:
65
+ def __call__(self, observation: Any, *args: Any, **kwargs: Any) -> np.ndarray:
54
66
  raise NotImplementedError()
55
67
 
56
68
 
57
- class HiddenMarkovModel(object):
69
+ class HiddenMarkovModel:
58
70
  """
59
71
  Hidden Markov Model
60
72
 
@@ -67,6 +79,16 @@ class HiddenMarkovModel(object):
67
79
  state_space: iterable (optional)
68
80
  Labels of the states (e.g., a list of strings containing
69
81
  the names of each state).
82
+ forward: {"optimized", "standard"}
83
+ The implementation of the forward algorithm step used by
84
+ :meth:`forward_algorithm_step`. ``"optimized"`` (default)
85
+ restricts the vector-matrix product to the states that currently
86
+ have non-zero probability and to the columns reachable from them
87
+ (see :func:`forward_algorithm_step_optimized`); it requires a
88
+ :class:`ConstantTransitionModel`, and for any other transition
89
+ model the standard implementation is used instead. ``"standard"``
90
+ uses :func:`forward_algorithm_step`. Both give numerically
91
+ equivalent results.
70
92
 
71
93
  Attributes
72
94
  ----------
@@ -83,8 +105,22 @@ class HiddenMarkovModel(object):
83
105
  observation_model: ObservationModel,
84
106
  transition_model: TransitionModel,
85
107
  state_space: Optional[Iterable] = None,
108
+ forward: str = "optimized",
86
109
  ) -> None:
87
110
  super().__init__()
111
+ if forward not in _FORWARD_ALGORITHMS:
112
+ raise ValueError(
113
+ "`forward` needs to be 'optimized' or 'standard' "
114
+ f"but is {forward!r}"
115
+ )
116
+ self.forward: str = forward
117
+ self._forward_step: Callable[..., np.ndarray] = _FORWARD_ALGORITHMS[forward]
118
+ if forward == "optimized" and not isinstance(
119
+ transition_model, ConstantTransitionModel
120
+ ):
121
+ # The optimization relies on the structure of a constant
122
+ # transition matrix; other models use the standard algorithm.
123
+ self._forward_step = forward_algorithm_step
88
124
  self.observation_model: ObservationModel = observation_model
89
125
  self.transition_model: TransitionModel = transition_model
90
126
  self.n_states: int = self.transition_model.n_states
@@ -163,7 +199,7 @@ class HiddenMarkovModel(object):
163
199
  current_state : int
164
200
  Index of the current hidden state.
165
201
  """
166
- self.forward_variable = forward_algorithm_step(
202
+ self.forward_variable = self._forward_step(
167
203
  observation_model=self.observation_model,
168
204
  transition_model=self.transition_model,
169
205
  observation=observation,
@@ -182,7 +218,7 @@ HMM = HiddenMarkovModel
182
218
 
183
219
  def viterbi_algorithm_naive(
184
220
  hmm: HiddenMarkovModel,
185
- observations: Iterable,
221
+ observations: Iterable[Any],
186
222
  log_probabilities: bool = True,
187
223
  ) -> Tuple[np.ndarray, float]:
188
224
  """
@@ -303,57 +339,47 @@ def viterbi_algorithm(
303
339
  log proability if `log_probabilities` is True)
304
340
  of the best sequence.
305
341
  """
306
- # Set whether to use log probabilities in transition and
307
- # observation models
308
342
  hmm.transition_model.use_log_probabilities = log_probabilities
309
343
  hmm.observation_model.use_log_probabilities = log_probabilities
310
- # Initialize matrix for holding the best sub-sequence
311
- # (log-)likelihood
312
- omega = np.zeros((len(observations), hmm.n_states))
313
- # Initialize matrix for holding the best sub-sequence idx
314
- omega_idx = np.zeros((len(observations), hmm.n_states), dtype=int)
315
-
316
- # Initiate for i == 0
317
- obs_prob = hmm.observation_model(observations[0])
318
-
319
- if log_probabilities:
320
- omega[0, :] = obs_prob + hmm.transition_model.init_probabilities
321
- else:
322
- omega[0, :] = obs_prob * hmm.transition_model.init_probabilities
323
-
324
- omega_idx[0, :] = 0
325
344
 
326
- # Viterbi recursion
327
- if log_probabilities:
328
- for i, obs in enumerate(observations[1:], 1):
329
- obs_prob = hmm.observation_model(obs)
330
- # omega slice is a row vector, transition_model is a matrix
331
- # of prob from state id_row to state id_column
332
- prob_of_jump_to_state = omega[i - 1, :] + hmm.transition_model().T
345
+ T = len(observations)
346
+ N = hmm.n_states
347
+ omega = np.zeros((T, N))
348
+ omega_idx = np.zeros((T, N), dtype=np.int64)
349
+
350
+ # Pre-compute all observation probabilities so the inner loop only
351
+ # operates on plain arrays (required for the Cython path).
352
+ obs_probs = np.ascontiguousarray(
353
+ [hmm.observation_model(obs) for obs in observations]
354
+ )
355
+ trans_mat = np.ascontiguousarray(hmm.transition_model())
356
+ init_probs = hmm.transition_model.init_probabilities
357
+
358
+ if _HAS_CYTHON:
359
+ _viterbi_loop(omega, omega_idx, obs_probs, trans_mat, init_probs,
360
+ log_probabilities)
361
+ elif log_probabilities:
362
+ omega[0, :] = obs_probs[0] + init_probs
363
+ for t in range(1, T):
364
+ prob_of_jump_to_state = omega[t - 1, :] + trans_mat.T
333
365
  state = np.argmax(prob_of_jump_to_state, axis=1)
334
- prob = prob_of_jump_to_state[np.arange(hmm.n_states), state]
335
- omega[i, :] = obs_prob + prob
336
- omega_idx[i, :] = state
337
-
366
+ prob = prob_of_jump_to_state[np.arange(N), state]
367
+ omega[t, :] = obs_probs[t] + prob
368
+ omega_idx[t, :] = state
338
369
  else:
339
- for i, obs in enumerate(observations[1:], 1):
340
- obs_prob = hmm.observation_model(obs)
341
- # omega slice is a row vector, transition_model is a matrix
342
- # of prob from state id_row to state id_column
343
- prob_of_jump_to_state = omega[i - 1, :] * hmm.transition_model().T
370
+ omega[0, :] = obs_probs[0] * init_probs
371
+ for t in range(1, T):
372
+ prob_of_jump_to_state = omega[t - 1, :] * trans_mat.T
344
373
  state = np.argmax(prob_of_jump_to_state, axis=1)
345
- prob = prob_of_jump_to_state[np.arange(hmm.n_states), state]
346
- omega[i, :] = obs_prob * prob
347
- omega_idx[i, :] = state
374
+ prob = prob_of_jump_to_state[np.arange(N), state]
375
+ omega[t, :] = obs_probs[t] * prob
376
+ omega_idx[t, :] = state
348
377
 
349
- # Get best path (backtracking!)
350
- # Get index of the best state
378
+ # Backtrack
351
379
  best_sequence_idx = omega[-1, :].argmax()
352
- # likelihood of the path
353
380
  path_likelihood = omega[-1, best_sequence_idx]
354
- # Get best path (backtracking!)
355
381
  seq = [best_sequence_idx]
356
- for s in range(len(observations) - 1):
382
+ for s in range(T - 1):
357
383
  best_sequence_idx = omega_idx[-(s + 1), best_sequence_idx]
358
384
  seq.append(best_sequence_idx)
359
385
  best_sequence = np.array(seq[::-1], dtype=int)
@@ -519,7 +545,11 @@ def forward_algorithm_step(
519
545
  if forward_variable is None:
520
546
  transition_prob: np.ndarray = transition_model.init_probabilities
521
547
  else:
522
- transition_prob: np.ndarray = np.dot(transition_model().T, forward_variable)
548
+ # The matrix multiply must happen in raw-probability space.
549
+ # When log_probabilities=True the stored forward_variable holds log
550
+ # probs, so we exponentiate before the dot product.
551
+ fv = np.exp(forward_variable) if log_probabilities else forward_variable
552
+ transition_prob: np.ndarray = np.dot(transition_model().T, fv)
523
553
  observation_prob: np.ndarray = observation_model(observation)
524
554
  if log_probabilities:
525
555
  forward_variable = observation_prob + np.log(transition_prob)
@@ -531,6 +561,80 @@ def forward_algorithm_step(
531
561
  return forward_variable
532
562
 
533
563
 
564
+ def forward_algorithm_step_optimized(
565
+ observation_model: ObservationModel,
566
+ transition_model: ConstantTransitionModel,
567
+ observation: Any,
568
+ forward_variable: Optional[np.ndarray] = None,
569
+ log_probabilities: bool = False,
570
+ ) -> np.ndarray:
571
+ """
572
+ Step of the forward algorithm exploiting sparsity.
573
+
574
+ Numerically equivalent to :func:`forward_algorithm_step` (up to
575
+ floating point summation order), but the product ``T.T @ fv`` is
576
+ restricted to the rows of ``T`` between the first and last state with
577
+ non-zero probability and to the columns that can be reached from them.
578
+ This is much cheaper when the forward variable is concentrated in a
579
+ small region of a large, banded (e.g., left-to-right) transition matrix.
580
+
581
+ Based on a proposal by Meisterschueler in
582
+ https://github.com/pymatchmaker/matchmaker/pull/75
583
+
584
+ Parameters
585
+ ----------
586
+ observation_model : ObservationModel
587
+ An observation model.
588
+ transition_model : ConstantTransitionModel
589
+ A constant transition model. Other transition models are not
590
+ supported (use :func:`forward_algorithm_step` instead).
591
+ observation : Any
592
+ An observation. The observation needs to be of the same
593
+ type as specified by the observation model.
594
+ forward_variable : np.ndarray
595
+ The forward variable of the HMM. If none is given, the
596
+ initial probabilities specified by the transition model
597
+ will be used.
598
+ log_probabilities : bool
599
+ If true, use log probabilities.
600
+
601
+ Returns
602
+ -------
603
+ forward_variable : np.ndarray
604
+ The updated forward variable.
605
+ """
606
+ transition_model.use_log_probabilities = False
607
+ observation_model.use_log_probabilities = log_probabilities
608
+ if forward_variable is None:
609
+ transition_prob: np.ndarray = transition_model.init_probabilities
610
+ else:
611
+ fv = np.exp(forward_variable) if log_probabilities else forward_variable
612
+ transition_prob = np.zeros_like(fv)
613
+ nonzero = np.flatnonzero(fv)
614
+ if nonzero.size:
615
+ lo, hi = nonzero[0], nonzero[-1] + 1
616
+ # Rows < hi have no non-zero entries beyond column `m - 1`.
617
+ m = transition_model.last_nonzero_columns[hi - 1] + 1
618
+ transition_prob[:m] = (
619
+ fv[lo:hi] @ transition_model.transition_probabilities[lo:hi, :m]
620
+ )
621
+ observation_prob: np.ndarray = observation_model(observation)
622
+ if log_probabilities:
623
+ forward_variable = observation_prob + np.log(transition_prob)
624
+ forward_variable -= logsumexp(forward_variable)
625
+ else:
626
+ forward_variable = observation_prob * transition_prob
627
+ forward_variable /= max(forward_variable.sum(), 1e-6)
628
+
629
+ return forward_variable
630
+
631
+
632
+ _FORWARD_ALGORITHMS: dict = {
633
+ "optimized": forward_algorithm_step_optimized,
634
+ "standard": forward_algorithm_step,
635
+ }
636
+
637
+
534
638
  class ConstantTransitionModel(TransitionModel):
535
639
  """
536
640
  Constant Transition Model
@@ -577,22 +681,23 @@ class ConstantTransitionModel(TransitionModel):
577
681
  self.init_probabilities = init_probabilities
578
682
 
579
683
  if normalize_init_probabilities:
580
- # Normalize initial distribution
581
- self.init_probabilities /= np.maximum(
582
- np.sum(self.init_probabilities), 1e-10
583
- )
684
+ # Normalize in raw-probability space, then recompute log version.
685
+ # (The property getter returns log probs when use_log_probabilities
686
+ # is True, so we bypass it and work on the backing arrays directly.)
687
+ self._init_dist /= np.maximum(np.sum(self._init_dist), 1e-10)
688
+ self._log_init_dist = np.log(self._init_dist)
584
689
 
585
690
  if normalize_transition_probabilities:
586
- self.transition_probabilities /= np.sum(
587
- self.transition_probabilities, 1, keepdims=True
691
+ self._transition_prob /= np.sum(
692
+ self._transition_prob, 1, keepdims=True
588
693
  )
694
+ self._log_transition_prob = np.log(self._transition_prob)
589
695
 
590
696
  @property
591
697
  def init_probabilities(self) -> np.ndarray:
592
698
  if self.use_log_probabilities:
593
699
  return self._log_init_dist
594
- else:
595
- return self._init_dist
700
+ return self._init_dist
596
701
 
597
702
  @init_probabilities.setter
598
703
  def init_probabilities(self, init_probabilities: np.ndarray) -> None:
@@ -603,23 +708,36 @@ class ConstantTransitionModel(TransitionModel):
603
708
  def transition_probabilities(self) -> np.ndarray:
604
709
  if self.use_log_probabilities:
605
710
  return self._log_transition_prob
606
- else:
607
- return self._transition_prob
711
+ return self._transition_prob
608
712
 
609
713
  @transition_probabilities.setter
610
- def transition_probabilities(self, transition_probabilities) -> None:
714
+ def transition_probabilities(self, transition_probabilities: np.ndarray) -> None:
611
715
  self._transition_prob = transition_probabilities
612
716
  self._log_transition_prob = np.log(self._transition_prob)
717
+ # Rightmost non-zero column of each row, made monotonic with a
718
+ # cumulative max so that it bounds the columns reachable from any
719
+ # range of rows [0, i] (used by forward_algorithm_step_optimized).
720
+ T = np.asarray(transition_probabilities)
721
+ self._last_nonzero_columns = np.maximum.accumulate(
722
+ T.shape[1] - 1 - np.argmax(T[:, ::-1] != 0, axis=1)
723
+ )
724
+
725
+ @property
726
+ def last_nonzero_columns(self) -> np.ndarray:
727
+ return self._last_nonzero_columns
613
728
 
614
- def __call__(self, i=None, j=None) -> np.ndarray:
729
+ def __call__(
730
+ self,
731
+ i: Optional[int] = None,
732
+ j: Optional[int] = None,
733
+ ) -> np.ndarray:
615
734
  if i is None and j is None:
616
735
  return self.transition_probabilities
617
- elif i is not None and j is None:
736
+ if i is not None and j is None:
618
737
  return self.transition_probabilities[i, :]
619
- elif i is None and j is not None:
738
+ if i is None and j is not None:
620
739
  return self.transition_probabilities[:, j]
621
- else:
622
- return self.transition_probabilities[i, j]
740
+ return self.transition_probabilities[i, j]
623
741
 
624
742
 
625
743
  class CategoricalObservationModel(ObservationModel):
@@ -629,9 +747,9 @@ class CategoricalObservationModel(ObservationModel):
629
747
  Parameters
630
748
  ----------
631
749
  observation_probabilities : np.ndarray
632
- A table of probabilities for each observation in each state.
633
- observations : Iterable
634
- A list of the observations
750
+ A (num_observations, num_states) table of emission probabilities.
751
+ observations : Iterable or None
752
+ Labels for each observation row. When None, integer strings are used.
635
753
  use_log_probabilities : bool
636
754
  If True, use log probabilities.
637
755
  """
@@ -639,37 +757,35 @@ class CategoricalObservationModel(ObservationModel):
639
757
  def __init__(
640
758
  self,
641
759
  observation_probabilities: np.ndarray,
642
- observations: Iterable[Any] = None,
760
+ observations: Optional[Iterable[Any]] = None,
643
761
  use_log_probabilities: bool = True,
644
- ):
762
+ ) -> None:
645
763
  super().__init__(use_log_probabilities=use_log_probabilities)
646
764
 
647
765
  self.observation_probabilities = observation_probabilities
648
766
 
649
767
  if observations is not None:
650
- self.observations = list(observations)
768
+ self.observations: List[Any] = list(observations)
651
769
  else:
652
770
  self.observations = [str(i) for i in range(len(observation_probabilities))]
653
771
 
654
- self.observation_indices = dict(
655
- [(obs, i) for obs, i in zip(self.observations, range(len(observations)))]
656
- )
772
+ self.observation_indices: dict[Any, int] = {
773
+ obs: i for i, obs in enumerate(self.observations)
774
+ }
657
775
 
658
776
  @property
659
- def observation_probabilities(self):
777
+ def observation_probabilities(self) -> np.ndarray:
660
778
  if self.use_log_probabilities:
661
779
  return self._log_obs_prob
662
- else:
663
- return self._obs_prob
780
+ return self._obs_prob
664
781
 
665
782
  @observation_probabilities.setter
666
- def observation_probabilities(self, observation_probabilities):
783
+ def observation_probabilities(self, observation_probabilities: np.ndarray) -> None:
667
784
  self._obs_prob = observation_probabilities
668
785
  self._log_obs_prob = np.log(self._obs_prob)
669
786
 
670
- def __call__(self, observation, *args, **kwargs):
787
+ def __call__(self, observation: Any, *args: Any, **kwargs: Any) -> np.ndarray:
671
788
  idx = self.observation_indices[observation]
672
- # idx = self.observations.index(observation)
673
789
  return self.observation_probabilities[idx]
674
790
 
675
791
 
@@ -679,58 +795,58 @@ CategoricalStringObservationModel = CategoricalObservationModel
679
795
 
680
796
  class WindowedObservationModel(ObservationModel):
681
797
  """
682
- Windowed Observation Model
683
- Uses a list of state-specific probability models
684
- as observation model. Probability models can also be distances,
685
- in which case the different distances are inverted and softmaxed.
798
+ Windowed Observation Model.
686
799
 
687
- Only works with viterbi_algorithm_windowed
800
+ Uses a list of state-specific probability models as the observation model.
801
+ Distances are supported: pass ``use_inverted_probs=True`` to convert
802
+ distances (lower = more probable) to probabilities via inverted softmax.
688
803
 
689
- Parameters
690
- ----------
691
- prob_models_at_state : list of tuples
692
- A list of tuples (probability_model,prob_model_state_id)
693
- indexed by state_id
804
+ Only works with :func:`viterbi_algorithm_windowed`.
694
805
 
695
- Attributes
806
+ Parameters
696
807
  ----------
697
- prob_models_at_state: list of tuples
698
-
808
+ prob_models_at_state : list of lists of (callable, int) pairs
809
+ ``prob_models_at_state[state_id]`` is a list of
810
+ ``(probability_model, global_state_index)`` pairs for the window
811
+ centred at ``state_id``.
812
+ use_inverted_probs : bool
813
+ When True, model outputs are treated as distances and converted to
814
+ probabilities via inverted softmax (lower distance → higher prob).
815
+ When False, outputs are treated as scores and converted via softmax.
816
+ use_log_probabilities : bool
817
+ If True, return log probabilities.
699
818
  """
700
819
 
701
820
  def __init__(
702
821
  self,
703
- prob_models_at_state: List[tuple],
822
+ prob_models_at_state: List[List[_ProbModelEntry]],
704
823
  use_inverted_probs: bool = True,
705
824
  use_log_probabilities: bool = True,
706
- ):
825
+ ) -> None:
707
826
  super().__init__(use_log_probabilities=use_log_probabilities)
708
- self.use_log_probabilities = use_log_probabilities
709
- self.use_inverted_probs = use_inverted_probs
710
- self.prob_models_at_state = prob_models_at_state
711
- self.state_number = len(prob_models_at_state)
712
- if self.use_inverted_probs:
713
- if self.use_log_probabilities:
714
- self.outfunc = lambda d: np.log(inverted_softmax(np.array(d)))
715
- else:
716
- self.outfunc = lambda d: inverted_softmax(np.array(d))
717
- else:
718
- if self.use_log_probabilities:
719
- self.outfunc = lambda d: np.log(softmax(np.array(d)))
720
- else:
721
- self.outfunc = lambda d: softmax(np.array(d))
827
+ self.use_inverted_probs: bool = use_inverted_probs
828
+ self.prob_models_at_state: List[List[_ProbModelEntry]] = prob_models_at_state
829
+ self.state_number: int = len(prob_models_at_state)
722
830
 
723
- def __call__(self, observation, current_state, *args, **kwargs):
724
- # give the current state pick the right states
831
+ def __call__(
832
+ self,
833
+ observation: Any,
834
+ current_state: int,
835
+ *args: Any,
836
+ **kwargs: Any,
837
+ ) -> Tuple[np.ndarray, np.ndarray]:
725
838
  prob_models = self.prob_models_at_state[
726
839
  max(0, min(current_state, self.state_number - 1))
727
840
  ]
728
- # compute the probability for all models
729
- dists = list()
730
- glob_ref_idx = list()
731
-
841
+ dists: List[Any] = []
842
+ glob_ref_idx: List[int] = []
732
843
  for prob_model, idx in prob_models:
733
844
  dists.append(prob_model(observation))
734
845
  glob_ref_idx.append(idx)
735
846
 
736
- return self.outfunc(dists), np.array(glob_ref_idx)
847
+ arr = np.array(dists)
848
+ probs = inverted_softmax(arr) if self.use_inverted_probs else softmax(arr)
849
+
850
+ if self.use_log_probabilities:
851
+ return np.log(probs), np.array(glob_ref_idx)
852
+ return probs, np.array(glob_ref_idx)