Develop/AIclinicalresearch
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(asl): Complete Tool 4 SR Chart Generator and Tool 5 Meta Analysis Engine

Browse Source 
Tool 4 - SR Chart Generator:
- PRISMA 2020 flow diagram with Chinese/English toggle (SVG)
- Baseline characteristics table (Table 1)
- Dual data source: project pipeline API + Excel upload
- SVG/PNG export support
- Backend: ChartingService with Prisma aggregation
- Frontend: PrismaFlowDiagram, BaselineTable, DataSourceSelector

Tool 5 - Meta Analysis Engine:
- 3 data types: HR (metagen), dichotomous (metabin), continuous (metacont)
- Random and fixed effects models
- Multiple effect measures: HR / OR / RR
- Forest plot + funnel plot (base64 PNG from R)
- Heterogeneity statistics: I2, Q, p-value, Tau2
- Data input via Excel upload or project pipeline
- R Docker image updated with meta package (13 tools total)
- E2E test: 36/36 passed
- Key fix: exp() back-transformation for log-scale ratio measures

Also includes:
- IIT CRA Agent V3.0 routing and AI chat page integration
- Updated ASL module status guide (v2.3)
- Updated system status guide (v6.3)
- Updated R statistics engine guide (v1.4)

Tested: Frontend renders correctly, backend APIs functional, E2E tests passed
Made-with: Cursor
This commit is contained in:
HaHafeng
2026-02-26 21:51:02 +08:00
parent 7c3cc12b2e
commit 205932bb3f
30 changed files with 3596 additions and 114 deletions
Download Patch File Download Diff File Expand all files Collapse all files

175
docs/02-通用能力层/06-R统计引擎/01-R统计引擎架构与部署指南.md
View File

@@ -1,9 +1,9 @@
# R 统计引擎架构与部署指南
> **版本：** v1.3
> **更新日期：** 2026-02-22
> **维护者：** SSA-Pro 开发团队
> **状态：** ✅ 生产就绪（Phase Deploy 完成 — 12 工具 + Block-based 标准化输出）
> **版本：** v1.4
> **更新日期：** 2026-02-26
> **维护者：** SSA-Pro 开发团队 / ASL 循证工具箱团队
> **状态：** ✅ 生产就绪（13 工具 + Block-based 标准化输出 — 新增 Meta 分析引擎）
---
@@ -42,11 +42,11 @@ R 统计引擎是平台的**专用统计计算服务**，基于 Docker 容器化
┌─────────────────────────────────────────────────────────────┐
│ 业务模块层 │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ SSA-Pro │ │ 其他 │ │ 其他 │ │
│ │ 智能统计 │ │ 模块 │ │ 模块 │ │
│ └────┬────┘ └─────────┘ └─────────┘ │
├───────┼─────────────────────────────────────────────────────┤
│ ▼ 通用能力层 │
│ │ SSA-Pro │ │ ASL │ │ 其他 │ │
│ │ 智能统计 │ │Meta分析 │ │ 模块 │ │
│ └────┬────┘ └────┬────┘ └─────────┘ │
├───────┼──────────┼──────────────────────────────────────────┤
│ ▼ ▼ 通用能力层 │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ R 统计引擎 (Docker) │ │
│ │ • /health 健康检查 │ │
@@ -68,6 +68,7 @@ R 统计引擎是平台的**专用统计计算服务**，基于 Docker 容器化
| gtsummary | 最新 | 基线特征表生成（Phase Deploy 新增） |
| gt/broom | 最新 | 表格渲染/模型整理（Phase Deploy 新增） |
| scales/gridExtra | 最新 | 坐标轴格式化/多图排版（Phase Deploy 新增） |
| meta | 8.2.1 | Meta 分析引擎（ASL 工具 5 新增 — metagen/metabin/metacont） |
| Docker | 24+ | 容器化部署 |
---
@@ -187,7 +188,7 @@ RUN apt-get update && apt-get install -y \
curl \
&& rm -rf /var/lib/apt/lists/*
# 直接安装 R 包（含 Phase Deploy 新增依赖）
# 直接安装 R 包（含 Phase Deploy + ASL Meta 分析依赖）
RUN R -e "install.packages(c( \
'plumber', \
'jsonlite', \
@@ -203,7 +204,8 @@ RUN R -e "install.packages(c( \
'gridExtra', \
'gtsummary', \
'gt', \
'broom' \
'broom', \
'meta' \
), repos='https://cloud.r-project.org/', Ncpus=2)"
# 安全加固：创建非特权用户
@@ -273,8 +275,8 @@ ssa-r-statistics 1.0.1 xxxxxxxxxxxx x minutes ago 1.81GB
|------|------|
| 基础镜像下载 | ~2 分钟（首次） |
| 系统依赖安装 | ~1 分钟 |
| R 包安装（15 个包含 gtsummary/gt） | ~10 分钟 |
| **总计** | **~13 分钟** |
| R 包安装（16 个，含 gtsummary/gt/meta） | ~15 分钟 |
| **总计** | **~17 分钟** |
---
@@ -378,7 +380,7 @@ GET /health
"timestamp": "2026-02-19 08:00:00",
"version": "1.0.1",
"dev_mode": true,
"tools_loaded": 1
"tools_loaded": 13
}
```
@@ -402,15 +404,16 @@ GET /api/v1/tools
"linear_reg",
"logistic_binary",
"mann_whitney",
"meta_analysis",
"t_test_ind",
"t_test_paired",
"wilcoxon"
],
"count": 12
"count": 13
}
```
#### 已实现的统计工具（12 个）
#### 已实现的统计工具（13 个）
**Phase 2A 基础工具（7 个）**
@@ -434,6 +437,14 @@ GET /api/v1/tools
| `ST_LINEAR_REG` | 线性回归 | 连续结局多因素分析 |
| `ST_BASELINE_TABLE` | 基线特征表（复合工具） | 基于 gtsummary 的一键式基线表生成 |
**ASL 循证工具箱新增（1 个）**
| tool_code | 名称 | 场景 | 调用方 |
|-----------|------|------|--------|
| `ST_META_ANALYSIS` | Meta 分析引擎 | HR / 二分类 / 连续型 Meta 分析，生成森林图 + 漏斗图 | ASL 工具 5 |
> **跨模块复用说明：** `ST_META_ANALYSIS` 由 ASL 模块（工具 5：Meta 分析引擎）引入，后端代理位于 `backend/src/modules/asl/meta-analysis/`，使用 `inline` 数据协议（Meta 分析通常 5-30 个研究，数据量极小）。该工具同样可被 SSA 或其他模块复用。
### 5.3 执行技能
```http
@@ -593,6 +604,79 @@ Content-Type: application/json
> **特点：** `ST_BASELINE_TABLE` 是复合工具，基于 `gtsummary::tbl_summary()` 自动判断变量类型（连续/分类）、选择统计方法（T 检验/Mann-Whitney/卡方/Fisher），输出标准三线表。`report_blocks[0].metadata.is_baseline_table = true` 触发前端特殊渲染（P 值标星、rowspan 合并行）。
### 5.6 Meta 分析示例（ASL 工具 5 — v1.4 新增）
```http
POST /api/v1/skills/ST_META_ANALYSIS
Content-Type: application/json
```
**请求体（HR 数据类型）：**
```json
{
"data_source": {
"type": "inline",
"data": [
{"study_id": "Gandhi 2018", "hr": 0.49, "lower_ci": 0.38, "upper_ci": 0.64},
{"study_id": "Socinski 2018", "hr": 0.56, "lower_ci": 0.45, "upper_ci": 0.70},
{"study_id": "West 2019", "hr": 0.60, "lower_ci": 0.45, "upper_ci": 0.80}
]
},
"params": {
"data_type": "hr",
"model": "random"
}
}
```
**支持的 3 种数据类型：**
| data_type | 必需列 | R 函数 | 效应指标 |
|-----------|--------|--------|----------|
| `hr` | `study_id`, `hr`, `lower_ci`, `upper_ci` | `meta::metagen()` | HR |
| `dichotomous` | `study_id`, `events_e`, `total_e`, `events_c`, `total_c` | `meta::metabin()` | OR / RR / RD |
| `continuous` | `study_id`, `mean_e`, `sd_e`, `n_e`, `mean_c`, `sd_c`, `n_c` | `meta::metacont()` | MD |
**params 参数：**
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `data_type` | string | 必填 | `"hr"` / `"dichotomous"` / `"continuous"` |
| `model` | string | `"random"` | `"random"` (DerSimonian-Laird) / `"fixed"` |
| `effect_measure` | string | 自动 | 仅二分类有效：`"OR"` / `"RR"` / `"RD"` |
**成功响应（核心字段）：**
```json
{
"status": "success",
"results": {
"pooled_effect": 0.5948,
"pooled_lower": 0.5255,
"pooled_upper": 0.6733,
"pooled_pvalue": 0.0,
"i_squared": 15.4,
"tau_squared": 0.0031,
"q_statistic": 4.73,
"q_pvalue": 0.316,
"k_studies": 3,
"effect_measure": "HR",
"model": "Random Effects"
},
"plots": [
"data:image/png;base64,...(森林图)",
"data:image/png;base64,...(漏斗图)"
],
"report_blocks": [
{"type": "key_value", "title": "Meta-Analysis Summary", "items": [...]},
{"type": "image", "title": "Forest Plot", "data": "..."},
{"type": "image", "title": "Funnel Plot", "data": "..."},
{"type": "markdown", "title": "Heterogeneity Assessment", "content": "..."}
]
}
```
> **重要实现细节 — 对数尺度反变换：** `meta` R 包对比值类效应量（HR / OR / RR）的内部计算在**对数尺度**上进行，即 `TE.random` 返回的是 `log(HR)` 而非 HR。`meta_analysis.R` 在结果提取阶段对比值类指标自动执行 `exp()` 反变换，确保 API 返回临床可读的效应量（如 HR = 0.59 而非 log(HR) = -0.52）。连续型指标（MD）无需反变换。
---
## 6. 开发指南
@@ -798,6 +882,7 @@ blocks[[length(blocks) + 1]] <- make_markdown_block("两组差异具有统计学
| `ST_WILCOXON` | `before_var`, `after_var` | — |
| `ST_LINEAR_REG` | `outcome_var`, `predictors` (数组) | `confounders` (数组) |
| `ST_BASELINE_TABLE` | `group_var` | `analyze_vars` (数组，不传则自动全选) |
| `ST_META_ANALYSIS` | `data_type` (`hr` / `dichotomous` / `continuous`) | `model` (`random` / `fixed`)、`effect_measure` (二分类: `OR` / `RR` / `RD`) |
### 6.6 R 语言陷阱速查（从实际 Bug 中总结）
@@ -921,6 +1006,23 @@ cd r-statistics-service
docker-compose restart
```
#### 陷阱 8：`meta` 包返回对数尺度效应量（v1.4 新增）
**现象：** Meta 分析返回 HR = -0.52，但期望 HR ≈ 0.59
**原因：** `meta` R 包的 `metagen()`/`metabin()` 对比值类效应量（HR、OR、RR）在**对数尺度**上计算。`TE.random`/`TE.fixed` 返回的是 `log(HR)` 或 `log(OR)`，而非原始比值。
```r
# ❌ 错误：直接返回 TE（对数尺度）
pooled_effect = ma_result$TE.random # 返回 -0.52（这是 log(HR)）
# ✅ 正确：对比值类指标做 exp() 反变换
is_ratio <- sm_label %in% c("HR", "OR", "RR")
display_te <- if (is_ratio) exp(pooled_te) else pooled_te # 返回 0.59（真实 HR）
```
**影响范围：** 仅 `meta_analysis.R`，不影响其他统计工具。连续型指标（MD）无需反变换。
### 6.7 开发环境新增 R 包
当新工具依赖尚未安装的 R 包时，有两种方式：
@@ -1156,7 +1258,7 @@ curl -s -X POST "http://localhost:8082/api/v1/skills/ST_T_TEST_IND" \
curl -s http://localhost:8082/health | jq
```
### 9.3 R 工具集中测试脚本（12 工具 + JIT）
### 9.3 R 工具集中测试脚本（13 工具 + JIT）
项目提供了 R 统计引擎的全工具测试脚本：
@@ -1166,7 +1268,7 @@ node r-statistics-service/tests/run_all_tools_test.js
```
测试覆盖：
- 12 个统计工具（Phase 2A × 7 + Phase Deploy × 5）
- 13 个统计工具（Phase 2A × 7 + Phase Deploy × 5 + ASL × 1）
- JIT 护栏检查（ST_T_TEST_IND / ST_ANOVA_ONE / ST_FISHER / ST_LINEAR_REG）
- `report_blocks` 协议校验（类型、必填字段、metadata）
@@ -1180,17 +1282,44 @@ node run_e2e_test.js
```
测试覆盖：
- Layer 1: R 服务（12 个统计工具 + JIT 护栏）
- Layer 1: R 服务（13 个统计工具 + JIT 护栏）
- Layer 2: Python DataProfile API
- Layer 3: Node.js 后端 API（登录 → 会话 → 规划 → 执行）
### 9.5 Meta 分析引擎专项 E2E 测试（v1.4 新增）
覆盖 Meta 分析的完整链路（Node.js → R Docker → 森林图/漏斗图生成）：
```bash
cd backend
npx tsx src/modules/asl/meta-analysis/__tests__/meta-e2e-test.ts
```
测试覆盖（8 个测试项，36 个断言）：
- R 服务健康检查 + meta_analysis 工具注册验证
- HR 风险比 Meta 分析（5 个研究，随机效应）
- 二分类 OR Meta 分析（4 个研究）
- 二分类 RR Meta 分析（效应指标切换）
- 连续型 MD Meta 分析（5 个研究）
- 固定效应模型切换
- 边界条件：仅 1 个研究（应返回错误）
- 森林图 + 漏斗图 Base64 PNG 生成验证
最近一次测试结果（2026-02-26）：
```
Results: 36 passed, 0 failed (1.3s)
HR = 0.5948 [0.5255, 0.6733], I² = 15.4%
OR = 0.4530 [0.3328, 0.6166], p < .001
MD = -1.4923 [-1.9098, -1.0749], I² = 70%
```
---
## 附录：文件结构
```
r-statistics-service/
├── Dockerfile # 生产镜像定义（含 gtsummary/gt/broom/scales/gridExtra）
├── Dockerfile # 生产镜像定义（含 gtsummary/gt/broom/scales/gridExtra/meta）
├── docker-compose.yml # 开发环境编排（含 volume 挂载）
├── renv.lock # R 包版本锁定（备用）
├── .Rprofile # R 启动配置（备用）
@@ -1201,7 +1330,7 @@ r-statistics-service/
│ ├── error_codes.R # 错误映射
│ ├── result_formatter.R # 结果格式化
│ └── block_helpers.R # Block-based 输出辅助函数（Phase E+ 协议）
├── tools/ # 统计工具（12 个）
├── tools/ # 统计工具（13 个）
│ ├── t_test_ind.R # 独立样本 T 检验
│ ├── t_test_paired.R # 配对 T 检验
│ ├── mann_whitney.R # Mann-Whitney U 检验
@@ -1213,7 +1342,8 @@ r-statistics-service/
│ ├── anova_one.R # 🆕 单因素方差分析（Phase Deploy）
│ ├── wilcoxon.R # 🆕 Wilcoxon 符号秩检验（Phase Deploy）
│ ├── linear_reg.R # 🆕 线性回归（Phase Deploy）
│ └── baseline_table.R # 🆕 基线特征表 — 复合工具（Phase Deploy）
│ ├── baseline_table.R # 🆕 基线特征表 — 复合工具（Phase Deploy）
│ └── meta_analysis.R # 🆕 Meta 分析引擎 — HR/二分类/连续型（ASL 工具 5）
├── tests/
│ ├── run_all_tools_test.js # 🆕 全工具自动化测试（12 工具 + JIT + blocks 校验）
│ ├── test_t_test.json # T 检验测试数据
@@ -1234,6 +1364,7 @@ r-statistics-service/
| 版本 | 日期 | 更新内容 |
|------|------|----------|
| v1.4 | 2026-02-26 | ASL Meta 分析引擎：工具 12→13（+ST_META_ANALYSIS），Dockerfile 新增 `meta` 包，新增 §5.6 Meta 分析 API 示例、陷阱 8（对数尺度反变换）、§9.5 Meta E2E 测试（36 断言全通过），架构图更新 ASL 调用方 |
| v1.3 | 2026-02-22 | 开发者体验增强：新工具模板补全 report_blocks（§6.1）、各工具 params 速查表（§6.5）、R 语言 7 大陷阱实录（§6.6）、新增 R 包操作指南（§6.7）、新增 Q11-Q13 常见问题 |
| v1.2 | 2026-02-22 | Phase Deploy 完成：工具 7→12（+Fisher/ANOVA/Wilcoxon/线性回归/基线表）、Dockerfile 新增 gtsummary 等 5 包、Block-based 输出协议文档化（§6.4）、全工具测试脚本 |
| v1.1 | 2026-02-20 | Phase 2A 完成：7 个统计工具、JIT 护栏、热重载说明、常见问题补充 |