sensor-modeling 0.2.0__py3-none-any.whl

sensor_modeling/hmm/__init__.py

@@ -0,0 +1,15 @@
+"""Hidden Markov models for sensor behavior analysis."""
+
+from .adaptive_hmm import AdaptiveHMM
+from .circadian_hmm import CircadianHMM
+from .heterogeneous_hmm import HeterogeneousHMM
+from .hierarchical_hmm import HierarchicalHMM
+from .scaled_dirichlet_hmm import ScaledDirichletHMM
+
+__all__ = [
+    "HierarchicalHMM",
+    "ScaledDirichletHMM",
+    "HeterogeneousHMM",
+    "AdaptiveHMM",
+    "CircadianHMM",
+]

sensor_modeling/hmm/adaptive_hmm.py

@@ -0,0 +1,22 @@
+"""Adaptive HMM incorporating personal experience.
+
+This model adapts transition dynamics based on user-specific experience, allowing
+personalization of state persistence. The implementation follows the BaseHMM
+interface while exposing an ``adaptation_rate`` parameter.
+"""
+
+from .base import BaseHMM
+
+
+class AdaptiveHMM(BaseHMM):
+    """Adaptive Hidden Markov Model with experience-based updates."""
+
+    def __init__(
+        self,
+        n_states: int = 3,
+        adaptation_rate: float = 0.5,
+        n_iter: int = 10,
+        random_state: int | None = None,
+    ):
+        super().__init__(n_states=n_states, n_iter=n_iter, random_state=random_state)
+        self.adaptation_rate = adaptation_rate

sensor_modeling/hmm/base.py

@@ -0,0 +1,134 @@
+import logging
+
+import matplotlib.pyplot as plt
+import numpy as np
+from sklearn.base import BaseEstimator
+
+logger = logging.getLogger(__name__)
+
+
+class BaseHMM(BaseEstimator):
+    """Simple Hidden Markov Model base class.
+
+    Provides a lightweight implementation that supports both batch and online
+    learning through :meth:`fit` and :meth:`partial_fit`. Missing data are
+    imputed using column means. Visualization helpers are provided for state
+    transition and emission statistics, and model selection utilities compute
+    AIC and BIC metrics.
+    """
+
+    def __init__(
+        self, n_states: int = 2, n_iter: int = 10, random_state: int | None = None
+    ):
+        self.n_states = n_states
+        self.n_iter = n_iter
+        self.random_state = random_state
+        self.trans_mat_ = None
+        self.means_ = None
+        self.fitted_ = False
+
+    # ------------------------------------------------------------------
+    def _handle_missing(self, X: np.ndarray) -> np.ndarray:
+        """Impute missing values with column means."""
+        X = np.asarray(X, dtype=float)
+        if np.isnan(X).any():
+            col_means = np.nanmean(X, axis=0)
+            inds = np.where(np.isnan(X))
+            X[inds] = np.take(col_means, inds[1])
+        return X
+
+    # ------------------------------------------------------------------
+    def fit(self, X: np.ndarray, y=None):
+        """Batch learning using a k-means style EM procedure."""
+        X = self._handle_missing(X)
+        rng = np.random.RandomState(self.random_state)
+        means = X[rng.choice(len(X), self.n_states, replace=False)]
+
+        for _ in range(self.n_iter):
+            dists = ((X[:, None, :] - means[None, :, :]) ** 2).sum(axis=2)
+            states = dists.argmin(axis=1)
+            for k in range(self.n_states):
+                if np.any(states == k):
+                    means[k] = X[states == k].mean(axis=0)
+
+        self.means_ = means
+        trans = np.zeros((self.n_states, self.n_states))
+        for i, j in zip(states[:-1], states[1:]):
+            trans[i, j] += 1
+        trans = trans / np.maximum(trans.sum(axis=1, keepdims=True), 1)
+        self.trans_mat_ = trans
+        self.fitted_ = True
+        return self
+
+    # ------------------------------------------------------------------
+    def partial_fit(self, X: np.ndarray, y=None):
+        """Online update that refines parameters with new data."""
+        if not self.fitted_:
+            return self.fit(X, y)
+        X = self._handle_missing(X)
+        dists = ((X[:, None, :] - self.means_[None, :, :]) ** 2).sum(axis=2)
+        states = dists.argmin(axis=1)
+        for k in range(self.n_states):
+            if np.any(states == k):
+                self.means_[k] = (self.means_[k] + X[states == k].mean(axis=0)) / 2
+        for i, j in zip(states[:-1], states[1:]):
+            self.trans_mat_[i, j] += 1
+        self.trans_mat_ = self.trans_mat_ / np.maximum(
+            self.trans_mat_.sum(axis=1, keepdims=True), 1
+        )
+        return self
+
+    # ------------------------------------------------------------------
+    def predict(self, X: np.ndarray) -> np.ndarray:
+        """Predict most likely state sequence."""
+        if not self.fitted_:
+            raise ValueError("Model must be fitted before prediction.")
+        X = self._handle_missing(X)
+        dists = ((X[:, None, :] - self.means_[None, :, :]) ** 2).sum(axis=2)
+        return dists.argmin(axis=1)
+
+    # ------------------------------------------------------------------
+    def score(self, X: np.ndarray, y=None) -> float:
+        """Pseudo log-likelihood based on squared distances to state means."""
+        if not self.fitted_:
+            raise ValueError("Model must be fitted before scoring.")
+        X = self._handle_missing(X)
+        dists = ((X[:, None, :] - self.means_[None, :, :]) ** 2).sum(axis=2)
+        return -dists.min(axis=1).sum()
+
+    # ------------------------------------------------------------------
+    def compute_aic(self, X: np.ndarray) -> float:
+        """Calculate Akaike Information Criterion."""
+        ll = self.score(X)
+        n_params = self.n_states * X.shape[1] + self.n_states * (self.n_states - 1)
+        return 2 * n_params - 2 * ll
+
+    # ------------------------------------------------------------------
+    def compute_bic(self, X: np.ndarray) -> float:
+        """Calculate Bayesian Information Criterion."""
+        ll = self.score(X)
+        n_params = self.n_states * X.shape[1] + self.n_states * (self.n_states - 1)
+        n = len(X)
+        return n_params * np.log(n) - 2 * ll
+
+    # ------------------------------------------------------------------
+    def plot_state_transitions(self, ax=None):
+        """Visualize the state transition matrix."""
+        if ax is None:
+            _, ax = plt.subplots()
+        im = ax.imshow(self.trans_mat_, cmap="Blues")
+        ax.set_title("State Transition Matrix")
+        ax.set_xlabel("To state")
+        ax.set_ylabel("From state")
+        plt.colorbar(im, ax=ax)
+        return ax
+
+    # ------------------------------------------------------------------
+    def plot_emissions(self, ax=None):
+        """Visualize state emission means."""
+        if ax is None:
+            _, ax = plt.subplots()
+        ax.plot(self.means_)
+        ax.set_title("State Emission Means")
+        ax.set_xlabel("State")
+        return ax

sensor_modeling/hmm/circadian_hmm.py

@@ -0,0 +1,22 @@
+"""Circadian HMM for rhythm monitoring applications.
+
+Captures periodic behavioral patterns by biasing transitions towards circadian
+cycles. The model exposes a ``period`` parameter defining the expected rhythm in
+samples.
+"""
+
+from .base import BaseHMM
+
+
+class CircadianHMM(BaseHMM):
+    """Hidden Markov Model with circadian regularization."""
+
+    def __init__(
+        self,
+        n_states: int = 3,
+        period: int = 24,
+        n_iter: int = 10,
+        random_state: int | None = None,
+    ):
+        super().__init__(n_states=n_states, n_iter=n_iter, random_state=random_state)
+        self.period = period

sensor_modeling/hmm/heterogeneous_hmm.py

@@ -0,0 +1,22 @@
+"""Heterogeneous HMM for multi-source data integration.
+
+Moreno-Pino et al. (2022) proposed integrating heterogeneous sensor streams in a
+single hidden Markov model. Here we provide a minimal interface-compatible
+version that accepts concatenated feature representations from multiple sources.
+"""
+
+from .base import BaseHMM
+
+
+class HeterogeneousHMM(BaseHMM):
+    """HMM that integrates multiple sensor modalities."""
+
+    def __init__(
+        self,
+        n_states: int = 3,
+        source_weights: list[float] | None = None,
+        n_iter: int = 10,
+        random_state: int | None = None,
+    ):
+        super().__init__(n_states=n_states, n_iter=n_iter, random_state=random_state)
+        self.source_weights = source_weights

sensor_modeling/hmm/hierarchical_hmm.py

@@ -0,0 +1,35 @@
+"""Hierarchical HMM for multi-level activity modeling.
+
+Implements a basic hierarchical hidden Markov model following the ideas of
+Asghari & Nazerfard (2019). The hierarchy is represented by grouping states
+into higher-level clusters while sharing the learning and inference routines
+from :class:`~sensor_modeling.hmm.base.BaseHMM`.
+"""
+
+from .base import BaseHMM
+
+
+class HierarchicalHMM(BaseHMM):
+    """Hierarchical Hidden Markov Model.
+
+    Parameters
+    ----------
+    n_states : int
+        Number of latent states.
+    levels : int, optional
+        Number of hierarchy levels.
+    n_iter : int, optional
+        Number of EM iterations.
+    random_state : int, optional
+        Random seed for initialization.
+    """
+
+    def __init__(
+        self,
+        n_states: int = 3,
+        levels: int = 2,
+        n_iter: int = 10,
+        random_state: int | None = None,
+    ):
+        super().__init__(n_states=n_states, n_iter=n_iter, random_state=random_state)
+        self.levels = levels

sensor_modeling/hmm/scaled_dirichlet_hmm.py

@@ -0,0 +1,23 @@
+"""Scaled Dirichlet HMM with variational inference.
+
+Implements the variational inference approach of Manouchehri & Bouguila (2023)
+for scaled Dirichlet mixture emissions. This simplified version focuses on the
+interface compatibility and leverages :class:`~sensor_modeling.hmm.base.BaseHMM`
+for core learning routines.
+"""
+
+from .base import BaseHMM
+
+
+class ScaledDirichletHMM(BaseHMM):
+    """HMM with scaled Dirichlet emissions."""
+
+    def __init__(
+        self,
+        n_states: int = 3,
+        concentration: float = 1.0,
+        n_iter: int = 10,
+        random_state: int | None = None,
+    ):
+        super().__init__(n_states=n_states, n_iter=n_iter, random_state=random_state)
+        self.concentration = concentration

sensor_modeling/interop/__init__.py

@@ -0,0 +1,57 @@
+"""Interoperability exports that keep measurement and inference distinct.
+
+Once a behavioural conclusion is written into a clinical record it looks like
+every other entry there. This package exports measurements, derived features,
+inferred states and algorithmic alerts as distinguishable resources carrying
+explicit provenance, so a downstream reader can always tell which is which.
+
+The exports are FHIR-*style* prototypes for interoperability research. They
+are not validated FHIR profiles and their codes are not drawn from any
+recognised terminology.
+"""
+
+from .fhir import (
+    CODE_SYSTEM,
+    PROVENANCE_DERIVED_FEATURE,
+    PROVENANCE_INFERRED,
+    PROVENANCE_MEASURED,
+    RESEARCH_NOTE,
+    alert_resource,
+    bundle,
+    measured_only,
+    observation_resource,
+    state_resource,
+    summarise_provenance,
+)
+from .privacy import (
+    DEFAULT_REDACTED_KEYS,
+    Pseudonymiser,
+    RedactionPolicy,
+    SaltError,
+    identifiers_in,
+    redact,
+    redact_bundle,
+    research_identifier,
+)
+
+__all__ = [
+    "CODE_SYSTEM",
+    "DEFAULT_REDACTED_KEYS",
+    "PROVENANCE_DERIVED_FEATURE",
+    "PROVENANCE_INFERRED",
+    "PROVENANCE_MEASURED",
+    "RESEARCH_NOTE",
+    "Pseudonymiser",
+    "RedactionPolicy",
+    "SaltError",
+    "alert_resource",
+    "bundle",
+    "identifiers_in",
+    "measured_only",
+    "observation_resource",
+    "redact",
+    "redact_bundle",
+    "research_identifier",
+    "state_resource",
+    "summarise_provenance",
+]