sensor-modeling 0.2.0__py3-none-any.whl

sensor_modeling/baseline/features.py

@@ -0,0 +1,224 @@
+"""Daily behavioural features derived from the state posterior.
+
+A baseline needs a small number of stable, interpretable quantities per day:
+how long the resident appeared to be asleep, how often they were active in the
+kitchen, how much the day was spent in states the model could not name.
+
+Two decisions here matter for the honesty of everything downstream.
+
+*Aggregate the posterior, not the argmax.* Time in a state is accumulated as
+``sum P(state | t) * dt`` rather than by counting the intervals where a state
+happened to win. A day made of 60%-confident guesses and a day made of
+99%-confident conclusions are genuinely different, and collapsing to argmax
+first would erase that difference before the baseline ever sees it.
+
+*Record how much of the day was actually observed.* Every summary carries the
+fraction of the day covered by estimates and the mean sensor coverage behind
+them. Days where the apparatus was not working are identifiable as such, so
+the baseline can refuse them instead of recording a broken sensor as a quiet
+day.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass
+from datetime import date, datetime, timedelta, tzinfo
+
+from ..fusion.estimate import StateEstimate
+from ..states.ontology import BehaviouralState
+
+logger = logging.getLogger(__name__)
+
+SECONDS_PER_DAY = 86400.0
+
+
+@dataclass(frozen=True)
+class DailySummary:
+    """Aggregated behaviour and data quality for one local calendar day.
+
+    Attributes
+    ----------
+    day
+        The local calendar date summarised.
+    hours
+        Expected hours spent in each latent state, from the posterior.
+    transitions
+        Expected number of state changes across the day.
+    coverage
+        Mean sensor coverage behind the day's estimates, in ``[0, 1]``.
+    abstention
+        Fraction of the observed day for which the model declined to name a
+        state.
+    observed
+        Fraction of the day's 24 hours covered by estimates at all.
+    """
+
+    day: date
+    hours: dict[BehaviouralState, float]
+    transitions: float
+    coverage: float
+    abstention: float
+    observed: float
+
+    def hours_in(self, state: BehaviouralState) -> float:
+        """Return expected hours spent in *state*."""
+        return self.hours.get(state, 0.0)
+
+    def is_usable(self, min_coverage: float = 0.5, min_observed: float = 0.6) -> bool:
+        """Whether the day was observed well enough to inform a baseline.
+
+        A day that fails this test is not a quiet day. It is a day the
+        apparatus did not watch, and it must be excluded rather than
+        recorded as low activity.
+        """
+        return self.coverage >= min_coverage and self.observed >= min_observed
+
+    def to_dict(self) -> dict[str, object]:
+        """Return a serialisable form of the summary."""
+        return {
+            "day": self.day.isoformat(),
+            "hours": {state.value: value for state, value in self.hours.items()},
+            "transitions": self.transitions,
+            "coverage": self.coverage,
+            "abstention": self.abstention,
+            "observed": self.observed,
+        }
+
+
+def _local_day(moment: datetime, zone: tzinfo | None) -> date:
+    """Return the local calendar date of *moment*."""
+    return (moment.astimezone(zone) if zone is not None else moment).date()
+
+
+def _split_by_day(
+    start: datetime, end: datetime, zone: tzinfo | None
+) -> list[tuple[date, float]]:
+    """Split an interval into per-local-day durations in seconds.
+
+    Days are bounded by local midnight, so a day containing a DST transition
+    is correctly 23 or 25 hours long rather than assumed to be 24.
+    """
+    if end <= start:
+        return []
+    pieces: list[tuple[date, float]] = []
+    cursor = start
+    while cursor < end:
+        local = cursor.astimezone(zone) if zone is not None else cursor
+        next_midnight_local = datetime.combine(
+            local.date() + timedelta(days=1), datetime.min.time(), tzinfo=local.tzinfo
+        )
+        boundary = min(next_midnight_local.astimezone(cursor.tzinfo), end)
+        if boundary <= cursor:  # pragma: no cover - defensive against odd zones
+            boundary = end
+        pieces.append((local.date(), (boundary - cursor).total_seconds()))
+        cursor = boundary
+    return pieces
+
+
+def summarise_days(
+    estimates: Sequence[StateEstimate],
+    *,
+    tz: tzinfo | None = None,
+    max_interval: timedelta = timedelta(hours=1),
+) -> list[DailySummary]:
+    """Aggregate a run of state estimates into per-day behavioural summaries.
+
+    Each estimate is taken to describe the interval since the previous one,
+    which is the standard filtering approximation: the posterior at ``t``
+    conditions on everything up to ``t``.
+
+    Parameters
+    ----------
+    estimates
+        State estimates in non-decreasing time order.
+    tz
+        Timezone whose calendar days are used. Defaults to the timezone of
+        the first estimate, so days align with the resident's local clock.
+    max_interval
+        Longest interval a single estimate may be held to describe. Gaps
+        beyond this are left uncounted rather than being attributed to
+        whatever state was current before the outage.
+
+    Returns
+    -------
+    list[DailySummary]
+        One summary per local day that has any observed time, in order.
+    """
+    if not estimates:
+        return []
+    ordered = list(estimates)
+    for previous, current in zip(ordered, ordered[1:]):
+        if current.at < previous.at:
+            raise ValueError("estimates must be in non-decreasing time order")
+
+    zone = tz if tz is not None else ordered[0].at.tzinfo
+    states = ordered[0].ontology.states
+
+    seconds: dict[date, dict[BehaviouralState, float]] = {}
+    observed: dict[date, float] = {}
+    coverage: dict[date, float] = {}
+    abstained: dict[date, float] = {}
+    transitions: dict[date, float] = {}
+
+    for previous, current in zip(ordered, ordered[1:]):
+        span = current.at - previous.at
+        if span <= timedelta(0) or span > max_interval:
+            continue
+        for day, duration in _split_by_day(previous.at, current.at, zone):
+            bucket = seconds.setdefault(day, dict.fromkeys(states, 0.0))
+            for index, state in enumerate(states):
+                bucket[state] += float(current.belief[index]) * duration
+            observed[day] = observed.get(day, 0.0) + duration
+            coverage[day] = coverage.get(day, 0.0) + current.completeness * duration
+            if current.abstained:
+                abstained[day] = abstained.get(day, 0.0) + duration
+
+        # Expected number of state changes over the interval, from the
+        # probability that the two posteriors disagree.
+        change = 1.0 - float((previous.belief * current.belief).sum())
+        day = _local_day(current.at, zone)
+        transitions[day] = transitions.get(day, 0.0) + change
+
+    summaries = []
+    for day in sorted(observed):
+        total = observed[day]
+        summaries.append(
+            DailySummary(
+                day=day,
+                hours={state: value / 3600.0 for state, value in seconds[day].items()},
+                transitions=transitions.get(day, 0.0),
+                coverage=coverage[day] / total if total > 0 else 0.0,
+                abstention=abstained.get(day, 0.0) / total if total > 0 else 0.0,
+                observed=total / SECONDS_PER_DAY,
+            )
+        )
+    return summaries
+
+
+def feature_series(
+    summaries: Iterable[DailySummary],
+    state: BehaviouralState,
+    *,
+    min_coverage: float = 0.5,
+    min_observed: float = 0.6,
+) -> tuple[list[date], list[float]]:
+    """Extract a per-day series of hours in *state*, skipping unusable days.
+
+    Days the apparatus did not observe are dropped rather than recorded as
+    zeros. A missing day is missing evidence; treating it as an observation
+    of no activity is the single most damaging mistake this codebase exists
+    to avoid.
+    """
+    days: list[date] = []
+    values: list[float] = []
+    for summary in summaries:
+        if not summary.is_usable(min_coverage, min_observed):
+            logger.debug(
+                "Excluding poorly observed day %s from the series", summary.day
+            )
+            continue
+        days.append(summary.day)
+        values.append(summary.hours_in(state))
+    return days, values

sensor_modeling/change_point/__init__.py

@@ -0,0 +1,13 @@
+"""Change point detection algorithms."""
+
+from .adaptive_normalization import AdaptiveNormalizer
+from .embedding_cpd import EmbeddingCPD
+from .energy_efficient import EnergyEfficientCPD
+from .genetic_optimization import GeneticOptimizationCPD
+
+__all__ = [
+    "EmbeddingCPD",
+    "EnergyEfficientCPD",
+    "AdaptiveNormalizer",
+    "GeneticOptimizationCPD",
+]

sensor_modeling/change_point/_validation.py

@@ -0,0 +1,31 @@
+"""Validation helpers for lightweight change-point detectors."""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def validate_positive_int(value: int, name: str) -> None:
+    """Require a positive integer configuration value."""
+    if isinstance(value, bool) or not isinstance(value, int) or value < 1:
+        raise ValueError(f"{name} must be a positive integer")
+
+
+def validate_series(series: np.ndarray) -> np.ndarray:
+    """Return a one-dimensional finite numeric series."""
+    values = np.asarray(series, dtype=float)
+    if values.ndim != 1:
+        raise ValueError("series must be one-dimensional")
+    if values.size == 0:
+        raise ValueError("series must contain at least one observation")
+    if not np.isfinite(values).all():
+        raise ValueError("series must contain only finite values")
+    return values
+
+
+def validate_positive_threshold(threshold: float) -> float:
+    """Return a positive finite detection threshold."""
+    value = float(threshold)
+    if not np.isfinite(value) or value <= 0:
+        raise ValueError("threshold must be positive and finite")
+    return value

sensor_modeling/change_point/adaptive_normalization.py

@@ -0,0 +1,55 @@
+"""Adaptive normalization for real-time change point detection.
+
+Based on Gupta et al. (2022) real-time preprocessing approach.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+
+import numpy as np
+
+from ..utils.plotting import plot_change_points
+from ._validation import (
+    validate_positive_int,
+    validate_positive_threshold,
+    validate_series,
+)
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class AdaptiveNormalizer:
+    """Normalize data online before detecting change points."""
+
+    window: int = 20
+
+    def __post_init__(self) -> None:
+        validate_positive_int(self.window, "window")
+
+    def fit(self, series: np.ndarray) -> AdaptiveNormalizer:
+        self.series = validate_series(series)
+        return self
+
+    def _normalize(self) -> np.ndarray:
+        normed = []
+        for i in range(len(self.series)):
+            start = max(0, i - self.window)
+            segment = self.series[start : i + 1]
+            normed.append((self.series[i] - segment.mean()) / (segment.std() + 1e-6))
+        return np.array(normed)
+
+    def predict(self, threshold: float = 3.0, plot: bool = False) -> np.ndarray:
+        """Detect change points after adaptive normalization."""
+        if not hasattr(self, "series"):
+            raise ValueError("Model must be fitted before prediction")
+        threshold = validate_positive_threshold(threshold)
+        normed = self._normalize()
+        diffs = np.abs(np.diff(normed))
+        cps = np.where(diffs > threshold)[0] + 1
+        if plot:
+            plot_change_points(self.series, cps, title="Adaptive Normalization CPD")
+        logger.info("AdaptiveNormalizer detected %d change points", len(cps))
+        return cps

sensor_modeling/change_point/embedding_cpd.py

@@ -0,0 +1,60 @@
+"""Neural embedding change point detection.
+
+Implementation inspired by Dadi et al. (2021) "ADAF".
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+
+import numpy as np
+
+from ..utils.plotting import plot_change_points
+from ._validation import (
+    validate_positive_int,
+    validate_positive_threshold,
+    validate_series,
+)
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class EmbeddingCPD:
+    """Detect change points using simple neural embeddings.
+
+    This simplified detector follows the spirit of the neural embedding
+    approach by Dadi et al. (2021). It computes rolling mean embeddings and
+    flags large embedding differences as change points.
+    """
+
+    window: int = 5
+
+    def __post_init__(self) -> None:
+        validate_positive_int(self.window, "window")
+
+    def fit(self, series: np.ndarray) -> EmbeddingCPD:
+        """Learn embeddings from the input series."""
+        self.series = validate_series(series)
+        kernel = np.ones(self.window) / self.window
+        self.embeddings = np.convolve(self.series, kernel, mode="valid")
+        logger.debug("Computed embeddings of length %d", len(self.embeddings))
+        return self
+
+    def predict(self, threshold: float = 0.2, plot: bool = False) -> np.ndarray:
+        """Return detected change point indices.
+
+        Args:
+            threshold: Difference threshold on successive embeddings.
+            plot: Whether to plot results using utility helpers.
+        """
+        if not hasattr(self, "embeddings"):
+            raise ValueError("Model must be fitted before prediction")
+        threshold = validate_positive_threshold(threshold)
+        diffs = np.abs(np.diff(self.embeddings))
+        cps = np.where(diffs > threshold)[0] + 1
+        if plot:
+            plot_change_points(self.series, cps, title="Embedding CPD")
+        logger.info("EmbeddingCPD detected %d change points", len(cps))
+        return cps

sensor_modeling/change_point/energy_efficient.py

@@ -0,0 +1,57 @@
+"""Energy-efficient change point detection.
+
+Simplified implementation of the CPAM algorithm from Cook et al. (2020).
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+
+import numpy as np
+
+from ..utils.plotting import plot_change_points
+from ._validation import (
+    validate_positive_int,
+    validate_positive_threshold,
+    validate_series,
+)
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class EnergyEfficientCPD:
+    """Detect change points using energy-efficient statistics."""
+
+    window: int = 10
+
+    def __post_init__(self) -> None:
+        validate_positive_int(self.window, "window")
+
+    def fit(self, series: np.ndarray) -> EnergyEfficientCPD:
+        self.series = validate_series(series)
+        return self
+
+    def predict(self, threshold: float = 0.5, plot: bool = False) -> np.ndarray:
+        """Detect change points based on energy across windows."""
+        if not hasattr(self, "series"):
+            raise ValueError("Model must be fitted before prediction")
+        threshold = validate_positive_threshold(threshold)
+        n = len(self.series)
+        energies = [
+            np.sum(
+                (
+                    self.series[i : i + self.window]
+                    - self.series[i : i + self.window].mean()
+                )
+                ** 2
+            )
+            for i in range(n - self.window)
+        ]
+        diffs = np.abs(np.diff(energies))
+        cps = np.where(diffs > threshold)[0] + 1
+        if plot:
+            plot_change_points(self.series, cps, title="Energy Efficient CPD")
+        logger.info("EnergyEfficientCPD detected %d change points", len(cps))
+        return cps

sensor_modeling/change_point/genetic_optimization.py

@@ -0,0 +1,65 @@
+"""Genetic algorithm based change point tuning.
+
+Simplified GA approach inspired by Awais et al. (2016).
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+
+import numpy as np
+
+from ..utils.plotting import plot_change_points
+from ._validation import validate_positive_int, validate_series
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class GeneticOptimizationCPD:
+    """Use a tiny genetic search to tune the detection threshold."""
+
+    population: int = 5
+    generations: int = 5
+
+    def __post_init__(self) -> None:
+        validate_positive_int(self.population, "population")
+        validate_positive_int(self.generations, "generations")
+
+    def fit(self, series: np.ndarray) -> GeneticOptimizationCPD:
+        self.series = validate_series(series)
+        self.threshold_ = self._ga_search()
+        logger.debug("Optimized threshold to %.3f", self.threshold_)
+        return self
+
+    def _ga_search(self) -> float:
+        rng = np.random.default_rng(0)
+        candidates = rng.uniform(0.1, 2.0, self.population)
+        for _ in range(self.generations):
+            scores = [self._fitness(th) for th in candidates]
+            best = np.argmin(scores)
+            # mutate around best
+            candidates = candidates[best] + rng.normal(0, 0.1, self.population)
+            candidates = np.clip(candidates, 0.1, 2.0)
+        return candidates[0]
+
+    def _fitness(self, threshold: float) -> float:
+        diffs = np.abs(np.diff(self.series))
+        cps = np.where(diffs > threshold)[0]
+        # simple fitness: prefer at least one cp around middle
+        target = len(self.series) // 2
+        if len(cps) == 0:
+            return target
+        return min(abs(cp - target) for cp in cps)
+
+    def predict(self, plot: bool = False) -> np.ndarray:
+        """Detect change points using GA-optimized threshold."""
+        if not hasattr(self, "threshold_"):
+            raise ValueError("Model must be fitted before prediction")
+        diffs = np.abs(np.diff(self.series))
+        cps = np.where(diffs > self.threshold_)[0] + 1
+        if plot:
+            plot_change_points(self.series, cps, title="GA Optimization CPD")
+        logger.info("GeneticOptimizationCPD detected %d change points", len(cps))
+        return cps