# GDEFN 用户操作手册

## 1. 软件简介

GDEFN V1.0 是一款本地运行的生物关联科研软件，用于 miRNA–mRNA 与药物–靶标数据的二分类预测、快速基线评估、GDEFN 五折训练、数据质检和实验记录管理。

请先记住两条核心规则：

1. “快速科研基线”是现场拟合的 Diagonal LDA，**不是** GDEFN 论文模型。
2. 内置节点编号是特征矩阵的 **0 基行索引**，不是药物、基因或 miRNA 的名称。

## 2. 运行要求

### 2.1 快速基线模式

至少需要：

- Python 3.8 或更高版本。
- Flask。
- NumPy。
- 完整的 `datasets` 目录及特征、标签、划分文件。

### 2.2 完整 GDEFN 训练/推理模式

除上述环境外，还需要：

- PyTorch（需支持 `torch.load(..., weights_only=True)` 安全加载；软件会在启用完整引擎前检查）。
- SciPy。
- scikit-learn。
- PyTorch Geometric。
- 推理时需有有效的 `active_manifest.json` 活动清单，且清单所指向的同一不可变运行必须包含五折检查点与对应 JSON 元数据。
- 训练建议使用配置合适的 CUDA GPU；CPU 可能非常缓慢。

软件不会自动联网安装依赖。请在使用完整模型前由环境管理人员核对根目录下的 `requirements.txt` 与当前 PyTorch/CUDA 兼容性。

## 3. 启动与退出

软件的所有路径均按项目相对位置解析。下面使用 `<完整代码>` 代表复制到任意磁盘后的项目根目录，不需要把路径改写为某个固定盘符。

```powershell
cd "<完整代码>\research_software"
python app.py
```

当终端显示访问地址后，使用浏览器打开：

```text
http://127.0.0.1:7860
```

如需退出，回到启动终端按 `Ctrl+C`。不要在训练进程正在写入检查点时强制关机；建议先在“训练中心”停止任务。

## 4. 页面导航

| 页面 | 主要用途 |
| --- | --- |
| 科研总览 | 查看历史论文指标、数据概况和最近运行记录 |
| 智能预测 | 直接预测完整测试折、查看论文案例、预测指定样本或外部同维特征文件 |
| 图网络可视化 | 默认查看真实名称论文案例，也可浏览标准折次结构图并导出 SVG |
| 模型评估 | 在指定测试折上现场评估快速 Diagonal LDA |
| 训练中心 | 启动原始 GDEFN 五折训练、查看进度和检查点状态 |
| 数据质检 | 查看矩阵大小、标签分布、划分重复、交叉与越界情况 |
| 实验记录 | 区分原始训练日志和软件现场运行历史 |
| 模型架构 | 查看三视图 GCN、DEF、UFE 和超参数说明 |
| 帮助与关于 | 查看版本、使用边界与文档位置 |

## 5. 智能预测与统一测试集

### 5.1 选择数据集

- `miRNA–mRNA`：7,611 行、900 维特征，有效节点索引 0–7610。
- `Drug–Target`：2,664 行、500 维特征，有效节点索引 0–2663。

### 5.2 选择折次

选择 Fold 01–Fold 05。折次会同时决定快速基线的训练索引、数据划分展示和完整模型的检查点路径。

### 5.3 选择引擎

- **快速科研基线**：可直接使用，在当前折的训练数据上拟合 Diagonal LDA。
- **GDEFN 完整模型**：只在依赖与安全加载能力完整、`checkpoints/<dataset>/active_manifest.json` 合法，且活动清单所指 `runs/<run_id>/fold_XX.pt` 及元数据验证通过时可用。

系统不会在 GDEFN 不可用时假装执行完整模型。如界面显示“缺少依赖”或“缺少该折检查点”，请先完成环境配置和训练。

### 5.4 直接预测完整测试折

预测页默认选中“整折测试集”。选择数据集、Fold、引擎与阈值后，页面会显示该测试折的关系数、参考阳性数、真实名称覆盖率和 CSV 下载入口。点击“运行智能预测”即可一次处理该折全部测试样本，不需要手工复制记录号。

- mi-m 每个测试折为 736 条关系；能回连可靠证据的关系显示真实 miRNA/mRNA 名称，其余显示原始 0 基关系索引。
- DTI 每个测试折为 222 条关系，2,664 条全集关系均已映射为药物名/DrugBank ID 与靶蛋白名/UniProt ID。
- 下载的测试集与预测导出统一保留 `pair_id`、`regulator`、`target`、`transcript_or_target_id`、`reference_label`、`source_index`、`mapping_status` 和 `mapping_source` 等关系字段。

### 5.5 查看论文案例

选择“论文案例”后，可直接查看 `hsa-miR-139-5p` 的 10 个靶基因或 `BACH1` 的 6 个调控 miRNA。该模式返回的是有来源的历史案例快照，结果来源固定标为 `gdefn-archived-case-study`、`is_live_inference=false`，不能表述成当前检查点现场推理。

### 5.6 输入指定样本索引

支持逗号、空格、换行和连续范围。例如：

```text
0, 18, 42
100-105
256
```

输入 `100-105` 代表 100、101、102、103、104、105。不要把第 1 行写成 1；特征矩阵第 1 行的索引是 0。单次最多处理 5,000 个节点。

### 5.7 设置阈值

正类判定阈值允许 0.05–0.95，默认 0.50。概率大于或等于阈值时输出正类。下调阈值通常会增加阳性召回和假阳性；上调阈值通常更严格。阈值不能让模型变成另一种模型，也不应为追求某个测试指标而在测试集上反复调整。

### 5.8 查看结果

结果表包含：

- 调控实体、靶实体与可追溯关系标识。
- 仅供回连原矩阵的样本索引/ID。
- 正类概率。
- 预测结论。
- 按概率与阈值距离分档的“高/中/低”置信度。
- 节点在所选折次中的划分归属。
- 内置数据的参考标签、名称映射状态与映射来源。

“参考标签”来自已加载的数据文件，不是软件新完成的实验验证。请始终查看结果上方的引擎标签与来源说明。

## 6. 特征文件预测

### 6.1 下载模板

在“智能预测”选择“特征文件预测”，先选择数据集，再下载当前模板。

- `mi-m` 模板：`sample_id` + 900 个特征列，共 901 列。
- `dti` 模板：`sample_id` + 500 个特征列，共 501 列。

### 6.2 文件格式

支持 `.csv`、`.tsv` 和 `.txt`，文件必须使用 UTF-8，不超过 20 MB。可以使用表头；数据行支持两种形式：

```text
# 形式 A：样本 ID + 全部特征
sample_id,feature_0,feature_1,...
sample-A,0.12,-0.03,...

# 形式 B：只有全部特征
0.12,-0.03,...
```

如不提供 ID，系统自动生成 `sample-0001` 等标识。各行必须等宽，不得包含空值、无穷值或非数值特征。单次最多 5,000 行。

### 6.3 方法边界

特征文件仅由快速 Diagonal LDA 处理。GDEFN 需要整个节点特征矩阵及结构图、KNN 图、加/删边图、超图和扩散特征，所以不能把一行上传特征直接冒充为完整 GDEFN 推理。

## 7. 图网络可视化

### 7.1 查看真实名称案例网络

打开“图网络可视化”后，系统默认进入“真实名称案例”模式。可选择：

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

节点标题使用已核实的 miRNA 或基因名称，边检查器显示概率、排名、Ensembl 转录本和原矩阵来源行。案例图是论文历史案例关系的可视化，不等同于一次新的模型计算。

### 7.2 生成标准折次结构图

1. 打开“图网络可视化”。
2. 选择 `miRNA–mRNA` 或 `Drug–Target`，再选择 Fold 01–Fold 05。
3. 输入中心节点的 0 基索引。`mi-m` 范围为 0–7610，`dti` 范围为 0–2663；也可使用“随机中心”或预设节点按钮。
4. 使用滑块设置最大显示节点数，界面范围为 20–100，默认 60。该值是上限；若中心节点所在连通分量较小，实际显示节点会更少。
5. 选择“按参考标签”“按数据划分”或“按节点度”着色，点击“生成局部关系图”。

服务从所选折次的原始结构边开始，以中心节点执行确定性 BFS，并返回已选节点之间的全部诱导边。相同数据、折次、中心和数量参数会得到相同的节点/边集合；浏览器中的力导向坐标可随交互变化。

标准结构图是高级模式：选择数据集与 Fold，输入内部中心记录号并生成局部诱导子图。DTI 节点显示真实药物—蛋白关系；mi-m 已核实的 16 个来源行显示真实关系，其余直接显示原始 0 基关系索引。索引用于回连矩阵和划分文件，不作为生物名称。

### 7.3 查看与交互

- 中心节点使用橙色强调；其他节点按当前着色方式显示。
- 单击节点可查看真实名称、实体类型、映射证据、原始参考标签、所选折次的数据划分和完整折图度数；相关边会高亮。
- 拖拽节点可调整局部布局，拖动画布可平移，滚轮或工具栏的“−/＋”可缩放，“⌂”可重置视图。
- 页面上方统计显示当前子图的节点数、边数、平均完整图度数和子图密度。
- 点击“导出 SVG”可保存当前矢量图，默认文件名形如 `GDEFN_mi-m_fold1_node100.svg`，便于插入论文草稿或软著截图材料。

### 7.4 解释边界与错误处理

标准结构图中的边来自原始 `alledgXXX.txt` 文件，不是 GDEFN 或快速基线刚预测出的关联；力导向位置也不代表分子距离、注意力或因果关系。DTI 名称来自固定上游快照的嵌入精确匹配；mi-m 只显示已核实案例名称，不会给其余关系编造名称。`label` 是原始参考标签，`degree` 是完整折图的唯一邻居数，不应误读为当前子图内度数。

图服务会拒绝重复或交叉造成的冲突划分，不会为了显示而替用户决定节点应属于训练集还是测试集。因此，含已知质量问题的 DTI Fold 02 或 Fold 05 可能提示图数据错误；请先到“数据质检”查看训练重复和训练/测试交叉详情，必要时改看无冲突折次。该错误是对原始数据边界的保护，不表示系统已经自动清洗数据。

## 8. 快速基线现场评估

1. 打开“模型评估”。
2. 选择数据集、测试折和阈值。
3. 点击“开始评估”。
4. 查看 Accuracy、F1、Precision、Recall、Specificity、NPV、AUC、ROC 曲线和混淆矩阵。

该页面只评估快速 Diagonal LDA，不是 GDEFN 论文五折实验。对 DTI 评估时还必须考虑原始划分泄漏：第 2 折节点 623 同时出现于训练和测试，第 5 折节点 28 同时出现于训练和测试，且第 2 折训练索引有 1 个重复项。请不要将这些折次的数值不加说明地当作完全独立测试结果。

## 9. GDEFN 训练与完整推理

### 9.1 启动训练

在“训练中心”设置：

- 数据集：`mi-m` 或 `dti`。
- 计算设备：`cpu`、`0`、`1` 或 `cuda:0` 等合法形式。
- 最大轮次：10–5000，默认 1000。
- 早停耐心值：至少 5，且不得超过最大轮次，默认 100。
- 随机种子：默认 100。

点击“启动五折训练”后，页面显示当前折次、轮次、最新日志和任务状态。同一时间只允许一个训练任务。每次训练获得独立 `run_id`，新运行在五折全部成功前不会影响已经激活的模型。

### 9.2 检查点位置

每次训练使用不可变的运行目录：

```text
<完整代码>/checkpoints/<dataset>/runs/<run_id>/fold_01.pt
<完整代码>/checkpoints/<dataset>/runs/<run_id>/fold_01.json
...
<完整代码>/checkpoints/<dataset>/runs/<run_id>/fold_05.pt
<完整代码>/checkpoints/<dataset>/runs/<run_id>/fold_05.json

<完整代码>/checkpoints/<dataset>/active_manifest.json
```

每折 `.pt` 保存权重和内部元数据，同名 `.json` 侧车文件供加载前校验。这些文件先写入 `.tmp` 再原子替换，避免把半写入文件当作完整检查点。

只有同一 `run_id` 的五折都成功，程序才会原子替换 `active_manifest.json`，将该运行设为新的活动模型。用户主动停止、进程崩溃或任一折失败时，旧活动清单保持不变；若从未成功发布过活动清单，完整引擎仍为不可用。中断运行的部分文件仅用于排查，不会自动参与推理。

训练中心的“检查点就绪状态”会同时检查依赖、安全 PyTorch 加载能力、活动清单、文件存在性与 JSON 元数据。请不要手工拼接清单，也不要仅复制或重命名不相干的 `.pt` 文件；检查点必须由对应数据集、折次和模型配置生成。

### 9.3 使用完整模型预测

1. 在训练中心确认对应数据集的活动 `run_id` 及目标折次为可用。
2. 返回“智能预测”，选择同一数据集与折次。
3. 选择“GDEFN 完整模型”。
4. 可直接选择“整折测试集”运行，也可选择“指定样本”输入合法的 0 基记录号。
5. 确认输出来源为 `gdefn-checkpoint`，并记录检查点相对路径、`run_id`、SHA-256、随机种子、模型配置和最佳轮次。

完整推理还会输出每个节点的三视图注意力权重。这些权重是模型内部表征的辅助解释，不是生物机制的直接因果证据。

## 10. 数据质检

打开“数据质检”后，对每个折次查看：

- 训练、验证和测试数量。
- 各划分内的重复索引数。
- 训练/测试交叉索引。
- 超出数据行范围的索引。

“注意”是数据资产风险披露，不是软件运行失败。系统保留原始划分以便复现，不会在背景中悄悄删除索引。

当前 DTI 2,664 条关系已完成全量实体映射；mi-m 的 7,611 条关系均可按 0 基索引查看，其中 16 条论文案例关系具备可验证名称。名称覆盖率、来源和索引可在数据集可视化、图网络与预测结果中查看。

## 11. 实验记录与导出

### 11.1 原始训练日志

“原始训练日志”页签读取 `<完整代码>/logs/*.txt`，显示日志文件、数据集、是否有完整五折记录及六项指标。注意：日志只记录指标，不包含可直接推理的模型权重。

### 11.2 软件预测历史

“软件预测历史”来自：

```text
research_software/runtime/prediction_history.jsonl
```

每个运行编号保留引擎、数据集、折次、样本数和耗时等溯源字段。对含逐样本记录的预测，可导出 UTF-8 BOM CSV，其中包含两类概率、结论、参考标签和数据划分。

复制整个项目前，如需保留历史，请一并备份 `runtime` 和 `checkpoints` 目录。

## 12. 结果解读原则

1. 先看来源，再看概率和结论。
2. `quick-baseline` 与 `gdefn-checkpoint` 不可在图表或表格中不加区分地合并。
3. 历史论文六指标与现场单折评估不是同一统计口径。
4. 模型概率不是已知生物事实的概率。数据偏差、划分泄漏、特征分布偏移和校准情况都会影响解释。
5. 对新候选关联的科研结论，应结合独立数据、消融/对照实验与湿实验验证。

## 13. 常见问题

### 13.1 页面无法打开

确认启动终端没有报错，地址为 `http://127.0.0.1:7860`，并确认 7860 端口未被其他程序占用。

### 13.2 提示“节点索引超出范围”

确认使用 0 基索引，且未将生物学数据库的外部 ID 直接当作行号。

### 13.3 提示“完整模型暂不可用”

到“训练中心”查看缺失依赖、安全加载能力、活动 `run_id`、检查点和元数据状态。如最新任务被中断，请确认它没有切换 `active_manifest.json`；完整重新运行五折后才能发布新活动模型。

### 13.4 上传后提示列数错误

确认选择的数据集与特征维度一致，并确认第一列只在作为样本 ID 时额外增加。建议使用系统下载的模板。

### 13.5 首次预测、评估或图网络生成较慢

预测/评估需首次加载较大特征矩阵并拟合基线模型；图网络页需首次解析所选折次的边、标签与划分文件。同一进程内的后续相同数据集/折次会使用各自的内存缓存。

### 13.6 页面显示 DTI 质量警告

这是对原始划分的真实报告，不是可以忽略的界面故障。请在结果引用时披露警告，必要时另建严格去重且无交叉的版本化划分开展对照实验。

## 14. 科研使用声明

本软件仅用于科研分析与方法复现。对外发布截图、表格或论文时，请同时保留软件版本、数据集、折次、引擎来源、阈值、随机种子/检查点信息及数据质量警告。