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 完成报告再列出实际读取的项目规则、实际运行命令、患者级切分、来源与处理过程核对、异常处理及输出位置。