# DataPrepare

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

当前仓库的主线是：

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

更详细的项目背景说明见 [AGENT_BACKGROUND_CN.md](./AGENT_BACKGROUND_CN.md)。

## 项目在做什么

仓库主要服务两类数据：

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

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

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

## 仓库结构

| 目录 | 作用 |
| --- | --- |
| `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`

流程概要：

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

### HYS_PSG

对应脚本：

- `event_mask_process/HYS_PSG_process.py`
- `dataset_builder/HYS_PSG_dataset.py`

流程概要：

1. 读取 `PSG_Aligned/<id>/` 下的多通道信号
2. 读取 `SA Label_Sync.csv`
3. 根据同步标签与睡眠分期生成逐秒标签
4. 对努力带、流量、SpO2、RRI 做统一重采样和长度对齐
5. 切分窗口并保存 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：

```bash
python event_mask_process/HYS_process.py
```

HYS_PSG：

```bash
python event_mask_process/HYS_PSG_process.py
```

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

- `*_Processed_Labels.csv`
- `*_Signal_Plots.png`

### 3. 构建数据集

HYS：

```bash
python dataset_builder/HYS_dataset.py
```

HYS_PSG：

```bash
python dataset_builder/HYS_PSG_dataset.py
```

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

- `Signals/`
- `Segments_List/`
- `Labels/`

### 4. 可视化与辅助工具

配对拷贝原始数据：

```bash
python dataset_tools/resp_pair_copy.py
```

检查 SHHS XML 标注：

```bash
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`

## 关键文件

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

1. `dataset_config/HYS_config.yaml`
2. `event_mask_process/HYS_process.py`
3. `utils/operation_tools.py`
4. `utils/split_method.py`
5. `dataset_builder/HYS_dataset.py`
6. `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/` 里的文件更适合拿来理解格式与结果，不代表完整数据集

## 相关文档

- 详细项目背景：[AGENT_BACKGROUND_CN.md](./AGENT_BACKGROUND_CN.md)