sensor-modeling 0.2.0__py3-none-any.whl

sensor_modeling-0.2.0.dist-info/METADATA

@@ -0,0 +1,683 @@
+Metadata-Version: 2.4
+Name: sensor-modeling
+Version: 0.2.0
+Summary: Interpretable, probabilistic, privacy-preserving multimodal ambient sensing for behavioural research
+Author-email: Diogo Ribeiro <dfr@esmad.ipp.pt>
+Maintainer-email: Diogo Ribeiro <dfr@esmad.ipp.pt>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/DiogoRibeiro7/behavioral-sensing-research
+Project-URL: Documentation, https://sensor-modeling.readthedocs.io
+Project-URL: Repository, https://github.com/DiogoRibeiro7/behavioral-sensing-research
+Project-URL: Bug Tracker, https://github.com/DiogoRibeiro7/behavioral-sensing-research/issues
+Project-URL: Feature Requests, https://github.com/DiogoRibeiro7/behavioral-sensing-research/discussions
+Project-URL: Changelog, https://github.com/DiogoRibeiro7/behavioral-sensing-research/blob/main/CHANGELOG.md
+Project-URL: Zenodo DOI, https://doi.org/10.5281/zenodo.17070041
+Project-URL: Citation, https://github.com/DiogoRibeiro7/behavioral-sensing-research/blob/main/CITATION.cff
+Project-URL: Research Papers, https://github.com/DiogoRibeiro7/behavioral-sensing-research/blob/main/paper.bib
+Project-URL: Funding, https://github.com/sponsors/DiogoRibeiro7
+Keywords: sensor-modeling,ambient-assisted-living,digital-health,smart-homes,time-series-analysis,change-point-detection,hidden-markov-models,behavioral-monitoring,activity-recognition,machine-learning,healthcare-technology,iot-sensors,elderly-care,assistive-technology,python
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Home Automation
+Classifier: Topic :: System :: Monitoring
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Operating System :: OS Independent
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: MacOS
+Classifier: Natural Language :: English
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Flask
+Classifier: Framework :: Matplotlib
+Classifier: Framework :: Jupyter
+Requires-Python: <3.13,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21.0
+Requires-Dist: pandas>=1.3.0
+Requires-Dist: scipy>=1.7.0
+Requires-Dist: scikit-learn>=1.0.0
+Requires-Dist: matplotlib>=3.5.0
+Requires-Dist: seaborn>=0.11.0
+Requires-Dist: networkx>=2.6
+Requires-Dist: h5py>=3.1.0
+Requires-Dist: plotly>=5.0.0
+Requires-Dist: bokeh>=2.4.0
+Requires-Dist: flask>=2.0.0
+Requires-Dist: click>=8.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: tqdm>=4.60.0
+Requires-Dist: joblib>=1.1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-xdist>=3.0.0; extra == "dev"
+Requires-Dist: pytest-benchmark>=4.0.0; extra == "dev"
+Requires-Dist: hypothesis>=6.0.0; extra == "dev"
+Requires-Dist: coverage[toml]>=7.0.0; extra == "dev"
+Requires-Dist: pre-commit>=3.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Requires-Dist: flake8-docstrings>=1.7.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: bandit>=1.7.0; extra == "dev"
+Requires-Dist: safety>=2.0.0; extra == "dev"
+Requires-Dist: radon>=6.0.1; extra == "dev"
+Requires-Dist: build>=0.10.0; extra == "dev"
+Requires-Dist: twine>=6.2.0; extra == "dev"
+Requires-Dist: setuptools-scm>=7.0.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.6.0; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5.0; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.24.0; extra == "docs"
+Requires-Dist: mkdocs-jupyter>=0.24.0; extra == "docs"
+Requires-Dist: jupyterlab>=4.0.0; extra == "docs"
+Requires-Dist: notebook>=7.0.0; extra == "docs"
+Requires-Dist: ipykernel>=6.20.0; extra == "docs"
+Provides-Extra: performance
+Requires-Dist: numba>=0.58.0; extra == "performance"
+Requires-Dist: cython>=3.0.0; extra == "performance"
+Requires-Dist: bottleneck>=1.3.0; extra == "performance"
+Requires-Dist: numexpr>=2.8.0; extra == "performance"
+Provides-Extra: viz
+Requires-Dist: plotly>=5.15.0; extra == "viz"
+Requires-Dist: bokeh>=3.0.0; extra == "viz"
+Requires-Dist: holoviews>=1.16.0; extra == "viz"
+Requires-Dist: panel>=1.8.10; extra == "viz"
+Requires-Dist: dash>=2.10.0; extra == "viz"
+Requires-Dist: streamlit>=1.25.0; extra == "viz"
+Provides-Extra: ml
+Requires-Dist: tensorflow>=2.13.0; extra == "ml"
+Requires-Dist: torch>=2.0.0; extra == "ml"
+Requires-Dist: transformers>=4.30.0; extra == "ml"
+Requires-Dist: xgboost>=1.7.0; extra == "ml"
+Requires-Dist: lightgbm>=4.0.0; extra == "ml"
+Requires-Dist: catboost>=1.2.0; extra == "ml"
+Provides-Extra: clinical
+Requires-Dist: fhir.resources>=7.0.0; extra == "clinical"
+Requires-Dist: pydicom>=2.4.0; extra == "clinical"
+Requires-Dist: nibabel>=5.0.0; extra == "clinical"
+Requires-Dist: mne>=1.4.0; extra == "clinical"
+Provides-Extra: all
+Requires-Dist: sensor-modeling[clinical,dev,docs,ml,performance,viz]; extra == "all"
+Dynamic: license-file
+
+# Sensor Modeling Research Toolkit
+
+A research-grade Python toolkit for **interpretable, probabilistic,
+privacy-preserving** analysis of behavioural sensor data, and for multimodal
+ambient sensing in ambient assisted living (AAL), digital health and smart-home
+research.
+
+It provides an end-to-end pipeline from heterogeneous sensor observations to
+explained alerts, alongside an established modelling core of Bernoulli
+autoregressive models, hidden Markov models, change-point detection and
+non-homogeneous Poisson processes.
+
+> **This is a research toolkit, not a medical device.** Nothing it produces is
+> a diagnosis, and no claim of clinical effectiveness is made or supported.
+> Every quantitative result quoted here comes from the bundled simulator and
+> has **not** been validated against real sensor data.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python Version](https://img.shields.io/badge/python-3.10--3.12-blue.svg)](https://www.python.org/downloads/)
+[![CI](https://github.com/DiogoRibeiro7/behavioral-sensing-research/actions/workflows/ci.yml/badge.svg)](https://github.com/DiogoRibeiro7/behavioral-sensing-research/actions/workflows/ci.yml)
+[![Documentation Status](https://readthedocs.org/projects/sensor-modeling/badge/?version=latest)](https://sensor-modeling.readthedocs.io/en/latest/?badge=latest)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.17070041.svg)](https://doi.org/10.5281/zenodo.17070041)
+[![Version](https://img.shields.io/badge/version-0.2.0-informational.svg)](CHANGELOG.md)
+
+## 🎯 Overview
+
+The **Sensor Modeling Research Toolkit** addresses the growing need for reproducible, interpretable analysis of behavioral sensor streams in smart environments. Unlike general-purpose machine learning libraries, this toolkit provides domain-specific implementations optimized for the unique characteristics of ambient sensor data: irregular sampling, frequent missingness, binary activations, and the need for transparent, clinically interpretable models.
+
+### Key Differentiators
+
+- **Research-Grade Implementation**: Clean, documented, and tested implementations of established algorithms from recent literature
+- **Unified Interface**: Consistent API across different modeling approaches for easy comparison and ensemble methods
+- **Clinical Focus**: Visualization and reporting utilities designed for healthcare stakeholders and non-technical users
+- **Lightweight Deployment**: Minimal dependencies and efficient implementations suitable for edge computing and real-time applications
+- **Extensible Architecture**: Modular design allows researchers to easily add new algorithms and extend existing functionality
+
+## 🧭 Observation, state, change, alert
+
+The platform keeps five kinds of thing strictly distinct, and most of its
+design follows from refusing to collapse them:
+
+| Kind | What it is | Example |
+| --- | --- | --- |
+| **Measured observation** | A sensor reported a value at an instant | The fridge contact closed at 08:14 |
+| **Derived feature** | A value an upstream device computed, carrying its own confidence | The radar reports 2 tracked people |
+| **Inferred state** | A posterior over what the resident was probably doing | `P(kitchen_activity) = 0.81` |
+| **Behavioural change** | A shift against the resident's own history | Sleep has trended down for three weeks |
+| **Alert** | A judgement that a person should look at something | An `attention` alert, with its caveats |
+
+A sensor event is not a behaviour:
+
+```text
+fridge opening      != eating
+tap activation      != drinking
+toilet event        != confirmed toileting
+chair activity      != sedentary behaviour
+door event          != resident movement
+missing observation != inactivity
+```
+
+The state ontology therefore stops at `kitchen_activity` and makes no claim
+about food intake. Two rules are enforced mechanically rather than by
+convention:
+
+- **A missing observation is missing evidence, never negative evidence.**
+  Sensor reliability enters the fusion likelihood as a tempering weight, so a
+  failed sensor contributes a flat likelihood and cannot look like a quiet
+  resident.
+- **Ambient activity is not automatically the resident's.** Occupancy
+  estimation produces `P(activity was the resident's)`, which discounts
+  evidence while a visitor or carer may be present.
+
+The system can also return `unknown`. Abstention is a first-class output, not
+a failure.
+
+### Supported and unsupported claims
+
+The distinction the platform is built to hold. The left column is what the
+evidence supports; the right is what it does **not**, however tempting the
+inference.
+
+| Supported | Not supported |
+| --- | --- |
+| Evidence of kitchen activity | Food consumption |
+| Evidence of bathroom activity | Confirmed toileting |
+| Bed occupancy with sustained low movement | Clinically defined sleep, or a sleep disorder |
+| A door was crossed | The resident left the house |
+| A sustained change against the resident's own history | A cause, a prognosis, or a diagnosis |
+| Reduced room-to-room transitions | Deterioration in mobility as a clinical finding |
+| Sensor coverage has fallen | The resident has become less active |
+| `P(resident generated this activity) = 0.5` | Identification of who did it |
+
+Two of these deserve spelling out.
+
+**`kitchen_activity` is not eating.** A fridge contact records a door opening.
+Turning that into a meal requires evidence the sensor cannot supply, so the
+ontology stops where the evidence stops.
+
+**`sleeping` is not sleep.** It is bed occupancy accompanied by sustained low
+movement. It has no relationship to polysomnography, and mapping it to a
+clinical sleep concept is a further inferential step this platform does not
+take.
+
+## 🏠 Multimodal ambient sensing pipeline
+
+```text
+heterogeneous observations -> validation -> sensor health -> occupancy context
+    -> multimodal fusion -> behavioural state -> adaptive baseline
+    -> change detection -> restrained alerts -> evaluation
+```
+
+| Package | Responsibility |
+| --- | --- |
+| `sensor_modeling.observations` | Canonical hardware-neutral observation model, sensor registry, boundary validation, clock-drift correction |
+| `sensor_modeling.health` | Online per-sensor reliability, emitted as an evidence weight |
+| `sensor_modeling.context` | Occupancy contexts and uncertainty-aware attribution, from anonymous evidence only |
+| `sensor_modeling.states` / `sensor_modeling.fusion` | Continuous-time state ontology and the recursive multimodal filter |
+| `sensor_modeling.baseline` | Adaptive, weekday-aware, non-stationary personal baselines |
+| `sensor_modeling.alerts` | Restrained, explained alerting with deduplication and rate limiting |
+| `sensor_modeling.simulation` | Synthetic households with controlled ground truth |
+| `sensor_modeling.evaluation` | Problem-appropriate metrics and paired sensor-ablation studies |
+| `sensor_modeling.online` | Incremental, snapshot-able orchestration |
+
+### Reproducible end-to-end example
+
+```bash
+sensor-modeling demo --days 90 --seed 20240304 --step-minutes 10
+```
+
+Simulates a household with a carer and visitors, injects a three-day bed-sensor
+dropout and five days of wearable non-adherence, loses, duplicates, delays and
+clock-skews the record, introduces a genuine change in sleep on a known day,
+then runs the whole pipeline and reports what it did and did not recover —
+including its own false-alert burden. Two runs produce identical numbers.
+
+### Sensor-ablation experiment
+
+```bash
+sensor-modeling ablate --days 14 --seeds 11 22 33 44
+```
+
+Every configuration is evaluated on identical simulated households, so the
+comparison measures sensing rather than residents. On a four-seed sweep, adding
+a person-bound wearable to six object sensors recovered most of the full
+ten-sensor deployment's accuracy — the remaining gap is 0.012 balanced accuracy
+(95% CI [+0.004, +0.020]), real but small — while removing the wearable cost
+0.173 (95% CI [+0.140, +0.201]). A five-sensor configuration was the *best
+calibrated* of all despite lower accuracy, which an accuracy-only evaluation
+would have hidden. See [`docs/evaluation.md`](docs/evaluation.md).
+
+> These numbers describe behaviour on the bundled simulator under its default
+> parameters. They are not estimates of field performance. Nothing here has
+> been validated against real sensor data — see
+> [`docs/limitations.md`](docs/limitations.md).
+
+## ✨ Features
+
+### 🔧 **Comprehensive Data Pipeline**
+
+- **Multi-format Loaders**: Support for CSV, JSON, HDF5, and real-time streaming data
+- **Robust Preprocessing**: Missing value imputation, outlier detection, temporal alignment, and data validation
+- **Synthetic Data Generation**: Configurable simulation of sensor networks with ground truth for benchmarking
+- **Quality Assessment**: Automated data quality reporting and sensor failure detection
+
+### 🧠 **Advanced Modeling Capabilities**
+
+#### **Bernoulli Autoregressive Models**
+
+- Implementation of Gillam et al. (2022) approach for activity prediction
+- Automatic sensor selection using stepwise BIC optimization
+- Seasonal pattern detection and multivariate extensions
+- Uncertainty quantification through prediction intervals
+
+#### **Hidden Markov Models (HMMs)**
+
+- Hierarchical HMMs for multi-level activity modeling ([Asghari & Nazerfard, 2019](https://arxiv.org/abs/1903.04820))
+- Scaled Dirichlet HMMs with variational inference
+- Heterogeneous HMMs for multi-source data integration
+- Adaptive HMMs incorporating personal experience
+- Circadian HMMs for rhythm monitoring applications
+
+#### **Change-Point Detection**
+
+- Embedding-based real-time detection ([Dadi et al., 2021](https://doi.org/10.1016/j.eswa.2021.115217))
+- Energy-efficient CPAM algorithm ([Cook et al., 2020](https://doi.org/10.3390/s20010310))
+- Adaptive normalization for non-stationary data
+- Genetic algorithm optimization for parameter tuning
+- Univariate PELT-based segmentation with configurable penalty and L1/L2 costs
+
+#### **Non-Homogeneous Poisson Processes (NHPP)**
+
+- B-spline intensity estimation with PELT segmentation
+- Automatic model selection via AIC/BIC
+- P-spline regularization for smooth intensity curves
+- Time-rescaling diagnostics for model validation
+- Lewis-Shedler thinning for simulation and testing
+
+### 📊 **Advanced Analysis & Interpretation**
+
+#### **Causal Analysis**
+
+- Granger causality testing adapted for binary time series
+- Sensor dependency network construction and analysis
+- Community detection in sensor interaction graphs
+- Critical sensor identification for system robustness
+
+#### **Behavioral Metrics**
+
+- Activity pattern recognition (peak/quiet hours, routine detection)
+- Anomaly scoring using statistical and network-based approaches
+- Trend detection with configurable temporal windows
+- Health indicators derived from activity levels and variability
+
+#### **Cross-Model Comparison**
+
+- Standardized evaluation metrics across different modeling paradigms
+- Statistical significance testing for model performance
+- Automated hyperparameter sweeps and elbow plot generation
+- Cross-validation frameworks adapted for time series data
+
+### 🎨 **Rich Visualization & Reporting**
+
+#### **Interactive Dashboards**
+
+- Real-time data exploration using Plotly and Bokeh
+- Parameter tuning interfaces with immediate visual feedback
+- Drill-down capabilities for detected changes and anomalies
+- Export functionality for presentations and publications
+
+#### **Clinical Visualizations**
+
+- Patient-friendly activity summaries and trend monitors
+- Alert generation based on configurable clinical thresholds
+- Comparison against normative population statistics
+- Minimal FHIR-style observation export for clinical workflow prototyping
+
+#### **Research Tools**
+
+- Publication-quality figures with customizable styling
+- Model diagnostic plots (residuals, QQ plots, time-rescaling)
+- Performance comparison visualizations across multiple models
+- Statistical test result visualization and interpretation
+
+### 🌐 **Deployment & Integration**
+
+#### **Command-Line Interface**
+
+- Batch processing capabilities for large-scale experiments
+- Configurable analysis pipelines with JSON/YAML configuration
+- Automated report generation in multiple formats (LaTeX, HTML, minimal FHIR-style JSON)
+- Integration with cluster computing environments
+
+#### **Web Application**
+
+- Lightweight Flask-based interface for non-technical users
+- Secure file upload with authentication and validation
+- Real-time analysis results and interactive visualizations
+- RESTful API for integration with existing systems
+
+## 🚀 Installation
+
+```bash
+# Basic installation
+pip install -e .[dev]
+
+# For development with all tools
+pip install -e .[dev]
+pre-commit install
+```
+
+## 📖 Quick Start
+
+### Basic Usage Example
+
+```python
+from sensor_modeling.models import BernoulliAutoregressiveModel
+from sensor_modeling.utils import simulate_sensor_data
+import pandas as pd
+
+# Load or simulate sensor data
+data = simulate_sensor_data(n_days=30, n_sensors=4)
+print(f"Generated {len(data.data)} 15-minute intervals")
+
+# Fit Bernoulli autoregressive model
+model = BernoulliAutoregressiveModel(
+    sensor_names=data.data.columns.tolist(),
+    target_sensor="sensor_0"
+)
+result = model.fit(data)
+
+if result["convergence"]:
+    print(f"Model converged with BIC: {result['bic']:.2f}")
+    print(f"Selected sensors: {result['selected_sensors']}")
+
+    # Generate predictions
+    probabilities = model.predict_probabilities(data)
+    print(f"Predicted activation probabilities: {probabilities[:5]}")
+```
+
+### Advanced Multi-Model Analysis
+
+```python
+from sensor_modeling.analysis import AnalysisPipeline
+from sensor_modeling.models import BernoulliAutoregressiveModel
+from sensor_modeling.hmm import HierarchicalHMM
+from sensor_modeling.change_point import EmbeddingCPD
+
+# Set up comprehensive analysis pipeline
+pipeline = AnalysisPipeline()
+
+# Run all available models
+results = pipeline.run(data)
+
+# Generate comprehensive reports
+pipeline.generate_report(results, output_dir="analysis_output")
+print("Analysis complete! Check analysis_output/ for results.")
+```
+
+### Causal Network Analysis
+
+```python
+from sensor_modeling.analysis import SensorDependencyNetwork
+
+# Build causal dependency network
+network_builder = SensorDependencyNetwork(significance_level=0.05)
+network = network_builder.build_network(data.data)
+
+# Analyze network structure
+stats = network_builder.get_network_statistics()
+roles = network_builder.identify_sensor_roles()
+critical = network_builder.find_critical_sensors()
+
+print(f"Network has {stats['num_edges']} causal relationships")
+print(f"Most critical sensor: {critical['most_critical']}")
+
+# Visualize network
+network_builder.plot_network()
+```
+
+### Command-Line Usage
+
+```bash
+# Fit Bernoulli autoregressive model
+sensor-modeling bernoulli-ar data/sensor_readings.csv kitchen_motion
+
+# Run NHPP-PELT change-point detection  
+sensor-modeling nhpp-pelt data/sensor_readings.csv motion_sensor
+
+# Get help on available options
+sensor-modeling --help
+```
+
+## 🏗️ Architecture Overview
+
+The toolkit is organized into four primary layers designed for modularity and extensibility:
+
+### Core Models (`sensor_modeling.models`)
+
+- **Bernoulli Autoregressive**: Single and multivariate models for activity prediction
+- **NHPP-PELT**: Non-homogeneous Poisson process with change-point segmentation
+- **Change-Point Detection**: Multiple algorithms for detecting behavioral changes
+- **Hidden Markov Models**: Various HMM variants for state-based modeling
+
+### Analysis Framework (`sensor_modeling.analysis`)
+
+- **Preprocessing**: Data cleaning, validation, and feature engineering pipelines
+- **Causal Analysis**: Granger causality testing and network analysis
+- **Behavioral Metrics**: Activity pattern recognition and health indicators
+- **Model Comparison**: Cross-validation and statistical testing frameworks
+
+### Visualization Suite (`sensor_modeling.visualization`)
+
+- **Interactive**: Real-time dashboards and parameter tuning interfaces
+- **Clinical**: Patient-friendly summaries and alert systems
+- **Research**: Publication-quality plots and diagnostic visualizations
+- **Web Application**: Browser-based interface for non-technical users
+
+### Utilities (`sensor_modeling.utils`)
+
+- **Data I/O**: Multi-format loaders and synthetic data generation
+- **Validation**: Model performance assessment and calibration testing
+- **Plotting**: Specialized plotting functions for sensor data
+- **Missing Data**: Robust handling of incomplete observations
+
+## 📈 Roadmap Progress
+
+The high-level status table below summarizes current capabilities. See
+[`ROADMAP.md`](ROADMAP.md) for release milestones, quality gates, and
+longer-term priorities.
+
+Feature                             | Status     | Implementation
+----------------------------------- | ---------- | -----------------------------------------
+**Bernoulli Autoregressive Models** | ✅ Complete | Single/multivariate, automatic selection
+**Hidden Markov Models**            | ✅ Complete | 5 variants with different emission models
+**Change Point Detection**          | 🟡 Partial | 4 algorithms, expanding to deep learning
+**NHPP-PELT**                       | ✅ Complete | B-spline intensities, diagnostics
+**Causal Network Analysis**         | ✅ Complete | Granger tests, network metrics
+**Missing Data Handling**           | ✅ Complete | Gap-aware workflows plus reliability-tempered fusion
+**Multimodal Fusion**               | ✅ Complete | Continuous-time filter over asynchronous modalities
+**Sensor Health Modelling**         | ✅ Complete | Online reliability feeding the inference layer
+**Occupancy & Attribution**         | ✅ Complete | Probabilistic visitor/resident attribution
+**Adaptive Baselines**              | ✅ Complete | Robust, weekday-aware, non-stationary
+**Sensor Ablation Studies**         | ✅ Complete | Paired designs with effect sizes
+**Deep Learning CPD**               | 🔵 Planned | Transformer and CNN-based approaches
+**Real-time Processing**            | ✅ Complete | Incremental pipeline, bounded memory, snapshot/restore
+**Clinical Integration**            | 🟡 Partial | Minimal FHIR-style export, expanding toward validated HL7 profiles
+
+## 📚 Research Foundation
+
+This toolkit implements and extends algorithms from recent peer-reviewed research:
+
+### Core Publications
+
+- **Gillam et al. (2022)**: "Modeling and forecasting of at home activity in older adults using passive sensor technology" - _Computers in Biology and Medicine_
+- **Asghari & Nazerfard (2019)**: "Online Human Activity Recognition Employing Hierarchical Hidden Markov Models" - _arXiv:1903.04820_
+- **Dadi et al. (2021)**: "Embedding-based real-time change point detection" - _Expert Systems with Applications_
+- **Cook et al. (2020)**: "Easing Power Consumption of Wearable Activity Monitoring with Change Point Detection" - _Sensors_
+
+### Additional References
+
+The toolkit incorporates methodologies from 20+ research papers in ambient assisted living, change-point detection, and time series analysis. See [`paper.bib`](paper.bib) for complete references.
+
+## 🔬 Example Applications
+
+### Smart Home Monitoring
+
+```python
+# Detect changes in daily routines
+from sensor_modeling.change_point import EmbeddingCPD
+
+cpd = EmbeddingCPD(window=7)
+cpd.fit(daily_activity_data)
+change_points = cpd.predict(plot=True)
+print(f"Detected {len(change_points)} routine changes")
+```
+
+### Clinical Decision Support
+
+```python
+# Generate clinical alerts
+from sensor_modeling.visualization.clinical import clinical_alerts
+
+thresholds = {
+    "bathroom_visits": 8,  # per day
+    "sleep_duration": 4,   # hours minimum
+    "activity_level": 0.1  # baseline activity
+}
+
+alerts = clinical_alerts(patient_data, thresholds)
+active_alerts = [sensor for sensor, triggered in alerts.items() if triggered]
+print(f"Active clinical alerts: {active_alerts}")
+```
+
+### Research Studies
+
+```python
+# Cross-model comparison for publication
+from sensor_modeling.analysis.comparison import cross_validate
+
+models = {
+    "Bernoulli AR": BernoulliAutoregressiveModel(sensors, target),
+    "Hierarchical HMM": HierarchicalHMM(n_states=4),
+    "NHPP-PELT": NHPPPELT(NHPPConfig(n_basis=5))
+}
+
+cv_scores = cross_validate(models, dataset, n_splits=5)
+print("Cross-validation results:", cv_scores)
+```
+
+## 🤝 Contributing
+
+We welcome contributions from researchers and practitioners! The toolkit is designed to be easily extensible:
+
+### Getting Started
+
+1. **Fork the repository** and create your feature branch:
+
+  ```bash
+  git checkout -b feature/my-new-algorithm
+  ```
+
+2. **Install development dependencies**:
+
+  ```bash
+  pip install -e .[dev]
+  pre-commit install
+  ```
+
+3. **Add your implementation** following the existing patterns:
+
+  ```python
+  # Example: New change-point detector
+  from sensor_modeling.change_point.base import BaseCPD
+
+  class MyNewCPD(BaseCPD):
+      def fit(self, series):
+          # Your algorithm here
+          return self
+
+      def predict(self):
+          # Return change points
+          return self.change_points_
+  ```
+
+4. **Write tests and documentation**:
+
+  ```bash
+  pytest tests/test_my_new_algorithm.py
+  mkdocs build --strict
+  ```
+
+5. **Submit a pull request** with:
+
+  - Clear description of the algorithm and its benefits
+  - Tests demonstrating correctness and performance
+  - Documentation updates including usage examples
+  - Reference to relevant publications
+
+### Contribution Guidelines
+
+- **Code Style**: Follow PEP 8, use type hints, write comprehensive docstrings
+- **Testing**: Maintain >90% test coverage, include property-based tests for core algorithms
+- **Documentation**: Update API docs and add tutorial notebooks for new features
+- **Performance**: Include benchmarks for computationally intensive algorithms
+- **Reproducibility**: Use fixed random seeds and provide example datasets
+
+See <CONTRIBUTING.md> for detailed guidelines and our [Code of Conduct](CODE_OF_CONDUCT.md).
+Maintainers should use [`RELEASE.md`](RELEASE.md) for the main-only release
+checklist.
+
+## 📄 License
+
+Distributed under the [MIT License](LICENSE). This allows for both academic and commercial use while maintaining attribution to the original authors.
+
+## 📞 Contact & Support
+
+- **Primary Author**: Diogo Ribeiro (<dfr@esmad.ipp.pt>)
+- **Institution**: ESMAD - Instituto Politécnico do Porto
+- **Issues**: Use GitHub Issues for bug reports and feature requests
+- **Discussions**: GitHub Discussions for questions and community support
+- **Security**: Follow [`SECURITY.md`](SECURITY.md) for private vulnerability reports
+- **Support**: See [`SUPPORT.md`](SUPPORT.md) for the right support channel
+
+## 📖 Documentation
+
+- **Online Documentation**: [sensor-modeling.readthedocs.io](https://sensor-modeling.readthedocs.io)
+- **API Reference**: Complete documentation of all classes and functions
+- **Tutorials**: Step-by-step guides for common use cases
+- **Examples**: Jupyter notebooks demonstrating advanced workflows
+
+## 🏆 Citation
+
+If you use this software in your research, please cite it as:
+
+```bibtex
+@software{ribeiro2025sensor,
+  title={Sensor Modeling Research Toolkit},
+  author={Ribeiro, Diogo},
+  year={2026},
+  url={https://github.com/DiogoRibeiro7/behavioral-sensing-research},
+  version={0.2.0},
+  doi={10.5281/zenodo.17070041}
+}
+```
+
+For the underlying methodology, please also cite relevant papers listed in [`CITATION.cff`](CITATION.cff).