sensor-modeling 0.2.0__py3-none-any.whl

sensor_modeling/fusion/estimate.py

@@ -0,0 +1,375 @@
+"""The output of multimodal fusion: a state belief with its justification.
+
+A :class:`StateEstimate` is deliberately more than an argmax. It carries the
+full posterior, how confident that posterior is, how much of the sensing
+apparatus was actually contributing, which sensors supported the conclusion
+and which contradicted it, and which supplied nothing at all.
+
+It can also decline. When confidence is low or too little evidence was
+available, :attr:`StateEstimate.state` is
+:attr:`~sensor_modeling.states.BehaviouralState.UNKNOWN` -- an abstention,
+not a prediction of an eighth behaviour.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from datetime import datetime
+
+import numpy as np
+
+from ..observations.types import Modality
+from ..states.ontology import BehaviouralState, StateOntology
+
+
+@dataclass(frozen=True)
+class EvidenceContribution:
+    """What one sensor contributed to the conclusion.
+
+    Attributes
+    ----------
+    sensor_id
+        Sensor the contribution came from.
+    modality
+        Modality of that sensor.
+    support
+        Log-likelihood margin the sensor gives the winning state over the
+        best alternative. Positive means the sensor favours the conclusion,
+        negative means it favours something else, zero means it is
+        indifferent between them.
+    reliability
+        Health-derived evidence weight applied to the sensor.
+    attribution
+        Probability that what the sensor saw was generated by the monitored
+        resident rather than someone else.
+    observations
+        Number of records this sensor supplied over the interval.
+    """
+
+    sensor_id: str
+    modality: Modality
+    support: float
+    reliability: float
+    attribution: float
+    observations: int
+
+    @property
+    def supports(self) -> bool:
+        """Whether the sensor favours the reported state."""
+        return self.support > 0.0
+
+    @property
+    def contradicts(self) -> bool:
+        """Whether the sensor favours some other state."""
+        return self.support < 0.0
+
+    @property
+    def reported(self) -> bool:
+        """Whether the sensor produced any records over the interval."""
+        return self.observations > 0
+
+    @property
+    def informative(self) -> bool:
+        """Whether the sensor's likelihood was applied at all.
+
+        A trusted event sensor that stayed quiet is still informative: under
+        a Poisson observation model its silence actively penalises the
+        states that would have triggered it. Only a sensor discounted to
+        zero reliability contributes nothing.
+        """
+        return self.reliability > 0.0
+
+    def to_dict(self) -> dict[str, object]:
+        """Return a serialisable form of the contribution."""
+        return {
+            "sensor_id": self.sensor_id,
+            "modality": self.modality.value,
+            "support": self.support,
+            "reliability": self.reliability,
+            "attribution": self.attribution,
+            "observations": self.observations,
+        }
+
+
+@dataclass(frozen=True)
+class Explanation:
+    """Why an estimate reached its conclusion, as addressable parts.
+
+    Four fields carry information that a bare probability cannot, and each
+    answers a question a reader would otherwise have to guess at:
+
+    ``supporting`` / ``contradicting``
+        Which sensors agreed and which pointed elsewhere. Disagreement is
+        surfaced rather than averaged away.
+    ``silent``
+        Trusted sensors that reported nothing. Their silence *did* inform the
+        posterior -- under a Poisson model it penalises the states that would
+        have triggered them.
+    ``missing``
+        Sensors discounted to zero reliability. These contributed nothing at
+        all, and the distinction from ``silent`` is the difference between a
+        quiet room and a broken sensor.
+    """
+
+    at: datetime
+    state: BehaviouralState
+    probability: float
+    abstained: bool
+    reason: str | None
+    supporting: tuple[str, ...]
+    contradicting: tuple[str, ...]
+    silent: tuple[str, ...]
+    missing: tuple[str, ...]
+    completeness: float
+
+    def render(self) -> str:
+        """Render the explanation as an indented, human-readable block."""
+        lines = [
+            f"State:                 {self.state.value}",
+            f"Probability:           {self.probability:.2f}",
+            f"Sensor coverage:       {self.completeness:.2f}",
+        ]
+        if self.abstained and self.reason:
+            lines.append(f"Declined because:      {self.reason}")
+        lines.append(f"Supporting evidence:   {', '.join(self.supporting) or 'none'}")
+        lines.append(
+            f"Contradictory:         {', '.join(self.contradicting) or 'none'}"
+        )
+        lines.append(f"Quiet but working:     {', '.join(self.silent) or 'none'}")
+        lines.append(f"No evidence from:      {', '.join(self.missing) or 'none'}")
+        return "\n".join(lines)
+
+    def to_dict(self) -> dict[str, object]:
+        """Return a serialisable form of the explanation."""
+        return {
+            "at": self.at.isoformat(),
+            "state": self.state.value,
+            "probability": self.probability,
+            "abstained": self.abstained,
+            "reason": self.reason,
+            "supporting": list(self.supporting),
+            "contradicting": list(self.contradicting),
+            "silent": list(self.silent),
+            "missing": list(self.missing),
+            "completeness": self.completeness,
+        }
+
+
+@dataclass(frozen=True)
+class StateEstimate:
+    """A posterior over latent behavioural states, with its justification."""
+
+    at: datetime
+    ontology: StateOntology
+    belief: np.ndarray
+    evidence: tuple[EvidenceContribution, ...]
+    completeness: float
+    min_confidence: float
+    min_completeness: float
+
+    def __post_init__(self) -> None:
+        """Validate the belief vector."""
+        belief = np.asarray(self.belief, dtype=float)
+        if belief.shape != (self.ontology.size,):
+            raise ValueError("belief must have one entry per ontology state")
+        if not np.all(np.isfinite(belief)) or belief.min() < 0.0:
+            raise ValueError("belief must be finite and non-negative")
+        total = belief.sum()
+        if total <= 0.0:
+            raise ValueError("belief must contain at least some probability mass")
+        object.__setattr__(self, "belief", belief / total)
+
+    # ------------------------------------------------------------------
+    @property
+    def probabilities(self) -> dict[BehaviouralState, float]:
+        """Posterior probability of each latent state."""
+        return dict(zip(self.ontology.states, (float(p) for p in self.belief)))
+
+    @property
+    def most_likely(self) -> BehaviouralState:
+        """The highest-posterior state, regardless of whether it is credible."""
+        return self.ontology.states[int(np.argmax(self.belief))]
+
+    @property
+    def confidence(self) -> float:
+        """Posterior mass on the most likely state."""
+        return float(self.belief.max())
+
+    @property
+    def margin(self) -> float:
+        """Gap between the two highest posterior probabilities."""
+        if self.belief.size < 2:
+            return self.confidence
+        ordered = np.sort(self.belief)
+        return float(ordered[-1] - ordered[-2])
+
+    @property
+    def entropy(self) -> float:
+        """Shannon entropy of the posterior in nats."""
+        mass = self.belief[self.belief > 0.0]
+        return float(-(mass * np.log(mass)).sum())
+
+    @property
+    def normalised_entropy(self) -> float:
+        """Entropy scaled to ``[0, 1]``; one means completely undecided."""
+        if self.ontology.size < 2:
+            return 0.0
+        return self.entropy / math.log(self.ontology.size)
+
+    @property
+    def abstained(self) -> bool:
+        """Whether the estimate declines to name a state.
+
+        Two independent reasons force an abstention: the posterior is too
+        flat to justify a claim, or too little of the sensing apparatus was
+        contributing for any posterior to be trustworthy.
+        """
+        return (
+            self.confidence < self.min_confidence
+            or self.completeness < self.min_completeness
+        )
+
+    @property
+    def state(self) -> BehaviouralState:
+        """The reported state, or ``UNKNOWN`` when the estimate abstains."""
+        return BehaviouralState.UNKNOWN if self.abstained else self.most_likely
+
+    # ------------------------------------------------------------------
+    @property
+    def supporting(self) -> tuple[EvidenceContribution, ...]:
+        """Sensors favouring the most likely state, strongest first."""
+        return tuple(
+            sorted(
+                (c for c in self.evidence if c.supports),
+                key=lambda c: c.support,
+                reverse=True,
+            )
+        )
+
+    @property
+    def contradicting(self) -> tuple[EvidenceContribution, ...]:
+        """Sensors favouring some other state, strongest first."""
+        return tuple(
+            sorted((c for c in self.evidence if c.contradicts), key=lambda c: c.support)
+        )
+
+    @property
+    def missing(self) -> tuple[str, ...]:
+        """Sensors discounted to zero reliability, contributing nothing."""
+        return tuple(c.sensor_id for c in self.evidence if not c.informative)
+
+    @property
+    def silent(self) -> tuple[str, ...]:
+        """Trusted sensors that reported nothing over the interval.
+
+        Their silence still informed the posterior; this is a record of what
+        was quiet, not of what was broken.
+        """
+        return tuple(
+            c.sensor_id for c in self.evidence if c.informative and not c.reported
+        )
+
+    def explanation(self, limit: int = 3) -> Explanation:
+        """Return the justification for this estimate as structured data.
+
+        Separate from :meth:`explain` because the two have different
+        consumers: a report renders the sentence, while an interface or an
+        export needs the parts addressable. Both are built from the same
+        evidence, so they cannot drift apart.
+        """
+        return Explanation(
+            at=self.at,
+            state=self.state,
+            probability=self.confidence,
+            abstained=self.abstained,
+            reason=(
+                None
+                if not self.abstained
+                else (
+                    "insufficient sensor coverage"
+                    if self.completeness < self.min_completeness
+                    else "no state was clearly indicated"
+                )
+            ),
+            supporting=tuple(c.sensor_id for c in self.supporting[:limit]),
+            contradicting=tuple(c.sensor_id for c in self.contradicting[:limit]),
+            silent=self.silent,
+            missing=self.missing,
+            completeness=self.completeness,
+        )
+
+    def explain(self, limit: int = 3) -> str:
+        """Return a short human-readable justification for the estimate.
+
+        The wording is intentionally cautious. It reports what the sensors
+        indicated and how confident the model is, and makes no clinical claim.
+        """
+        if self.abstained:
+            reason = (
+                "insufficient sensor coverage"
+                if self.completeness < self.min_completeness
+                else "no state was clearly indicated"
+            )
+            return (
+                f"State unknown at {self.at.isoformat()}: {reason} "
+                f"(confidence {self.confidence:.2f}, "
+                f"coverage {self.completeness:.2f})."
+            )
+
+        parts = [
+            f"{self.state.value} at {self.at.isoformat()} "
+            f"with probability {self.confidence:.2f}"
+        ]
+        supporting = self.supporting[:limit]
+        if supporting:
+            named = ", ".join(f"{c.sensor_id} (+{c.support:.2f})" for c in supporting)
+            parts.append(f"supported by {named}")
+        contradicting = self.contradicting[:limit]
+        if contradicting:
+            named = ", ".join(f"{c.sensor_id} ({c.support:.2f})" for c in contradicting)
+            parts.append(f"contradicted by {named}")
+        if self.missing:
+            parts.append(f"no evidence from {', '.join(self.missing)}")
+        if self.silent:
+            parts.append(f"nothing reported by {', '.join(self.silent)}")
+        return "; ".join(parts) + "."
+
+    def to_dict(self) -> dict[str, object]:
+        """Return a serialisable form of the estimate."""
+        return {
+            "at": self.at.isoformat(),
+            "state": self.state.value,
+            "most_likely": self.most_likely.value,
+            "abstained": self.abstained,
+            "confidence": self.confidence,
+            "margin": self.margin,
+            "normalised_entropy": self.normalised_entropy,
+            "completeness": self.completeness,
+            "probabilities": {
+                state.value: probability
+                for state, probability in self.probabilities.items()
+            },
+            "evidence": [c.to_dict() for c in self.evidence],
+            "missing": list(self.missing),
+            "silent": list(self.silent),
+            "explanation_parts": self.explanation().to_dict(),
+            "explanation": self.explain(),
+        }
+
+
+def belief_from_mapping(
+    ontology: StateOntology, probabilities: Mapping[BehaviouralState, float]
+) -> np.ndarray:
+    """Build a belief vector from a mapping, filling absent states with zero."""
+    return np.array(
+        [float(probabilities.get(state, 0.0)) for state in ontology.states], dtype=float
+    )
+
+
+def belief_matrix(estimates: Sequence[StateEstimate]) -> np.ndarray:
+    """Stack the beliefs of several estimates into a ``(n, n_states)`` array."""
+    if not estimates:
+        return np.zeros((0, 0))
+    return np.vstack([estimate.belief for estimate in estimates])

sensor_modeling/fusion/filter.py

@@ -0,0 +1,323 @@
+"""Recursive multimodal fusion into a latent behavioural state.
+
+:class:`MultimodalBayesFilter` maintains ``P(Z_t | O_1:t)`` -- the posterior
+over latent states given every observation so far, from every modality.
+
+It is a forward filter over a continuous-time Markov chain, which is what lets
+it accept the traffic an ambient deployment actually produces: observations
+arriving asynchronously, at different rates per modality, with modalities
+appearing and disappearing as sensors fail and recover. Between updates the
+belief is propagated by the chain's transition operator for exactly the
+elapsed interval; at each update every sensor that had something to say
+contributes a tempered log-likelihood.
+
+Three properties follow from the construction rather than from special cases:
+
+*A failed sensor is silent, not negative.* Reliability enters as a tempering
+exponent, so a sensor with reliability zero contributes a flat likelihood and
+leaves the belief entirely to the other modalities.
+
+*Absence of evidence widens the posterior.* With nothing to condition on, the
+prediction step relaxes the belief toward the chain's stationary distribution,
+confidence falls, and the estimate eventually abstains instead of coasting on
+a stale conclusion.
+
+*Contradiction is preserved, not resolved.* Sensors pointing at different
+states pull the posterior apart, which shows up as a lower confidence and as
+explicitly recorded contradicting evidence, rather than being averaged away.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Iterable, Mapping, Sequence
+from dataclasses import dataclass
+from datetime import datetime
+
+import numpy as np
+from scipy.special import logsumexp
+
+from ..observations.observation import Observation, require_aware
+from ..observations.registry import SensorRegistry
+from ..observations.types import Modality
+from ..states.ontology import StateOntology
+from .emissions import EmissionModel
+from .estimate import EvidenceContribution, StateEstimate
+
+logger = logging.getLogger(__name__)
+
+
+class NonMonotonicUpdateError(ValueError):
+    """Raised when a filter update would move backwards in time.
+
+    The filter is causal by construction. Reordering late-arriving records is
+    the job of the surrounding pipeline, which owns a buffer and can decide
+    how much lateness to tolerate; silently folding a stale record into the
+    current belief would corrupt it without any trace.
+    """
+
+
+@dataclass
+class FusionConfig:
+    """Thresholds governing when the filter declines to name a state.
+
+    Parameters
+    ----------
+    min_confidence
+        Posterior mass the leading state must hold to be reported.
+    min_completeness
+        Mean sensor reliability required before any posterior is trusted.
+    evidence_floor
+        Reliability below which a sensor is recorded as supplying nothing.
+    """
+
+    min_confidence: float = 0.35
+    min_completeness: float = 0.25
+    evidence_floor: float = 0.05
+
+    def __post_init__(self) -> None:
+        """Validate the abstention thresholds."""
+        for name in ("min_confidence", "min_completeness", "evidence_floor"):
+            value = float(getattr(self, name))
+            if not 0.0 <= value <= 1.0:
+                raise ValueError(f"{name} must lie in [0, 1]")
+            setattr(self, name, value)
+
+
+class MultimodalBayesFilter:
+    """Forward filtering of latent behavioural state over asynchronous evidence.
+
+    Parameters
+    ----------
+    ontology
+        Latent states and their continuous-time dynamics.
+    emissions
+        One observation model per sensor that should inform the state.
+    registry
+        Sensor declarations, used to label evidence with its modality.
+    config
+        Abstention thresholds.
+    prior
+        Initial belief. Defaults to the ontology's stationary distribution,
+        which is the most defensible starting point before any evidence.
+    """
+
+    def __init__(
+        self,
+        ontology: StateOntology,
+        emissions: Iterable[EmissionModel],
+        registry: SensorRegistry | None = None,
+        config: FusionConfig | None = None,
+        prior: np.ndarray | None = None,
+    ) -> None:
+        self.ontology = ontology
+        self.registry = registry
+        self.config = config or FusionConfig()
+        self.emissions: dict[str, EmissionModel] = {}
+        for emission in emissions:
+            if emission.sensor_id in self.emissions:
+                raise ValueError(
+                    f"duplicate emission model for sensor '{emission.sensor_id}'"
+                )
+            self.emissions[emission.sensor_id] = emission
+        if not self.emissions:
+            raise ValueError("at least one emission model is required")
+
+        self._prior: np.ndarray = self._validated_prior(prior)
+        self._belief: np.ndarray = self._prior.copy()
+        self._at: datetime | None = None
+
+    def _validated_prior(self, prior: np.ndarray | None) -> np.ndarray:
+        """Return a normalised prior belief vector."""
+        if prior is None:
+            return self.ontology.stationary()
+        vector = np.asarray(prior, dtype=float)
+        if vector.shape != (self.ontology.size,):
+            raise ValueError("prior must have one entry per ontology state")
+        if not np.all(np.isfinite(vector)) or vector.min() < 0.0 or vector.sum() <= 0.0:
+            raise ValueError("prior must be finite, non-negative, and non-zero")
+        normalised: np.ndarray = vector / vector.sum()
+        return normalised
+
+    # ------------------------------------------------------------------
+    @property
+    def at(self) -> datetime | None:
+        """Time of the most recent update, if the filter has been used."""
+        return self._at
+
+    @property
+    def belief(self) -> np.ndarray:
+        """A copy of the current posterior over latent states."""
+        current: np.ndarray = self._belief.copy()
+        return current
+
+    def reset(self, prior: np.ndarray | None = None) -> None:
+        """Return the filter to its initial belief and clear its clock."""
+        self._prior = self._validated_prior(prior)
+        self._belief = self._prior.copy()
+        self._at = None
+
+    # ------------------------------------------------------------------
+    @staticmethod
+    def _weight_for(
+        weights: Mapping[str, float] | float | None, sensor_id: str, default: float
+    ) -> float:
+        """Resolve a per-sensor weight from a mapping, scalar, or default."""
+        if weights is None:
+            return default
+        if isinstance(weights, Mapping):
+            return float(weights.get(sensor_id, default))
+        return float(weights)
+
+    def _modality_of(self, sensor_id: str) -> Modality:
+        """Return the modality of *sensor_id*, or ``OTHER`` when unknown."""
+        if self.registry is None:
+            return Modality.OTHER
+        spec = self.registry.get(sensor_id)
+        return spec.modality if spec is not None else Modality.OTHER
+
+    def update(
+        self,
+        now: datetime,
+        observations: Sequence[Observation] = (),
+        *,
+        reliabilities: Mapping[str, float] | float | None = None,
+        attribution: Mapping[str, float] | float | None = None,
+    ) -> StateEstimate:
+        """Advance the filter to *now* and fold in the interval's evidence.
+
+        Parameters
+        ----------
+        now
+            Timezone-aware instant to advance to. Must not precede the
+            previous update.
+        observations
+            Records covering the interval since the previous update. Records
+            from sensors without an emission model are ignored.
+        reliabilities
+            Per-sensor evidence weights from the health monitor. A missing
+            entry defaults to full reliability.
+        attribution
+            Per-sensor probability that the monitored resident generated the
+            observation. A missing entry defaults to full attribution.
+
+        Returns
+        -------
+        StateEstimate
+            The posterior with its supporting and contradicting evidence.
+        """
+        moment = require_aware(now, "now")
+        if self._at is not None and moment < self._at:
+            raise NonMonotonicUpdateError(
+                f"update at {moment.isoformat()} precedes the filter clock at "
+                f"{self._at.isoformat()}"
+            )
+
+        elapsed = moment - self._at if self._at is not None else moment - moment
+        predicted = self._belief @ self.ontology.transition(elapsed)
+
+        grouped: dict[str, list[Observation]] = {}
+        for observation in observations:
+            if observation.sensor_id in self.emissions:
+                grouped.setdefault(observation.sensor_id, []).append(observation)
+            else:
+                logger.debug(
+                    "No emission model for sensor '%s'; observation ignored",
+                    observation.sensor_id,
+                )
+
+        log_belief = np.log(np.maximum(predicted, 1e-300))
+        likelihoods: dict[str, np.ndarray] = {}
+        weights: dict[str, tuple[float, float]] = {}
+        reliability_total = 0.0
+
+        for sensor_id, emission in self.emissions.items():
+            reliability = self._weight_for(reliabilities, sensor_id, 1.0)
+            share = self._weight_for(attribution, sensor_id, 1.0)
+            reliability_total += min(max(reliability, 0.0), 1.0)
+            weights[sensor_id] = (reliability, share)
+            likelihoods[sensor_id] = emission.log_likelihood(
+                self.ontology,
+                grouped.get(sensor_id, []),
+                elapsed,
+                reliability=reliability,
+                attribution=share,
+            )
+            log_belief = log_belief + likelihoods[sensor_id]
+
+        self._belief = np.exp(log_belief - logsumexp(log_belief))
+        self._at = moment
+
+        # Support is measured against the state the posterior actually
+        # settled on, so a sensor pointing somewhere else is recorded as
+        # contradicting the conclusion rather than as backing its own guess.
+        winner = int(np.argmax(self._belief))
+        contributions = tuple(
+            EvidenceContribution(
+                sensor_id=sensor_id,
+                modality=self._modality_of(sensor_id),
+                support=_support_for(likelihoods[sensor_id], winner),
+                reliability=(
+                    weights[sensor_id][0]
+                    if weights[sensor_id][0] >= self.config.evidence_floor
+                    else 0.0
+                ),
+                attribution=weights[sensor_id][1],
+                observations=len(grouped.get(sensor_id, [])),
+            )
+            for sensor_id in self.emissions
+        )
+
+        return StateEstimate(
+            at=moment,
+            ontology=self.ontology,
+            belief=self._belief.copy(),
+            evidence=contributions,
+            completeness=reliability_total / len(self.emissions),
+            min_confidence=self.config.min_confidence,
+            min_completeness=self.config.min_completeness,
+        )
+
+    # ------------------------------------------------------------------
+    def snapshot(self) -> dict[str, object]:
+        """Return restartable filter state."""
+        return {
+            "belief": self._belief.tolist(),
+            "at": self._at.isoformat() if self._at else None,
+            "states": self.ontology.labels(),
+        }
+
+    def restore(self, state: Mapping[str, object]) -> None:
+        """Restore filter state produced by :meth:`snapshot`.
+
+        The stored state labels are checked against the current ontology, so
+        a belief saved under a different state set is rejected rather than
+        silently reinterpreted position by position.
+        """
+        labels = state.get("states")
+        if labels is not None and list(labels) != self.ontology.labels():  # type: ignore[call-overload]
+            raise ValueError("snapshot was taken under a different state ontology")
+        belief = np.asarray(state["belief"], dtype=float)
+        if belief.shape != (self.ontology.size,):
+            raise ValueError("snapshot belief does not match the ontology size")
+        total = belief.sum()
+        if not np.all(np.isfinite(belief)) or belief.min() < 0.0 or total <= 0.0:
+            raise ValueError(
+                "snapshot belief must be finite, non-negative, and non-zero"
+            )
+        self._belief = belief / total
+        moment = state.get("at")
+        self._at = datetime.fromisoformat(str(moment)) if moment else None
+
+
+def _support_for(likelihood: np.ndarray, winner: int) -> float:
+    """Return how much a sensor favours *winner* over the best alternative.
+
+    Positive means the sensor backs the reported state, negative means it
+    points elsewhere, and zero means it is indifferent -- which is what an
+    uninformative or fully discounted sensor produces.
+    """
+    if likelihood.size < 2:
+        return 0.0
+    others = np.delete(likelihood, winner)
+    return float(likelihood[winner] - others.max())