marques 8ee5980906 feat: Add utility functions for signal processing and event mapping

- Created a new module `utils/__init__.py` to consolidate utility imports.
- Added `event_map.py` for mapping apnea event types to numerical values and colors.
- Implemented various filtering functions in `filter_func.py`, including Butterworth, Bessel, downsampling, and notch filters.
- Developed `operation_tools.py` for dataset configuration loading, event mask generation, and signal processing utilities.
- Introduced `split_method.py` for segmenting data based on movement and amplitude criteria.
- Added `statistics_metrics.py` for calculating amplitude metrics and generating confusion matrices.
- Included a new Excel file for additional data storage.

2026-03-24 21:15:05 +08:00

5.0 KiB

Raw Blame History

DataPrepare

DataPrepare 是一个面向睡眠呼吸暂停数据的预处理仓库，用于把原始 BCG / PSG 信号与事件标签整理成可训练的数据集。

当前仓库的主线是：

生成逐秒标签掩码
按固定窗口切分数据集
输出可视化结果用于人工检查

更详细的项目背景说明见 AGENT_BACKGROUND_CN.md。

项目在做什么

仓库主要服务两类数据：

HYS：以 OrgBCG 为核心，结合人工修正的呼吸暂停标签，提取呼吸分量、BCG 分量并生成逐秒可用性掩码
HYS_PSG：以 PSG 多通道信号为核心，整理胸腹带、流量、SpO2、RRI、睡眠分期与同步呼吸暂停标签

两条主线都采用同一个设计：

先把整夜记录整理成逐秒标签
再根据标签切出固定长度窗口

仓库结构

目录	作用
`dataset_config/`	数据集配置文件，包含路径、采样率、阈值、切窗参数
`event_mask_process/`	逐秒标签掩码生成脚本
`dataset_builder/`	数据集切片与保存脚本
`signal_method/`	信号预处理、规则检测、特征计算
`utils/`	文件读取、标签转换、切窗、滤波等通用工具
`draw_tools/`	全夜图、分段图和统计图绘制
`dataset_tools/`	辅助脚本，如配对数据拷贝、SHHS 标注检查
`output/`	仓库内的中间结果样例

核心流程

HYS

对应脚本：

event_mask_process/HYS_process.py
dataset_builder/HYS_dataset.py

流程概要：

读取 OrgBCG_Aligned/<id>/OrgBCG_Sync_*.txt
读取 Label/<id>/SA Label_corrected.csv
对原始信号做陷波、呼吸分量提取和 BCG 分量提取
检测低幅值、体动、幅值变化，并结合 排除区间.xlsx 生成逐秒标签
保存 Processed_Labels.csv
根据 window_sec 与 stride_sec 切分训练窗口并保存 npz

HYS_PSG

对应脚本：

event_mask_process/HYS_PSG_process.py
dataset_builder/HYS_PSG_dataset.py

流程概要：

读取 PSG_Aligned/<id>/ 下的多通道信号
读取 SA Label_Sync.csv
根据同步标签与睡眠分期生成逐秒标签
对努力带、流量、SpO2、RRI 做统一重采样和长度对齐
切分窗口并保存 PSG 数据集

快速开始

1. 先检查配置

所有主脚本都依赖 dataset_config/*.yaml 中的绝对路径。
在新机器或新数据目录下，优先修改这些配置文件：

dataset_config/HYS_config.yaml
dataset_config/HYS_PSG_config.yaml
dataset_config/ZD5Y_config.yaml
dataset_config/SHHS1_config.yaml

重点检查：

root_path
mask_save_path 或 save_path
dataset_save_path
dataset_visual_path
select_ids

2. 生成逐秒标签

HYS：

python event_mask_process/HYS_process.py

HYS_PSG：

python event_mask_process/HYS_PSG_process.py

执行后通常会在 output/ 下生成：

*_Processed_Labels.csv
*_Signal_Plots.png

3. 构建数据集

HYS：

python dataset_builder/HYS_dataset.py

HYS_PSG：

python dataset_builder/HYS_PSG_dataset.py

输出目录由对应 YAML 中的 dataset_save_path 控制，通常包含：

Signals/
Segments_List/
Labels/

4. 可视化与辅助工具

配对拷贝原始数据：

python dataset_tools/resp_pair_copy.py

检查 SHHS XML 标注：

python dataset_tools/shhs_annotations_check.py

输入与输出约定

输入

仓库本身不包含原始数据，原始数据目录由 YAML 指定。代码默认外部数据目录中至少存在：

OrgBCG_Aligned/<id>/OrgBCG_Sync_*.txt
PSG_Aligned/<id>/...
Label/<id>/SA Label_corrected.csv
PSG_Aligned/<id>/SA Label_Sync.csv

中间输出

仓库内 output/ 保存的是中间标签与图像样例，不是最终训练数据集。例如：

output/HYS/<id>/<id>_Processed_Labels.csv
output/HYS_PSG/<id>/<id>_Processed_Labels.csv

最终输出

由 dataset_builder/ 写入 YAML 中配置的外部目录。典型结构为：

Signals/*.npz
Segments_List/*.npz
Labels/*.csv

关键文件

如果你是第一次阅读这个仓库，推荐优先看：

dataset_config/HYS_config.yaml
event_mask_process/HYS_process.py
utils/operation_tools.py
utils/split_method.py
dataset_builder/HYS_dataset.py
signal_method/rule_base_event.py

当前状态与注意事项

仓库目前没有依赖清单文件，常见依赖包括 numpy、pandas、scipy、matplotlib、seaborn、yaml、tqdm、rich、polars、lxml、mne
大多数脚本没有命令行参数接口，配置文件路径直接写在脚本 __main__ 中
event_mask_process/SHHS1_process.py 目前基本还是占位
event_mask_process/HYS_PSG_process.py 当前实现偏简化，Resp_* / BCG_* 掩码尚未真正展开
output/ 里的文件更适合拿来理解格式与结果，不代表完整数据集

5.0 KiB Raw Blame History Unescape Escape