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).
