python-hiddenmarkov 0.1.4__py3-none-any.whl

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.
@@ -0,0 +1,739 @@
1
+ #!/usr/bin/env python
2
+ # -*- coding: utf-8 -*-
3
+ """
4
+ Hidden Markov Models
5
+
6
+ This module contains case classes to define Hidden Markov Models.
7
+ """
8
+ import warnings
9
+ import numpy as np
10
+ from importlib.metadata import version, PackageNotFoundError
11
+
12
+ from collections import defaultdict
13
+ from typing import Any, Iterable, Optional, Tuple, ClassVar, List
14
+
15
+ from scipy.special import logsumexp
16
+
17
+ from .utils import inverted_softmax, softmax
18
+
19
+
20
+ # define a version variable
21
+ try:
22
+ __version__ = version("python-hiddenmarkov")
23
+ except PackageNotFoundError:
24
+ __version__ = "unknown"
25
+
26
+
27
+ class TransitionModel(object):
28
+ """
29
+ Base class for implementing a Transition Model
30
+ """
31
+
32
+ init_probabilities: ClassVar[np.ndarray]
33
+ n_states: int
34
+
35
+ def __init__(self, use_log_probabilities: bool = True) -> None:
36
+ self.use_log_probabilities: bool = use_log_probabilities
37
+
38
+ def __call__(
39
+ self,
40
+ i: Optional[int] = None,
41
+ j: Optional[int] = None,
42
+ *args,
43
+ **kwargs,
44
+ ) -> np.ndarray:
45
+ raise NotImplementedError
46
+
47
+
48
+ class ObservationModel(object):
49
+ """
50
+ Base class for implementing an Observation Model
51
+ """
52
+
53
+ def __init__(self, use_log_probabilities: bool = True) -> None:
54
+ self.use_log_probabilities = use_log_probabilities
55
+
56
+ def __call__(self, observation: Any, *args, **kwargs) -> np.ndarray:
57
+ raise NotImplementedError()
58
+
59
+
60
+ class HiddenMarkovModel(object):
61
+ """
62
+ Hidden Markov Model
63
+
64
+ Parameters
65
+ ----------
66
+ observation_model : ObservationModel
67
+ A model for computiong the observation (emission) probabilities.
68
+ transition_model: TransitionModel
69
+ A model for computing the transition probabilities.
70
+ state_space: iterable (optional)
71
+ Labels of the states (e.g., a list of strings containing
72
+ the names of each state).
73
+
74
+ Attributes
75
+ ----------
76
+ observation_model: ObservationModel
77
+ transition_model: TransitionModel
78
+ n_states: int
79
+ Number of states
80
+ state_space: np.array
81
+
82
+ """
83
+
84
+ def __init__(
85
+ self,
86
+ observation_model: ObservationModel,
87
+ transition_model: TransitionModel,
88
+ state_space: Optional[Iterable] = None,
89
+ ) -> None:
90
+ super().__init__()
91
+ self.observation_model: ObservationModel = observation_model
92
+ self.transition_model: TransitionModel = transition_model
93
+ self.n_states: int = self.transition_model.n_states
94
+ if state_space is not None:
95
+ self.state_space: np.ndarray = np.asarray(state_space)
96
+ else:
97
+ self.state_space: np.ndarray = np.arange(self.n_states)
98
+
99
+ self.forward_variable: Optional[np.ndarray] = None
100
+
101
+ def find_best_sequence(
102
+ self,
103
+ observations: Iterable[Any],
104
+ log_probabilities: bool = True,
105
+ viterbi: str = "optimized",
106
+ ) -> Tuple[np.ndarray, float]:
107
+ """
108
+ Find the best sequence of hidden states given a sequence of
109
+ observations using the viterbi algorithm
110
+
111
+ Parameters
112
+ ----------
113
+ observations : Iterable
114
+ The sequence of observations.
115
+ log_probabilities : bool
116
+ If True, log probabilities will be used.
117
+ viterbi : {"optimized", "windowed", "naive"}
118
+ The implementation of the viterbi algorithm.
119
+
120
+ Returns
121
+ -------
122
+ best_sequence : np.ndarray
123
+ The best sequence of hidden states
124
+ sequence_likelihood : float
125
+ The probability (or log probability if `log_probabilities=True`)
126
+ of the sequence of observations.
127
+ """
128
+ if viterbi == "optimized":
129
+ viterbi_fun = viterbi_algorithm
130
+ elif viterbi == "windowed":
131
+ viterbi_fun = viterbi_algorithm_windowed
132
+ elif viterbi == "naive":
133
+ viterbi_fun = viterbi_algorithm_naive
134
+ else:
135
+ raise ValueError(
136
+ "`viterbi` needs to be 'optimized', 'windowed', or 'naive' "
137
+ f"but is {viterbi}"
138
+ )
139
+ # warnings.warn("viterbi needs to be 'optimized', 'windowed', or 'naive'")
140
+ # return
141
+ best_sequence, sequence_likelihood = viterbi_fun(
142
+ hmm=self,
143
+ observations=observations,
144
+ log_probabilities=log_probabilities,
145
+ )
146
+ return best_sequence, sequence_likelihood
147
+
148
+ def forward_algorithm_step(
149
+ self,
150
+ observation: Any,
151
+ log_probabilities: bool = False,
152
+ ) -> int:
153
+ """
154
+ Find the hidden state that has the maximal probability
155
+ given the current observation.
156
+
157
+ Parameters
158
+ ----------
159
+ observation : Any
160
+ The current observation
161
+ log_probabilities: bool
162
+ If True, log probabilities will be used.
163
+
164
+ Returns
165
+ -------
166
+ current_state : int
167
+ Index of the current hidden state.
168
+ """
169
+ self.forward_variable = forward_algorithm_step(
170
+ observation_model=self.observation_model,
171
+ transition_model=self.transition_model,
172
+ observation=observation,
173
+ forward_variable=self.forward_variable,
174
+ log_probabilities=log_probabilities,
175
+ )
176
+ current_state: int = np.argmax(self.forward_variable)
177
+
178
+ return current_state
179
+ # pass
180
+
181
+
182
+ # alias
183
+ HMM = HiddenMarkovModel
184
+
185
+
186
+ def viterbi_algorithm_naive(
187
+ hmm: HiddenMarkovModel,
188
+ observations: Iterable,
189
+ log_probabilities: bool = True,
190
+ ) -> Tuple[np.ndarray, float]:
191
+ """
192
+ Find the most probable sequence of latent variables given
193
+ a sequence of observations
194
+
195
+ Parameters
196
+ ----------
197
+ observations: iterable
198
+ An iterable containing observations. The type of each
199
+ element depends on input types accepted by the
200
+ `hmm.observation_model`
201
+ log_probabilities: Bool (optional)
202
+ If True, uses log probabilities to compute the Viterbi
203
+ recursion (better for numerical stability). Default is True.
204
+
205
+ Returns
206
+ -------
207
+ path: np.ndarray
208
+ The most probable sequence of latent variables
209
+ likelihood: float
210
+ The likelihood (either the probability or the
211
+ log proability if `log_probabilities` is True)
212
+ of the best sequence.
213
+
214
+ Note
215
+ ----
216
+ This is a naïve implementation, mostly for educational purposes!
217
+ """
218
+ # Set whether to use log probabilities in transition and
219
+ # observation models
220
+ hmm.transition_model.use_log_probabilities = log_probabilities
221
+ hmm.observation_model.use_log_probabilities = log_probabilities
222
+ # Initialize matrix for holding the best sub-sequence
223
+ # (log-)likelihood
224
+ omega = np.zeros((len(observations), hmm.n_states))
225
+ # Initialize dictionary for tracking the best paths
226
+ path = defaultdict(lambda: list())
227
+
228
+ # Initiate for i == 0
229
+ obs_prob = hmm.observation_model(observations[0])
230
+
231
+ if log_probabilities:
232
+ omega[0, :] = obs_prob + hmm.transition_model.init_probabilities
233
+ else:
234
+ omega[0, :] = obs_prob * hmm.transition_model.init_probabilities
235
+
236
+ # Viterbi recursion
237
+ for i, obs in enumerate(observations[1:], 1):
238
+ obs_prob = hmm.observation_model(obs)
239
+ for j in range(hmm.n_states):
240
+ if log_probabilities:
241
+ prob, state = max(
242
+ [
243
+ (omega[i - 1, k] + hmm.transition_model(k, j), k)
244
+ for k in range(hmm.n_states)
245
+ ],
246
+ key=lambda x: x[0],
247
+ )
248
+ omega[i, j] = obs_prob[j] + prob
249
+
250
+ else:
251
+ prob, state = max(
252
+ [
253
+ (omega[i - 1, k] * hmm.transition_model(k, j), k)
254
+ for k in range(hmm.n_states)
255
+ ],
256
+ key=lambda x: x[0],
257
+ )
258
+ omega[i, j] = obs_prob[j] * prob
259
+ # keep track of the best state
260
+ path[j].append(state)
261
+
262
+ # Get best path (backtracking!)
263
+ # Get index of the best state
264
+ best_sequence_idx = omega[-1, :].argmax()
265
+ # likelihood of the path
266
+ path_likelihood = omega[-1, best_sequence_idx]
267
+ # follow the best path backwards
268
+ seq = [best_sequence_idx]
269
+ for s in range(len(path[best_sequence_idx])):
270
+ best_sequence_idx = path[best_sequence_idx][-(s + 1)]
271
+ seq.append(best_sequence_idx)
272
+ # invert the path
273
+ best_sequence = np.array(seq[::-1], dtype=int)
274
+
275
+ if hmm.state_space is not None:
276
+ best_sequence = hmm.state_space[best_sequence]
277
+
278
+ return best_sequence, path_likelihood
279
+
280
+
281
+ def viterbi_algorithm(
282
+ hmm: HiddenMarkovModel,
283
+ observations: Iterable[Any],
284
+ log_probabilities: bool = True,
285
+ ) -> Tuple[np.ndarray, float]:
286
+ """
287
+ Find the most probable sequence of latent variables given
288
+ a sequence of observations
289
+
290
+ Parameters
291
+ ----------
292
+ observations: iterable
293
+ An iterable containing observations. The type of each
294
+ element depends on input types accepted by the
295
+ `hmm.observation_model`
296
+ log_probabilities: Bool (optional)
297
+ If True, uses log probabilities to compute the Viterbi
298
+ recursion (better for numerical stability). Default is True.
299
+
300
+ Returns
301
+ -------
302
+ path: np.ndarray
303
+ The most probable sequence of latent variables
304
+ likelihood: float
305
+ The likelihood (either the probability or the
306
+ log proability if `log_probabilities` is True)
307
+ of the best sequence.
308
+ """
309
+ # Set whether to use log probabilities in transition and
310
+ # observation models
311
+ hmm.transition_model.use_log_probabilities = log_probabilities
312
+ 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
+
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
336
+ 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
+
341
+ 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
347
+ 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
351
+
352
+ # Get best path (backtracking!)
353
+ # Get index of the best state
354
+ best_sequence_idx = omega[-1, :].argmax()
355
+ # likelihood of the path
356
+ path_likelihood = omega[-1, best_sequence_idx]
357
+ # Get best path (backtracking!)
358
+ seq = [best_sequence_idx]
359
+ for s in range(len(observations) - 1):
360
+ best_sequence_idx = omega_idx[-(s + 1), best_sequence_idx]
361
+ seq.append(best_sequence_idx)
362
+ best_sequence = np.array(seq[::-1], dtype=int)
363
+ if hmm.state_space is not None:
364
+ best_sequence = hmm.state_space[best_sequence]
365
+
366
+ return best_sequence, path_likelihood
367
+
368
+
369
+ def viterbi_algorithm_windowed(
370
+ hmm: HiddenMarkovModel,
371
+ observations: Iterable[Any],
372
+ log_probabilities: bool = True,
373
+ ) -> Tuple[np.ndarray, float]:
374
+ """
375
+ Find the most probable sequence of latent variables given
376
+ a sequence of observations.
377
+
378
+ !!! This version uses a transition model with fixed window of
379
+ states (see WindowedHiddenMarkiovModel). This window represents
380
+ the currently "visible" states from any of an underlying
381
+ longer sequence of global states.
382
+
383
+ The viterbi uses the current best path at each step to
384
+ update the global path. This effectively limits the path
385
+ to corridor in the states. The observation model is called
386
+ with a global state id, so the true, underlying states
387
+ can have different probabilities.
388
+
389
+
390
+ Parameters
391
+ ----------
392
+ observations: iterable
393
+ An iterable containing observations. The type of each
394
+ element depends on input types accepted by the
395
+ `hmm.observation_model`
396
+ log_probabilities: Bool (optional)
397
+ If True, uses log probabilities to compute the Viterbi
398
+ recursion (better for numerical stability). Default is True.
399
+
400
+ Returns
401
+ -------
402
+ path: np.ndarray
403
+ The most probable sequence of latent variables
404
+ likelihood: float
405
+ The likelihood (either the probability or the
406
+ log proability if `log_probabilities` is True)
407
+ of the best sequence.
408
+ """
409
+ # Set whether to use log probabilities in transition and
410
+ # observation models
411
+ hmm.transition_model.use_log_probabilities = log_probabilities
412
+ hmm.observation_model.use_log_probabilities = log_probabilities
413
+ # Initialize matrix for holding the best sub-sequence
414
+ # (log-)likelihood
415
+ omega = np.zeros((len(observations), hmm.n_states))
416
+ # Initialize matrix for holding the best sub-sequence idx
417
+ omega_idx = np.zeros((len(observations), hmm.n_states), dtype=int)
418
+
419
+ # Initialize vector for holding the current best idx
420
+ # Current window id; start at state 0 and keep the state at the
421
+ # start of the current window
422
+ current_window_idx = np.zeros((len(observations) + 1), dtype=int)
423
+
424
+ omega_idx[0, :] = 0
425
+ current_window_idx[0] = 0 # zero is a dummy state just for jump size
426
+ current_window_idx[1] = 0 # zero is the actual first window idx
427
+
428
+ # Initiate for i == 0
429
+ obs_prob, _ = hmm.observation_model(observations[0], current_window_idx[0])
430
+
431
+ if log_probabilities:
432
+ omega[0, :] = obs_prob + hmm.transition_model.init_probabilities
433
+ else:
434
+ omega[0, :] = obs_prob * hmm.transition_model.init_probabilities
435
+
436
+ # Viterbi recursion
437
+ if log_probabilities:
438
+ for i, obs in enumerate(observations[1:], 1):
439
+ obs_prob, glob_ref_idx = hmm.observation_model(obs, current_window_idx[i])
440
+ # omega slice is a row vector, transition_model is a matrix
441
+ # of prob from state id_row to state id_column
442
+ # use only the slice of omega that is shifted by the previous jump
443
+ previous_jump = current_window_idx[i] - current_window_idx[i - 1]
444
+ prob_of_jump_to_state = (
445
+ np.concatenate(
446
+ (omega[i - 1, previous_jump:], np.ones(previous_jump) * -np.inf)
447
+ )
448
+ + hmm.transition_model().T
449
+ )
450
+ state = np.argmax(prob_of_jump_to_state, axis=1)
451
+ prob = prob_of_jump_to_state[np.arange(hmm.n_states), state]
452
+ omega[i, :] = obs_prob + prob
453
+ omega_idx[i, :] = state
454
+ # slide the window to the current best
455
+ current_best_sequence_idx = omega[i, :].argmax()
456
+ current_window_idx[i + 1] = glob_ref_idx[current_best_sequence_idx]
457
+
458
+ else:
459
+ for i, obs in enumerate(observations[1:], 1):
460
+ obs_prob, glob_ref_idx = hmm.observation_model(obs, current_window_idx[i])
461
+ # omega slice is a row vector, transition_model is a matrix
462
+ # of prob from state id_row to state id_column
463
+ # use only the slice of omega that is shifted by the previous jump
464
+ previous_jump = current_window_idx[i] - current_window_idx[i - 1]
465
+ prob_of_jump_to_state = (
466
+ np.concatenate((omega[i - 1, previous_jump:], np.zeros(previous_jump)))
467
+ * hmm.transition_model().T
468
+ )
469
+ state = np.argmax(prob_of_jump_to_state, axis=1)
470
+ prob = prob_of_jump_to_state[np.arange(hmm.n_states), state]
471
+ omega[i, :] = obs_prob * prob
472
+ omega_idx[i, :] = state
473
+ # slide the window to the current best
474
+ current_best_sequence_idx = omega[i, :].argmax()
475
+ current_window_idx[i + 1] = glob_ref_idx[current_best_sequence_idx]
476
+
477
+ # Get best path (backtracking!)
478
+ # Get index of the best state
479
+ best_sequence_idx = omega[-1, :].argmax()
480
+ # likelihood of the path
481
+ path_likelihood = omega[-1, best_sequence_idx]
482
+
483
+ return current_window_idx[1:], path_likelihood
484
+
485
+
486
+ def forward_algorithm_step(
487
+ observation_model: ObservationModel,
488
+ transition_model: TransitionModel,
489
+ observation: Any,
490
+ forward_variable: Optional[np.ndarray] = None,
491
+ log_probabilities: bool = False,
492
+ ) -> np.ndarray:
493
+ """
494
+ Step of the forward algorithm.
495
+
496
+ Parameters
497
+ ----------
498
+ observation_model : ObservationModel
499
+ An observation model.
500
+ transition_model: TransitionModel
501
+ A transition model.
502
+ observation: Any
503
+ An observation. The observation needs to be of the same
504
+ type as specified by the observation model.
505
+ forward_variable : np.ndarray
506
+ The forward variable of the HMM. If none is given, the
507
+ initial probabilities specified by the transition model
508
+ will be used.
509
+ log_probabilities : bool
510
+ If true, use log probabilities.
511
+
512
+ Returns
513
+ -------
514
+ forward_variable : np.ndarray
515
+ The updated forward variable.
516
+ """
517
+ # since computing the log of the matrix vector multiplication is not
518
+ # trivial (TODO: see if there is a clever way to do this multiplication
519
+ # efficiently)
520
+ transition_model.use_log_probabilities = False
521
+ observation_model.use_log_probabilities = log_probabilities
522
+ if forward_variable is None:
523
+ transition_prob: np.ndarray = transition_model.init_probabilities
524
+ else:
525
+ transition_prob: np.ndarray = np.dot(transition_model().T, forward_variable)
526
+ observation_prob: np.ndarray = observation_model(observation)
527
+ if log_probabilities:
528
+ forward_variable = observation_prob + np.log(transition_prob)
529
+ forward_variable -= logsumexp(forward_variable)
530
+ else:
531
+ forward_variable = observation_prob * transition_prob
532
+ forward_variable /= max(forward_variable.sum(), 1e-6)
533
+
534
+ return forward_variable
535
+
536
+
537
+ class ConstantTransitionModel(TransitionModel):
538
+ """
539
+ Constant Transition Model
540
+
541
+ This transition model represents the case were the
542
+ transition proabilities do not change over time (i.e.,
543
+ they are static). In this case, the transition probabilities
544
+ can be represented by a transition matrix
545
+
546
+ Parameters
547
+ ----------
548
+ transition_probabilities: np.ndarray
549
+ A (n_states, n_states) matrix where component
550
+ [i, j] represents the probability of going to state j
551
+ coming from state i.
552
+ init_probabilities: np.ndarray or None (optional)
553
+ A 1D vector of length n_states defining the initial
554
+ probabilities of each state
555
+ normalize_init_probabilities: bool (optional)
556
+ If True, the initial distribution will be normalized.
557
+ Default is False.
558
+ use_log_probabilities: bool (optional)
559
+ If True, use log proabilities instead of norm proabilities
560
+ (better for numerical stability)
561
+ """
562
+
563
+ def __init__(
564
+ self,
565
+ transition_probabilities: np.ndarray,
566
+ init_probabilities: Optional[np.ndarray] = None,
567
+ normalize_init_probabilities: bool = False,
568
+ normalize_transition_probabilities: bool = False,
569
+ use_log_probabilities: bool = True,
570
+ ) -> None:
571
+ super().__init__(use_log_probabilities=use_log_probabilities)
572
+ self.transition_probabilities = transition_probabilities
573
+ self.n_states = len(transition_probabilities)
574
+
575
+ if init_probabilities is None:
576
+ self.init_probabilities = (
577
+ 1.0 / float(self.n_states) * np.ones(self.n_states, dtype=float)
578
+ )
579
+ else:
580
+ self.init_probabilities = init_probabilities
581
+
582
+ if normalize_init_probabilities:
583
+ # Normalize initial distribution
584
+ self.init_probabilities /= np.maximum(
585
+ np.sum(self.init_probabilities), 1e-10
586
+ )
587
+
588
+ if normalize_transition_probabilities:
589
+ self.transition_probabilities /= np.sum(
590
+ self.transition_probabilities, 1, keepdims=True
591
+ )
592
+
593
+ @property
594
+ def init_probabilities(self) -> np.ndarray:
595
+ if self.use_log_probabilities:
596
+ return self._log_init_dist
597
+ else:
598
+ return self._init_dist
599
+
600
+ @init_probabilities.setter
601
+ def init_probabilities(self, init_probabilities: np.ndarray) -> None:
602
+ self._init_dist = init_probabilities
603
+ self._log_init_dist = np.log(self._init_dist)
604
+
605
+ @property
606
+ def transition_probabilities(self) -> np.ndarray:
607
+ if self.use_log_probabilities:
608
+ return self._log_transition_prob
609
+ else:
610
+ return self._transition_prob
611
+
612
+ @transition_probabilities.setter
613
+ def transition_probabilities(self, transition_probabilities) -> None:
614
+ self._transition_prob = transition_probabilities
615
+ self._log_transition_prob = np.log(self._transition_prob)
616
+
617
+ def __call__(self, i=None, j=None) -> np.ndarray:
618
+ if i is None and j is None:
619
+ return self.transition_probabilities
620
+ elif i is not None and j is None:
621
+ return self.transition_probabilities[i, :]
622
+ elif i is None and j is not None:
623
+ return self.transition_probabilities[:, j]
624
+ else:
625
+ return self.transition_probabilities[i, j]
626
+
627
+
628
+ class CategoricalObservationModel(ObservationModel):
629
+ """
630
+ A Categorical observation model.
631
+
632
+ Parameters
633
+ ----------
634
+ observation_probabilities : np.ndarray
635
+ A table of probabilities for each observation in each state.
636
+ observations : Iterable
637
+ A list of the observations
638
+ use_log_probabilities : bool
639
+ If True, use log probabilities.
640
+ """
641
+
642
+ def __init__(
643
+ self,
644
+ observation_probabilities: np.ndarray,
645
+ observations: Iterable[Any] = None,
646
+ use_log_probabilities: bool = True,
647
+ ):
648
+ super().__init__(use_log_probabilities=use_log_probabilities)
649
+
650
+ self.observation_probabilities = observation_probabilities
651
+
652
+ if observations is not None:
653
+ self.observations = list(observations)
654
+ else:
655
+ self.observations = [str(i) for i in range(len(observation_probabilities))]
656
+
657
+ self.observation_indices = dict(
658
+ [(obs, i) for obs, i in zip(self.observations, range(len(observations)))]
659
+ )
660
+
661
+ @property
662
+ def observation_probabilities(self):
663
+ if self.use_log_probabilities:
664
+ return self._log_obs_prob
665
+ else:
666
+ return self._obs_prob
667
+
668
+ @observation_probabilities.setter
669
+ def observation_probabilities(self, observation_probabilities):
670
+ self._obs_prob = observation_probabilities
671
+ self._log_obs_prob = np.log(self._obs_prob)
672
+
673
+ def __call__(self, observation, *args, **kwargs):
674
+ idx = self.observation_indices[observation]
675
+ # idx = self.observations.index(observation)
676
+ return self.observation_probabilities[idx]
677
+
678
+
679
+ # deprecated alias
680
+ CategoricalStringObservationModel = CategoricalObservationModel
681
+
682
+
683
+ class WindowedObservationModel(ObservationModel):
684
+ """
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.
689
+
690
+ Only works with viterbi_algorithm_windowed
691
+
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
697
+
698
+ Attributes
699
+ ----------
700
+ prob_models_at_state: list of tuples
701
+
702
+ """
703
+
704
+ def __init__(
705
+ self,
706
+ prob_models_at_state: List[tuple],
707
+ use_inverted_probs: bool = True,
708
+ use_log_probabilities: bool = True,
709
+ ):
710
+ 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))
725
+
726
+ def __call__(self, observation, current_state, *args, **kwargs):
727
+ # give the current state pick the right states
728
+ prob_models = self.prob_models_at_state[
729
+ max(0, min(current_state, self.state_number - 1))
730
+ ]
731
+ # compute the probability for all models
732
+ dists = list()
733
+ glob_ref_idx = list()
734
+
735
+ for prob_model, idx in prob_models:
736
+ dists.append(prob_model(observation))
737
+ glob_ref_idx.append(idx)
738
+
739
+ return self.outfunc(dists), np.array(glob_ref_idx)
hiddenmarkov/utils.py ADDED
@@ -0,0 +1,57 @@
1
+ #!/usr/bin/env python
2
+ # -*- coding: utf-8 -*-
3
+ """
4
+ Utility functions
5
+ """
6
+ import numpy as np
7
+
8
+
9
+ def inverted_softmax(array: np.ndarray) -> np.ndarray:
10
+ """
11
+ array of distances (non-negative) converted to probabilities
12
+ the lowest distance has the highest probability
13
+ """
14
+ return np.exp(-array) / np.sum(np.exp(-array))
15
+
16
+
17
+ def softmax(array: np.ndarray) -> np.ndarray:
18
+ """
19
+ array of estimations converted to probabilities
20
+ the highest prob has the highest probability
21
+ """
22
+ return np.exp(array) / np.sum(np.exp(array))
23
+
24
+
25
+ def create_prob_models(no_global_states: int = 100, window_size: int = 5) -> dict:
26
+ """
27
+ example function to create a
28
+ list of state-specific probability models
29
+ for use with viterbi_algorithm_windowed
30
+ and WindowedObservationModel
31
+
32
+ Parameters
33
+ ----------
34
+ no_global_states : int
35
+ number of global states in the HMM
36
+ window_size : int
37
+ number of states visible to the transition model
38
+
39
+ Attributes
40
+ ----------
41
+ prob_models_at_state: dict
42
+
43
+ """
44
+ models_per_state = list()
45
+ for i in range(no_global_states):
46
+ # for each global state, create list of prob models
47
+ # corresponding to local states in the window
48
+ models = list()
49
+ for j in range(window_size):
50
+ # for each local state, create a prob models
51
+ def probf(input, ref=i + j):
52
+ # dummy prob function
53
+ return int(input == ref)
54
+
55
+ models.append((probf, max(0, min(no_global_states - 1, i + j))))
56
+ models_per_state.append(models)
57
+ return models_per_state
@@ -0,0 +1,82 @@
1
+ Metadata-Version: 2.4
2
+ Name: python-hiddenmarkov
3
+ Version: 0.1.4
4
+ Summary: A simple Python package for Hidden Markov Models
5
+ Author: Silvan Peter
6
+ Author-email: Carlos Cancino-Chacón <carloscancinochacon@gmail.com>
7
+ License: MIT
8
+ Project-URL: Homepage, https://github.com/neosatrapahereje/hiddenmarkov
9
+ Keywords: hmm,hidden_markov_models
10
+ Classifier: License :: OSI Approved :: MIT License
11
+ Classifier: Programming Language :: Python
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Programming Language :: Python :: Implementation :: CPython
14
+ Classifier: Programming Language :: Python :: Implementation :: PyPy
15
+ Requires-Python: >=3.8
16
+ Description-Content-Type: text/markdown
17
+ License-File: LICENSE
18
+ Requires-Dist: numpy
19
+ Requires-Dist: scipy
20
+ Dynamic: license-file
21
+
22
+ # hiddenmarkov
23
+
24
+ [![PyPI](https://img.shields.io/pypi/v/python-hiddenmarkov)](https://pypi.org/project/python-hiddenmarkov/)
25
+
26
+ A simple Python library for Hidden Markov Models.
27
+
28
+ This library was created for educational purposes and does not aim to have the most efficient implementation.
29
+
30
+ ## Setup
31
+
32
+ Simple installation
33
+
34
+ ```
35
+ pip install python-hiddenmarkov
36
+ ```
37
+
38
+ Develop version
39
+ ```bash
40
+ git clone https://github.com/neosatrapahereje/hiddenmarkov.git
41
+ cd hiddenmarkov
42
+ pip install -e .
43
+ ```
44
+
45
+ ## Usage
46
+
47
+ Example from [Wikipedia](https://en.wikipedia.org/wiki/Viterbi_algorithm#Example)
48
+
49
+ ```python
50
+ import numpy as np
51
+ from hiddenmarkov import CategoricalObservationModel, ConstantTransitionModel, HMM
52
+
53
+ obs = ("normal", "cold", "dizzy")
54
+ observations = ("normal", "cold", "dizzy")
55
+ states = ("Healthy", "Fever")
56
+ observation_probabilities = np.array([[0.5, 0.1], [0.4, 0.3], [0.1, 0.6]])
57
+ transition_probabilities = np.array([[0.7, 0.3], [0.4, 0.6]])
58
+
59
+ observation_model = CategoricalObservationModel(
60
+ observation_probabilities, obs
61
+ )
62
+
63
+ init_distribution = np.array([0.6, 0.4])
64
+
65
+ transition_model = ConstantTransitionModel(
66
+ transition_probabilities, init_distribution
67
+ )
68
+
69
+ hmm = HMM(observation_model, transition_model, state_space=states)
70
+
71
+ path, prob = hmm.find_best_sequence(observations, log_probabilities=False)
72
+ print("Example Wikipedia")
73
+ print("Best sequence", path)
74
+ print("Expected Sequence", ["Healthy", "Healthy", "Fever"])
75
+ print("Sequence probability", prob)
76
+ print("Expected probability", 0.01512)
77
+ ```
78
+
79
+ ## Licence
80
+
81
+ 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.
@@ -0,0 +1,7 @@
1
+ hiddenmarkov/__init__.py,sha256=JKht38bCpbM_VrmbSdEF_BpEOl_NQ6QkNeNWzL5CSqE,25872
2
+ hiddenmarkov/utils.py,sha256=Y0rKPjy_CdnLkFWgs3k7OXCaRC3LINjH5vN85UUGNgE,1612
3
+ python_hiddenmarkov-0.1.4.dist-info/licenses/LICENSE,sha256=TkgLCmklI4zKi74kiE88uwDNoZShlCvRLmmL556LRPI,1101
4
+ python_hiddenmarkov-0.1.4.dist-info/METADATA,sha256=KXr4ucHG5BUq5eZf4PPzQ-j4-tq5aKNwCn6ZRGk331g,2440
5
+ python_hiddenmarkov-0.1.4.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
6
+ python_hiddenmarkov-0.1.4.dist-info/top_level.txt,sha256=qLUEvJoSPXvGUDwYIqbvVf1nUex3BN1uch2iPfoghII,13
7
+ python_hiddenmarkov-0.1.4.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (82.0.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2022 Carlos Eduardo Cancino-Chacón, Silvan Peter
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1 @@
1
+ hiddenmarkov