fitfile hr伪影校正器
FIT心率伪影校正工具包，具有离线ML训练、CLI和MCP服务器，用于基于工具的集成。
这个项目做什么
- 解析
.fit/.fit.gz活动文件。 - 检测可能的光学HR伪影。
- 用模型预测替换工件点。
- 导出更正审计数据(
original_hr,corrected_hr,confidence,artifact_flag). - 提供MCP服务器，为代理工作流提供更正/导出工具。
- 绘制校正前后的HR图（可选配功率叠加和校正区域突出显示）。
当前的管道针对循环FIT数据进行了优化。
当前模型方法
该项目使用 序列模型 支持两种训练模式：
- 仅胸部基线：乘坐清洁胸带列车(
hr-chest/)学习一般的人力资源动态。 - 联合训练：将仅限胸部的游乐设施与以下配对旅游相结合
touren/，其中每个touren//包含一个*_chest.fit.gz还有一个*_optical.fit.gz。在配对旅游中，该模型使用 光学特征作为输入 和匹配 胸部HR为目标.
常见模型行为：
- 每个时间步的输入（16个特征）：
power,cadence,speed,altitude,grade滚动平均值（30s/60s/120s窗口）和时间导数(d_power,d_speed,d_altitude). - 具有动态感知损失的序列训练，以阻止不切实际的快速HR下降。
- OneCycleLR 学习速率调度器，以实现更好的收敛。
- 验证拆分 （15%） 早停 （耐心5）防止过度拟合。
- MC退学 基于模型的置信度得分的不确定性估计。
- 重叠窗口推理 在长途骑行中保持接近训练序列长度。
- 自适应伪影检测器 从游乐设施自身的HR/功率分布中得出每次乘坐的阈值。
- 推理结合了：
- 模型预测（重叠窗口） - 自适应伪影检测器 - 每次骑行校准 - MC放弃信心 - 用于残余向下尖峰的后置滤波器
存储库布局
src/hf_corrector/核心包scripts/辅助脚本（训练、批量校正、绘图）outputs/生成的报告和更正文件（忽略）models/训练模型伪影（忽略）hr-chest/,hr-optical/,touren/本地数据集（忽略）
安装
python -m venv .venv
source .venv/bin/activate
pip install -e .1） 建立清洁胸部训练清单
为胸带骑行提供高质量的门控：
hf-corrector qa-chest \
--chest-dir hr-chest \
--out-report outputs/chest_qa_report.json \
--out-manifest outputs/train_manifest_clean.json2） 训练ML模型
选项A：仅胸部基线
推荐（苹果硅MPS）
./scripts/train_seq_mps.sh稳定的预设（更强的平滑/动态约束）：
./scripts/train_seq_mps.sh \
models/model_seq_v1_mps_stable \
stable \
outputs/train_manifest_clean.json人工训练指挥
PYTHONPATH=src python -m hf_corrector.cli train \
--manifest outputs/train_manifest_clean.json \
--out models/model_seq_v1_mps \
--device mps \
--seq-len 120 \
--stride 10 \
--epochs 12 \
--batch-size 64 \
--lr 0.001 \
--lambda-dynamics 0.35 \
--max-drop-bpm-per-step 1.2 \
--max-windows 40000 \
--patience 5 \
--val-fraction 0.15如果你通过 --device mps MPS不可用，培训故意失败。
选项B：联合训练 hr-chest/ 并配对 touren/
预期的配对旅游布局：
touren/
tour1/
476019853281493296_chest.fit.gz
476019863744184622_optical.fit.gz
tour2/
..._chest.fit.gz
..._optical.fit.gz组合管道：
- 从以下位置加载所有仅限胸部的FITs
hr-chest/ - 发现以下所有配对旅游
touren/ - 在可配置的公差范围内，通过最近的时间戳对齐光学和胸部记录
- 仅胸部组加成对训练
optical -> chest群组 - 将重复的配对组保持在验证分割的同一侧
推荐（苹果硅MPS）：
./scripts/train_combined_mps.sh \
hr-chest \
touren \
models/model_seq_combined_mps \
stable手动命令：
PYTHONPATH=src python -m hf_corrector.cli train-combined \
--chest-dir hr-chest \
--tours-dir touren \
--out models/model_seq_combined_mps \
--device mps \
--seq-len 180 \
--stride 8 \
--epochs 16 \
--batch-size 64 \
--lr 0.0008 \
--lambda-dynamics 0.55 \
--max-drop-bpm-per-step 0.9 \
--max-windows 50000 \
--patience 5 \
--val-fraction 0.15 \
--pair-match-max-seconds 2.0 \
--paired-weight 4 \
--min-paired-points 900联合训练写作 dataset_report.json 将配对统计数据和接受/拒绝的旅行记录放入模型目录中。
3） 更正FIT文件
hf-corrector correct \
--fit activity.fit.gz \
--model models/model_seq_v1_mps_stable \
--mode balanced \
--hr-bias 8 \
--out outputs/run/correction.json笔记：
--hr-bias仅适用于替换的点。--mode:safe | balanced | aggressive.
4） 导出校正结果
hf-corrector export \
--fit activity.fit.gz \
--correction outputs/run/correction.json \
--out-dir outputs/run \
--formats csv fitaudit.csv总是生产出来的。- 由于中严格的解析器约束，FIT重写可能会在某些文件上失败
fit-tool；出口退货fit_error并继续。
5） 绘制人力资源前后图
完全活动+校正区域阴影：
PYTHONPATH=src python scripts/plot_hr_comparison.py \
--correction-json outputs/run/correction.json \
--fit activity.fit.gz \
--out outputs/run/hr_power_full.png \
--title "Full ride: corrected HR + power"中间30分钟窗口：
PYTHONPATH=src python scripts/plot_hr_comparison.py \
--correction-json outputs/run/correction.json \
--fit activity.fit.gz \
--window-minutes 30 \
--window-center middle \
--out outputs/run/hr_power_middle30.png \
--title "Middle 30 min: corrected HR + power"批量校正脚本
./scripts/batch_correct_optical.sh \
models/model_seq_v1_mps_stable \
hr-optical \
outputs/optical_corrected_v2 \
balancedMCP服务器
PYTHONPATH=src python -m hf_corrector.mcp_server --model-dir models/model_seq_v1_mps_stable已知限制
- FIT重写(
fit-tool)对于具有格式错误/边缘情况字段定义的特定供应商FIT变体，可能会失败。 - 在这些情况下，使用
audit.csv和correction.json作为可靠的输出。