python-ecg-analysis

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

Python ECG 分析

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

1. 先解析项目契约

按顺序完整读取：

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 不一致时先报告，不猜命令。无法证明入口的帮助调用无副作用时，不执行它，改为从源码和项目文档核对参数。原始数据位置、输出目录、导联、采样率、轮次和特征集均以项目单源为准。

开工前写明：

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

2. 身份与数据谱系检查

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

3. ECG 工作流

3.1 信号盘点与质量控制

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

3.2 预处理与特征

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

3.3 纵向或多轮对齐

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

3.4 超声与临床结局连接

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

3.5 患者级建模

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

4. 执行与验证

1. 对修改的 Python 文件运行 python -m py_compile <files>。
2. 使用从源码、项目文档及无副作用帮助入口核实的真实命令实跑，不凭本 skill 生成入口；首次运行前确认输出位置与原始数据只读边界。
3. 保存完整 stdout/stderr，并全量扫描 error|warning|traceback|failed|nan。
4. 对每项异常定位为代码、数据、阈值或库问题；修复后重跑，不能用“失败比例低”带过。
5. 核对每一步的文件数、记录数、患者数、轮次数、未匹配数和输出 schema。
6. 对表图和模型结果做范围、单位、方向、泄漏与重复性检查；实际生成统计图时调用 publication-figures。
7. 结果变化同步项目结果单源，方法变化同步 DECISIONS.md，操作同步 SESSION_LOG.md，新缺口同步 BACKLOG.md。

完成报告必须列出实际读取的项目规则、实际运行命令、患者级切分、lineage 核对、异常处理及输出位置。