sensor-modeling 0.2.0__py3-none-any.whl

sensor_modeling/data/preprocessing.py

@@ -0,0 +1,83 @@
+"""Data cleaning and preparation routines for sensor data."""
+
+from __future__ import annotations
+
+import logging
+
+import numpy as np
+import pandas as pd
+
+from sensor_modeling.utils.data_io import SensorDataset
+from sensor_modeling.utils.missing import handle_missing_data
+
+logger = logging.getLogger(__name__)
+
+
+def detect_missing(dataset: SensorDataset) -> pd.Series:
+    """Return the fraction of missing values per sensor."""
+    df = dataset.to_dataframe()
+    miss = df.isna().mean()
+    logger.debug("Missing value ratios: %s", miss.to_dict())
+    return miss
+
+
+def impute_missing(dataset: SensorDataset, strategy: str = "ffill") -> SensorDataset:
+    """Impute missing values using the specified strategy."""
+    df = dataset.to_dataframe().copy()
+    if strategy == "ffill":
+        df = handle_missing_data(df, strategy="gap_aware").data
+    elif strategy == "interpolate":
+        df = handle_missing_data(df, strategy="interpolate").data
+    elif strategy == "mean":
+        numeric_means = df.select_dtypes(include="number").mean()
+        df = df.fillna(numeric_means)
+    else:
+        raise ValueError(f"Unsupported imputation strategy: {strategy}")
+    logger.info("Imputed missing values using %s strategy", strategy)
+    return SensorDataset(df)
+
+
+def detect_outliers(dataset: SensorDataset, z_thresh: float = 3.0) -> pd.DataFrame:
+    """Identify outlier readings using a z-score threshold."""
+    if z_thresh <= 0:
+        raise ValueError("z_thresh must be positive")
+
+    df = dataset.to_dataframe()
+    outliers = pd.DataFrame(False, index=df.index, columns=df.columns)
+    numeric = df.select_dtypes(include="number")
+    if not numeric.empty:
+        std = numeric.std(ddof=0).replace(0, np.nan)
+        z = (numeric - numeric.mean()) / std
+        outliers.loc[:, numeric.columns] = (np.abs(z) > z_thresh).fillna(False)
+    logger.debug("Outlier counts per sensor: %s", outliers.sum().to_dict())
+    return outliers
+
+
+def align_sensors(
+    datasets: list[SensorDataset], freq: str = "1min"
+) -> list[SensorDataset]:
+    """Temporal alignment across multiple sensors/datasets."""
+    if not datasets:
+        raise ValueError("No datasets provided for alignment")
+    target_index = pd.date_range(
+        start=min(ds.to_dataframe().index.min() for ds in datasets),
+        end=max(ds.to_dataframe().index.max() for ds in datasets),
+        freq=freq,
+    )
+    aligned = []
+    for ds in datasets:
+        df = ds.to_dataframe().reindex(target_index).interpolate()
+        aligned.append(SensorDataset(df))
+    logger.info("Aligned %d datasets to frequency %s", len(datasets), freq)
+    return aligned
+
+
+def data_quality_report(dataset: SensorDataset) -> dict[str, float]:
+    """Compute simple data quality metrics."""
+    df = dataset.to_dataframe()
+    report = {
+        "missing_ratio": 0.0 if df.empty else float(df.isna().mean().mean()),
+        "outlier_ratio": float(detect_outliers(dataset).mean().mean()),
+    }
+    logger.info("Data quality report: %s", report)
+    return report

sensor_modeling/data/synthetic.py

@@ -0,0 +1,121 @@
+"""Synthetic data generation utilities for benchmarking."""
+
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Mapping
+from dataclasses import dataclass
+from numbers import Integral
+from os import PathLike
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+from sensor_modeling.utils.data_io import SensorDataset
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class SyntheticConfig:
+    n_steps: int = 1000
+    n_sensors: int = 3
+    change_points: list[int] | None = None
+    failure_rate: float = 0.0
+    seed: int = 0
+
+
+def _validate_config(config: SyntheticConfig) -> list[int]:
+    """Validate a synthetic generation config and return change points."""
+    if config.n_steps < 1:
+        raise ValueError("n_steps must be at least 1")
+    if config.n_sensors < 1:
+        raise ValueError("n_sensors must be at least 1")
+    if not 0 <= config.failure_rate <= 1:
+        raise ValueError("failure_rate must be between 0 and 1")
+
+    change_points = config.change_points or [config.n_steps // 2]
+    invalid = [
+        cp
+        for cp in change_points
+        if not isinstance(cp, Integral)
+        or isinstance(cp, bool)
+        or cp < 0
+        or cp >= config.n_steps
+    ]
+    if invalid:
+        raise ValueError(
+            "change_points must be integer offsets between 0 and n_steps - 1"
+        )
+    return change_points
+
+
+def generate(config: SyntheticConfig) -> tuple[SensorDataset, dict[str, list[int]]]:
+    """Generate synthetic sensor data with ground truth change points."""
+    cps = _validate_config(config)
+    rng = np.random.default_rng(config.seed)
+    probs = np.zeros((config.n_steps, config.n_sensors)) + 0.1
+    for cp in cps:
+        probs[cp:] += 0.5  # behavioral change after change point
+    probs = np.clip(probs, 0.0, 1.0)
+    data = rng.binomial(1, probs)
+    # introduce sensor failures
+    for s in range(config.n_sensors):
+        if rng.random() < config.failure_rate:
+            fail_start = rng.integers(0, max(config.n_steps // 2, 1))
+            data[fail_start:, s] = 0
+            logger.warning(
+                "Injected failure in sensor %s starting at %s", s, fail_start
+            )
+    index = pd.date_range("2024-01-01", periods=config.n_steps, freq="1min")
+    df = pd.DataFrame(
+        data, index=index, columns=[f"sensor_{i}" for i in range(config.n_sensors)]
+    )
+    return SensorDataset(df), {"change_points": cps}
+
+
+def export(
+    dataset: SensorDataset,
+    metadata: Mapping[str, object],
+    path: str | PathLike[str],
+    fmt: str = "csv",
+) -> dict[str, Path]:
+    """Export synthetic dataset and metadata in multiple formats."""
+    if fmt not in {"csv", "json", "hdf5"}:
+        raise ValueError(f"Unsupported export format: {fmt}")
+
+    df = dataset.to_dataframe()
+    output_path = Path(path)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    if fmt == "csv":
+        df.to_csv(output_path)
+        metadata_path = Path(f"{output_path}.meta.json")
+        with metadata_path.open("w", encoding="utf-8") as f:
+            json.dump(metadata, f)
+        output_paths = {"data": output_path, "metadata": metadata_path}
+    elif fmt == "json":
+        records_df = df.reset_index().rename(
+            columns={df.index.name or "index": "timestamp"}
+        )
+        records_df["timestamp"] = records_df["timestamp"].astype(str)
+        records = records_df.to_dict(orient="records")
+        with output_path.open("w", encoding="utf-8") as f:
+            json.dump({"data": records, "meta": metadata}, f)
+        output_paths = {"data": output_path}
+    else:
+        try:
+            import h5py
+        except ImportError as exc:  # pragma: no cover - dependency is installed in CI
+            raise ImportError("h5py is required for HDF5 export") from exc
+
+        with h5py.File(output_path, "w") as h5:
+            dset = h5.create_dataset("data", data=df.values)
+            dset.attrs["timestamp"] = df.index.astype(str).to_list()
+            h5.create_dataset("meta", data=json.dumps(metadata).encode("utf-8"))
+        output_paths = {"data": output_path}
+
+    logger.info("Exported synthetic dataset to %s (format=%s)", output_path, fmt)
+    return output_paths

sensor_modeling/data/validation.py

@@ -0,0 +1,81 @@
+"""Data validation utilities."""
+
+from __future__ import annotations
+
+import logging
+
+import pandas as pd
+
+from sensor_modeling.utils.data_io import SensorDataset
+
+logger = logging.getLogger(__name__)
+
+
+def check_temporal_consistency(dataset: SensorDataset) -> bool:
+    """Verify that timestamps are monotonic and evenly spaced."""
+    idx = dataset.to_dataframe().index
+    if not isinstance(idx, pd.DatetimeIndex):
+        logger.error("Index must be a DatetimeIndex")
+        return False
+    if not idx.is_monotonic_increasing:
+        logger.error("Timestamps are not sorted")
+        return False
+    if idx.has_duplicates:
+        logger.error("Duplicate timestamps detected")
+        return False
+    diffs = idx.to_series().diff().dropna().value_counts()
+    if len(diffs) > 1:
+        logger.warning("Irregular sampling detected: %s", diffs.to_dict())
+        return False
+    return True
+
+
+def validate_sensor_ranges(
+    dataset: SensorDataset, min_val: float = 0.0, max_val: float = 1.0
+) -> bool:
+    """Ensure sensor readings fall within expected bounds."""
+    if min_val > max_val:
+        raise ValueError("min_val must be less than or equal to max_val")
+
+    df = dataset.to_dataframe()
+    if df.empty or len(df.columns) == 0:
+        logger.error("Sensor range validation requires data")
+        return False
+
+    numeric = df.apply(pd.to_numeric, errors="coerce")
+    valid = (
+        numeric.notna().all().all()
+        and numeric.apply(lambda c: c.between(min_val, max_val).all()).all()
+    )
+    if not valid:
+        logger.error("Sensor readings outside [%s, %s]", min_val, max_val)
+    return bool(valid)
+
+
+def detect_sensor_failures(
+    dataset: SensorDataset, window: int = 100
+) -> dict[str, bool]:
+    """Detect potential sensor failures using long constant stretches."""
+    if window < 1:
+        raise ValueError("window must be at least 1")
+
+    df = dataset.to_dataframe()
+    failures: dict[str, bool] = {}
+    for col in df.columns:
+        series = df[col]
+        rolling = series.rolling(window=window, min_periods=window)
+        constant_windows = rolling.apply(
+            lambda x: x.nunique(dropna=False) <= 1,
+            raw=False,
+        )
+        failures[col] = bool(constant_windows.fillna(0).astype(bool).any())
+        if failures[col]:
+            logger.warning("Possible failure detected in sensor '%s'", col)
+    return failures
+
+
+def cross_sensor_correlation(dataset: SensorDataset) -> pd.DataFrame:
+    """Compute correlation matrix across sensors."""
+    corr = dataset.to_dataframe().corr()
+    logger.debug("Sensor correlation matrix:\n%s", corr)
+    return corr

sensor_modeling/evaluation/__init__.py

@@ -0,0 +1,92 @@
+"""Evaluation metrics and sensor-ablation experiments.
+
+Metrics are chosen per problem rather than defaulting to accuracy, which is
+close to meaningless on states this imbalanced. Ablation studies are paired by
+construction: every configuration sees identical simulated trajectories, so a
+difference between configurations is a difference in sensing rather than in
+the person being sensed.
+"""
+
+from .ablation import (
+    AblationReport,
+    AblationRun,
+    SensorConfiguration,
+    evaluate_configuration,
+    leave_one_out,
+    named_subsets,
+    run_ablation,
+)
+from .attribution import (
+    ArmResult,
+    AttributionStudy,
+    Scenario,
+    ScenarioComparison,
+    compare_scenario,
+    run_attribution_study,
+    standard_scenarios,
+)
+from .detection import (
+    ArmOutcome,
+    ChangeArm,
+    DetectionStudy,
+    run_detection_study,
+    standard_arms,
+)
+from .metrics import (
+    BinaryMetrics,
+    DetectionMetrics,
+    PairedDifference,
+    StateMetrics,
+    TimingMetrics,
+    binary_metrics,
+    detection_metrics,
+    paired_difference,
+    state_metrics,
+    summarise,
+    transition_timing,
+)
+from .provenance import (
+    METRIC_DEFINITIONS,
+    RESULTS_DIR,
+    ExperimentRecord,
+    environment,
+    load_record,
+)
+
+__all__ = [
+    "METRIC_DEFINITIONS",
+    "RESULTS_DIR",
+    "AblationReport",
+    "ArmOutcome",
+    "ArmResult",
+    "AttributionStudy",
+    "AblationRun",
+    "BinaryMetrics",
+    "ChangeArm",
+    "DetectionMetrics",
+    "DetectionStudy",
+    "ExperimentRecord",
+    "PairedDifference",
+    "Scenario",
+    "ScenarioComparison",
+    "SensorConfiguration",
+    "StateMetrics",
+    "TimingMetrics",
+    "binary_metrics",
+    "compare_scenario",
+    "detection_metrics",
+    "environment",
+    "evaluate_configuration",
+    "leave_one_out",
+    "load_record",
+    "named_subsets",
+    "paired_difference",
+    "run_ablation",
+    "run_attribution_study",
+    "run_detection_study",
+    "standard_arms",
+    "standard_scenarios",
+    "state_metrics",
+    "summarise",
+    "transition_timing",
+]

sensor_modeling/evaluation/ablation.py

@@ -0,0 +1,303 @@
+"""Sensor-ablation experiments: what is each modality actually worth?
+
+The research question this package exists to answer is whether useful
+behavioural inference survives with fewer physical sensors. Answering it needs
+more discipline than running a few configurations and comparing numbers.
+
+Three things are built in rather than left to the user to remember.
+
+*The design is paired.* Every configuration is evaluated on identical
+simulated trajectories. Simulated households differ from each other far more
+than two sensor configurations differ on one household, so an unpaired
+comparison buries a real effect under between-household variance.
+
+*Ablation removes sensors, not code.* A configuration is a subset of the
+registry. The pipeline is constructed from that subset exactly as it would be
+from a full deployment, so an ablated run exercises the same inference path a
+real sparse deployment would.
+
+*Marginal value is not assumed additive.* Two sensors that each look
+worthless alone can be jointly essential -- a door tells you little without
+something to say who walked through it. :func:`interaction` reports how far
+the joint contribution departs from the sum of the individual ones, so that
+departure is measured rather than assumed away.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Iterable, Mapping, Sequence
+from dataclasses import dataclass, field
+from datetime import timedelta
+
+import numpy as np
+
+from ..observations.registry import SensorRegistry
+from ..online.pipeline import BehaviouralSensingPipeline, PipelineConfig
+from ..simulation.faults import DegradationConfig, degrade
+from ..simulation.household import HouseholdConfig, simulate
+from .metrics import PairedDifference, StateMetrics, paired_difference, state_metrics
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class SensorConfiguration:
+    """A named subset of a deployment to evaluate."""
+
+    name: str
+    sensors: tuple[str, ...]
+
+    def __post_init__(self) -> None:
+        """Validate the configuration."""
+        if not self.name.strip():
+            raise ValueError("a configuration needs a name")
+        if not self.sensors:
+            raise ValueError(f"configuration '{self.name}' has no sensors")
+
+    def restrict(self, registry: SensorRegistry) -> SensorRegistry:
+        """Return the registry restricted to this configuration."""
+        return registry.subset(self.sensors)
+
+
+@dataclass(frozen=True)
+class AblationRun:
+    """The outcome of one configuration on one simulated trajectory."""
+
+    configuration: str
+    seed: int
+    metrics: StateMetrics
+    sensors: tuple[str, ...]
+
+    def to_dict(self) -> dict[str, object]:
+        """Return a serialisable form of the run."""
+        return {
+            "configuration": self.configuration,
+            "seed": self.seed,
+            "sensors": list(self.sensors),
+            "metrics": self.metrics.to_dict(),
+        }
+
+
+@dataclass
+class AblationReport:
+    """Results of a paired ablation sweep."""
+
+    runs: list[AblationRun] = field(default_factory=list)
+
+    @property
+    def configurations(self) -> list[str]:
+        """Names of the configurations evaluated, in first-seen order."""
+        seen: dict[str, None] = {}
+        for run in self.runs:
+            seen.setdefault(run.configuration, None)
+        return list(seen)
+
+    @property
+    def seeds(self) -> list[int]:
+        """Seeds evaluated, sorted."""
+        return sorted({run.seed for run in self.runs})
+
+    def series(
+        self, configuration: str, metric: str = "balanced_accuracy"
+    ) -> list[float]:
+        """Return one configuration's scores, ordered by seed.
+
+        Ordering by seed is what keeps the pairing intact: position ``i`` in
+        two configurations' series refers to the same simulated household.
+        """
+        by_seed = {
+            run.seed: getattr(run.metrics, metric)
+            for run in self.runs
+            if run.configuration == configuration
+        }
+        missing = set(self.seeds) - set(by_seed)
+        if missing:
+            raise ValueError(
+                f"configuration '{configuration}' is missing seeds {sorted(missing)}; "
+                "the paired design requires every configuration on every seed"
+            )
+        return [by_seed[seed] for seed in self.seeds]
+
+    def compare(
+        self,
+        treatment: str,
+        control: str,
+        *,
+        metric: str = "balanced_accuracy",
+        seed: int = 0,
+    ) -> PairedDifference:
+        """Compare two configurations on the trajectories they share."""
+        return paired_difference(
+            self.series(treatment, metric),
+            self.series(control, metric),
+            seed=seed,
+        )
+
+    def marginal(
+        self,
+        full: str,
+        without: str,
+        *,
+        metric: str = "balanced_accuracy",
+    ) -> PairedDifference:
+        """Return the value lost by removing a sensor from *full*.
+
+        This is ``performance(S) - performance(S without j)``, evaluated on
+        paired trajectories.
+        """
+        return self.compare(full, without, metric=metric)
+
+    def interaction(
+        self,
+        full: str,
+        without_first: str,
+        without_second: str,
+        without_both: str,
+        *,
+        metric: str = "balanced_accuracy",
+    ) -> float:
+        """Return how far two sensors' joint value departs from additivity.
+
+        Positive means the pair is worth more together than separately --
+        they are complementary. Negative means they are redundant, each
+        covering for the other's absence.
+        """
+        scores = {
+            name: float(np.mean(self.series(name, metric)))
+            for name in (full, without_first, without_second, without_both)
+        }
+        first = scores[full] - scores[without_first]
+        second = scores[full] - scores[without_second]
+        joint = scores[full] - scores[without_both]
+        return joint - (first + second)
+
+    def summary(self, metric: str = "balanced_accuracy") -> dict[str, dict[str, float]]:
+        """Return mean and spread of *metric* for each configuration."""
+        result: dict[str, dict[str, float]] = {}
+        for name in self.configurations:
+            series = self.series(name, metric)
+            result[name] = {
+                "mean": float(np.mean(series)),
+                "sd": float(np.std(series, ddof=1)) if len(series) > 1 else 0.0,
+                "min": float(np.min(series)),
+                "max": float(np.max(series)),
+                "n_sensors": float(
+                    len(
+                        next(
+                            run.sensors
+                            for run in self.runs
+                            if run.configuration == name
+                        )
+                    )
+                ),
+            }
+        return result
+
+    def to_dict(self, metric: str = "balanced_accuracy") -> dict[str, object]:
+        """Return a serialisable form of the report."""
+        return {
+            "metric": metric,
+            "seeds": self.seeds,
+            "summary": self.summary(metric),
+            "runs": [run.to_dict() for run in self.runs],
+        }
+
+
+def evaluate_configuration(
+    configuration: SensorConfiguration,
+    result: object,
+    *,
+    step: timedelta = timedelta(minutes=5),
+    degradation: DegradationConfig | None = None,
+) -> StateMetrics:
+    """Run one sensor configuration over one simulated trajectory."""
+    registry = configuration.restrict(result.registry)  # type: ignore[attr-defined]
+    observations = result.observations_for(configuration.sensors)  # type: ignore[attr-defined]
+    if degradation is not None:
+        observations, _ = degrade(observations, degradation)
+
+    pipeline = BehaviouralSensingPipeline(
+        registry,
+        config=PipelineConfig(tz=result.config.tz, step=step),  # type: ignore[attr-defined]
+    )
+    steps = pipeline.run(observations)
+    steps.extend(pipeline.close(result.end))  # type: ignore[attr-defined]
+    if not steps:
+        raise ValueError(
+            f"configuration '{configuration.name}' produced no pipeline steps"
+        )
+
+    truth = result.truth.states_at([step_.at for step_ in steps])  # type: ignore[attr-defined]
+    return state_metrics(truth, [step_.state for step_ in steps])
+
+
+def run_ablation(
+    configurations: Sequence[SensorConfiguration],
+    *,
+    seeds: Iterable[int],
+    household: HouseholdConfig | None = None,
+    step: timedelta = timedelta(minutes=5),
+    degradation: DegradationConfig | None = None,
+) -> AblationReport:
+    """Evaluate every configuration on every seeded trajectory.
+
+    One household is simulated per seed and shared by all configurations, so
+    differences between configurations are differences in sensing rather than
+    differences in the person being sensed.
+    """
+    if not configurations:
+        raise ValueError("at least one configuration is required")
+    names = [configuration.name for configuration in configurations]
+    if len(set(names)) != len(names):
+        raise ValueError("configuration names must be unique")
+
+    base = household or HouseholdConfig()
+    report = AblationReport()
+    for seed in seeds:
+        from dataclasses import replace as _replace
+
+        result = simulate(_replace(base, seed=seed))
+        for configuration in configurations:
+            metrics = evaluate_configuration(
+                configuration, result, step=step, degradation=degradation
+            )
+            report.runs.append(
+                AblationRun(
+                    configuration=configuration.name,
+                    seed=seed,
+                    metrics=metrics,
+                    sensors=configuration.sensors,
+                )
+            )
+            logger.info(
+                "seed %s | %-22s | balanced accuracy %.3f | abstention %.3f",
+                seed,
+                configuration.name,
+                metrics.balanced_accuracy,
+                metrics.abstention_rate,
+            )
+    return report
+
+
+def leave_one_out(
+    registry: SensorRegistry, sensors: Iterable[str] | None = None
+) -> list[SensorConfiguration]:
+    """Build the full configuration plus one with each sensor removed."""
+    everything = tuple(registry.sensor_ids())
+    candidates = tuple(sensors) if sensors is not None else everything
+    configurations = [SensorConfiguration("all", everything)]
+    for sensor_id in candidates:
+        remaining = tuple(s for s in everything if s != sensor_id)
+        if remaining:
+            configurations.append(
+                SensorConfiguration(f"without_{sensor_id}", remaining)
+            )
+    return configurations
+
+
+def named_subsets(subsets: Mapping[str, Sequence[str]]) -> list[SensorConfiguration]:
+    """Build configurations from a mapping of name to sensor identifiers."""
+    return [
+        SensorConfiguration(name, tuple(sensors)) for name, sensors in subsets.items()
+    ]