# GDEFN 真实名称测试集与可视化升级说明

## 1. 文档目的

本文记录 GDEFN 生物关联智能预测与分析系统针对“整折测试集直接预测、真实实体名称、案例关系图、全文件数据可视化和详细模型架构图”的升级过程，可用于软件设计留档、测试复核和软件著作权材料整理。

所有新增代码、证据快照、运行文件和文档均位于：

`E:\YWH2\BEST\完整代码`

系统仅以只读方式核验原论文、原案例目录和权威上游数据，没有修改目标目录之外的文件。

## 2. 论文依据

本次升级核对了 `E:\YWH2\DAGFN7.10.pdf`：

- Fig. 1 将每个候选 miRNA–mRNA 关系定义为一个 MMP 图节点，并由混合特征、拓扑图、特征图和度感知图学习完成二分类；
- Table 6 给出 `hsa-miR-139-5p` 的 10 个真实靶基因及 Ensembl 转录本；
- Table 7 给出 `BACH1` 的 6 个真实调控 miRNA；
- Section 4.6 说明案例测试集的构造原则：保留一个相关关系参与训练，其余同一查询实体的已知关系作为测试集。

软件的详细 GDEFN 架构图继续以实际代码和 `Fig1_GDEFN_architecture.png` 为主；原 DAGFN Fig. 1 用于核对 MMP 关系节点、上游混合特征和图融合语义。二者不会被错误地画成同一套网络。

## 3. 测试集统一关系格式

预测页默认进入“整折测试集”模式。选择数据集和 Fold 后，系统直接读取该折全部 `testXXX` 样本并送入所选引擎，不再要求手工复制节点编号。

测试集预览、预测结果和 CSV 导出统一使用以下关系字段：

| 字段 | 含义 |
|---|---|
| `pair_id` | 关系样本标识 |
| `query_name` | 查询实体或关系起点 |
| `candidate_name` | 候选实体或关系终点 |
| `regulator` | 调控实体名称 |
| `target` | 靶实体名称 |
| `transcript_or_target_id` | Ensembl、UniProt 等可追溯标识 |
| `reference_label` | 原测试集 0/1 标签 |
| `source_index` | 仅供内部回连原矩阵的 0-based 记录号 |
| `fold` / `split` | 折次与数据划分 |
| `mapping_status` | `verified`、`mapped` 或 `indexed` |
| `mapping_source` | 名称证据来源 |

界面以“调控实体 → 靶实体”为主标题。缺少实名证据时明确显示“关系索引 N”，该编号只表示特征矩阵的 0 基来源行，不解释为生物实体名称。

## 4. miRNA–mRNA 名称证据

### 4.1 已核实关系

系统内置 16 条 `archived_verified` 案例关系：

- `hsa-miR-139-5p` → `IGF1R、CKB、AKIRIN2、ARF6、HEG1、HNRNPF、PDE3A、ADGRG1、ETNK1、SCD`；
- `hsa-let-7g-5p、hsa-let-7e-5p、hsa-miR-196b-5p、hsa-miR-185-5p、hsa-miR-93-5p、hsa-miR-1303` → `BACH1`。

每条记录同时保留：

- 论文 Table 6/7 中的真实名称和转录本；
- 案例重构数据中的记录号；
- 标准 mi-m 矩阵中的原始来源行；
- 本地案例排名表中的概率和排名。

### 4.2 不能可靠实名的范围

标准 mi-m 数值发布文件没有随附全量 index-to-entity 表。本地另一份序列重算清单与发布矩阵不能一一对应，因此系统不采用该清单。

除上述 16 条外，mi-m 样本统一显示原始 0 基关系索引（0–7610）。用户可按模板导入人工核实的 CSV；系统不会根据特征相似性猜测 miRNA 或基因名称。

## 5. DTI 全量真实名称映射

DTI 的 `dti.feature` 为 2,664 × 500：前 100 维是药物 DAE 嵌入，后 400 维是蛋白质 DAE 嵌入。

系统使用论文关联的权威上游 `catly/drug-target` 固定提交 `5323df4a90b08f28fa22f263050dff8f8b9607e0`，按 `float64 round(8)` 分块精确匹配，得到：

- 药物侧 2,664/2,664 唯一解析；
- 靶标侧 2,664/2,664 唯一解析；
- 682 个 DrugBank 药物；
- 1,003 个已使用目标嵌入条目；因上游条目重复，实际为 993 个不同 UniProt ID；
- 1,332 条阳性、1,332 条阴性；
- 唯一重复实体对对应内部记录 2209 和 2329。

输出快照：`research_software/data/dti_entity_pairs.csv`

SHA-256：`4646d3b9f903d08e80c0a067fb0bec3ea204bb2196838a6a965f92a0f0c7012b`

完整来源、源文件哈希和断言见：

- `research_software/data/DTI_实体映射来源说明.md`
- `research_software/data/dti_source/source_manifest.json`
- `research_software/tools/build_dti_mapping.py`

## 6. 可视化模块

### 6.1 真实名称案例网络

“图网络可视化”默认显示真实名称案例，可选择：

1. `hsa-miR-139-5p` → 10 个靶基因；
2. 6 个调控 miRNA → `BACH1`；
3. 两个案例合并网络。

网络支持拖拽节点、拖动画布、滚轮缩放、节点检查和 SVG 导出。节点 ID 与标题均为真实生物名称；边保留概率、排名、转录本和原矩阵来源行。

### 6.2 标准结构图

标准图仍从所选 Fold 的原始边文件执行确定性 BFS 抽样：

- DTI 的全部关系节点显示真实药物、DrugBank ID、靶标和 UniProt ID；
- mi-m 的 16 条已核实来源行显示真实关系，其余显示原始 0 基关系索引；
- 数据集可视化页提供 7,611 条关系目录的分页浏览、0 基索引直接定位和完整 CSV 下载。

### 6.3 全文件数据流图

“数据质检”页新增全文件数据资产图，按以下角色展示：

- 特征矩阵；
- 标签向量；
- 五折训练/验证/测试划分；
- 图结构边；
- KNN 特征近邻图；
- 真实名称案例快照；
- DTI 实体映射和权威来源快照。

接口只返回相对文件名、大小、角色、格式和折次，不向浏览器泄露绝对路径。

### 6.4 GDEFN 详细架构图

模型架构页按实际代码绘制三条并行分支：

1. 共享三视图 GCN：`F → 512 → 256`；
2. 属性 MLP：`F → 128 → 256`；
3. 高阶信号预计算后 UFE MLP：`(F→64)×2 → 128 → 256`。

三视图经共享 GCN 后堆叠并执行视图注意力；属性 MLP 与 UFE 同时并行计算。CrossModalGate 以两类度、图/属性余弦相似度和范数比生成门值，先得到 `Z_DEF = Z_attn + α·gate·Z_mlp`，再与已包含 `γ` 缩放的 `Z_ufe` 相加，最后进入 `256 → 16 → 2 → LogSoftmax` 分类器。点击模块可查看张量维度和职责，也可按真实并行顺序播放数据流。

架构页明确区分：

- 架构设计态：只显示真实计算结构，不虚构 attention、gate、α 或 γ 数值；
- 检查点追踪态：仅当完整 GDEFN 推理实际返回中间值时显示该值。

mi-m 参数量显示为 1,065,365，DTI 参数量显示为 758,165。

## 7. 新增主要接口

| 方法 | 路径 | 功能 |
|---|---|---|
| GET | `/api/test-sets` | 列出全部可选测试折及名称覆盖率 |
| GET | `/api/test-sets/<dataset>/<fold>.csv` | 下载关系格式测试集 |
| POST | `/api/predict/test-set` | 预测整折测试集 |
| GET | `/api/case-studies` | 列出真实名称案例 |
| POST | `/api/predict/case-study` | 查看明确标记为历史快照的案例结果 |
| GET | `/api/case-studies/<case_id>/network` | 生成真实名称案例图 |
| GET | `/api/entities/status` | 查看实体映射覆盖率 |
| GET | `/api/entities/verified-relations` | 分页查看仅有证据的实名关系 |
| GET | `/api/entities/relation-catalog` | 分页查看全部关系，未实名项使用 0 基索引 |
| GET | `/api/entities/relation-catalog/<dataset>.csv` | 下载完整关系索引目录 |
| POST | `/api/entities/import/<dataset>` | 校验并原子导入名称 CSV |
| GET | `/api/data-assets` | 获取全文件数据资产图谱 |

## 8. 结果来源边界

- `quick-baseline`：软件现场拟合 Diagonal LDA；
- `gdefn-checkpoint`：由匹配数据集和折次的 GDEFN 检查点现场推理；
- `gdefn-archived-case-study`：论文案例历史结果快照，`is_live_inference=false`。

三类结果在界面、历史和 CSV 中均单独标识，不能混作同一实验结果。

## 9. 查看方式

1. 双击 `E:\YWH2\BEST\完整代码\启动科研预测软件.bat`；
2. 浏览器会自动打开 `http://127.0.0.1:7860`；
3. “智能预测”选择整折测试集或论文案例；
4. “图网络可视化”查看真实名称关系图；
5. “数据集可视化”查看五个测试折、完整关系索引目录和全文件图谱；
6. “模型架构”点击模块或播放 GDEFN 数据流。

## 10. 安全与目录约束

- 服务仅绑定 `127.0.0.1`；
- 原论文、原案例和原数据文件均按只读方式访问；
- 运行历史、用户映射和临时预览只写入 `research_software/runtime`；
- 用户映射先完整校验，再使用临时文件和 `os.replace` 原子更新；
- 未知数据集、越界记录、重复记录、空名称和非 UTF-8 CSV 均会被拒绝。