Wearable_TimeSeries_Health_Monitor

<div align="center">

Language / 语言: 中文 | English

</div>

---

<a id="中文版本"></a>

Wearable_TimeSeries_Health_Monitor

面向可穿戴设备的多用户健康监控方案：一份模型、一个配置，就能为不同用户构建个性化异常检测。模型基于 Phased LSTM + Temporal Fusion Transformer (TFT)，并整合自适应基线、因子特征以及单位秒级的数据滑窗能力，适合当作 HuggingFace 模型或企业内部服务快速接入。

---

🌟 模型应用亮点

---

⚡ 核心特点与技术优势

🎯 自适应基线：个人与群体智能融合

模型采用自适应基线策略，根据用户历史数据量动态选择最优基线：

• 个人基线优先：当用户有足够历史数据（如 ≥7 天）时，使用个人 HRV 均值/标准差作为基线，捕捉个体生理节律差异
• 群体基线兜底：新用户或数据稀疏时，自动切换到群体统计基线，确保冷启动也能稳定检测
• 平滑过渡机制：通过加权混合（如 final_mean = α × personal_mean + (1-α) × group_mean）实现从群体到个人的渐进式适应
• 实时基线更新：推理过程中持续累积用户数据，基线随用户状态演化而动态调整，提升长期监控精度

优势：相比固定阈值或纯群体基线，自适应基线能同时兼顾个性化敏感度（减少误报）和冷启动鲁棒性（新用户可用），特别适合多用户、长周期监控场景。

⏱️ 灵活的时间窗口与周期

• 5 分钟级粒度：每条数据点代表 5 分钟聚合，支持秒级到小时级的灵活时间尺度
• 可配置窗口大小：默认 12 点（1 小时），可根据业务需求调整为 6 点（30 分钟）或 24 点（2 小时）
• 不等间隔容错：Phased LSTM 架构天然处理缺失数据点，即使数据稀疏（如夜间传感器断开）也能稳定推理
• 多时间尺度特征：同时提取短期波动（RMSSD）、中期趋势（滑动均值）和长期模式（日/周周期），捕捉不同时间尺度的异常信号

优势：适应不同设备采样频率、用户佩戴习惯，无需强制对齐时间戳，降低数据预处理复杂度。

🔄 多通道数据协同作用

模型整合4 大类特征通道，通过因子特征与注意力机制实现跨通道信息融合：

1. 生理通道（HR、HRV 系列、呼吸率、血氧）

   • 直接反映心血管与呼吸系统状态
   • 因子特征：physiological_mean, physiological_std, physiological_max, physiological_min

2. 活动通道（步数、距离、能量消耗、加速度、陀螺仪）

   • 捕捉运动强度与身体负荷
   • 因子特征：activity_mean, activity_std 等

3. 环境通道（光线、时间周期、数据质量）

   • 提供上下文信息，区分运动性心率升高 vs 静息异常
   • 类别特征：time_period_primary（morning/day/evening/night）

4. 基线通道（自适应基线均值/标准差、偏差特征）

   • 提供个性化参考基准，计算 hrv_deviation_abs, hrv_z_score 等相对异常指标

协同机制：

• 因子特征聚合：将同类通道的统计量（均值/标准差/最值）作为高层特征，让模型学习通道间的关联模式
• TFT 注意力：Temporal Fusion Transformer 的变量选择网络自动识别哪些通道在特定时间点最重要
• 已知未来特征：时间特征（小时、星期、是否周末）帮助模型理解周期性，区分正常波动与异常

优势：多通道协同能显著降低单一指标误报（如运动导致心率升高），提升异常检测的上下文感知能力，特别适合可穿戴设备的多传感器融合场景。

---

📊 核心指标（短期窗口）

• F1: 0.2819
• Precision: 0.1769
• Recall: 0.6941
• 最佳阈值: 0.53
• 窗口定义: 12 条 5 分钟数据（1小时时间窗，预测未来 0.5 小时）

模型偏向召回，适合“异常先提醒、人机协同复核”的场景。可通过阈值/采样策略调节精度与召回。

---

🚀 快速体验

1. 克隆或下载模型仓库

git clone https://huggingface.co/oscarzhang/Wearable_TimeSeries_Health_Monitor
cd Wearable_TimeSeries_Health_Monitor
pip install -r requirements.txt

2. 运行内置 Demo（无需额外数据）

# 默认跑 ab60 案例
python test_wearable_service.py

# 批量跑全部预置客户
python test_wearable_service.py --case all

# 想从原始 stage1 CSV 抽样测试
python test_wearable_service.py --from-raw

test_wearable_service.py 将自动：

• 加载 WearableAnomalyDetector
• 读取配置驱动特征
• 构建窗口并执行预测
• 输出每位“客户”的异常分数、阈值、预测详情

3. 在业务代码中调用

from wearable_anomaly_detector import WearableAnomalyDetector

detector = WearableAnomalyDetector(
    model_dir="checkpoints/phase2/exp_factor_balanced",
    threshold=0.53,
)

result = detector.predict(data_points, return_score=True, return_details=True)
print(result)

data_points 为 12 条最新的 5 分钟记录；若缺静态特征/设备信息，系统会自动从配置/缓存补齐。

---

🔧 输入与输出

输入（单个数据点）

{
  "timestamp": "2024-01-01T08:00:00",
  "deviceId": "ab60",            # 可选，缺失时会自动创建匿名 ID
  "features": {
    "hr": 72.0,
    "hrv_rmssd": 30.0,
    "time_period_primary": "morning",
    "data_quality": "high",
    ...
  }
}

• 每个窗口需 12 条数据（默认 1 小时）
• 特征是否必填由 configs/features_config.json 控制
• 缺失值会自动回落到 default 或 category_mapping 定义值

输出

{
  "is_anomaly": True,
  "anomaly_score": 0.5760,
  "threshold": 0.5300,
  "details": {
     "window_size": 12,
     "model_output": 0.5760,
     "prediction_confidence": 0.0460
  }
}

---

🧱 模型架构与训练

• 模型骨干：Phased LSTM 处理不等间隔序列 + Temporal Fusion Transformer 聚合时间上下文
• 异常检测头：增强注意力、多层 MLP、可选对比学习/类型辅助头
• 特征体系：
  • 生理：HR、HRV（RMSSD/SDNN/PNN50…）
  • 活动：步数、距离、能量消耗、加速度、陀螺仪
  • 环境：光线、昼夜标签、数据质量
  • 基线：自适应基线均值/标准差 + 偏差特征
• 标签来源：问卷高置信度标签 + 自适应基线低置信度标签
• 训练流程：Stage1/2/3 数据加工 ➜ Phase1 自监督预训练 ➜ Phase2 监督微调 ➜ 阈值/案例校正

---

📦 仓库结构（部分）

├─ configs/
│   └─ features_config.json     # 特征定义 & 归一化策略
├─ wearable_anomaly_detector.py # 核心封装：加载、预测、批处理
├─ feature_calculator.py        # 配置驱动的特征构建 + 用户历史缓存
├─ test_wearable_service.py     # HuggingFace Demo脚本（内含预置案例）
└─ checkpoints/phase2/...       # 模型权重 & summary

---

📚 数据来源与许可证

• 训练数据基于 “A continuous real-world dataset comprising wearable-based heart rate variability alongside sleep diaries”（Baigutanova et al., Scientific Data, 2025）以及其 Figshare 数据集 doi:10.1038/s41597-025-05801-3 / dataset link。
• 该数据集以 Creative Commons Attribution 4.0 (CC BY 4.0) 许可发布，可自由使用、修改、分发，但必须保留署名并附上许可证链接。
• 本仓库沿用 CC BY 4.0 对原始数据的要求；若你在此基础上再加工或发布，请继续保留上述署名与许可证说明。
• 代码/模型可根据需要使用 MIT/Apache 等许可证，但凡涉及数据的部分，仍需遵循 CC BY 4.0。

---

🤝 贡献与扩展

欢迎：

1. 新增特征或数据源 ⇒ 更新 features_config.json + 提交 PR
2. 接入新的用户数据管理/基线策略 ⇒ 扩展 FeatureCalculator 或贡献 UserDataManager
3. 反馈案例或真实部署经验 ⇒ 提 Issue 或 Discussion

---

📄 许可证

• 模型与代码：Apache-2.0。可在保留版权与许可证声明的前提下任意使用/修改/分发。
• 训练数据：原始可穿戴 HRV 数据集使用 CC BY 4.0，复用时请继续保留作者署名与许可信息。

---

🔖 引用

@software{Wearable_TimeSeries_Health_Monitor,
  title  = {Wearable\_TimeSeries\_Health\_Monitor},
  author = {oscarzhang},
  year   = {2025},
  url    = {https://huggingface.co/oscarzhang/Wearable_TimeSeries_Health_Monitor}
}

---

<a id="english-version"></a>

Wearable_TimeSeries_Health_Monitor

A multi-user health monitoring solution for wearable devices: one model, one configuration, enabling personalized anomaly detection for different users. The model is based on Phased LSTM + Temporal Fusion Transformer (TFT), integrating adaptive baselines, factor features, and second-level data sliding window capabilities, suitable for deployment as a HuggingFace model or rapid integration into enterprise services.

---

🌟 Model Highlights

---

⚡ Core Features & Technical Advantages

🎯 Adaptive Baseline: Intelligent Fusion of Personal and Group

The model employs an adaptive baseline strategy that dynamically selects the optimal baseline based on user historical data volume:

• Personal Baseline Priority: When users have sufficient historical data (e.g., ≥7 days), use personal HRV mean/std as baseline to capture individual physiological rhythm differences
• Group Baseline Fallback: For new users or sparse data, automatically switch to group statistical baseline, ensuring stable detection even during cold start
• Smooth Transition Mechanism: Achieve gradual adaptation from group to personal through weighted mixing (e.g., final_mean = α × personal_mean + (1-α) × group_mean)
• Real-Time Baseline Updates: Continuously accumulate user data during inference, baseline dynamically adjusts as user state evolves, improving long-term monitoring accuracy

Advantage: Compared to fixed thresholds or pure group baselines, adaptive baselines balance personalized sensitivity (reducing false positives) and cold-start robustness (usable for new users), especially suitable for multi-user, long-term monitoring scenarios.

⏱️ Flexible Time Windows & Periods

• 5-Minute Granularity: Each data point represents 5-minute aggregation, supporting flexible time scales from seconds to hours
• Configurable Window Size: Default 12 points (1 hour), adjustable to 6 points (30 minutes) or 24 points (2 hours) based on business needs
• Uneven Interval Tolerance: Phased LSTM architecture naturally handles missing data points, stable inference even with sparse data (e.g., sensor disconnection at night)
• Multi-Time-Scale Features: Simultaneously extract short-term fluctuations (RMSSD), medium-term trends (rolling mean), and long-term patterns (daily/weekly cycles), capturing anomaly signals at different time scales

Advantage: Adapts to different device sampling frequencies and user wearing habits, no need to force timestamp alignment, reducing data preprocessing complexity.

🔄 Multi-Channel Data Synergy

The model integrates 4 major feature channels, achieving cross-channel information fusion through factor features and attention mechanisms:

1. Physiological Channel (HR, HRV series, respiratory rate, blood oxygen)

   • Directly reflects cardiovascular and respiratory system status
   • Factor features: physiological_mean, physiological_std, physiological_max, physiological_min

2. Activity Channel (steps, distance, energy consumption, acceleration, gyroscope)

   • Captures exercise intensity and body load
   • Factor features: activity_mean, activity_std, etc.

3. Environmental Channel (light, time period, data quality)

   • Provides contextual information, distinguishing exercise-induced heart rate elevation vs. resting anomalies
   • Categorical features: time_period_primary (morning/day/evening/night)

4. Baseline Channel (adaptive baseline mean/std, deviation features)

   • Provides personalized reference baseline, calculating relative anomaly indicators like hrv_deviation_abs, hrv_z_score

Synergy Mechanism:

• Factor Feature Aggregation: Use statistical measures (mean/std/max/min) of similar channels as high-level features, enabling the model to learn association patterns between channels
• TFT Attention: Temporal Fusion Transformer's variable selection network automatically identifies which channels are most important at specific time points
• Known Future Features: Time features (hour, day of week, is_weekend) help the model understand periodicity, distinguishing normal fluctuations from anomalies

Advantage: Multi-channel synergy significantly reduces single-indicator false positives (e.g., exercise-induced heart rate elevation) and improves context-aware anomaly detection, especially suitable for multi-sensor fusion scenarios in wearable devices.

---

📊 Core Metrics (Short-Term Window)

• F1: 0.2819
• Precision: 0.1769
• Recall: 0.6941
• Optimal Threshold: 0.53
• Window Definition: 12 data points of 5-minute intervals (1-hour time window, predicting 0.5 hours ahead)

The model favors recall, suitable for "anomaly-first alert, human-machine collaborative review" scenarios. Precision and recall can be adjusted through threshold/sampling strategies.

---

🚀 Quick Start

1. Clone or Download the Model Repository

git clone https://huggingface.co/oscarzhang/Wearable_TimeSeries_Health_Monitor
cd Wearable_TimeSeries_Health_Monitor
pip install -r requirements.txt

2. Run Built-in Demo (No Additional Data Required)

# Run ab60 case by default
python test_wearable_service.py

# Run all predefined clients
python test_wearable_service.py --case all

# Sample from raw stage1 CSV for testing
python test_wearable_service.py --from-raw

test_wearable_service.py will automatically:

• Load WearableAnomalyDetector
• Read configuration-driven features
• Build windows and execute predictions
• Output anomaly scores, thresholds, and prediction details for each "client"

3. Call in Business Code

from wearable_anomaly_detector import WearableAnomalyDetector

detector = WearableAnomalyDetector(
    model_dir="checkpoints/phase2/exp_factor_balanced",
    threshold=0.53,
)

result = detector.predict(data_points, return_score=True, return_details=True)
print(result)

data_points should be 12 latest 5-minute records; if static features/device information are missing, the system will automatically fill from configuration/cache.

---

🔧 Input & Output

Input (Single Data Point)

{
  "timestamp": "2024-01-01T08:00:00",
  "deviceId": "ab60",            # Optional, anonymous ID will be created if missing
  "features": {
    "hr": 72.0,
    "hrv_rmssd": 30.0,
    "time_period_primary": "morning",
    "data_quality": "high",
    ...
  }
}

• Each window requires 12 data points (default 1 hour)
• Whether features are required is controlled by configs/features_config.json
• Missing values automatically fall back to default or category_mapping defined values

Output

{
  "is_anomaly": True,
  "anomaly_score": 0.5760,
  "threshold": 0.5300,
  "details": {
     "window_size": 12,
     "model_output": 0.5760,
     "prediction_confidence": 0.0460
  }
}

---

🧱 Model Architecture & Training

• Model Backbone: Phased LSTM handles unevenly-spaced sequences + Temporal Fusion Transformer aggregates temporal context
• Anomaly Detection Head: Enhanced attention, multi-layer MLP, optional contrastive learning/type auxiliary head
• Feature System:
  • Physiological: HR, HRV (RMSSD/SDNN/PNN50…)
  • Activity: Steps, distance, energy consumption, acceleration, gyroscope
  • Environmental: Light, day/night labels, data quality
  • Baseline: Adaptive baseline mean/std + deviation features
• Label Source: High-confidence questionnaire labels + low-confidence adaptive baseline labels
• Training Pipeline: Stage1/2/3 data processing ➜ Phase1 self-supervised pre-training ➜ Phase2 supervised fine-tuning ➜ Threshold/case calibration

---

📦 Repository Structure (Partial)

├─ configs/
│   └─ features_config.json     # Feature definitions & normalization strategies
├─ wearable_anomaly_detector.py # Core wrapper: loading, prediction, batch processing
├─ feature_calculator.py        # Configuration-driven feature construction + user history cache
├─ test_wearable_service.py     # HuggingFace Demo script (includes predefined cases)
└─ checkpoints/phase2/...       # Model weights & summary

---

📚 Data Source & License

• Training data is based on "A continuous real-world dataset comprising wearable-based heart rate variability alongside sleep diaries" (Baigutanova et al., Scientific Data, 2025) and its Figshare dataset doi:10.1038/s41597-025-05801-3 / dataset link.
• This dataset is released under Creative Commons Attribution 4.0 (CC BY 4.0) license, allowing free use, modification, and distribution, but attribution and license link must be retained.
• This repository follows CC BY 4.0 requirements for original data; if you further process or publish based on this, please continue to retain the above attribution and license information.
• Code/models can use MIT/Apache or other licenses as needed, but any parts involving data must still follow CC BY 4.0.

---

🤝 Contributions & Extensions

Welcome to:

1. Add new features or data sources ⇒ Update features_config.json + submit PR
2. Integrate new user data management/baseline strategies ⇒ Extend FeatureCalculator or contribute UserDataManager
3. Provide feedback on cases or real deployment experiences ⇒ Open Issues or Discussions

---

📄 License

• Model & Code: Apache-2.0. Can be used/modified/distributed freely while retaining copyright and license notices.
• Training Data: Original wearable HRV dataset uses CC BY 4.0; please continue to retain author attribution and license information when reusing.

---

🔖 Citation

@software{Wearable_TimeSeries_Health_Monitor,
  title  = {Wearable\_TimeSeries\_Health\_Monitor},
  author = {oscarzhang},
  year   = {2025},
  url    = {https://huggingface.co/oscarzhang/Wearable_TimeSeries_Health_Monitor}
}