# Python Ecg Analysis

> 通用 Python 心电图（ECG）分析技能，覆盖 ECG 预处理与波形质量控制、心拍/心率变异性（HRV）/表征特征、纵向或多轮 ECG 对齐、超声或临床结局连接及患者级建模。 触发场景：(1) 用 Python 处理 ECG 原始信号；(2) 做心拍、HRV、波形或表征特征；(3) 对齐同一患者多轮 ECG；(4) 连接 ECG 与超声/临床结局；(5) 构建患者级 ECG 模型。 不适用：普通 R 生物统计任务、非 ECG 的通用机器学习、仅写论文或报告。项目命令、参数和数据位置必须从项目规则、README、代码与实际 --help 读取，不得写死。 配合规则：开工前对齐 biostat-principles；实际生成统计图时使用 publication-figures。

- Skill: `kangwang42/python-ecg-analysis` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kangwang42/python-ecg-analysis`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kangwang42/python-ecg-analysis/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: kangwang42 (https://skillmd.com/u/kangwang42)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kangwang42/python-ecg-analysis

---


# Python ECG 分析

本 skill 提供跨项目的 ECG 分析原则与检查要求，不保存任何项目专属路径、脚本名、参数或分析流程假设。

## 1. 先解析项目要求

按范围读取，不因 ECG 任务自动扫描整项研究：

- Q 只读取回答当前问题所需的权威项目说明、代码或方法来源，不创建文件。
- L 读取项目规则、目标脚本/配置和直接定义该输入、参数或输出的文档；只修目标并验证受影响记录、患者、轮次或结果，不强制读取全部 PROTOCOL、SAP、DECISIONS 和 `02_code/`。
- P/R 再按顺序完整读取：

1. 项目 `AGENTS.md` 与 `CLAUDE.md`，确认规则唯一来源、原始数据目录、已经确认的终点和记录标识字段。
2. 项目 `README.md`、`PROTOCOL.md`、`SAP.md` 与 `DECISIONS.md`，确认研究设计、轮次、时间窗和预设方法。
3. `02_code/` 的实际脚本与配置；先静态检查主程序、参数解析和 `if __name__ == "__main__"` 保护。只有确认 `--help` 会在业务逻辑前退出且不会写文件时，才执行 `python <script> --help`。

规则、README、代码或已经安全核验的 `--help` 不一致时先报告，不猜命令。无法确认某个程序在显示帮助信息前不会写文件时，不执行该命令，改为从源码和项目文档核对参数。原始数据位置、输出目录、导联、采样率、轮次和特征集均以项目文件中已经确认的记录为准。

P/R 开工前写明下列项目级合同；L 只记录与目标修改直接有关的输入、输出、只读边界和验证标准：

- 原始信号根及只读边界；
- 患者、记录、轮次、采集时间和导联的标识字段；
- 预处理输入输出、主要结局与连接时间窗；
- 训练、验证、测试的患者级切分单位；
- 预期记录数、患者数与验证标准。

## 2. 标识与数据来源追溯

- 原始信号只读；派生数据写入项目规定的结果目录。
- `subject_id` 及其他身份标识字段全程保持字符串，保留前导零，不从行号或文件顺序推断身份。
- 在处理前验证主要标识字段的唯一性、重复记录、同一患者轮次数、采集时间顺序和一对多关系。
- 所有 `join` 明确指定连接字段，并核对连接前后的行数、未匹配记录和重复扩增；不得按行顺序拼接。
- 每个预处理产物、特征表和结局连接表记录源文件、源记录标识、参数、生成脚本与运行时间，确保可以追溯到来源和处理步骤。
- 出现记录丢失、未知轮次、身份冲突或无法解释的缺失时停止后续建模，回到最早来源核验并向用户报告。

## 3. ECG 工作流

### 3.1 信号盘点与质量控制

1. 盘点文件、患者、轮次、导联、采样率、时长、单位和数据类型。
2. 检查空信号、恒定段、截断、饱和、基线漂移、工频干扰、导联错位和采样率不一致。
3. 预先定义可接受、需复核和排除的 QC 规则；记录每条记录的状态与原因。
4. 不把读取失败或 NaN 静默当作低质量信号排除。

### 3.2 预处理与特征

- 滤波、重采样、R 峰检测、心拍切分和归一化的参数来自项目配置或经核验的方法依据。
- 保留处理前后信号索引与单位；重采样和切窗不得改变患者、轮次或采集时间映射。
- 心拍、HRV、形态、频域和学习表征特征分别记录定义、窗口、聚合层级与缺失原因。
- 数据驱动特征学习、降维和特征选择只在训练折内拟合，禁止使用验证或测试信息。

### 3.3 纵向或多轮对齐

- 先核验轮次含义、时间顺序、允许时间窗及重复采集的取舍规则。
- 仅在同一患者内配对或建立序列；报告每个对比的可配对患者数，以及各阶段丢失的记录和原因。
- 差值、变化率、轨迹或表征距离需明确方向、时间分母、导联和基线定义。
- 未配对记录不擅自填补，也不混入配对分析。

### 3.4 超声与临床结局连接

- 明确结局来源、测量时间、单位、重复测量处理与允许连接窗口。
- 连接后核对患者数、ECG 记录数、结局记录数、未匹配原因与一对多扩增。
- 不用文献替代项目数据本身的来源核验；异常结局先回原始登记和单位规则。

### 3.5 患者级建模

- 同一患者的全部记录必须位于同一数据分区；使用按患者分组的验证或嵌套验证（grouped or nested validation），禁止按单条记录随机切分造成信息泄漏。
- 标准化、插补、特征选择、表示学习与超参数搜索全部在训练折内完成。
- 固定并保存患者级切分清单与随机种子；比较模型时使用同一患者、同一切分和同一评价指标。
- 分类、回归或时间结局采用与研究设计匹配的指标，并报告患者数、事件数及不确定性。
- 试新方法时先走 `biostat-principles` 的隔离实验、公平对照和主流程纳入条件。

## 4. 执行与验证

1. 对修改的 Python 文件运行 `python -m py_compile <files>`。
2. 使用从源码、项目文档及已经确认不会写文件的帮助命令中核实的真实命令运行，不凭本 skill 猜测应该运行哪个脚本；首次运行前确认输出位置与原始数据只读边界。
3. 保存本轮实际运行命令的完整 stdout/stderr，并全量扫描 `error|warning|traceback|failed|nan`；不为 L 重跑无关脚本以制造全项目日志。
4. 对每项异常定位为代码、数据、阈值或库问题；修复后重跑，不能用“失败比例低”带过。
5. L 核对受影响步骤的文件数、记录数、患者数、轮次数、未匹配数，以及输出字段、类型和层级结构；P/R 再覆盖完整受影响数据链。
6. 对表图和模型结果做范围、单位、方向、泄漏与重复性检查；实际生成统计图时调用 `publication-figures`。
7. 项目执行和正式发布的关键结果由实际生成结果的脚本写入 `results/results.yaml`；方法变化同步写入 `DECISIONS.md`；总运行脚本自动保存命令、状态、日志和环境信息。只有需要后续补充材料、外部资源或由用户决定的事项才进入 `BACKLOG.md`。

Q/L 只报告实际读取和运行的目标范围、验证结果、异常及输出位置；没有触及建模时不补写患者级切分或完整处理链。P/R 完成报告再列出实际读取的项目规则、实际运行命令、患者级切分、来源与处理过程核对、异常处理及输出位置。