sensor-modeling 0.2.0__py3-none-any.whl

sensor_modeling/states/__init__.py

@@ -0,0 +1,23 @@
+"""Configurable ontology of latent behavioural states."""
+
+from .markov import build_generator, stationary_distribution, transition_matrix
+from .ontology import (
+    DEFAULT_DWELL,
+    DEFAULT_JUMPS,
+    DEFAULT_ROOMS,
+    DEFAULT_STATES,
+    BehaviouralState,
+    StateOntology,
+)
+
+__all__ = [
+    "DEFAULT_DWELL",
+    "DEFAULT_JUMPS",
+    "DEFAULT_ROOMS",
+    "DEFAULT_STATES",
+    "BehaviouralState",
+    "StateOntology",
+    "build_generator",
+    "stationary_distribution",
+    "transition_matrix",
+]

sensor_modeling/states/markov.py

@@ -0,0 +1,105 @@
+"""Continuous-time Markov chain mechanics shared by the latent-state models.
+
+Both the behavioural state ontology and the occupancy context model are
+continuous-time chains over a small discrete state set. The maths is the same
+in each case -- build a generator from dwell times and permitted jumps,
+exponentiate it over an arbitrary interval, solve for the stationary
+distribution -- so it lives here once rather than being written twice.
+
+Working in continuous time is what lets both models accept observations that
+arrive whenever they happen to arrive, without resampling anything onto a
+common grid.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+
+import numpy as np
+from scipy.linalg import expm
+
+
+def build_generator(rates: np.ndarray, jumps: np.ndarray) -> np.ndarray:
+    """Build a transition rate matrix from exit rates and permitted jumps.
+
+    Parameters
+    ----------
+    rates
+        Total exit rate of each state, in transitions per second. The inverse
+        of the state's mean dwell time.
+    jumps
+        Non-negative ``(n, n)`` weights describing where each state may go.
+        Rows are normalised to distribute that state's exit rate; the
+        diagonal is ignored. A row of zeros falls back to a uniform jump to
+        every other state, so a state can never become a trap by accident.
+
+    Returns
+    -------
+    numpy.ndarray
+        The generator ``Q``, whose rows sum to zero.
+    """
+    exit_rates = np.asarray(rates, dtype=float)
+    weights = np.array(jumps, dtype=float, copy=True)
+    size = exit_rates.size
+    if weights.shape != (size, size):
+        raise ValueError("jumps must be a square matrix matching the number of states")
+    if exit_rates.min() <= 0.0 or not np.all(np.isfinite(exit_rates)):
+        raise ValueError("exit rates must be positive and finite")
+    if weights.min() < 0.0 or not np.all(np.isfinite(weights)):
+        raise ValueError("jump weights must be non-negative and finite")
+
+    np.fill_diagonal(weights, 0.0)
+    row_totals = weights.sum(axis=1)
+    uniform = (np.ones((size, size)) - np.eye(size)) / max(size - 1, 1)
+    weights = np.where(row_totals[:, None] > 0.0, weights, uniform)
+    row_totals = weights.sum(axis=1)
+
+    generator: np.ndarray = weights * (exit_rates / row_totals)[:, None]
+    np.fill_diagonal(generator, -exit_rates)
+    return generator
+
+
+def transition_matrix(generator: np.ndarray, seconds: float) -> np.ndarray:
+    """Return ``expm(Q * seconds)`` as a row-stochastic matrix.
+
+    A non-positive interval yields the identity, so repeated updates at the
+    same instant leave a belief untouched.
+    """
+    matrix = np.asarray(generator, dtype=float)
+    if seconds <= 0.0:
+        return np.eye(matrix.shape[0])
+    return _cached_transition(matrix.tobytes(), matrix.shape[0], round(seconds, 3))
+
+
+def stationary_distribution(generator: np.ndarray) -> np.ndarray:
+    """Return the long-run distribution implied by *generator*.
+
+    This is the most defensible prior for a filter that has seen no evidence
+    yet: it is what the declared dynamics say about the system on average.
+    """
+    matrix = np.asarray(generator, dtype=float)
+    size = matrix.shape[0]
+    system = np.vstack([matrix.T, np.ones(size)])
+    target = np.zeros(size + 1)
+    target[-1] = 1.0
+    solution, *_ = np.linalg.lstsq(system, target, rcond=None)
+    distribution = np.clip(solution, 0.0, None)
+    total = distribution.sum()
+    if total <= 0.0:
+        return np.full(size, 1.0 / size)
+    normalised: np.ndarray = distribution / total
+    return normalised
+
+
+@lru_cache(maxsize=512)
+def _cached_transition(generator_bytes: bytes, size: int, seconds: float) -> np.ndarray:
+    """Exponentiate a generator, caching on the rounded interval.
+
+    Ambient streams produce the same handful of intervals over and over, so
+    caching keeps the matrix exponential off the hot path of online updates.
+    """
+    generator = np.frombuffer(generator_bytes, dtype=float).reshape(size, size)
+    matrix = np.clip(np.asarray(expm(generator * seconds), dtype=float), 0.0, None)
+    row_sums = matrix.sum(axis=1, keepdims=True)
+    stochastic: np.ndarray = matrix / np.where(row_sums > 0.0, row_sums, 1.0)
+    return stochastic

sensor_modeling/states/ontology.py

@@ -0,0 +1,238 @@
+"""The configurable ontology of latent behavioural states.
+
+The states here are deliberately weaker than the activities of daily living a
+clinician would name. ``KITCHEN_ACTIVITY`` says the resident appears to be
+active in the kitchen; it does not say they ate. Claiming food intake needs
+evidence that a contact sensor cannot supply, so the ontology stops where the
+evidence stops and leaves the stronger claim to be made -- or not -- further
+downstream.
+
+Transitions are modelled in continuous time. Ambient observations arrive
+asynchronously and irregularly, so the transition operator has to be defined
+for an arbitrary elapsed interval rather than for a fixed time step. A
+continuous-time Markov chain gives exactly that: the generator encodes how
+long a state typically persists, and the transition matrix over any interval
+follows from its matrix exponential.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from datetime import timedelta
+from enum import Enum
+
+import numpy as np
+
+from .markov import build_generator, stationary_distribution, transition_matrix
+
+
+class BehaviouralState(str, Enum):
+    """A latent behavioural state of the monitored resident.
+
+    ``UNKNOWN`` is not a latent state the chain can occupy. It is the value an
+    estimator returns when it declines to commit, and is excluded from the
+    ontology's state vector.
+    """
+
+    AWAY = "away"
+    """Not in the home."""
+
+    HOME_ACTIVE = "home_active"
+    """At home and moving about, without a more specific location."""
+
+    HOME_INACTIVE = "home_inactive"
+    """At home, awake, and largely stationary."""
+
+    SLEEPING = "sleeping"
+    """In bed with sustained low movement."""
+
+    BED_AWAKE = "bed_awake"
+    """In bed but moving; distinguishable from sleep only with bed sensing."""
+
+    BATHROOM_ACTIVITY = "bathroom_activity"
+    """Active in the bathroom. Not a claim about toileting."""
+
+    KITCHEN_ACTIVITY = "kitchen_activity"
+    """Active in the kitchen. Not a claim about eating or drinking."""
+
+    UNKNOWN = "unknown"
+    """Insufficient evidence to commit to any state."""
+
+
+#: The states a resident can actually occupy, in canonical vector order.
+DEFAULT_STATES: tuple[BehaviouralState, ...] = (
+    BehaviouralState.AWAY,
+    BehaviouralState.HOME_ACTIVE,
+    BehaviouralState.HOME_INACTIVE,
+    BehaviouralState.SLEEPING,
+    BehaviouralState.BED_AWAKE,
+    BehaviouralState.BATHROOM_ACTIVITY,
+    BehaviouralState.KITCHEN_ACTIVITY,
+)
+
+#: Typical persistence of each state, used to build the generator matrix.
+DEFAULT_DWELL: dict[BehaviouralState, timedelta] = {
+    BehaviouralState.AWAY: timedelta(hours=3),
+    BehaviouralState.HOME_ACTIVE: timedelta(minutes=20),
+    BehaviouralState.HOME_INACTIVE: timedelta(hours=1),
+    BehaviouralState.SLEEPING: timedelta(hours=3),
+    BehaviouralState.BED_AWAKE: timedelta(minutes=20),
+    BehaviouralState.BATHROOM_ACTIVITY: timedelta(minutes=6),
+    BehaviouralState.KITCHEN_ACTIVITY: timedelta(minutes=15),
+}
+
+#: Room each state implies, where it implies one. States without a room make
+#: no spatial claim and receive no room-specific evidence.
+DEFAULT_ROOMS: dict[BehaviouralState, str | None] = {
+    BehaviouralState.AWAY: None,
+    BehaviouralState.HOME_ACTIVE: None,
+    BehaviouralState.HOME_INACTIVE: None,
+    BehaviouralState.SLEEPING: "bedroom",
+    BehaviouralState.BED_AWAKE: "bedroom",
+    BehaviouralState.BATHROOM_ACTIVITY: "bathroom",
+    BehaviouralState.KITCHEN_ACTIVITY: "kitchen",
+}
+
+#: Plausible state-to-state moves. Reaching or leaving the home passes through
+#: a general at-home state rather than teleporting out of bed to the street.
+DEFAULT_JUMPS: dict[BehaviouralState, tuple[BehaviouralState, ...]] = {
+    BehaviouralState.AWAY: (BehaviouralState.HOME_ACTIVE,),
+    BehaviouralState.HOME_ACTIVE: (
+        BehaviouralState.AWAY,
+        BehaviouralState.HOME_INACTIVE,
+        BehaviouralState.BED_AWAKE,
+        BehaviouralState.BATHROOM_ACTIVITY,
+        BehaviouralState.KITCHEN_ACTIVITY,
+    ),
+    BehaviouralState.HOME_INACTIVE: (
+        BehaviouralState.HOME_ACTIVE,
+        BehaviouralState.BED_AWAKE,
+        BehaviouralState.BATHROOM_ACTIVITY,
+        BehaviouralState.KITCHEN_ACTIVITY,
+    ),
+    BehaviouralState.SLEEPING: (BehaviouralState.BED_AWAKE,),
+    BehaviouralState.BED_AWAKE: (
+        BehaviouralState.SLEEPING,
+        BehaviouralState.HOME_ACTIVE,
+        BehaviouralState.BATHROOM_ACTIVITY,
+    ),
+    BehaviouralState.BATHROOM_ACTIVITY: (
+        BehaviouralState.HOME_ACTIVE,
+        BehaviouralState.HOME_INACTIVE,
+        BehaviouralState.BED_AWAKE,
+    ),
+    BehaviouralState.KITCHEN_ACTIVITY: (
+        BehaviouralState.HOME_ACTIVE,
+        BehaviouralState.HOME_INACTIVE,
+    ),
+}
+
+
+@dataclass(frozen=True)
+class StateOntology:
+    """A configurable set of latent states with continuous-time dynamics.
+
+    Parameters
+    ----------
+    states
+        Latent states in canonical vector order. ``UNKNOWN`` is not allowed.
+    dwell
+        Mean persistence of each state. Longer dwell means the chain is more
+        reluctant to leave, which is what supplies temporal smoothing.
+    rooms
+        Room each state implies, or ``None`` when it makes no spatial claim.
+    jumps
+        Permitted destinations from each state. Defaults to every other state.
+    """
+
+    states: tuple[BehaviouralState, ...] = DEFAULT_STATES
+    dwell: Mapping[BehaviouralState, timedelta] = field(
+        default_factory=lambda: dict(DEFAULT_DWELL)
+    )
+    rooms: Mapping[BehaviouralState, str | None] = field(
+        default_factory=lambda: dict(DEFAULT_ROOMS)
+    )
+    jumps: Mapping[BehaviouralState, Sequence[BehaviouralState]] = field(
+        default_factory=lambda: dict(DEFAULT_JUMPS)
+    )
+
+    def __post_init__(self) -> None:
+        """Validate the ontology and precompute its generator."""
+        if len(self.states) < 2:
+            raise ValueError("an ontology needs at least two states")
+        if len(set(self.states)) != len(self.states):
+            raise ValueError("states must be unique")
+        if BehaviouralState.UNKNOWN in self.states:
+            raise ValueError(
+                "UNKNOWN is an estimator abstention, not an occupiable state"
+            )
+        for state in self.states:
+            duration = self.dwell.get(state)
+            if duration is None:
+                raise ValueError(f"no mean dwell time declared for {state.value}")
+            if duration <= timedelta(0):
+                raise ValueError(f"mean dwell time for {state.value} must be positive")
+        object.__setattr__(self, "_generator", self._build_generator())
+
+    # ------------------------------------------------------------------
+    @property
+    def size(self) -> int:
+        """Number of latent states."""
+        return len(self.states)
+
+    def index(self, state: BehaviouralState) -> int:
+        """Return the vector position of *state*."""
+        return self.states.index(state)
+
+    def room_of(self, state: BehaviouralState) -> str | None:
+        """Return the room *state* implies, if any."""
+        return self.rooms.get(state)
+
+    def states_in_room(self, room: str) -> tuple[BehaviouralState, ...]:
+        """Return the states that imply presence in *room*."""
+        return tuple(s for s in self.states if self.rooms.get(s) == room)
+
+    # ------------------------------------------------------------------
+    def _build_generator(self) -> np.ndarray:
+        """Build the continuous-time transition rate matrix.
+
+        A state with mean dwell ``d`` leaves at total rate ``1/d``, split
+        evenly across its permitted destinations.
+        """
+        size = self.size
+        rates = np.array(
+            [1.0 / self.dwell[state].total_seconds() for state in self.states],
+            dtype=float,
+        )
+        jumps = np.zeros((size, size), dtype=float)
+        for row, state in enumerate(self.states):
+            for target in self.jumps.get(state, self.states):
+                if target in self.states and target is not state:
+                    jumps[row, self.index(target)] = 1.0
+        return build_generator(rates, jumps)
+
+    @property
+    def generator(self) -> np.ndarray:
+        """The continuous-time generator matrix, in transitions per second."""
+        return np.asarray(object.__getattribute__(self, "_generator"))
+
+    def transition(self, elapsed: timedelta) -> np.ndarray:
+        """Return ``P(Z_{t+elapsed} | Z_t)`` as a row-stochastic matrix."""
+        return transition_matrix(self.generator, elapsed.total_seconds())
+
+    def stationary(self) -> np.ndarray:
+        """Return the stationary distribution implied by the generator.
+
+        Used as the default prior: before any evidence arrives, the most
+        defensible belief is the long-run behaviour of the declared dynamics.
+        """
+        return stationary_distribution(self.generator)
+
+    def uniform(self) -> np.ndarray:
+        """Return a uniform belief over the latent states."""
+        return np.full(self.size, 1.0 / self.size)
+
+    def labels(self) -> list[str]:
+        """Return the state names in vector order."""
+        return [state.value for state in self.states]

sensor_modeling/utils/__init__.py

@@ -0,0 +1,41 @@
+"""Utility helpers for the sensor modeling package."""
+
+from .data_io import (
+    SensorDataset,
+    export_analysis_results,
+    simulate_sensor_data,
+)
+from .logging_config import setup_logging
+from .missing import (
+    MissingDataResult,
+    forward_fill,
+    handle_missing_data,
+    interpolate_linear,
+)
+from .plotting import (
+    plot_benchmark_results,
+    plot_change_points,
+    plot_quantile_intervals,
+    plot_sensor_activity_patterns,
+)
+from .validation import (
+    create_model_comparison_report,
+    validate_model_predictions,
+)
+
+__all__ = [
+    "SensorDataset",
+    "simulate_sensor_data",
+    "export_analysis_results",
+    "plot_sensor_activity_patterns",
+    "plot_quantile_intervals",
+    "plot_change_points",
+    "plot_benchmark_results",
+    "validate_model_predictions",
+    "create_model_comparison_report",
+    "setup_logging",
+    "MissingDataResult",
+    "forward_fill",
+    "handle_missing_data",
+    "interpolate_linear",
+]

sensor_modeling/utils/data_io.py

@@ -0,0 +1,199 @@
+"""Data loading and simulation utilities for sensor modeling."""
+
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Mapping
+from dataclasses import dataclass
+from os import PathLike
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+logger = logging.getLogger(__name__)
+
+FilePath = str | PathLike[str]
+
+
+def read_sensor_csv(
+    path: FilePath, timestamp_col: str = "timestamp", **kwargs
+) -> pd.DataFrame:
+    """Read a sensor CSV using the public loader contract.
+
+    Supported layouts are:
+
+    - a named timestamp column, by default ``timestamp``
+    - an unnamed first column created by ``DataFrame.to_csv(index=True)``
+    - a plain tabular sensor matrix with no timestamp index
+    """
+    df = pd.read_csv(path, **kwargs)
+    if timestamp_col in df.columns:
+        df[timestamp_col] = pd.to_datetime(df[timestamp_col])
+        return df.set_index(timestamp_col).sort_index()
+
+    first_col = df.columns[0] if len(df.columns) else None
+    if isinstance(first_col, str) and first_col.startswith("Unnamed:"):
+        parsed_index = pd.to_datetime(df[first_col], errors="coerce")
+        if parsed_index.notna().all():
+            df = df.drop(columns=[first_col])
+            df.index = parsed_index
+            return df.sort_index()
+
+    return df
+
+
+@dataclass
+class SensorDataset:
+    """Unified in-memory representation of sensor time series data.
+
+    Parameters
+    ----------
+    data : pd.DataFrame
+        DataFrame indexed by timestamps with one column per sensor.
+    """
+
+    data: pd.DataFrame
+
+    @classmethod
+    def from_csv(
+        cls, path: FilePath, timestamp_col: str = "timestamp", **kwargs
+    ) -> SensorDataset:
+        """Load sensor data from a CSV file."""
+        df = read_sensor_csv(path, timestamp_col=timestamp_col, **kwargs)
+        logger.info("Loaded %d rows from %s", len(df), path)
+        return cls(df)
+
+    def to_dataframe(self) -> pd.DataFrame:
+        """Return the underlying DataFrame."""
+        return self.data
+
+    def to_event_sequences(self, sensor: str) -> list[np.ndarray]:
+        """Convert binary activations for *sensor* into per-day event times."""
+        if sensor not in self.data.columns:
+            raise KeyError(f"Sensor '{sensor}' not found in dataset")
+        df = self.data[self.data[sensor] > 0]
+        grouped = df.groupby(df.index.date)
+        events: list[np.ndarray] = []
+        for _, day_df in grouped:
+            times = day_df.index
+            events.append(
+                np.array([t.hour + t.minute / 60.0 for t in times], dtype=float)
+            )
+        return events
+
+
+def simulate_sensor_data(
+    n_days: int = 60,
+    n_sensors: int = 4,
+    seed: int = 42,
+    interaction_strength: float = 0.3,
+) -> SensorDataset:
+    """Simulate realistic binary sensor activations."""
+    if n_days < 1:
+        raise ValueError("n_days must be at least 1")
+    if n_sensors < 1:
+        raise ValueError("n_sensors must be at least 1")
+    if interaction_strength < 0:
+        raise ValueError("interaction_strength must be non-negative")
+
+    rng = np.random.default_rng(seed)
+    n_intervals = n_days * 96
+    time_index = pd.date_range("2024-01-01", periods=n_intervals, freq="15min")
+    sensor_names = [f"sensor_{i}" for i in range(n_sensors)]
+
+    data = pd.DataFrame(index=time_index, columns=sensor_names)
+    sensor_data = np.zeros((n_intervals, n_sensors))
+
+    activity_patterns = []
+    for i in range(n_sensors):
+        morning_peak = 24 + i * 4
+        evening_peak = 72 + i * 2
+        activity_patterns.append(
+            {
+                "morning_start": morning_peak,
+                "morning_end": morning_peak + 12,
+                "morning_prob": 0.4 - i * 0.05,
+                "evening_start": evening_peak,
+                "evening_end": evening_peak + 16,
+                "evening_prob": 0.5 - i * 0.06,
+                "baseline_prob": 0.02 + i * 0.01,
+            }
+        )
+
+    for day in range(n_days):
+        day_start = day * 96
+        for sensor_idx, pattern in enumerate(activity_patterns):
+            day_probs = np.full(96, pattern["baseline_prob"])
+            day_probs[pattern["morning_start"] : pattern["morning_end"]] = pattern[
+                "morning_prob"
+            ]
+            evening_end = min(pattern["evening_start"] + 16, 96)
+            day_probs[pattern["evening_start"] : evening_end] = pattern["evening_prob"]
+            for t in range(96):
+                if day_start + t < n_intervals:
+                    base_activation = rng.binomial(1, day_probs[t])
+                    sensor_data[day_start + t, sensor_idx] = base_activation
+
+    if interaction_strength > 0:
+        for day in range(n_days):
+            day_start = day * 96
+            for t in range(1, 96):
+                global_t = day_start + t
+                if global_t >= n_intervals:
+                    break
+                for target_sensor in range(n_sensors):
+                    if sensor_data[global_t, target_sensor] == 0:
+                        influence_prob = 0.0
+                        for source_sensor in range(n_sensors):
+                            if source_sensor == target_sensor:
+                                continue
+                            for lag in range(1, 4):
+                                if (
+                                    global_t - lag >= 0
+                                    and sensor_data[global_t - lag, source_sensor] == 1
+                                ):
+                                    if abs(source_sensor - target_sensor) == 1:
+                                        influence_prob += (
+                                            interaction_strength
+                                            * 0.3
+                                            * (0.8 ** (lag - 1))
+                                        )
+                                    else:
+                                        influence_prob += (
+                                            interaction_strength
+                                            * 0.1
+                                            * (0.8 ** (lag - 1))
+                                        )
+                        if influence_prob > rng.random():
+                            sensor_data[global_t, target_sensor] = 1
+
+    for i, sensor in enumerate(sensor_names):
+        data[sensor] = sensor_data[:, i]
+
+    return SensorDataset(data.astype(int))
+
+
+def export_analysis_results(
+    results: Mapping[str, object], filename: FilePath = "sensor_analysis_results"
+) -> dict[str, Path]:
+    """Export analysis results to JSON/CSV files and return written paths."""
+    json_path = Path(f"{filename}.json")
+    json_path.parent.mkdir(parents=True, exist_ok=True)
+    json_path.write_text(
+        json.dumps(results, indent=2, default=str),
+        encoding="utf-8",
+    )
+    logger.info("Results exported to %s", json_path)
+
+    output_paths = {"json": json_path}
+    causality_results = results.get("causality_results")
+    if isinstance(causality_results, pd.DataFrame):
+        csv_path = Path(f"{filename}_causality.csv")
+        csv_path.parent.mkdir(parents=True, exist_ok=True)
+        causality_results.to_csv(csv_path, index=False)
+        output_paths["causality_csv"] = csv_path
+        logger.info("Causality results exported to %s", csv_path)
+
+    return output_paths

sensor_modeling/utils/logging_config.py

@@ -0,0 +1,10 @@
+"""Logging configuration helpers."""
+
+from __future__ import annotations
+
+import logging
+
+
+def setup_logging(level: int = logging.INFO) -> None:
+    """Configure basic logging for the package."""
+    logging.basicConfig(level=level, format="[%(levelname)s] %(name)s: %(message)s")