sensor-modeling 0.2.0__py3-none-any.whl

sensor_modeling/cli.py

@@ -0,0 +1,416 @@
+"""Unified command-line interface for sensor modeling."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+from datetime import timedelta
+from pathlib import Path
+
+from .models.bernoulli_ar.base_model import BernoulliAutoregressiveModel
+from .models.nhpp_pelt.model import NHPPPELT, NHPPConfig
+from .utils.data_io import SensorDataset
+from .utils.logging_config import setup_logging
+
+
+def _add_model_parsers(sub: argparse._SubParsersAction) -> None:
+    """Register the single-model fitting commands."""
+    ar_p = sub.add_parser("bernoulli-ar", help="Run Bernoulli autoregressive model")
+    ar_p.add_argument("data", help="Path to CSV sensor data")
+    ar_p.add_argument("target", help="Target sensor column")
+
+    nhpp_p = sub.add_parser("nhpp-pelt", help="Run NHPP-PELT changepoint model")
+    nhpp_p.add_argument("data", help="Path to CSV sensor data")
+    nhpp_p.add_argument("sensor", help="Sensor column to use")
+
+
+def _add_demo_parser(sub: argparse._SubParsersAction) -> None:
+    """Register the reproducible end-to-end demonstration."""
+    demo = sub.add_parser(
+        "demo",
+        help="Run the end-to-end ambient sensing demonstration",
+        description=(
+            "Simulate a synthetic household with visitors, sensor faults and a "
+            "known behavioural change, run the full inference pipeline over the "
+            "degraded record, and report what was and was not recovered."
+        ),
+    )
+    demo.add_argument("--days", type=int, default=90, help="Days to simulate")
+    demo.add_argument("--seed", type=int, default=20240304, help="Random seed")
+    demo.add_argument(
+        "--step-minutes", type=int, default=10, help="Inference step in minutes"
+    )
+    demo.add_argument(
+        "--output", type=Path, default=None, help="Write structured results as JSON"
+    )
+
+
+def _add_ablation_parser(sub: argparse._SubParsersAction) -> None:
+    """Register the paired sensor-ablation experiment."""
+    ablate = sub.add_parser(
+        "ablate",
+        help="Run the paired sensor-ablation experiment",
+        description=(
+            "Evaluate several sensor configurations on identical simulated "
+            "households and report how much each modality contributes."
+        ),
+    )
+    ablate.add_argument("--days", type=int, default=14, help="Days per household")
+    ablate.add_argument(
+        "--seeds",
+        type=int,
+        nargs="+",
+        default=[11, 22, 33, 44],
+        help="Seeds to pair over",
+    )
+    ablate.add_argument(
+        "--step-minutes", type=int, default=10, help="Inference step in minutes"
+    )
+    ablate.add_argument(
+        "--metric",
+        default="balanced_accuracy",
+        help="Metric to compare configurations on",
+    )
+    ablate.add_argument(
+        "--output", type=Path, default=None, help="Write structured results as JSON"
+    )
+
+
+def _record(
+    experiment: str,
+    *,
+    configuration: dict[str, object],
+    seeds: list[int],
+    results: dict[str, object],
+    notes: list[str] | None = None,
+) -> object:
+    """Wrap a result in the provenance needed to interpret it later."""
+    from .evaluation.provenance import ExperimentRecord
+
+    return ExperimentRecord(
+        experiment=experiment,
+        configuration=configuration,
+        seeds=seeds,
+        results=results,
+        notes=notes or [],
+    )
+
+
+def _add_attribution_parser(sub: argparse._SubParsersAction) -> None:
+    """Register the attribution comparison experiment."""
+    study = sub.add_parser(
+        "attribution",
+        help="Compare naive against occupancy-aware activity attribution",
+        description=(
+            "Run the same simulated households twice -- once attributing all "
+            "ambient activity to the resident, once discounting it by the "
+            "probability the resident generated it -- and report the difference."
+        ),
+    )
+    study.add_argument("--days", type=int, default=10, help="Days per scenario")
+    study.add_argument("--seed", type=int, default=4242, help="Random seed")
+    study.add_argument(
+        "--seeds",
+        type=int,
+        nargs="+",
+        default=None,
+        help=(
+            "Two or more seeds to replicate over. A single seed demonstrates "
+            "the mechanism; estimating the effect needs replication, see "
+            "docs/SIMULATION_PROTOCOLS.md"
+        ),
+    )
+    study.add_argument(
+        "--step-minutes", type=int, default=15, help="Inference step in minutes"
+    )
+    study.add_argument(
+        "--output", type=Path, default=None, help="Write structured results as JSON"
+    )
+
+
+def _run_replicated_attribution(args: argparse.Namespace) -> None:
+    """Estimate attribution's effect across independent seeds."""
+    from .evaluation.attribution import run_replicated_attribution_study
+
+    study = run_replicated_attribution_study(
+        args.seeds,
+        days=args.days,
+        step=timedelta(minutes=args.step_minutes),
+    )
+
+    print()
+    print(f"Attribution across {len(study.seeds)} paired seeds per scenario")
+    print("Intervals are bootstrap; mcse is the Monte Carlo standard error.")
+    print()
+    print(
+        f"{'scenario':<28}{'contam':>8}{'acc gain':>10}"
+        f"{'95% CI':>20}{'calib gain':>12}{'visRec':>8}"
+    )
+    for aggregate in study.aggregates:
+        gain = aggregate.balanced_accuracy_gain
+        calibration = aggregate.calibration_gain
+        interval = f"[{gain.ci_low:+.4f},{gain.ci_high:+.4f}]"
+        print(
+            f"{aggregate.scenario:<28}"
+            f"{aggregate.contaminated_fraction['mean']:>8.2f}"
+            f"{gain.mean_difference:>+10.4f}"
+            f"{interval:>20}"
+            f"{calibration.mean_difference:>+12.4f}"
+            f"{aggregate.visitor_recall['mean']:>8.2f}"
+        )
+    print()
+    print(
+        "Attribution is not free. Discounting ambient evidence costs accuracy "
+        "wherever the discount is wrong, and over 100 seeds the cost is "
+        "measurable even in an empty home. Read the calibration column with "
+        "the accuracy one: the two do not move together."
+    )
+
+    if args.output is not None:
+        _record(
+            "attribution_replicated",
+            configuration={
+                "days": args.days,
+                "step_minutes": args.step_minutes,
+                "replications": len(study.seeds),
+                "scenarios": [a.scenario for a in study.aggregates],
+            },
+            seeds=list(study.seeds),
+            results=study.to_dict(),
+            notes=[
+                "Both arms see identical households, visitors and sensor "
+                "records, so any difference is attributable to attribution.",
+                "Report the MCSE with any effect quoted from this artefact.",
+            ],
+        ).write(
+            args.output
+        )  # type: ignore[attr-defined]
+        print(f"Structured results written to {args.output}")
+
+
+def _run_attribution(args: argparse.Namespace) -> None:
+    """Dispatch the attribution comparison experiment."""
+    from .evaluation.attribution import run_attribution_study, standard_scenarios
+
+    if getattr(args, "seeds", None):
+        if len(args.seeds) == 1:
+            args.seed = args.seeds[0]
+        else:
+            _run_replicated_attribution(args)
+            return
+
+    study = run_attribution_study(
+        standard_scenarios(days=args.days, seed=args.seed),
+        step=timedelta(minutes=args.step_minutes),
+    )
+
+    print("\nNaive against occupancy-aware attribution")
+    print("Both arms see identical households, visitors and sensor records.\n")
+    print(
+        f"{'scenario':<28}{'contam':>8}{'naive':>8}{'aware':>8}"
+        f"{'gain':>8}{'calib':>8}{'visF1':>7}"
+    )
+    for comparison in study.comparisons:
+        print(
+            f"{comparison.scenario:<28}"
+            f"{comparison.contaminated_fraction:>8.3f}"
+            f"{comparison.naive.states.balanced_accuracy:>8.3f}"
+            f"{comparison.occupancy_aware.states.balanced_accuracy:>8.3f}"
+            f"{comparison.balanced_accuracy_gain:>+8.3f}"
+            f"{comparison.calibration_gain:>+8.3f}"
+            f"{comparison.visitor_detection.f1:>7.2f}"
+        )
+
+    contaminated = study.contaminated
+    if contaminated:
+        mean_gain = sum(c.balanced_accuracy_gain for c in contaminated) / len(
+            contaminated
+        )
+        print(
+            "\nMean balanced-accuracy gain where another person was present: "
+            f"{mean_gain:+.4f}"
+        )
+    print(
+        "\nA gain of zero in an uncontaminated scenario is the expected result: "
+        "attribution should be a no-op when nobody else is in the home."
+    )
+
+    if args.output is not None:
+        _record(
+            "attribution_comparison",
+            configuration={
+                "days": args.days,
+                "step_minutes": args.step_minutes,
+                "scenarios": [s.scenario for s in study.comparisons],
+            },
+            seeds=[args.seed],
+            results=study.to_dict(),
+            notes=[
+                "Both arms see identical households, visitors and sensor "
+                "records, so any difference is attributable to attribution.",
+            ],
+        ).write(
+            args.output
+        )  # type: ignore[attr-defined]
+        print(f"Structured results written to {args.output}")
+
+
+def _run_demo(args: argparse.Namespace) -> None:
+    """Dispatch the end-to-end demonstration."""
+    from .examples.demos.ambient_pipeline_demo import run_demo
+
+    run_demo(
+        days=args.days,
+        seed=args.seed,
+        step=timedelta(minutes=args.step_minutes),
+        output=args.output,
+    )
+
+
+#: Sensor configurations compared by the ``ablate`` command. Each is a
+#: plausible real deployment rather than an arbitrary subset, so the
+#: comparison answers a question a designer would actually ask.
+ABLATION_SUBSETS: dict[str, tuple[str, ...]] = {
+    "all_modalities": (
+        "front_door",
+        "bedroom_motion",
+        "bathroom_motion",
+        "kitchen_motion",
+        "living_motion",
+        "fridge_contact",
+        "bed_pressure",
+        "living_radar",
+        "wearable_motion",
+        "resident_beacon",
+    ),
+    "object_sensors_only": (
+        "front_door",
+        "bedroom_motion",
+        "bathroom_motion",
+        "kitchen_motion",
+        "living_motion",
+        "fridge_contact",
+    ),
+    "objects_plus_wearable": (
+        "front_door",
+        "bedroom_motion",
+        "bathroom_motion",
+        "kitchen_motion",
+        "living_motion",
+        "fridge_contact",
+        "wearable_motion",
+        "resident_beacon",
+    ),
+    "radar_door_bed": ("front_door", "living_radar", "bed_pressure"),
+    "radar_door_bed_wearable": (
+        "front_door",
+        "living_radar",
+        "bed_pressure",
+        "wearable_motion",
+        "resident_beacon",
+    ),
+    "minimal_door_bed": ("front_door", "bed_pressure"),
+}
+
+
+def _run_ablation(args: argparse.Namespace) -> None:
+    """Dispatch the paired sensor-ablation experiment."""
+    from .evaluation.ablation import named_subsets, run_ablation
+    from .simulation.household import HouseholdConfig
+
+    report = run_ablation(
+        named_subsets(ABLATION_SUBSETS),
+        seeds=args.seeds,
+        household=HouseholdConfig(days=args.days),
+        step=timedelta(minutes=args.step_minutes),
+    )
+
+    summary = report.summary(args.metric)
+    print(f"\nPaired sensor ablation over seeds {report.seeds}")
+    print(f"Metric: {args.metric}\n")
+    print(
+        f"{'configuration':<26}{'sensors':>8}{'mean':>9}{'sd':>8}{'min':>8}{'max':>8}"
+    )
+    for name, stats in summary.items():
+        print(
+            f"{name:<26}{int(stats['n_sensors']):>8}{stats['mean']:>9.3f}"
+            f"{stats['sd']:>8.3f}{stats['min']:>8.3f}{stats['max']:>8.3f}"
+        )
+
+    reference = next(iter(summary))
+    print(f"\nPaired differences against '{reference}' (same households):")
+    for name in report.configurations:
+        if name == reference:
+            continue
+        difference = report.compare(reference, name, metric=args.metric)
+        verdict = "clear" if difference.excludes_zero else "not distinguishable"
+        print(
+            f"  {reference} - {name:<26} {difference.mean_difference:+.3f}  "
+            f"95% CI [{difference.ci_low:+.3f}, {difference.ci_high:+.3f}]  "
+            f"dz={difference.effect_size:+.2f}  {verdict}"
+        )
+
+    print(
+        "\nDifferences are paired: every configuration was evaluated on the same\n"
+        "simulated households, so these compare sensing rather than residents."
+    )
+    if args.output is not None:
+        _record(
+            "sensor_ablation",
+            configuration={
+                "days": args.days,
+                "step_minutes": args.step_minutes,
+                "metric": args.metric,
+                "subsets": {k: list(v) for k, v in ABLATION_SUBSETS.items()},
+            },
+            seeds=report.seeds,
+            results=report.to_dict(args.metric),
+            notes=[
+                "Configurations are evaluated on identical simulated "
+                "households, so differences compare sensing rather than "
+                "residents.",
+            ],
+        ).write(
+            args.output
+        )  # type: ignore[attr-defined]
+        print(f"Structured results written to {args.output}")
+
+
+def _run_model(args: argparse.Namespace, parser: argparse.ArgumentParser) -> None:
+    """Dispatch the single-model fitting commands."""
+    dataset = SensorDataset.from_csv(args.data)
+    if args.model == "bernoulli-ar":
+        model = BernoulliAutoregressiveModel(list(dataset.data.columns), args.target)
+        model.fit(dataset)
+    elif args.model == "nhpp-pelt":
+        nhpp = NHPPPELT(NHPPConfig())
+        nhpp.fit(dataset, sensor=args.sensor)
+    else:  # pragma: no cover - argparse rejects unknown commands first
+        parser.print_help()
+
+
+def main() -> None:
+    """Run the sensor modeling command-line interface."""
+    parser = argparse.ArgumentParser(description="Sensor modeling CLI")
+    sub = parser.add_subparsers(dest="model", required=True)
+    _add_model_parsers(sub)
+    _add_demo_parser(sub)
+    _add_ablation_parser(sub)
+    _add_attribution_parser(sub)
+
+    args = parser.parse_args()
+    setup_logging()
+    logging.getLogger("sensor_modeling").setLevel(logging.WARNING)
+
+    if args.model == "demo":
+        _run_demo(args)
+    elif args.model == "ablate":
+        _run_ablation(args)
+    elif args.model == "attribution":
+        _run_attribution(args)
+    else:
+        _run_model(args, parser)
+
+
+if __name__ == "__main__":
+    main()

sensor_modeling/context/__init__.py

@@ -0,0 +1,33 @@
+"""Occupancy, visitors, and uncertainty-aware attribution of activity.
+
+Ambient sensors observe a home, not a person. This package estimates who is
+present and converts that into the probability that the monitored resident --
+rather than a visitor or carer -- generated what each sensor saw. It uses
+only anonymous evidence, and deliberately never attempts biometric identity.
+"""
+
+from .occupancy import (
+    CONTEXTS,
+    DEFAULT_BEACON_PRESENCE,
+    DEFAULT_CONTEXT_DWELL,
+    DEFAULT_RESIDENT_SHARE,
+    DEFAULT_TRACK_COUNTS,
+    ContextConfig,
+    ContextEstimate,
+    OccupancyContext,
+    ResidentContextEstimator,
+    rooms_active_at,
+)
+
+__all__ = [
+    "CONTEXTS",
+    "DEFAULT_BEACON_PRESENCE",
+    "DEFAULT_CONTEXT_DWELL",
+    "DEFAULT_RESIDENT_SHARE",
+    "DEFAULT_TRACK_COUNTS",
+    "ContextConfig",
+    "ContextEstimate",
+    "OccupancyContext",
+    "ResidentContextEstimator",
+    "rooms_active_at",
+]