sensor-modeling 0.2.0__py3-none-any.whl

sensor_modeling/fusion/defaults.py

@@ -0,0 +1,296 @@
+"""Sensible default observation models derived from the sensor registry.
+
+Hand-writing an emission model per sensor is the right thing to do for a study
+that has calibration data. For everything else -- a first deployment, an
+ablation sweep, the worked example -- the registry already says enough to build
+a defensible model: the modality says what kind of likelihood applies, and the
+room says which states should expect the sensor to fire.
+
+Deriving the models from declarations rather than from sensor names is what
+keeps the platform sensor-agnostic. Adding a new device to a deployment means
+adding a :class:`~sensor_modeling.observations.registry.SensorSpec`, not
+editing inference code.
+
+The defaults are starting points and are meant to be replaced by fitted values
+where data allows. They are deliberately conservative: rates differ between
+states by roughly an order of magnitude rather than by several, so no single
+sensor can dominate the posterior on its own.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+
+from ..observations.registry import SensorRegistry, SensorSpec
+from ..observations.types import Modality, ObservationKind
+from ..observations.units import Unit
+from ..states.ontology import BehaviouralState, StateOntology
+from .emissions import (
+    BernoulliEmission,
+    BetaEmission,
+    EmissionModel,
+    GaussianEmission,
+    PoissonEventEmission,
+)
+
+logger = logging.getLogger(__name__)
+
+S = BehaviouralState
+
+
+@dataclass
+class EmissionDefaults:
+    """Rate and level assumptions used to build default emission models.
+
+    Parameters
+    ----------
+    active_rate
+        Activations per hour a room sensor produces when the resident is in
+        that room and fully active.
+    activity_levels
+        Fraction of ``active_rate`` each state actually generates. This is the
+        distinction between *where* a state puts the resident and *how much
+        they move* while there, and it is not optional: a sleeping person is
+        in the bedroom but almost perfectly still, so a bedroom sensor's
+        silence is expected during sleep rather than evidence against it.
+    idle_rate
+        Background rate: false activations, pets, draughts. Never zero, so a
+        single stray activation cannot rule a state out permanently.
+    away_rate
+        Rate while the resident is out. Non-zero because visitors exist.
+    door_rate
+        Rate for an entrance door in the states either side of a crossing.
+    wearable_levels
+        Expected wearable activity magnitude per state.
+    wearable_sigma
+        Standard deviation of the wearable signal.
+    presence_probability
+        Probability a personal beacon reads in-range in each home state.
+    bed_probability
+        Probability a bed sensor reads occupied in the in-bed states.
+    """
+
+    active_rate: float = 40.0
+    activity_levels: dict[BehaviouralState, float] | None = None
+    idle_rate: float = 0.15
+    away_rate: float = 0.05
+    door_rate: float = 4.0
+    wearable_levels: dict[BehaviouralState, float] | None = None
+    wearable_sigma: float = 0.35
+    presence_probability: float = 0.95
+    bed_probability: float = 0.97
+
+    def __post_init__(self) -> None:
+        """Validate the assumptions and supply per-state defaults."""
+        rates = (self.active_rate, self.idle_rate, self.away_rate, self.door_rate)
+        if any(rate < 0 for rate in rates):
+            raise ValueError("emission rates must be non-negative")
+        if self.wearable_sigma <= 0:
+            raise ValueError("wearable_sigma must be positive")
+        for name in ("presence_probability", "bed_probability"):
+            value = float(getattr(self, name))
+            if not 0.0 <= value <= 1.0:
+                raise ValueError(f"{name} must lie in [0, 1]")
+        if self.activity_levels is None:
+            self.activity_levels = {
+                S.SLEEPING: 0.02,
+                S.BED_AWAKE: 0.35,
+                S.HOME_INACTIVE: 0.25,
+                S.HOME_ACTIVE: 1.0,
+                S.KITCHEN_ACTIVITY: 1.0,
+                S.BATHROOM_ACTIVITY: 1.0,
+                S.AWAY: 0.0,
+            }
+        if any(level < 0 for level in self.activity_levels.values()):
+            raise ValueError("activity levels must be non-negative")
+        if self.wearable_levels is None:
+            self.wearable_levels = {
+                S.SLEEPING: 0.05,
+                S.BED_AWAKE: 0.3,
+                S.HOME_INACTIVE: 0.4,
+                S.HOME_ACTIVE: 1.4,
+                S.KITCHEN_ACTIVITY: 1.1,
+                S.BATHROOM_ACTIVITY: 0.9,
+                S.AWAY: 1.8,
+            }
+
+
+def _event_rates(
+    spec: SensorSpec, ontology: StateOntology, defaults: EmissionDefaults
+) -> dict[BehaviouralState, float]:
+    """Return per-state activation rates for an event sensor.
+
+    A rate is the product of two independent things: whether the state puts
+    the resident within range of this sensor, and how much they move while in
+    that state. Conflating the two is the classic way to make a bed sensor
+    and a bedroom motion sensor argue with each other all night.
+    """
+    levels = defaults.activity_levels or {}
+    located = {ontology.room_of(state) for state in ontology.states}
+    # A state that names no room could put the resident in any of the rooms
+    # the ontology does name, plus somewhere unmonitored, so its rate for any
+    # one sensor is diluted across those possibilities.
+    spread = max(len({room for room in located if room}) + 1, 1)
+
+    rates: dict[BehaviouralState, float] = {}
+    for state in ontology.states:
+        activity = float(levels.get(state, 0.5))
+        room = ontology.room_of(state)
+        if state is S.AWAY:
+            rate = defaults.away_rate
+        elif spec.room is None:
+            rate = defaults.active_rate * activity
+        elif room == spec.room:
+            rate = defaults.active_rate * activity
+        elif room is None:
+            rate = defaults.active_rate * activity / spread
+        else:
+            rate = defaults.idle_rate
+        rates[state] = max(rate, defaults.idle_rate)
+    return rates
+
+
+def _door_rates(
+    ontology: StateOntology, defaults: EmissionDefaults
+) -> dict[BehaviouralState, float]:
+    """Return per-state rates for an entrance door.
+
+    A door fires at the boundary between being in and being out, so it is
+    most informative about the states either side of a crossing rather than
+    about any state in isolation.
+    """
+    return {
+        state: (
+            defaults.door_rate
+            if state in (S.AWAY, S.HOME_ACTIVE)
+            else defaults.idle_rate
+        )
+        for state in ontology.states
+    }
+
+
+def default_emission_for(
+    spec: SensorSpec,
+    ontology: StateOntology,
+    defaults: EmissionDefaults | None = None,
+) -> EmissionModel | None:
+    """Build a default observation model for one declared sensor.
+
+    Returns
+    -------
+    EmissionModel | None
+        ``None`` when the modality carries no information about behavioural
+        state. A room-occupancy count, for instance, is evidence about *who
+        is present* and belongs to the occupancy layer, not here.
+    """
+    settings = defaults or EmissionDefaults()
+    levels = settings.wearable_levels or {}
+
+    if spec.modality is Modality.DOOR:
+        return PoissonEventEmission(
+            spec.sensor_id, rates=_door_rates(ontology, settings)
+        )
+
+    if spec.kind is ObservationKind.EVENT:
+        return PoissonEventEmission(
+            spec.sensor_id, rates=_event_rates(spec, ontology, settings)
+        )
+
+    if spec.modality is Modality.BED_PRESSURE:
+        occupied = {
+            state: (
+                settings.bed_probability
+                if state in (S.SLEEPING, S.BED_AWAKE)
+                else 1.0 - settings.bed_probability
+            )
+            for state in ontology.states
+        }
+        return BernoulliEmission(spec.sensor_id, probabilities=occupied)
+
+    if spec.modality in (Modality.WEARABLE_MOTION, Modality.WEARABLE_PHYSIOLOGY):
+        return GaussianEmission(
+            spec.sensor_id,
+            means={state: levels.get(state, 0.5) for state in ontology.states},
+            sigmas={state: settings.wearable_sigma for state in ontology.states},
+            # A wearable samples far more often than a contact sensor fires.
+            # Without this discount its sampling rate, rather than its
+            # informativeness, would decide how much it counts.
+            weight=0.25,
+        )
+
+    if spec.modality is Modality.PROXIMITY:
+        present = {
+            state: (
+                1.0 - settings.presence_probability
+                if state is S.AWAY
+                else settings.presence_probability
+            )
+            for state in ontology.states
+        }
+        return BernoulliEmission(spec.sensor_id, probabilities=present)
+
+    if spec.modality is Modality.RADAR:
+        if spec.unit is Unit.PROBABILITY:
+            return BetaEmission(
+                spec.sensor_id,
+                means={
+                    state: (0.05 if state is S.AWAY else 0.9)
+                    for state in ontology.states
+                },
+                weight=0.25,
+            )
+        # A track count is presence evidence: zero people means nobody home.
+        return GaussianEmission(
+            spec.sensor_id,
+            means={
+                state: (0.05 if state is S.AWAY else 1.0) for state in ontology.states
+            },
+            sigmas={state: 0.7 for state in ontology.states},
+            weight=0.25,
+        )
+
+    logger.debug(
+        "No default emission model for modality %s ('%s')",
+        spec.modality.value,
+        spec.sensor_id,
+    )
+    return None
+
+
+def _group_sizes(registry: SensorRegistry) -> dict[str, int]:
+    """Count how many sensors share each declared redundancy group."""
+    sizes: dict[str, int] = {}
+    for spec in registry:
+        if spec.redundancy_group:
+            sizes[spec.redundancy_group] = sizes.get(spec.redundancy_group, 0) + 1
+    return sizes
+
+
+def default_emissions(
+    registry: SensorRegistry,
+    ontology: StateOntology,
+    defaults: EmissionDefaults | None = None,
+) -> list[EmissionModel]:
+    """Build default observation models for every sensor that has one.
+
+    Sensors sharing a ``redundancy_group`` have their evidence weight divided
+    across the group. The filter combines sensors as conditionally
+    independent given the state, so without this, several views of the same
+    physical event accumulate as several independent observations and drive
+    the posterior toward certainty it has not earned.
+    """
+    sizes = _group_sizes(registry)
+    models: list[EmissionModel] = []
+    for spec in registry:
+        model = default_emission_for(spec, ontology, defaults)
+        if model is None:
+            continue
+        if spec.redundancy_group:
+            model.weight /= sizes[spec.redundancy_group]
+        models.append(model)
+    if not models:
+        raise ValueError(
+            "no sensor in the registry carries information about behavioural state"
+        )
+    return models

sensor_modeling/fusion/emissions.py

@@ -0,0 +1,339 @@
+"""Modality-specific observation models.
+
+Each emission model answers one question: given that the resident is in state
+``z``, how surprising is what this sensor reported over the last interval?
+Keeping that question per-sensor is what makes the fusion layer genuinely
+multimodal -- modalities with different units, sampling rates and temporal
+semantics each get an appropriate likelihood, and the filter combines them.
+
+Two mechanisms are shared by every model.
+
+*Tempering.* The raw log-likelihood is multiplied by the sensor's reliability
+and by the probability that what it saw was generated by the monitored
+resident. A reliability of zero contributes exactly nothing, which is the
+formal statement of "a broken sensor is missing evidence, not evidence of
+inactivity". This is a power-likelihood weighting in the sense of generalised
+Bayesian updating, and it degrades smoothly rather than switching a sensor
+abruptly on and off.
+
+*Centring.* Log-likelihoods are shifted so the best-supported state sits at
+zero. State-independent constants cancel under normalisation anyway, and
+centring makes each model's output directly readable as "how much worse is
+this state than the best one, according to this sensor".
+"""
+
+from __future__ import annotations
+
+import math
+from abc import ABC, abstractmethod
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from datetime import timedelta
+
+import numpy as np
+
+from ..observations.observation import Observation
+from ..states.ontology import BehaviouralState, StateOntology
+
+#: Smallest event rate any state may have, in events per second. A state that
+#: "never" triggers a sensor still needs a positive rate, or a single spurious
+#: activation would drive its posterior to exactly zero and make it
+#: unrecoverable for the rest of the deployment.
+MIN_RATE = 1e-9
+
+#: Floor applied to Bernoulli and Beta parameters for the same reason.
+EPSILON = 1e-6
+
+
+@dataclass
+class EmissionModel(ABC):
+    """Base class for per-sensor observation models.
+
+    Parameters
+    ----------
+    sensor_id
+        Sensor this model interprets.
+    weight
+        Evidence weight for the modality. Fast-sampling sensors accumulate
+        more log-likelihood per interval simply by reporting more often; this
+        multiplier lets a deployment correct that imbalance deliberately
+        rather than letting sampling rate decide how much a modality counts.
+    """
+
+    sensor_id: str
+    weight: float = 1.0
+
+    def __post_init__(self) -> None:
+        """Validate shared configuration."""
+        if not isinstance(self.sensor_id, str) or not self.sensor_id.strip():
+            raise ValueError("sensor_id must be a non-empty string")
+        if not math.isfinite(self.weight) or self.weight < 0.0:
+            raise ValueError("weight must be finite and non-negative")
+
+    @abstractmethod
+    def _raw_log_likelihood(
+        self,
+        ontology: StateOntology,
+        observations: Sequence[Observation],
+        elapsed: timedelta,
+    ) -> np.ndarray:
+        """Return the untempered per-state log-likelihood."""
+
+    def log_likelihood(
+        self,
+        ontology: StateOntology,
+        observations: Sequence[Observation],
+        elapsed: timedelta,
+        *,
+        reliability: float = 1.0,
+        attribution: float = 1.0,
+    ) -> np.ndarray:
+        """Return the tempered, centred per-state log-likelihood.
+
+        Parameters
+        ----------
+        reliability
+            Health-derived evidence weight in ``[0, 1]``.
+        attribution
+            Probability in ``[0, 1]`` that the monitored resident generated
+            what this sensor saw. Ambient sensors in a home with a visitor
+            should pass a value below one.
+        """
+        temper = self.weight * float(reliability) * float(attribution)
+        if temper <= 0.0:
+            return np.zeros(ontology.size)
+        raw = np.asarray(
+            self._raw_log_likelihood(ontology, observations, elapsed), dtype=float
+        )
+        if raw.shape != (ontology.size,):
+            raise ValueError("emission models must return one value per state")
+        if not np.all(np.isfinite(raw)):
+            raise ValueError(
+                f"emission model for '{self.sensor_id}' produced non-finite values"
+            )
+        tempered: np.ndarray = temper * (raw - raw.max())
+        return tempered
+
+    @staticmethod
+    def _per_state(
+        ontology: StateOntology,
+        values: Mapping[BehaviouralState, float],
+        default: float,
+    ) -> np.ndarray:
+        """Expand a per-state mapping into a vector in ontology order."""
+        return np.array(
+            [float(values.get(state, default)) for state in ontology.states],
+            dtype=float,
+        )
+
+
+@dataclass
+class PoissonEventEmission(EmissionModel):
+    """Event sensors modelled as a state-dependent Poisson process.
+
+    Over an interval of length ``T`` in which ``n`` activations were recorded,
+    a state with rate ``lambda`` has log-likelihood ``n log(lambda) -
+    lambda * T`` up to a constant. This is the natural model for irregular
+    event streams, and it handles the two hard cases correctly without
+    special-casing:
+
+    *Silence is graded evidence.* A long quiet interval penalises high-rate
+    states in proportion to how long the silence lasted, rather than being
+    treated as an observation of zero activity.
+
+    *Asynchrony is free.* The likelihood depends on elapsed time, so events
+    arriving at irregular moments need no resampling onto a grid.
+
+    Parameters
+    ----------
+    rates
+        Activations per hour expected in each state.
+    default_rate
+        Rate per hour for states not named in *rates*.
+    """
+
+    rates: Mapping[BehaviouralState, float] = field(default_factory=dict)
+    default_rate: float = 0.05
+
+    def __post_init__(self) -> None:
+        """Validate the declared rates."""
+        super().__post_init__()
+        for state, rate in self.rates.items():
+            if not math.isfinite(rate) or rate < 0.0:
+                raise ValueError(f"rate for {state} must be finite and non-negative")
+        if not math.isfinite(self.default_rate) or self.default_rate < 0.0:
+            raise ValueError("default_rate must be finite and non-negative")
+
+    def _raw_log_likelihood(
+        self,
+        ontology: StateOntology,
+        observations: Sequence[Observation],
+        elapsed: timedelta,
+    ) -> np.ndarray:
+        per_second = (
+            np.maximum(self._per_state(ontology, self.rates, self.default_rate), 0.0)
+            / 3600.0
+        )
+        per_second = np.maximum(per_second, MIN_RATE)
+        count = sum(1 for obs in observations if obs.value != 0.0)
+        duration = max(elapsed.total_seconds(), 0.0)
+        loglik: np.ndarray = count * np.log(per_second) - per_second * duration
+        return loglik
+
+
+@dataclass
+class GaussianEmission(EmissionModel):
+    """Sampled scalar signals modelled as state-dependent Gaussians.
+
+    Suitable for wearable activity counts, ambient light, or any continuously
+    sampled quantity whose typical level differs between states.
+
+    Parameters
+    ----------
+    means
+        Expected value of the signal in each state.
+    sigmas
+        Standard deviation in each state.
+    default_mean, default_sigma
+        Values used for states not named explicitly.
+    """
+
+    means: Mapping[BehaviouralState, float] = field(default_factory=dict)
+    sigmas: Mapping[BehaviouralState, float] = field(default_factory=dict)
+    default_mean: float = 0.0
+    default_sigma: float = 1.0
+
+    def __post_init__(self) -> None:
+        """Validate the declared moments."""
+        super().__post_init__()
+        if self.default_sigma <= 0.0 or not math.isfinite(self.default_sigma):
+            raise ValueError("default_sigma must be positive and finite")
+        for state, sigma in self.sigmas.items():
+            if not math.isfinite(sigma) or sigma <= 0.0:
+                raise ValueError(f"sigma for {state} must be positive and finite")
+
+    def _raw_log_likelihood(
+        self,
+        ontology: StateOntology,
+        observations: Sequence[Observation],
+        elapsed: timedelta,
+    ) -> np.ndarray:
+        if not observations:
+            return np.zeros(ontology.size)
+        means = self._per_state(ontology, self.means, self.default_mean)
+        sigmas = self._per_state(ontology, self.sigmas, self.default_sigma)
+        values = np.array([obs.value for obs in observations], dtype=float)
+        residuals = values[:, None] - means[None, :]
+        loglik: np.ndarray = -(
+            0.5 * (residuals / sigmas[None, :]) ** 2 + np.log(sigmas)[None, :]
+        ).sum(axis=0)
+        return loglik
+
+
+@dataclass
+class BernoulliEmission(EmissionModel):
+    """Binary state sensors modelled as state-dependent Bernoulli draws.
+
+    Suitable for bed or chair occupancy, where the sensor reports a level that
+    persists until it changes. Only the most recent reading in the interval is
+    used, because repeated reports of an unchanged state are not repeated
+    independent measurements of it.
+
+    Parameters
+    ----------
+    probabilities
+        Probability the sensor reads one in each state.
+    default_probability
+        Probability for states not named explicitly.
+    """
+
+    probabilities: Mapping[BehaviouralState, float] = field(default_factory=dict)
+    default_probability: float = 0.5
+
+    def __post_init__(self) -> None:
+        """Validate the declared probabilities."""
+        super().__post_init__()
+        values = [*self.probabilities.values(), self.default_probability]
+        if any(not math.isfinite(p) or not 0.0 <= p <= 1.0 for p in values):
+            raise ValueError("probabilities must lie in [0, 1]")
+
+    def _raw_log_likelihood(
+        self,
+        ontology: StateOntology,
+        observations: Sequence[Observation],
+        elapsed: timedelta,
+    ) -> np.ndarray:
+        if not observations:
+            return np.zeros(ontology.size)
+        probabilities = np.clip(
+            self._per_state(ontology, self.probabilities, self.default_probability),
+            EPSILON,
+            1.0 - EPSILON,
+        )
+        latest = observations[-1].value
+        loglik: np.ndarray = (
+            np.log(probabilities) if latest != 0.0 else np.log1p(-probabilities)
+        )
+        return loglik
+
+
+@dataclass
+class BetaEmission(EmissionModel):
+    """Probability-valued derived features modelled as Beta draws.
+
+    Radar and room-occupancy devices commonly report a presence probability
+    rather than a raw measurement. Treating that number as a Beta observation
+    keeps it on its natural support and lets the deployment state how much to
+    trust it through the concentration parameter, instead of hard-thresholding
+    it into a binary and discarding the uncertainty the device supplied.
+
+    Parameters
+    ----------
+    means
+        Expected feature value in each state, strictly inside ``(0, 1)``.
+    concentration
+        Beta concentration. Larger values mean the feature is expected to sit
+        tightly around its state mean.
+    default_mean
+        Mean for states not named explicitly.
+    """
+
+    means: Mapping[BehaviouralState, float] = field(default_factory=dict)
+    concentration: float = 8.0
+    default_mean: float = 0.5
+
+    def __post_init__(self) -> None:
+        """Validate the declared means and concentration."""
+        super().__post_init__()
+        if not math.isfinite(self.concentration) or self.concentration <= 0.0:
+            raise ValueError("concentration must be positive and finite")
+        values = [*self.means.values(), self.default_mean]
+        if any(not math.isfinite(m) or not 0.0 <= m <= 1.0 for m in values):
+            raise ValueError("means must lie in [0, 1]")
+
+    def _raw_log_likelihood(
+        self,
+        ontology: StateOntology,
+        observations: Sequence[Observation],
+        elapsed: timedelta,
+    ) -> np.ndarray:
+        if not observations:
+            return np.zeros(ontology.size)
+        means = np.clip(
+            self._per_state(ontology, self.means, self.default_mean),
+            EPSILON,
+            1.0 - EPSILON,
+        )
+        alpha = self.concentration * means
+        beta = self.concentration * (1.0 - means)
+        values = np.clip(
+            np.array([obs.value for obs in observations], dtype=float),
+            EPSILON,
+            1.0 - EPSILON,
+        )
+        log_values = np.log(values)[:, None]
+        log_complements = np.log1p(-values)[:, None]
+        loglik: np.ndarray = (
+            (alpha - 1.0) * log_values + (beta - 1.0) * log_complements
+        ).sum(axis=0)
+        return loglik