120 lines
4.3 KiB
Markdown
120 lines
4.3 KiB
Markdown
# **SSA-Executor 专家配置要素清单 (Configuration Specs)**
|
||
|
||
**文档版本：** v1.0
|
||
|
||
**创建日期：** 2026-02-18
|
||
|
||
**核心目标：** 定义统计专家需要在“配置中心”为每个 R 工具录入的详细信息。
|
||
|
||
**隐喻：** 如果 R 代码是“药方”，这个配置单就是“药品说明书”。
|
||
|
||
## **1\. 基础元数据 (Identity)**
|
||
|
||
*给这个 R 脚本一个系统内唯一的身份。*
|
||
|
||
| 配置项 | 说明 | 示例 |
|
||
| :---- | :---- | :---- |
|
||
| **Tool Code** | 唯一标识符 (Primary Key) | ST\_T\_TEST\_IND |
|
||
| **Tool Name** | 显示名称 | 独立样本 T 检验 |
|
||
| **Version** | 版本号 | v1.0.2 (用于回滚) |
|
||
| **R Script File** | **上传文件** | t\_test\_ind.R (专家直接上传脚本) |
|
||
| **Entry Function** | 入口函数名 | run\_analysis |
|
||
|
||
## **2\. 输入参数映射 (Input Contract)**
|
||
|
||
*告诉 Executor：这个 R 脚本需要什么原料？*
|
||
|
||
| 参数名 (JSON Key) | R 函数参数名 | 数据类型 | 校验规则 (Validator) | 默认值 |
|
||
| :---- | :---- | :---- | :---- | :---- |
|
||
| group\_col | group\_var | String | Must be column name | \- |
|
||
| val\_col | value\_var | String | Must be numeric column | \- |
|
||
| conf\_level | conf\_level | Float | 0.90 \- 0.99 | 0.95 |
|
||
| alternative | alt | String | "two.sided", "less", "greater" | "two.sided" |
|
||
|
||
## **3\. 统计护栏配置 (Guardrails Config) ⭐ 核心**
|
||
|
||
*告诉 Executor：在跑核心代码前，先做什么体检？*
|
||
|
||
**配置模式：** 规则链 (Rule Chain)
|
||
|
||
1. **检查项 (Check)**: Shapiro-Wilk Normality Test
|
||
* **目标变量**: val\_col (按 group\_col 分组)
|
||
* **阈值 (Threshold)**: P \< 0.05
|
||
* **失败动作 (Action)**:
|
||
* \[ \] **Block**: 报错并终止 ("数据不正态，无法计算")
|
||
* \[ \] **Warn**: 继续执行，但在结果中标记警告
|
||
* \[x\] **Switch**: 自动切换到工具 ST\_WILCOXON (非参数检验)
|
||
2. **检查项 (Check)**: Sample Size
|
||
* **规则**: Min(N) \< 3
|
||
* **失败动作**: **Block** ("样本量太少，无法计算")
|
||
|
||
## **4\. 输出结果定义 (Output Definition)**
|
||
|
||
*告诉 Executor：跑完代码后，要给用户看什么？*
|
||
|
||
### **4.1 结构化数据 (Table)**
|
||
|
||
定义返回的三线表里包含哪些指标。
|
||
|
||
* **指标 1**: Statistic (t值 / F值)
|
||
* **指标 2**: P-Value (保留 3 位小数，\<0.001 显示为 "\<0.001")
|
||
* **指标 3**: Mean ± SD (描述性统计)
|
||
* **指标 4**: CI (95%) (置信区间)
|
||
|
||
### **4.2 图表配置 (Visualization)**
|
||
|
||
定义 R 脚本生成的图表规范（ggplot2 模板）。
|
||
|
||
* **图表类型**: Boxplot with Jitter (箱线图+散点)
|
||
* **X 轴映射**: group\_col
|
||
* **Y 轴映射**: val\_col
|
||
* **配色方案**: Nature / Lancet (期刊风格)
|
||
* **其它元素**: 是否标注 P 值？(Yes/No)
|
||
|
||
### **4.3 智能解读模板 (Narrative Template)**
|
||
|
||
这是给 AI (Critic) 参考的“填空题”，或者是 R 直接生成的结论。
|
||
|
||
* **模板**:"本研究纳入 {{N}} 例样本。{{group\_col}} 各组间 {{val\_col}} 的差异 **{{significance\_text}}** (t={{statistic}}, P={{p\_value}})。具体而言，{{high\_group}} 的均值 ({{mean\_1}}) 显著高于 {{low\_group}} ({{mean\_2}})。"
|
||
|
||
## **5\. 代码交付配置 (Code Handover)**
|
||
|
||
*告诉 Executor：用户点击“下载代码”时，给他什么？*
|
||
|
||
这是一个 **glue 字符串模板**，用于生成可复现的 R 代码。
|
||
|
||
\# 模板示例
|
||
library(ggplot2)
|
||
library(stats)
|
||
|
||
\# 1\. 读取数据
|
||
data \<- read.csv("your\_data.csv")
|
||
|
||
\# 2\. 统计检验
|
||
res \<- t.test({{val\_col}} \~ {{group\_col}}, data=data, var.equal={{var\_equal}})
|
||
print(res)
|
||
|
||
\# 3\. 绘图
|
||
ggplot(data, aes(x={{group\_col}}, y={{val\_col}})) \+
|
||
geom\_boxplot(fill="\#3C5488") \+
|
||
theme\_bw() \+
|
||
labs(title="Difference Analysis")
|
||
|
||
## **6\. 环境依赖 (Dependencies)**
|
||
|
||
*告诉 Executor：运行这个脚本需要装什么包？*
|
||
|
||
* **Packages**: ggplot2, dplyr, car, ggpubr
|
||
* **System Libs**: libcairo2 (如果涉及特殊绘图)
|
||
|
||
## **7\. 总结：专家的工作流**
|
||
|
||
统计学专家在“配置中心”要做的事情就是：
|
||
|
||
1. **上传** 写好的 t\_test.R。
|
||
2. **勾选** 这个脚本需要的输入参数（列名）。
|
||
3. **设置** 护栏（P \< 0.05 切换 Wilcoxon）。
|
||
4. **粘贴** 代码模板（供用户下载）。
|
||
5. **预览** 这一套配置是否能跑通测试数据。
|
||
|
||
**这才是真正的“专家协同”。** |