Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/awa-si/nhsmm

Developing neural, hierarchical, and context-aware Hidden Semi-Markov Models (HSMMs) for structured temporal pattern learning
https://github.com/awa-si/nhsmm

finance healthcare hsmm iot ml neural-networks robotics trading

Last synced: 4 months ago
JSON representation

Developing neural, hierarchical, and context-aware Hidden Semi-Markov Models (HSMMs) for structured temporal pattern learning

Awesome Lists containing this project

README 

          
# NHSMM — Neural Hidden Semi-Markov Models



* **Repository:** [NHSMM on GitHub](https://github.com/awa-si/NHSMM)

* **Interfaces:** [NHSMM-INTERFACES on GitHub](https://github.com/awa-si/nhsmm-interfaces)

* **Documentation:** [NHSMM Wiki](https://github.com/awa-si/NHSMM/wiki)

* **Article:** [Unlocking Hidden Patterns in Time – Meet NHSMM](https://medium.com/@awa-si/unlocking-hidden-patterns-in-time-meet-nhsmm-the-neural-hidden-semi-markov-model-cd3f1e2428c2)



---



> ⚠️ **Alpha stage** — NHSMM is a **proof-of-concept** and actively evolving. Public APIs may change before stable `1.0.0`.



**NHSMM** is a **modular PyTorch library** for **context-aware sequential modeling**, forming the foundation of the **State Aware Engine ([SAE](https://github.com/awa-si/SAE))**.

**[NHSMM-INTERFACES](https://github.com/awa-si/nhsmm-interfaces)** defines domain-level contracts for integrating NHSMM in diverse systems.



Designed for **developers, data scientists, and system integrators**, NHSMM enables rapid understanding, deployment, and extension of **latent state models** for domains such as **finance, IoT, robotics, health, and cybersecurity**.



[![PyPI](https://img.shields.io/pypi/v/nhsmm.svg)](https://pypi.org/project/nhsmm/) [![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0) [![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)



---



## 🌟 Highlights



* **Neural HSMM** — integrates Hidden Semi-Markov Models with neural parameterization for expressive latent dynamics.

* **Context-Aware Modulation** — initial, transition, duration, and emission distributions adapt to external covariates.

* **Flexible Architectures** — supports hierarchical and hybrid models.

* **PyTorch & GPU Ready** — scalable multi-domain deployment.

* **Modular Foundation** — for research, experimentation, and production-ready sequence models.



---



## 🧩 Overview



NHSMM explicitly models:



* **Context-Dependent State Durations** — variable dwell-times per hidden state influenced by covariates.

* **Context-Dependent Transitions** — dynamic transition probabilities adapting to time-varying features.



Suitable for **non-stationary, heterogeneous, and time-aware sequences** across real-world applications.



---



## NHSMM Project Covenant



1. **Forever Open Core** — `nhsmm` remains fully open-source and actively maintained.

2. **No Hidden Dependencies** — core library uses only open components; experimental modules (`nhsmm-interfaces`) are optional.

3. **Transparent Evolution** — research previews and pre-release interfaces are clearly marked.

4. **Community Respect** — contributions are acknowledged; experimental previews may close but knowledge remains accessible.

5. **Clear Upgrade Path** — experimental work informs SAE; core NHSMM is stable and independent.



---



## 🚀 Key Features



* **Contextual HSMM** — dynamic modulation of initial, transition, duration, and emission probabilities.

* **Duration Models** — explicit, context-aware state dwell-times.

* **Emission Models** — Gaussian, Student-t, or discrete outputs; differentiable and context-aware.

* **Transition Models** — learnable, covariate-aware with gating and temperature scaling; supports low-rank factorization.

* **Hybrid HSMM-HMM Inference** — forward-backward and Viterbi adapted for neural latent states.

* **Subclassable Distributions** — extend Initial, Duration, Transition, Emission modules.

* **Differentiable Training** — gradient-based optimization, temperature annealing, neural modulation.

* **Neural Context Encoders** — CNN, LSTM, or hybrid encoders for time-varying covariates.

* **GPU-Ready** — fully batched operations.

* **Multi-Domain Applicability** — finance, IoT, robotics, health, cybersecurity.

* **Extensible Architecture** — foundation for SAE interfaces, API integration, and research projects.

* **Hybrid Update Modes** — neural gradient-based updates, optional alternative schemes.



---



## ⚡ Performance & Scalability



* Vectorized forward-backward for **batched likelihood computation**.

* Optional low-rank transitions for **large state spaces**.

* Supports **long sequences** efficiently.

* Memory-efficient Viterbi optimized for GPU.

* Handles **variable-length sequences** with padding and masking.



---



## 📌 Milestones



| Stage               | Status  | Notes                                   |

| ------------------- | ------- | --------------------------------------- |

| Proof of Concept    | ✅ Done  | Alpha release (0.0.1-alpha)            |

| Testing/Enhancement | ⚠️ Todo | Improve performance, extend API         |

| Production Release  | ⚠️ Todo | Stable 1.0.0 release with documentation |



---



## 📦 Installation



### 🔹 From PyPI (alpha stage)



```bash

pip install nhsmm

```



### 🔹 From Source (recommended)



```bash

git clone https://github.com/awa-si/NHSMM.git

cd NHSMM

pip install -e .

```



Editable mode allows modification and testing without reinstalling.



---



## 🧠 Usage Example — Market Regime Detection



See: [State Occupancy & Duration/Transition Diagnostics](docs/test_ohlcv.md)



Works similarly for **IoT signals, health telemetry, robotics, or cybersecurity logs**.



```python

from nhsmm.models import HSMM

model = HSMM(n_states=3, n_features=5)

seq_features, canonical = model.encoder.encode(sequences)

```



---



## 🔍 Conceptual Flow



```text

External Input → Neural Initial Module (π)

                → Neural Transition Module (A)

                → Neural Duration Module (D)

                → Emission Module (Gaussian/Student-t/Discrete)

                → Forward-Backward / Viterbi → Backprop

```



* **External Input:** features, covariates, embeddings.

* **Neural Modules:** context-conditioned initial, transition, duration, and emission distributions.

* **Inference:** latent states inferred via forward-backward and Viterbi.

* **Backpropagation:** updates all neural modules jointly.



---



## 🌐 Multi-Domain Applicability



* **Security & Cyber-Physical Systems:** anomaly and hidden state detection.

* **Finance & Trading:** regime detection, forecasting, adaptive strategies.

* **IoT & Industrial:** predictive maintenance, fault detection.

* **Health & Wearables:** activity and state tracking, multimodal fusion.

* **Robotics:** behavior monitoring, safe human-robot interaction.

* **Telecommunications & Energy:** latent state monitoring, resource optimization.

* **Research & AI:** temporal modeling, neural-probabilistic experiments.



---



## ⚙️ Development



> Contributions welcome! Bug reports, feature suggestions, or documentation improvements strengthen NHSMM.



```bash

git clone https://github.com/awa-si/NHSMM.git

cd NHSMM

pip install -e ".[dev]"

pytest -v

black nhsmm

ruff check nhsmm

```



---



## Support



Development is supported via **GitHub Sponsors, Patreon, Medium**.

See [FUNDING.md](./FUNDING.md) for details.



---



## 🧾 License



Apache License 2.0 © 2024 **AWA.SI**

Full terms: [LICENSE](https://github.com/awa-si/NHSMM/blob/develop/LICENSE)



If used in academic work, please cite the repository.