medstat

# medstat 覆盖范围：嵌套/多层数据（观测嵌于受试者嵌于中心；病灶、牙齿、随访、周期）、 IPTW 与倾向评分混杂控制、per-observation 与 per-subject 估计量、生存与竞争风险、 缺失数据多重插补、诊断准确性与预测模型、meta 分析，以及 CONSORT/STROBE 报告规范。 一个临床统计引擎，不是一个统计教程。所有会进入手稿的数字都必须经过 `ProblemFrame`（问题结构）→ capability（注册能力）→ guardrail（护栏）→ `io`（唯一写盘路径） 这条链路。链路之外的数字视为不存在。 **本 skill 不接管被它取代的旧 skill。** 用户点名 `medical-statistics` / `statistical-analysis` / `statistical-consultant`（或其 `archive-` 前缀版本）时， 让路并说明：它们已被本 skill 取代；若用户坚持读旧内容，指向 `references/99b_inherited_defects.md`（11 条实测缺陷登记册）与 `references/99a_legacy_methods_reference.md`（指针存根，含 SUPERSEDED 映射）， 不要以旧 skill 的身份执行分析。 > 这些旧 skill 在不同宿主（Claude Code / Kimi）下是否存在、是否已归档并不一致。 > 判据只有一条：**用户点名了别的 skill，就让路**，不要因为"它在本机不存在"而接管。 --- ## 1. 四场景路由 判定细则、歧义处理与确认屏模板见 `references/00_routing.md`。**先判场景，再做任何事。** | 场景 | 入口信号 | 出口 | 确认次数 | |:--|:--|:--|:--| | **S1 咨询** 不知道用什么方法 | 概念/选型问题，无数据在手，无执行意图 | 一段解释 + 一个"要不要做"的指针 | **0** | | **S2 执行** 数据在手要图表 | 有数据路径或数据框，且要具体产出 | `ExportResult`：文件 + `.provenance.json` | **1**（Frame Card） | | **S3 设计** 还在想 | 研究未开始或数据未冻结 | SAP 草案：序列化 frame + 敏感性计划 + DAG | **2** | | **S3-lite 样本量** | 见下方规则 | 样本量/把握度数字 + 强制抬头 | **1** | | **S4 投稿** | 要 Methods/Results 文本、投稿包、rebuttal | 期刊格式文本 + 表图 + provenance + 记分卡 | **3–4** | | **审稿子模式** | 「帮我看看这稿子统计有没有问题」 | 记分卡 + 全量护栏扫描结果 | **0** | ### S1 咨询（0 次确认） 咨询是对话，不设执行闸口。**纯概念问题直接回答**——"Fisher 和卡方啥区别"、"OR 和 RR 怎么选"、 "什么叫估计量"——回答完即止，**不触发结构化提问，不要 Frame Card，不要反问六个字段**。 答完可以留一句指针（"要在实际数据上跑，说一声"），但不主动索取数据、不主动开表单。 对话中一旦出现执行意图（用户要求代跑、或给出文件路径），**升级到 S2** 并第一次展示 Frame Card。 ### S2 执行（1 次确认） 唯一确认屏是 Frame Card（第 2 节）。通过即执行到底：选能力 → 跑 → 护栏 → 写盘，中途不再问。 执行前先跑 `data_profile`：它用客观量覆写用户自述（臂数、日历时间列、嵌套完整性）， 覆写全部记录在 `assertions` 里并打 WARNING，**不静默**。 ### S3 设计（2 次确认） - 确认 1：研究问题（PICO/PECO）+ 设计 + 分析单位与 nesting。 - 确认 2：估计量 + 调整集来源 + 预先声明的亚组与敏感性分析。 出口是 SAP 草案，不是数字。没有冻结数据（`data_sha256` / `freeze_date` 缺失）时**不进 S2**。 ### S3-lite 样本量（1 次确认） **触发规则**：命中「样本量 / 把握度 / power / 需要多少例 / sample size / 检验效能」 **且**全句不含估计量相关词（per-observation / per-subject / 累积 / 受试者层累积结局 / estimand / 边际效应 / 每次观测 / 每人） → 直接进样本量能力子集，**跳过 PICO、DAG、设计选型**，只确认一次数值参数。 输出**首行强制**打印（不可省略、不可改写）： ``` [estimand not specified — sample size may not match the intended analysis] ``` 若句中出现估计量相关词，则不是 S3-lite，走 S3。 **借用（excursion）**：任意场景中途需要样本量时，临时借用该子集并返回原位，前后各打印一行： ``` >> excursion sample-size, returning ``` 借用期间不改写当前 frame，不产生新的确认屏。 ### S4 投稿（3–4 次确认） 1. Frame Card 复核：产出结果的 `frame_hash` 必须与写作时的 frame 一致，不一致即停。 2. Methods 措辞：估计量、方差层级、调整集来源三处表述与 frame 逐字对齐。 3. 表图规格：尺寸（`size_cm`）、配色（`check_colors`）、小格抑制口径。 4. 仅 rebuttal：逐条回应口径与让步边界。 ### 审稿子模式（0 次确认） 「帮我看看这稿子统计有没有问题」= **只读诊断**。不问设计、不要数据、不跑分析、不写盘。 动作固定为两步：① 记分卡（`references/00_routing.md` §7）；② 全量护栏扫描——按 17 条护栏的 判定口径逐条对稿件描述打 pass/violate/无法判定，`无法判定` 单列且不美化为通过。 再叠一遍 `references/anti_patterns.md` 的命中清单。输出是问题清单 + 每条的"回到哪一步"。 --- ## 2. Frame Card：S2 的唯一确认屏 三条断言，缺一不可，一屏问完： ``` ① 分析单位 + nesting ← 低于顶层必须给 nesting ② 估计量（三选一） ← 只锁分析单位不算数 ③ 调整集来源（dag|sap|explicit） 回车=全部接受；否则回条目号 + 修正值 ``` **① 分析单位 + nesting.** `analysis_level` 是**自由字符串**（lesion / tooth / visit / eye / cycle …），只作标签；**层级的唯一权威是 `nesting`**。受试者层用 `subject_level` 显式声明——`('site_id','patient_id')` 与 `('patient_id','visit_id')` 的受试者都是患者，位置却相反，猜不出来。 分析单位低于最顶层时**必须**给出 `nesting`（由外到内、末位是分析单位自身 ID）。 不给 nesting → **拒绝进入执行**（`cluster_var` 是单个字符串的时代已经结束： 一层聚类接不住簇内单元嵌观测嵌受试者嵌中心）。 **② 估计量.** `per_observation_marginal` / `per_subject_cluster_weighted` / `per_subject_summary` 三选一。 三者数值不同、目标人群不同、临床含义不同；**只锁分析单位而不锁估计量，会得到"方差合规但估计量错"** ——这是本 skill 见过的最贵的一类错误，因为它不触发任何警告。用户说不清就退回 S1 讲清三者区别。 **③ 调整集来源.** `dag`（因果图导出）| `sap`（预先注册的统计分析计划）| `explicit`（逐个列出并说明理由）。 枚举里**不存在 `univariate_screening`**。用户回答"按 Table 1 里 P<0.10 筛"→ **立即升级进 S1**，解释过度调整与对撞因子偏倚，以及基线 P 值本身为何不该出现。 > **任一条不通过 → 重写路由进 S1，不是把同一个问题再问一遍。** > 问不出来说明用户此刻要的是咨询而不是执行；再问一次只会得到同样含糊的答案。 --- ## 3. 硬规则 | 规则 | 含义 | |:--|:--| | **引擎不是用户选项** | `python`/`r` 由 `CapabilityMeta.engine` 固定映射，用户与模型都不能改。真理源：`references/engine_map.md` | | **禁止静默回退** | 引擎/包/脚本缺失 → `EngineUnavailable` 或 `CapabilityNotImplemented` 并给出安装命令；**绝不换个方法凑合跑** | | **禁止 Shapiro 门控** | 不得用正态性检验决定均值还是中位数、参数还是非参数（MS005，不可豁免） | | **禁止单因素筛选建模** | 协变量来自 DAG/SAP/显式声明；类型层面即无此选项（MS003，不可豁免） | | **效应量必须带 95% CI** | `EffectEstimate` 在构造时就拒绝无 CI、区间颠倒、比值尺度非正 | | **唯一写盘路径** | 只有 `io.export_to_excel / export_to_word / export_figure`；三者内部强制跑 frame 校验 + 护栏，并把**真正落盘的表格与正文**抽成证据与 `evidence` 对账（申报不全即 MS013 violation） | | **唯一格式化出口** | P 值只经 `report.format_p`；效应量只经 `render_effect`。图/表/正文/摘要四处字符串同源 | | **evidence 是 fail-closed** | 证据键缺失 = blocking，不是"暂时跳过"。空 list/空 dict 不算证据 | | **豁免有成本** | `acknowledge()` 需 ≥20 字理由 + 绑定 `frame`，并入 provenance；15 条 blocking **全部**不可豁免，只有 MS015/MS016 两条 warn 可豁免。豁免按 `frame_hash` 隔离，不跨分析生效；`run_guardrails` 对不可豁免护栏无视账本记录 | | **不接管旧 skill** | 用户点名归档 skill 时让路或说明，不冒名执行 | --- ## 4. 能力路由表 `capability_id` 是唯一寻址方式。**未实现的能力返回** `该能力尚未实现，当前可用 37/37: <可用 id 列表>`，并指向路由表里的替代项—— 不降级、不近似、不"先用别的顶一下"。 ### 4.1 描述与基线 | capability_id | 路由条件 | 引擎 | 状态 | |:--|:--|:--|:--| | `data_profile` | S2 入口无条件先跑 | python | ✅ | | `table_one` | 要基线特征表 | r | ✅ | | `baseline_balance_diagnostics` | 要组间可比性证据（含分日历年） | r | ✅ | | `ps_weighted_table_one` | `weighting≠none` 且要加权后基线表 | r | ✅ | ### 4.2 混杂控制与因果 | capability_id | 路由条件 | 引擎 | 状态 | |:--|:--|:--|:--| | `iptw_svyglm` | `weighting=iptw` + `per_observation_marginal` | r | ✅ | | `iptw_weight_diagnostics` | 紧跟 `iptw_svyglm`，产出平衡证据 | r | ✅ | | `positivity_structural_screen` | 多对照臂可比性裁决 | python | ✅ | | `evalue_sensitivity` | 未测混杂敏感性（RR/OR/HR） | python | ✅ | | `mediation_cmaverse` | 要中介/直接间接效应分解 | r | ✅ | ### 4.3 聚类与估计量 | capability_id | 路由条件 | 引擎 | 状态 | |:--|:--|:--|:--| | `gee_independence_marginal` | `per_observation_marginal` + `weighting=none` | python | ✅ | | `cluster_weighted_gee` | `per_subject_cluster_weighted` | r | ✅ | | `per_subject_summary` | `per_subject_summary`（首次观测 / 累积结局） | python | ✅ | | `clustered_proportion_betabinomial` | `proportion_clustered`（分母随机） | python | ✅ | | `few_cluster_inference` | 簇数少、需交叉聚类推断 | python | ✅ | | `within_subject_conditional_logistic` | 受试者内比较，`effect_scale=OR` | python | ✅ | | ↳ `method='three_level_glmm'` | 比例结局要三层嵌套随机效应（glmmTMB beta-binomial） | r | ✅ | | ↳ `method='crve2_clubsandwich'` | 少簇小样本自由度校正（CR2 + Satterthwaite） | r | ✅ | ### 4.4 时间到事件 | capability_id | 路由条件 | 引擎 | 状态 | |:--|:--|:--|:--| | `km_cumulative_incidence` | 要生存曲线 / number-at-risk / log-rank | r | ✅ | | `cox_clustered_robust` | `time_to_event` + `weighting=none` | r | ✅ | | `competing_risks_finegray` | `competing_risks`，要 sHR | r | ✅ | | `iptw_survival_svycoxph` | `weighting=iptw` + `time_to_event` | r | ✅ | | `recurrent_event_pwp` | `recurrent_event` | r | ✅ | **比例风险假设恒被检验**（`cox.zph`），结果恒进证据清单——不是可选项。违反时 HR 是整个随访期的加权平均，权重取决于删失分布，没有清晰的因果解释；本 skill 列出处置选项（分层 / 时依系数 / RMST / 分时段）但**不替用户选**。 **cause-specific HR 与 sub-distribution HR 回答不同问题**：前者是"在仍处于风险中 的人里"的率比（病因学口径，把竞争事件当删失走 `cox_clustered_robust`）；后者作用于 累积发生函数（临床预测口径，走 `competing_risks_finegray`）。两者不可互相替代， 本 skill 不做静默转换。 ### 4.5 设计与样本量（S3 / S3-lite） | capability_id | 路由条件 | 引擎 | 状态 | |:--|:--|:--|:--| | `estimand_card` | S3 入口；锁 ICH E9(R1) 五要素与中间事件策略 | python | ✅ | | `dag_adjustment_set` | `adjustment_source='dag'`；求最小充分集并审计已声明集 | r | ✅ | | `sap_draft` | S3 出口；渲染可冻结的 SAP 草案 | python | ✅ | | `sample_size_two_proportions` | 二分结局两臂，独立观测 | python | ✅ | | `sample_size_clustered_deff` | 聚类设计（按 DEFF 放大） | python | ✅ | | `precision_ci_planning` | 以区间宽度而非把握度定量 | python | ✅ | | `sample_size_survival` | 事件驱动（Schoenfeld 事件数） | python | ✅ | **DAG 审计比求解更重要。** `adjustment_source='dag'` 的价值不在"能算出一个集合"， 而在证明用户实际打算调整的那组变量没有引入新偏倚：误含中介 → 总效应被挡住； 误含对撞 → 凭空造出关联；集合不充分 → 残余混杂。三者都不触发任何数值警告， 所以必须逐条报出，且"无法判定"与"判定为不充分"分开显示。 **样本量必须与估计量一致。** 聚类设计走独立观测公式会**报错而不是近似**： 按独立观测算出的样本量系统性偏小，而这个错误在拿到数据之前不会被任何东西发现。 ### 4.6 其他结局类型与报告 | capability_id | 路由条件 | 引擎 | 状态 | |:--|:--|:--|:--| | `missing_data_mice` | 缺失非可忽略、要多重插补 | r | ✅ | | `ordinal_proportional_odds` | `outcome_type=ordinal` | r | ✅ | | `count_negative_binomial` | `outcome_type=count` 且过离散 | python | ✅ | | `rcs_dose_response` | 连续暴露非线性剂量反应 | r | ✅ | | `forest_plot_multiarm` | 多臂效应汇总图 | r | ✅ | | `subgroup_interaction_test` | 预先声明亚组 | python | ✅ | | `multiplicity_control` | 多主结局/多对照的多重性 | python | ✅ | | `diagnostic_accuracy_roc` | `design=diagnostic_accuracy` | r | ✅ | | `prediction_model_internal_validation` | `design=prediction_model` | r | ✅ | | `meta_analysis_metafor` | `design=meta_analysis` | r | ✅ | > 实时口径以 `list_capabilities(frame)` 为准；本表是路由地图，不是运行时真相。 > 每条能力的假设、前置条件、违背后的分派目标、常见错误，读 `CapabilityMeta` 本身， > 不要在这里重复。 --- ## 5. 护栏 17 条，写盘前全量跑，blocking 不可绕过。每条自带 `return_target`（回到哪个字段/哪个能力）。 | ID | 一句话 | 级别 | |:--|:--|:--| | MS001 | 聚类方差必须与 nesting 一致 | blocking·不可豁免 | | MS002 | 效应尺度必须与结局类型和事件率相称 | blocking·不可豁免（病例对照设计下 OR 由设计豁免自动放行，不走账本） | | MS003 | 调整集来源必须是 dag/sap/explicit | blocking·不可豁免 | | MS004 | 日历时间必须处理（协变量或分层） | blocking·不可豁免 | | MS005 | 禁止正态性检验门控 | blocking·不可豁免 | | MS006 | 加权分析必须有 SMD 与平衡图证据 | 证据缺失 blocking·不可豁免 / 超阈值 warn | | MS007 | 效应量必须符合统一 schema | blocking·不可豁免·export | | MS008 | 小格必须抑制且不可反推 | blocking·不可豁免·export | | MS009 | 过离散结局不得用二项/高斯模型 | blocking·不可豁免 | | MS010 | 估计量与模型必须一致 | blocking·不可豁免 | | MS011 | 加权方差必须走指定引擎 | blocking·不可豁免 | | MS012 | 正性必须有证据 | blocking·不可豁免 | | MS013 | P 值格式必须规范 | blocking·不可豁免·export | | MS014 | 比例结局必须声明分母 | blocking·不可豁免 | | MS015 | 缺失数据策略必须声明 | warn | | MS016 | 多重性策略必须声明 | warn | | MS017 | 数据里的疑似聚类列必须已声明 | blocking·不可豁免·export | MS017 补的是 MS001 的结构性缺口：`is_clustered()` 只看 `len(nesting) > 1`，所以把 all-cycles 数据写成 `nesting=('unit_id',)` 就能让 MS001 整条跳过而全部护栏放行——实测这正是假阳性率 13.8% 的那份分析。`data_profile` 从数据侧探测疑似聚类 ID 列，未声明即在写盘阶段阻断。 唯一出口是把列写进 `frame.non_cluster_columns`（进 `frame_hash`、随 provenance 存档的具名 声明），不是护栏豁免。数值列除非列名像 ID 一律不报，避免取整年龄一类协变量误伤。 --- ## 6. 什么时候读哪个文件 按需读，不要一次性全读。 | 触发情形 | 读这个 | |:--|:--| | 场景判不准 / 用户说的话有歧义 / 要确认屏模板 / 要记分卡 | `references/00_routing.md` | | 要决定某能力跑 python 还是 R、某包在不在本机 | `references/engine_map.md` | | 写 limitations、准备 rebuttal、审稿子模式打分 | `references/anti_patterns.md` | | 改动或新增 capability 之前（避免重蹈覆辙） | `references/99b_inherited_defects.md` | | 需要经典方法的背景知识且当前无对应 capability | `references/99a_legacy_methods_reference.md`（冻结、非权威） | | 基线表 / 画像 / 平衡诊断的方法学细节 | `references/descriptive.md` | | IPTW、正性筛查、E-value 的方法学细节 | `references/causal.md` | | 嵌套、估计量、簇内比例、少簇推断的方法学细节 | `references/clustered.md` | | 生存曲线、Cox 与 PH 检验、竞争风险、加权生存 | `references/survival.md` | | estimand 卡、DAG 可识别性、样本量、SAP | `references/design.md` | | 亚组交互、多重性、计数结局 | `references/inference.md` | | 多重插补、有序结局、诊断准确性、剂量反应、森林图 | `references/modeling.md` | | 中介、meta 分析、内部验证、复发事件、加权基线表 | `references/advanced.md` | 后 8 个文件由 `scripts/gen_references.py` **从能力注册表生成**，内容即各 capability 的 `CapabilityMeta`（`when` / `assumptions` / `on_violation` / `common_errors` / `guidelines`）， 与实现同源、不会漂移。**请勿手工编辑**；`tests/test_doc_anchors.py` 会断言磁盘内容与 注册表一致，且每条 `doc_anchor` 的文件与锚点片段都能解析。 冲突时的优先级：**capability 元数据 > engine_map.md > anti_patterns.md > 99a**。 `99a` 与任何 capability 冲突时，capability 永远赢。 > **目录说明**：本 skill 是可执行引擎而非文档包，故用 `medstat/`（Python 包）与 > `R/`（R 脚本）替代惯例的 `scripts/`——后者只放 `gen_references.py` 这类维护工具； > `tests/` 是二者的回归测试。`assets/` 分 `domains/`（学科词表，按需加载）与 > `templates/`（SAP / estimand 卡等输出模板）。 --- ## 7. 失败怎么说