python-hiddenmarkov 0.1.4__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 (25) hide show
  1. {python_hiddenmarkov-0.1.4 → python_hiddenmarkov-0.3.0}/PKG-INFO +9 -7
  2. {python_hiddenmarkov-0.1.4 → python_hiddenmarkov-0.3.0}/README.md +4 -2
  3. {python_hiddenmarkov-0.1.4 → python_hiddenmarkov-0.3.0}/hiddenmarkov/__init__.py +234 -121
  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.1.4 → python_hiddenmarkov-0.3.0}/pyproject.toml +19 -6
  10. {python_hiddenmarkov-0.1.4 → python_hiddenmarkov-0.3.0}/python_hiddenmarkov.egg-info/PKG-INFO +9 -7
  11. {python_hiddenmarkov-0.1.4 → python_hiddenmarkov-0.3.0}/python_hiddenmarkov.egg-info/SOURCES.txt +9 -2
  12. python_hiddenmarkov-0.3.0/python_hiddenmarkov.egg-info/requires.txt +2 -0
  13. python_hiddenmarkov-0.3.0/setup.py +85 -0
  14. python_hiddenmarkov-0.3.0/tests/test_algorithms.py +313 -0
  15. python_hiddenmarkov-0.3.0/tests/test_forward_optimized.py +179 -0
  16. python_hiddenmarkov-0.3.0/tests/test_models.py +252 -0
  17. python_hiddenmarkov-0.3.0/tests/test_utils.py +66 -0
  18. python_hiddenmarkov-0.1.4/hiddenmarkov/utils.py +0 -57
  19. python_hiddenmarkov-0.1.4/python_hiddenmarkov.egg-info/requires.txt +0 -2
  20. python_hiddenmarkov-0.1.4/tests/test_viterbi.py +0 -161
  21. python_hiddenmarkov-0.1.4/tests/test_window.py +0 -246
  22. {python_hiddenmarkov-0.1.4 → python_hiddenmarkov-0.3.0}/LICENSE +0 -0
  23. {python_hiddenmarkov-0.1.4 → python_hiddenmarkov-0.3.0}/python_hiddenmarkov.egg-info/dependency_links.txt +0 -0
  24. {python_hiddenmarkov-0.1.4 → python_hiddenmarkov-0.3.0}/python_hiddenmarkov.egg-info/top_level.txt +0 -0
  25. {python_hiddenmarkov-0.1.4 → python_hiddenmarkov-0.3.0}/setup.cfg +0 -0
@@ -1,27 +1,29 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: python-hiddenmarkov
3
- Version: 0.1.4
3
+ Version: 0.3.0
4
4
  Summary: A simple Python package for Hidden Markov Models
5
5
  Author: Silvan Peter
6
6
  Author-email: Carlos Cancino-Chacón <carloscancinochacon@gmail.com>
7
7
  License: MIT
8
- Project-URL: Homepage, https://github.com/neosatrapahereje/hiddenmarkov
8
+ Project-URL: Homepage, https://github.com/CarlosCancino-Chacon/hiddenmarkov
9
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.8
15
+ Requires-Python: >=3.10
16
16
  Description-Content-Type: text/markdown
17
17
  License-File: LICENSE
18
- Requires-Dist: numpy
19
- Requires-Dist: scipy
18
+ Requires-Dist: numpy>=1.24
19
+ Requires-Dist: scipy>=1.7
20
20
  Dynamic: license-file
21
21
 
22
22
  # hiddenmarkov
23
23
 
24
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)
25
27
 
26
28
  A simple Python library for Hidden Markov Models.
27
29
 
@@ -37,7 +39,7 @@ pip install python-hiddenmarkov
37
39
 
38
40
  Develop version
39
41
  ```bash
40
- git clone https://github.com/neosatrapahereje/hiddenmarkov.git
42
+ git clone https://github.com/CarlosCancino-Chacon/hiddenmarkov.git
41
43
  cd hiddenmarkov
42
44
  pip install -e .
43
45
  ```
@@ -79,4 +81,4 @@ print("Expected probability", 0.01512)
79
81
  ## Licence
80
82
 
81
83
  The code in this package is licensed under the MIT Licence. For details,
82
- 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
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,26 +5,35 @@ Hidden Markov Models
5
5
 
6
6
  This module contains case classes to define Hidden Markov Models.
7
7
  """
8
- import warnings
8
+ from __future__ import annotations
9
+
9
10
  import numpy as np
10
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
30
  try:
22
31
  __version__ = version("python-hiddenmarkov")
23
- except PackageNotFoundError:
32
+ except PackageNotFoundError: # pragma: no cover
24
33
  __version__ = "unknown"
25
34
 
26
35
 
27
- class TransitionModel(object):
36
+ class TransitionModel:
28
37
  """
29
38
  Base class for implementing a Transition Model
30
39
  """
@@ -39,25 +48,25 @@ class TransitionModel(object):
39
48
  self,
40
49
  i: Optional[int] = None,
41
50
  j: Optional[int] = None,
42
- *args,
43
- **kwargs,
51
+ *args: Any,
52
+ **kwargs: Any,
44
53
  ) -> np.ndarray:
45
54
  raise NotImplementedError
46
55
 
47
56
 
48
- class ObservationModel(object):
57
+ class ObservationModel:
49
58
  """
50
59
  Base class for implementing an Observation Model
51
60
  """
52
61
 
53
62
  def __init__(self, use_log_probabilities: bool = True) -> None:
54
- self.use_log_probabilities = use_log_probabilities
63
+ self.use_log_probabilities: bool = use_log_probabilities
55
64
 
56
- def __call__(self, observation: Any, *args, **kwargs) -> np.ndarray:
65
+ def __call__(self, observation: Any, *args: Any, **kwargs: Any) -> np.ndarray:
57
66
  raise NotImplementedError()
58
67
 
59
68
 
60
- class HiddenMarkovModel(object):
69
+ class HiddenMarkovModel:
61
70
  """
62
71
  Hidden Markov Model
63
72
 
@@ -70,6 +79,16 @@ class HiddenMarkovModel(object):
70
79
  state_space: iterable (optional)
71
80
  Labels of the states (e.g., a list of strings containing
72
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.
73
92
 
74
93
  Attributes
75
94
  ----------
@@ -86,8 +105,22 @@ class HiddenMarkovModel(object):
86
105
  observation_model: ObservationModel,
87
106
  transition_model: TransitionModel,
88
107
  state_space: Optional[Iterable] = None,
108
+ forward: str = "optimized",
89
109
  ) -> None:
90
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
91
124
  self.observation_model: ObservationModel = observation_model
92
125
  self.transition_model: TransitionModel = transition_model
93
126
  self.n_states: int = self.transition_model.n_states
@@ -166,7 +199,7 @@ class HiddenMarkovModel(object):
166
199
  current_state : int
167
200
  Index of the current hidden state.
168
201
  """
169
- self.forward_variable = forward_algorithm_step(
202
+ self.forward_variable = self._forward_step(
170
203
  observation_model=self.observation_model,
171
204
  transition_model=self.transition_model,
172
205
  observation=observation,
@@ -185,7 +218,7 @@ HMM = HiddenMarkovModel
185
218
 
186
219
  def viterbi_algorithm_naive(
187
220
  hmm: HiddenMarkovModel,
188
- observations: Iterable,
221
+ observations: Iterable[Any],
189
222
  log_probabilities: bool = True,
190
223
  ) -> Tuple[np.ndarray, float]:
191
224
  """
@@ -306,57 +339,47 @@ def viterbi_algorithm(
306
339
  log proability if `log_probabilities` is True)
307
340
  of the best sequence.
308
341
  """
309
- # Set whether to use log probabilities in transition and
310
- # observation models
311
342
  hmm.transition_model.use_log_probabilities = log_probabilities
312
343
  hmm.observation_model.use_log_probabilities = log_probabilities
313
- # Initialize matrix for holding the best sub-sequence
314
- # (log-)likelihood
315
- omega = np.zeros((len(observations), hmm.n_states))
316
- # Initialize matrix for holding the best sub-sequence idx
317
- omega_idx = np.zeros((len(observations), hmm.n_states), dtype=int)
318
-
319
- # Initiate for i == 0
320
- obs_prob = hmm.observation_model(observations[0])
321
-
322
- if log_probabilities:
323
- omega[0, :] = obs_prob + hmm.transition_model.init_probabilities
324
- else:
325
- omega[0, :] = obs_prob * hmm.transition_model.init_probabilities
326
344
 
327
- omega_idx[0, :] = 0
328
-
329
- # Viterbi recursion
330
- if log_probabilities:
331
- for i, obs in enumerate(observations[1:], 1):
332
- obs_prob = hmm.observation_model(obs)
333
- # omega slice is a row vector, transition_model is a matrix
334
- # of prob from state id_row to state id_column
335
- 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
336
365
  state = np.argmax(prob_of_jump_to_state, axis=1)
337
- prob = prob_of_jump_to_state[np.arange(hmm.n_states), state]
338
- omega[i, :] = obs_prob + prob
339
- omega_idx[i, :] = state
340
-
366
+ prob = prob_of_jump_to_state[np.arange(N), state]
367
+ omega[t, :] = obs_probs[t] + prob
368
+ omega_idx[t, :] = state
341
369
  else:
342
- for i, obs in enumerate(observations[1:], 1):
343
- obs_prob = hmm.observation_model(obs)
344
- # omega slice is a row vector, transition_model is a matrix
345
- # of prob from state id_row to state id_column
346
- 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
347
373
  state = np.argmax(prob_of_jump_to_state, axis=1)
348
- prob = prob_of_jump_to_state[np.arange(hmm.n_states), state]
349
- omega[i, :] = obs_prob * prob
350
- 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
351
377
 
352
- # Get best path (backtracking!)
353
- # Get index of the best state
378
+ # Backtrack
354
379
  best_sequence_idx = omega[-1, :].argmax()
355
- # likelihood of the path
356
380
  path_likelihood = omega[-1, best_sequence_idx]
357
- # Get best path (backtracking!)
358
381
  seq = [best_sequence_idx]
359
- for s in range(len(observations) - 1):
382
+ for s in range(T - 1):
360
383
  best_sequence_idx = omega_idx[-(s + 1), best_sequence_idx]
361
384
  seq.append(best_sequence_idx)
362
385
  best_sequence = np.array(seq[::-1], dtype=int)
@@ -522,7 +545,79 @@ def forward_algorithm_step(
522
545
  if forward_variable is None:
523
546
  transition_prob: np.ndarray = transition_model.init_probabilities
524
547
  else:
525
- 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)
553
+ observation_prob: np.ndarray = observation_model(observation)
554
+ if log_probabilities:
555
+ forward_variable = observation_prob + np.log(transition_prob)
556
+ forward_variable -= logsumexp(forward_variable)
557
+ else:
558
+ forward_variable = observation_prob * transition_prob
559
+ forward_variable /= max(forward_variable.sum(), 1e-6)
560
+
561
+ return forward_variable
562
+
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
+ )
526
621
  observation_prob: np.ndarray = observation_model(observation)
527
622
  if log_probabilities:
528
623
  forward_variable = observation_prob + np.log(transition_prob)
@@ -534,6 +629,12 @@ def forward_algorithm_step(
534
629
  return forward_variable
535
630
 
536
631
 
632
+ _FORWARD_ALGORITHMS: dict = {
633
+ "optimized": forward_algorithm_step_optimized,
634
+ "standard": forward_algorithm_step,
635
+ }
636
+
637
+
537
638
  class ConstantTransitionModel(TransitionModel):
538
639
  """
539
640
  Constant Transition Model
@@ -580,22 +681,23 @@ class ConstantTransitionModel(TransitionModel):
580
681
  self.init_probabilities = init_probabilities
581
682
 
582
683
  if normalize_init_probabilities:
583
- # Normalize initial distribution
584
- self.init_probabilities /= np.maximum(
585
- np.sum(self.init_probabilities), 1e-10
586
- )
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)
587
689
 
588
690
  if normalize_transition_probabilities:
589
- self.transition_probabilities /= np.sum(
590
- self.transition_probabilities, 1, keepdims=True
691
+ self._transition_prob /= np.sum(
692
+ self._transition_prob, 1, keepdims=True
591
693
  )
694
+ self._log_transition_prob = np.log(self._transition_prob)
592
695
 
593
696
  @property
594
697
  def init_probabilities(self) -> np.ndarray:
595
698
  if self.use_log_probabilities:
596
699
  return self._log_init_dist
597
- else:
598
- return self._init_dist
700
+ return self._init_dist
599
701
 
600
702
  @init_probabilities.setter
601
703
  def init_probabilities(self, init_probabilities: np.ndarray) -> None:
@@ -606,23 +708,36 @@ class ConstantTransitionModel(TransitionModel):
606
708
  def transition_probabilities(self) -> np.ndarray:
607
709
  if self.use_log_probabilities:
608
710
  return self._log_transition_prob
609
- else:
610
- return self._transition_prob
711
+ return self._transition_prob
611
712
 
612
713
  @transition_probabilities.setter
613
- def transition_probabilities(self, transition_probabilities) -> None:
714
+ def transition_probabilities(self, transition_probabilities: np.ndarray) -> None:
614
715
  self._transition_prob = transition_probabilities
615
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
616
728
 
617
- 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:
618
734
  if i is None and j is None:
619
735
  return self.transition_probabilities
620
- elif i is not None and j is None:
736
+ if i is not None and j is None:
621
737
  return self.transition_probabilities[i, :]
622
- elif i is None and j is not None:
738
+ if i is None and j is not None:
623
739
  return self.transition_probabilities[:, j]
624
- else:
625
- return self.transition_probabilities[i, j]
740
+ return self.transition_probabilities[i, j]
626
741
 
627
742
 
628
743
  class CategoricalObservationModel(ObservationModel):
@@ -632,9 +747,9 @@ class CategoricalObservationModel(ObservationModel):
632
747
  Parameters
633
748
  ----------
634
749
  observation_probabilities : np.ndarray
635
- A table of probabilities for each observation in each state.
636
- observations : Iterable
637
- 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.
638
753
  use_log_probabilities : bool
639
754
  If True, use log probabilities.
640
755
  """
@@ -642,37 +757,35 @@ class CategoricalObservationModel(ObservationModel):
642
757
  def __init__(
643
758
  self,
644
759
  observation_probabilities: np.ndarray,
645
- observations: Iterable[Any] = None,
760
+ observations: Optional[Iterable[Any]] = None,
646
761
  use_log_probabilities: bool = True,
647
- ):
762
+ ) -> None:
648
763
  super().__init__(use_log_probabilities=use_log_probabilities)
649
764
 
650
765
  self.observation_probabilities = observation_probabilities
651
766
 
652
767
  if observations is not None:
653
- self.observations = list(observations)
768
+ self.observations: List[Any] = list(observations)
654
769
  else:
655
770
  self.observations = [str(i) for i in range(len(observation_probabilities))]
656
771
 
657
- self.observation_indices = dict(
658
- [(obs, i) for obs, i in zip(self.observations, range(len(observations)))]
659
- )
772
+ self.observation_indices: dict[Any, int] = {
773
+ obs: i for i, obs in enumerate(self.observations)
774
+ }
660
775
 
661
776
  @property
662
- def observation_probabilities(self):
777
+ def observation_probabilities(self) -> np.ndarray:
663
778
  if self.use_log_probabilities:
664
779
  return self._log_obs_prob
665
- else:
666
- return self._obs_prob
780
+ return self._obs_prob
667
781
 
668
782
  @observation_probabilities.setter
669
- def observation_probabilities(self, observation_probabilities):
783
+ def observation_probabilities(self, observation_probabilities: np.ndarray) -> None:
670
784
  self._obs_prob = observation_probabilities
671
785
  self._log_obs_prob = np.log(self._obs_prob)
672
786
 
673
- def __call__(self, observation, *args, **kwargs):
787
+ def __call__(self, observation: Any, *args: Any, **kwargs: Any) -> np.ndarray:
674
788
  idx = self.observation_indices[observation]
675
- # idx = self.observations.index(observation)
676
789
  return self.observation_probabilities[idx]
677
790
 
678
791
 
@@ -682,58 +795,58 @@ CategoricalStringObservationModel = CategoricalObservationModel
682
795
 
683
796
  class WindowedObservationModel(ObservationModel):
684
797
  """
685
- Windowed Observation Model
686
- Uses a list of state-specific probability models
687
- as observation model. Probability models can also be distances,
688
- in which case the different distances are inverted and softmaxed.
798
+ Windowed Observation Model.
689
799
 
690
- 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.
691
803
 
692
- Parameters
693
- ----------
694
- prob_models_at_state : list of tuples
695
- A list of tuples (probability_model,prob_model_state_id)
696
- indexed by state_id
804
+ Only works with :func:`viterbi_algorithm_windowed`.
697
805
 
698
- Attributes
806
+ Parameters
699
807
  ----------
700
- prob_models_at_state: list of tuples
701
-
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.
702
818
  """
703
819
 
704
820
  def __init__(
705
821
  self,
706
- prob_models_at_state: List[tuple],
822
+ prob_models_at_state: List[List[_ProbModelEntry]],
707
823
  use_inverted_probs: bool = True,
708
824
  use_log_probabilities: bool = True,
709
- ):
825
+ ) -> None:
710
826
  super().__init__(use_log_probabilities=use_log_probabilities)
711
- self.use_log_probabilities = use_log_probabilities
712
- self.use_inverted_probs = use_inverted_probs
713
- self.prob_models_at_state = prob_models_at_state
714
- self.state_number = len(prob_models_at_state)
715
- if self.use_inverted_probs:
716
- if self.use_log_probabilities:
717
- self.outfunc = lambda d: np.log(inverted_softmax(np.array(d)))
718
- else:
719
- self.outfunc = lambda d: inverted_softmax(np.array(d))
720
- else:
721
- if self.use_log_probabilities:
722
- self.outfunc = lambda d: np.log(softmax(np.array(d)))
723
- else:
724
- 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)
725
830
 
726
- def __call__(self, observation, current_state, *args, **kwargs):
727
- # 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]:
728
838
  prob_models = self.prob_models_at_state[
729
839
  max(0, min(current_state, self.state_number - 1))
730
840
  ]
731
- # compute the probability for all models
732
- dists = list()
733
- glob_ref_idx = list()
734
-
841
+ dists: List[Any] = []
842
+ glob_ref_idx: List[int] = []
735
843
  for prob_model, idx in prob_models:
736
844
  dists.append(prob_model(observation))
737
845
  glob_ref_idx.append(idx)
738
846
 
739
- 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)