HaHafeng
f0736dbca1
M1 Skeleton Pipeline: - Scatter-dispatch + Aggregator polling pattern (PgBoss) - PKB ACL bridge (PkbBridgeService -> PkbExportService DTOs) - ExtractionSingleWorker with DeepSeek-V3 LLM extraction - PermanentExtractionError for non-retryable failures - Phantom Retry Guard (idempotent worker) - 3-step minimal frontend (Setup -> Progress -> Workbench) - 4 new DB tables (extraction_templates, project_templates, tasks, results) - 3 system templates seed (RCT, Cohort, QC) - M1 integration test suite M2 HITL Workbench: - MinerU VLM integration for high-fidelity table extraction - XML-isolated DynamicPromptBuilder with flat JSON output template - fuzzyQuoteMatch validator (3-tier confidence scoring) - SSE real-time logging via ExtractionEventBus - Schema-driven ExtractionDrawer (dynamic field rendering from template) - Excel wide-table export with flattenModuleData normalization - M2 integration test suite Critical Fixes (data normalization): - DynamicPromptBuilder: explicit flat key-value output format with example - ExtractionExcelExporter: handle both array and flat data formats - ExtractionDrawer: schema-driven rendering instead of hardcoded fields - ExtractionValidator: array-format quote verification support - SSE route: Fastify register encapsulation to bypass auth for EventSource - LLM JSON sanitizer: strip illegal control chars before JSON.parse Also includes: RVW stats verification spec, SSA expert config guide Tested: M1 pipeline test + M2 HITL test + manual frontend verification Co-authored-by: Cursor <cursoragent@cursor.com>
480 lines
13 KiB
Markdown
480 lines
13 KiB
Markdown
# RVW V2.0 统计验证规则说明书
|
||
|
||
> **文档目的：** 供统计学专家评审和确认
|
||
> **版本：** v1.0
|
||
> **日期：** 2026-02-18
|
||
> **适用场景：** 医学期刊论文表格数据验证
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [概述](#概述)
|
||
2. [L1 算术验证规则](#l1-算术验证规则)
|
||
3. [L2 统计验证规则](#l2-统计验证规则)
|
||
4. [L2.5 一致性取证规则](#l25-一致性取证规则)
|
||
5. [容错阈值设置](#容错阈值设置)
|
||
6. [待评审问题清单](#待评审问题清单)
|
||
|
||
---
|
||
|
||
## 概述
|
||
|
||
### 验证层级架构
|
||
|
||
| 层级 | 名称 | 目标 | 复杂度 |
|
||
|------|------|------|--------|
|
||
| **L1** | 算术验证 | 检查基础计算（加减乘除）是否正确 | 低 |
|
||
| **L2** | 统计验证 | 逆向验证统计检验结果是否合理 | 中 |
|
||
| **L2.5** | 一致性取证 | 启发式规则，发现潜在数据问题 | 高 |
|
||
|
||
### 技术依赖
|
||
|
||
- **scipy.stats**：用于统计计算（t 分布、卡方分布、正态分布）
|
||
- **python-docx**：Word 文档表格提取
|
||
- **正则表达式**：数据格式识别
|
||
|
||
---
|
||
|
||
## L1 算术验证规则
|
||
|
||
### 规则 L1-1：百分比计算验证
|
||
|
||
**应用场景：** 分类变量描述统计（如 n (%) 格式）
|
||
|
||
**规则描述：**
|
||
|
||
对于格式为 `n (p%)` 的单元格，验证：
|
||
|
||
$$
|
||
\text{calculated\_percent} = \frac{n}{N} \times 100
|
||
$$
|
||
|
||
其中 N 为该列或该组的总数。
|
||
|
||
**判定条件：**
|
||
|
||
| 条件 | 判定 |
|
||
|------|------|
|
||
| `|reported_percent - calculated_percent| > 0.1%` | ❌ Error |
|
||
| `|reported_percent - calculated_percent| ≤ 0.1%` | ✅ Pass |
|
||
|
||
**示例：**
|
||
|
||
| 原始数据 | N | 报告值 | 计算值 | 判定 |
|
||
|---------|---|--------|--------|------|
|
||
| 45 (50.0%) | 90 | 50.0% | 50.0% | ✅ Pass |
|
||
| 45 (52.0%) | 90 | 52.0% | 50.0% | ❌ Error (差 2%) |
|
||
|
||
**识别模式（正则表达式）：**
|
||
|
||
```
|
||
(\d+(?:\.\d+)?)\s*\(\s*(\d+(?:\.\d+)?)\s*%?\s*\)
|
||
```
|
||
|
||
**N 值获取策略：**
|
||
|
||
1. 首先从表头识别标记为 "n"、"N"、"Total"、"合计" 的列
|
||
2. 其次检查同行中是否有总数列
|
||
3. 最后尝试从上下文推断
|
||
|
||
---
|
||
|
||
### 规则 L1-2：合计行验证
|
||
|
||
**应用场景：** 表格中的 Total/Sum/合计 行
|
||
|
||
**规则描述：**
|
||
|
||
对于标记为 "Total"、"Sum"、"合计"、"总计" 的行，验证该行的每个数值列是否等于上方各行之和。
|
||
|
||
$$
|
||
\text{Total}_{\text{col}} = \sum_{i=1}^{n-1} \text{Value}_{i, \text{col}}
|
||
$$
|
||
|
||
**判定条件：**
|
||
|
||
| 条件 | 判定 |
|
||
|------|------|
|
||
| `|reported_total - calculated_sum| > 0.5` | ❌ Error |
|
||
| `|reported_total - calculated_sum| ≤ 0.5` | ✅ Pass |
|
||
|
||
**示例：**
|
||
|
||
| 分组 | 人数 | 判定 |
|
||
|------|------|------|
|
||
| A 组 | 30 | - |
|
||
| B 组 | 25 | - |
|
||
| C 组 | 45 | - |
|
||
| **合计** | **100** | ✅ Pass (30+25+45=100) |
|
||
| **合计** | **110** | ❌ Error (30+25+45=100≠110) |
|
||
|
||
**识别关键词：**
|
||
|
||
- 英文：total, sum, all
|
||
- 中文：合计, 总计, 总和
|
||
|
||
---
|
||
|
||
## L2 统计验证规则
|
||
|
||
### 规则 L2-1：卡方检验 P 值逆向验证
|
||
|
||
**应用场景：** 分类变量组间比较（基线特征表、疗效比较表）
|
||
|
||
**规则描述：**
|
||
|
||
从表格中提取报告的 χ² 值，根据自由度（df）反算 P 值，与报告的 P 值对比。
|
||
|
||
**计算公式：**
|
||
|
||
$$
|
||
P_{\text{calculated}} = 1 - F_{\chi^2}(\chi^2, df)
|
||
$$
|
||
|
||
其中 $F_{\chi^2}$ 是卡方分布的累积分布函数。
|
||
|
||
**自由度估计：**
|
||
|
||
- **默认 df = 1**（适用于大多数 2×2 比较）
|
||
- 对于 r×c 表：df = (r-1) × (c-1)
|
||
|
||
**判定条件：**
|
||
|
||
| 条件 | 判定 |
|
||
|------|------|
|
||
| 显著性结论相反（P<0.05 vs P≥0.05） | ❌ Error |
|
||
| `|P_reported - P_calculated| > 0.05` | ⚠️ Warning |
|
||
| `|P_reported - P_calculated| ≤ 0.05` | ✅ Pass |
|
||
|
||
**示例：**
|
||
|
||
| χ² 值 | df | 报告 P | 计算 P | 判定 |
|
||
|-------|-----|--------|--------|------|
|
||
| 57.52 | 1 | 0.001 | 0.0000 | ✅ Pass（均显著） |
|
||
| 3.84 | 1 | 0.05 | 0.050 | ✅ Pass |
|
||
| 2.50 | 1 | 0.01 | 0.114 | ❌ Error（显著性结论相反） |
|
||
|
||
**识别模式（正则表达式）：**
|
||
|
||
```
|
||
# χ² 值识别
|
||
(?:χ[²2]|[χx]2|2)\s*[=:]\s*(\d+\.?\d*)
|
||
|
||
# P 值识别
|
||
[Pp][\s\-值]*[=<>≤≥]\s*(\d+\.?\d*)
|
||
```
|
||
|
||
**⚠️ 待专家确认：**
|
||
|
||
1. df=1 作为默认值是否合理？
|
||
2. 是否需要从表格结构推断实际自由度？
|
||
|
||
---
|
||
|
||
### 规则 L2-2：T 检验 P 值逆向验证
|
||
|
||
**应用场景：** 连续变量两组比较（Mean±SD 格式）
|
||
|
||
**规则描述：**
|
||
|
||
从表格中提取两组的 Mean±SD 和样本量 n，使用独立样本 t 检验公式反算 P 值。
|
||
|
||
**计算公式：**
|
||
|
||
$$
|
||
t = \frac{|\bar{X}_1 - \bar{X}_2|}{\sqrt{\frac{SD_1^2}{n_1} + \frac{SD_2^2}{n_2}}}
|
||
$$
|
||
|
||
$$
|
||
df = n_1 + n_2 - 2
|
||
$$
|
||
|
||
$$
|
||
P_{\text{calculated}} = 2 \times (1 - F_t(t, df))
|
||
$$
|
||
|
||
其中 $F_t$ 是 t 分布的累积分布函数。
|
||
|
||
**判定条件：**
|
||
|
||
| 条件 | 判定 |
|
||
|------|------|
|
||
| `|P_reported - P_calculated| > 0.05` | ❌ Error |
|
||
| `0.01 < |P_reported - P_calculated| ≤ 0.05` | ⚠️ Warning |
|
||
| `|P_reported - P_calculated| ≤ 0.01` | ✅ Pass |
|
||
|
||
**示例：**
|
||
|
||
| 组1 Mean±SD | 组2 Mean±SD | n1 | n2 | 报告 P | 计算 P | 判定 |
|
||
|-------------|-------------|-----|-----|--------|--------|------|
|
||
| 65.2±10.5 | 58.3±9.8 | 50 | 48 | 0.001 | 0.0007 | ✅ Pass |
|
||
| 45.0±12.0 | 44.5±11.5 | 30 | 30 | 0.001 | 0.86 | ❌ Error |
|
||
|
||
**识别模式（正则表达式）：**
|
||
|
||
```
|
||
# Mean±SD 格式
|
||
(\d+\.?\d*)\s*[±\+\-]\s*(\d+\.?\d*)
|
||
|
||
# 带括号的 SD 格式
|
||
(\d+\.?\d*)\s*\(\s*(\d+\.?\d*)\s*\)(?!\s*%)
|
||
```
|
||
|
||
**样本量获取策略：**
|
||
|
||
1. 从表头提取：`(n=50)`、`n=50`、`(50例)`
|
||
2. 从数据行提取：行首的 n 信息
|
||
3. 从上下文推断
|
||
|
||
**⚠️ 待专家确认：**
|
||
|
||
1. 使用 Welch's t-test（不假设方差齐性）是否更合适？
|
||
2. 当前假设为独立样本 t 检验，是否需要区分配对 t 检验？
|
||
|
||
---
|
||
|
||
### 规则 L2-3：CI 与 P 值逻辑一致性
|
||
|
||
**应用场景：** 回归分析结果表（OR、HR、RR 及其 95% CI）
|
||
|
||
**规则描述（黄金法则）：**
|
||
|
||
95% 置信区间与 P 值之间存在严格的逻辑对应关系：
|
||
|
||
| 95% CI 与 1.0 的关系 | P 值要求 |
|
||
|--------------------|----------|
|
||
| CI 跨越 1.0 (如 0.8-1.2) | P **必须** ≥ 0.05（不显著） |
|
||
| CI 不跨越 1.0 (如 1.1-1.5) | P **必须** < 0.05（显著） |
|
||
|
||
**违反此规则 = 数据逻辑矛盾**
|
||
|
||
**判定条件：**
|
||
|
||
| 场景 | CI | P 值 | 判定 |
|
||
|------|-----|------|------|
|
||
| 矛盾 1 | 0.8-1.2（跨越 1） | 0.03（<0.05） | ❌ Error |
|
||
| 矛盾 2 | 1.2-2.5（不跨越 1） | 0.10（≥0.05） | ❌ Error |
|
||
| 正确 1 | 0.8-1.2（跨越 1） | 0.45（≥0.05） | ✅ Pass |
|
||
| 正确 2 | 1.2-2.5（不跨越 1） | 0.01（<0.05） | ✅ Pass |
|
||
|
||
**示例：**
|
||
|
||
| OR | 95% CI | 报告 P | 判定 |
|
||
|----|--------|--------|------|
|
||
| 1.5 | 1.2-2.0 | 0.001 | ✅ Pass（CI 不跨越 1，P<0.05） |
|
||
| 0.9 | 0.7-1.1 | 0.30 | ✅ Pass（CI 跨越 1，P≥0.05） |
|
||
| 1.3 | 0.9-1.8 | 0.02 | ❌ Error（CI 跨越 1，但 P<0.05） |
|
||
|
||
**识别模式（正则表达式）：**
|
||
|
||
```
|
||
# OR/HR/RR 识别
|
||
(?:OR|HR|RR)\s*[=:]\s*(\d+\.?\d*)
|
||
|
||
# CI 识别（多种格式）
|
||
[\(\[]\s*(\d+\.?\d*)\s*[-–—,;]\s*(\d+\.?\d*)\s*[\)\]]
|
||
95%?\s*CI\s*[:\s]+(\d+\.?\d*)\s*[-–—,;to]+\s*(\d+\.?\d*)
|
||
```
|
||
|
||
**⚠️ 待专家确认：**
|
||
|
||
1. 此规则仅适用于比值指标（OR、HR、RR），对于回归系数（β）是否需要调整为 CI 跨越 0？
|
||
2. 90% CI 和 95% CI 的判定标准应如何区分？
|
||
|
||
---
|
||
|
||
## L2.5 一致性取证规则
|
||
|
||
### 规则 L2.5-1：SE 三角验证
|
||
|
||
**应用场景：** Logistic 回归、Cox 回归等报告 OR/HR/RR、95% CI 和 P 值的表格
|
||
|
||
**规则描述：**
|
||
|
||
利用 OR/HR 与 95% CI 的数学关系，反推标准误（SE），再计算 Z 值和 P 值，与报告的 P 值对比。
|
||
|
||
**计算公式：**
|
||
|
||
$$
|
||
SE = \frac{\ln(CI_{\text{upper}}) - \ln(CI_{\text{lower}})}{3.92}
|
||
$$
|
||
|
||
（3.92 = 2 × 1.96，对应 95% CI 的 Z 临界值）
|
||
|
||
$$
|
||
Z = \frac{|\ln(OR)|}{SE}
|
||
$$
|
||
|
||
$$
|
||
P_{\text{calculated}} = 2 \times (1 - \Phi(Z))
|
||
$$
|
||
|
||
其中 $\Phi$ 是标准正态分布的累积分布函数。
|
||
|
||
**判定条件：**
|
||
|
||
| 条件 | 判定 |
|
||
|------|------|
|
||
| `|P_reported - P_calculated| > 0.05` | ❌ Error |
|
||
| `0.01 < |P_reported - P_calculated| ≤ 0.05` | ⚠️ Warning |
|
||
| `|P_reported - P_calculated| ≤ 0.01` | ✅ Pass |
|
||
|
||
**示例：**
|
||
|
||
| OR | 95% CI | 报告 P | 计算 SE | 计算 Z | 计算 P | 判定 |
|
||
|----|--------|--------|---------|--------|--------|------|
|
||
| 2.0 | 1.2-3.3 | 0.008 | 0.258 | 2.69 | 0.007 | ✅ Pass |
|
||
| 1.5 | 1.0-2.25 | 0.001 | 0.206 | 1.97 | 0.049 | ❌ Error |
|
||
|
||
**⚠️ 待专家确认：**
|
||
|
||
1. SE 计算公式是否准确？是否需要考虑 CI 的不对称情况？
|
||
2. 对于 HR（风险比），此公式是否同样适用？
|
||
|
||
---
|
||
|
||
### 规则 L2.5-2：SD > Mean 检查
|
||
|
||
**应用场景：** 连续变量描述统计
|
||
|
||
**规则描述：**
|
||
|
||
对于**已知为正值的指标**（如年龄、体重、血压、实验室指标），标准差（SD）大于均值（Mean）通常是异常的，可能暗示：
|
||
|
||
1. 数据录入错误
|
||
2. SD 与 SEM 混淆
|
||
3. 数据分布异常
|
||
|
||
**计算公式：**
|
||
|
||
$$
|
||
CV = \frac{SD}{Mean}
|
||
$$
|
||
|
||
若 CV > 100%（即 SD > Mean），则触发警告。
|
||
|
||
**判定条件：**
|
||
|
||
| 场景 | 判定 |
|
||
|------|------|
|
||
| 已知正值指标 + SD > Mean | ❌ Error |
|
||
| 未知指标类型 + SD > Mean | ⚠️ Warning（建议核查） |
|
||
|
||
**已知正值指标关键词：**
|
||
|
||
| 类别 | 指标 |
|
||
|------|------|
|
||
| 人口学 | 年龄、身高、体重、BMI |
|
||
| 生命体征 | 收缩压、舒张压、心率、脉搏 |
|
||
| 血常规 | WBC、RBC、HGB、PLT |
|
||
| 生化 | 肌酐、尿素氮、血糖、ALT、AST、胆红素 |
|
||
| 其他 | 费用、时间、持续时间 |
|
||
|
||
**例外情况：**
|
||
|
||
- **差值指标**：如"治疗前后变化值"可正可负
|
||
- **某些偏态分布指标**：如住院天数（可能存在极端值）
|
||
|
||
**示例：**
|
||
|
||
| 指标 | Mean±SD | CV | 判定 |
|
||
|------|---------|-----|------|
|
||
| 年龄 | 65±12 | 18.5% | ✅ Pass |
|
||
| 体重 | 70±15 | 21.4% | ✅ Pass |
|
||
| 年龄 | 30±45 | 150% | ❌ Error（SD>Mean） |
|
||
| 变化值 | 5±12 | 240% | ⚠️ Warning（可能合理） |
|
||
|
||
**⚠️ 待专家确认：**
|
||
|
||
1. CV > 100% 作为阈值是否合理？
|
||
2. 是否有其他需要排除的例外情况？
|
||
|
||
---
|
||
|
||
## 容错阈值设置
|
||
|
||
### 当前阈值配置
|
||
|
||
| 参数 | 值 | 说明 |
|
||
|------|-----|------|
|
||
| `PVALUE_ERROR_THRESHOLD` | 0.05 | P 值差异 > 此值 → Error |
|
||
| `PVALUE_WARNING_THRESHOLD` | 0.01 | P 值差异 > 此值 → Warning |
|
||
| `DEFAULT_TOLERANCE_PERCENT` | 0.1% | 百分比容错 ±0.1% |
|
||
| `CI_RELATIVE_TOLERANCE` | 2% | CI 端点相对误差 ±2% |
|
||
| `STAT_RELATIVE_TOLERANCE` | 5% | t/χ² 值相对误差 ±5% |
|
||
|
||
### 阈值设置依据
|
||
|
||
1. **P 值阈值 0.05**：当计算的 P 值与报告的 P 值差异超过 0.05 时，可能导致显著性结论相反，属于严重问题
|
||
2. **P 值阈值 0.01**：0.01-0.05 之间的差异可能是舍入误差或计算方法差异，给予警告
|
||
3. **百分比容错 0.1%**：考虑四舍五入误差，允许 ±0.1% 的偏差
|
||
|
||
**⚠️ 待专家确认：**
|
||
|
||
1. 上述阈值是否合理？
|
||
2. 是否需要针对不同检验方法设置不同阈值？
|
||
|
||
---
|
||
|
||
## 待评审问题清单
|
||
|
||
### 高优先级（请专家重点关注）
|
||
|
||
| # | 问题 | 当前处理 | 请确认 |
|
||
|---|------|----------|--------|
|
||
| 1 | 卡方检验默认 df=1 | 适用于 2×2 比较 | 是否合理？如何推断多组比较？ |
|
||
| 2 | T 检验使用 Welch's 还是 Student's | 当前用合并方差公式 | 是否应默认使用 Welch's？ |
|
||
| 3 | CI vs P 值规则中的 "1.0" | 仅适用于比值指标 | 回归系数应使用 0？ |
|
||
| 4 | SE 三角公式的准确性 | 基于正态近似 | 对于小样本是否适用？ |
|
||
| 5 | SD > Mean 的阈值 | CV > 100% 触发 | 是否过于严格？ |
|
||
|
||
### 中优先级（功能扩展）
|
||
|
||
| # | 问题 | 说明 |
|
||
|---|------|------|
|
||
| 6 | 配对 T 检验验证 | 当前仅支持独立样本 |
|
||
| 7 | ANOVA P 值验证 | 多组比较 |
|
||
| 8 | 非参数检验验证 | Mann-Whitney、Wilcoxon |
|
||
| 9 | 相关性分析验证 | Pearson、Spearman |
|
||
|
||
### 低优先级（边缘情况）
|
||
|
||
| # | 问题 | 说明 |
|
||
|---|------|------|
|
||
| 10 | 90% CI vs 95% CI 区分 | 当前假设都是 95% CI |
|
||
| 11 | 单侧检验 vs 双侧检验 | 当前假设都是双侧 |
|
||
| 12 | Bonferroni 校正后的 P 值 | 多重比较场景 |
|
||
|
||
---
|
||
|
||
## 附录：识别模式汇总
|
||
|
||
### 正则表达式清单
|
||
|
||
```python
|
||
# 1. 百分比格式 n (%)
|
||
PERCENT_PATTERN = r"(\d+(?:\.\d+)?)\s*\(\s*(\d+(?:\.\d+)?)\s*%?\s*\)"
|
||
|
||
# 2. P 值
|
||
PVALUE_PATTERN = r"[Pp][\s\-值]*[=<>≤≥]\s*(\d+\.?\d*)"
|
||
|
||
# 3. 卡方值
|
||
CHI_SQUARE_PATTERN = r"(?:χ[²2]|[χx]2|2)\s*[=:]\s*(\d+\.?\d*)"
|
||
|
||
# 4. Mean±SD
|
||
MEAN_SD_PATTERN = r"(\d+\.?\d*)\s*[±\+\-]\s*(\d+\.?\d*)"
|
||
|
||
# 5. OR/HR/RR
|
||
EFFECT_SIZE_PATTERN = r"(?:OR|HR|RR)\s*[=:]\s*(\d+\.?\d*)"
|
||
|
||
# 6. 95% CI
|
||
CI_PATTERN = r"[\(\[]\s*(\d+\.?\d*)\s*[-–—,;]\s*(\d+\.?\d*)\s*[\)\]]"
|
||
```
|
||
|
||
---
|
||
|
||
**文档版本：** v1.0
|
||
**创建日期：** 2026-02-18
|
||
**待更新：** 专家评审反馈后更新
|