symfold

SymFold：基于 RNA 语言模型的 RNA 二级结构预测

SymFold 是一个研究型 RNA 二级结构预测项目，目标是把 RNA 序列映射为对称二值 contact map：给定长度为 (L) 的序列，模型预测每一对核苷酸是否配对，并进一步解码为配对集合或 dot-bracket 结构。

项目包含两条相互独立、但共享数据与 encoder 适配层的训练路线：

1. 直接判别式预测：一次前向输出 contact logits，是当前 GB.RNA/RNA-FM 消融和论文实验的主路线；
2. 离散 Flow Matching：从带噪二值 contact map 逐步去噪，通过 τ-leap CTMC 采样生成结构，用于生成式结构预测研究。

仓库不仅包含模型代码，还包含数据构建与防泄漏 split、训练配置、checkpoint/曲线、阈值扫描、bad-case 诊断和论文实验汇总。当前主要研究问题包括：RNA foundation model 的 1D/2D 表征适配、pair-space fusion、结构重复与数据泄漏、辅助监督（pairedness/pair type）、长程配对、跨 RNA family 泛化以及外部 benchmark 表现。

快速导航： 想先跑通项目，阅读 CLAUDE.md 的“从零开始”部分；想了解数据边界，阅读 data/README.md；想复现实验，先从 configs/ 中选择 YAML，再查看对应 outputs/<run>/logs/train.log。

---

1. 项目要解决什么问题

输入是一条 RNA 序列，例如：

GGCUCACCAAGGCG...

输出是其二级结构的配对集合或等价的 contact map。数据标签原始形式为 dot-bracket；项目会解析普通 stem 与多层 pseudoknot bracket，再转为对称 contact map。支持的 bracket tier 包括 () [] {} <> 及大小写字母配对。

[ C_{ij}=C_{ji}=\begin{cases} 1,& \text{nucleotide }i\text{ 与 }j\text{ 配对}\ 0,& \text{otherwise} \end{cases} ]

实现依据： dot-bracket 解析及伪结 tier 定义见 symfold/data/dotbracket.py:1-57；Parquet 样本读取、contact-map 构建和 batch padding 见 symfold/data/datasets.py:24-97。

---

2. 总体架构

RNA sequence
    │
    ├── RNA encoder（GB.RNA / RNA-FM / RiNALMo）
    │       ├── per-nucleotide hidden states: [B, L, H]
    │       └── selected attention maps:      [B, A, L, L]
    │
    ├── 直接判别式路线
    │       hidden/attention fusion → [B, L, L] contact logits
    │
    └── 离散 Flow Matching 路线
            pair condition + noisy x_t + time t
            → DiT-style pair backbone → [B, L, L] contact logits
            → τ-leap CTMC sampling → contact probabilities

2.1 共用 RNA encoder 适配层

RNAEncoderFeatureExtractor 统一封装本地 RNA-FM、RiNALMo 与 GB.RNA：

• 输出逐核苷酸 1D 表示 [B,L,H]；
• 输出最后若干 encoder layer 的 attention map [B,A,L,L]；
• 通过 mask 排除 padding；
• 支持冻结 encoder，或在解冻时启用 gradient checkpointing 降低显存。

GB.RNA 走仓库内置的 RNABert/tokenizer 路径；其输入按单碱基 token 化，且显式校验 token 数为 (L+2)。

实现依据： encoder 类型识别与加载见 symfold/models/rnafm_encoder.py:28-91；token 对齐与特征/attention 输出见 symfold/models/rnafm_encoder.py:117-194；配置键兼容逻辑见 symfold/models/rnafm_encoder.py:197-210。

2.2 直接判别式模型（当前主实验模型）

discriminative_contact_map 的前向输入只有 List[str]，一次输出：

logits: [B, L, L]
mask:   [B, L]

模型流程：

1. encoder hidden 经 LayerNorm + Linear 投影到 pair_dim；
2. 对任意位置对 ((i,j))，使用对称平均 ((h_i+h_j)/2) 构造 sequence pair feature；
3. encoder attention 用 1×1 Conv 投影为 pair feature；
4. 通过双向 gate 与 FiLM 调制融合两条路径；
5. 用 interaction MLP 和可选的单层 depthwise 3×3 pair smoother 建模局部一致性；
6. 输出对称 logits。

这条路线不使用 flow noising 或 CTMC，因此训练和评估显著快于生成式路线。

实现依据： gated fusion 见 symfold/models/discriminative_contact_map_model.py:19-50；局部 smoother 见 symfold/models/discriminative_contact_map_model.py:53-76；模型组装与对称 logits 输出见 symfold/models/discriminative_contact_map_model.py:79-149；训练损失与循环见 symfold/train_supervised_pair.py:54-86,186-268。

2.3 离散 Flow Matching 模型

Flow Matching 路线使用：

[ x_t\sim\mathrm{Bernoulli}((1-t)\rho_0+t x_1) ]

其中 (x_1) 为真实 contact map，(x_t) 是时间 (t) 的对称二值带噪状态。网络预测 (p(x_1=1\mid x_t,t,\mathrm{RNA}))。

其 pair condition 显式融合：

• (h_i,h_j,|h_i-h_j|,h_i\odot h_j)；
• encoder attention；
• log-distance embedding；
• 可选 AU/GC/GU/other/unknown base-pair type embedding。

随后在 pair space 上运行 DiT-style backbone；当 patch_size>1 时，主干在 patch space 计算，再回到全分辨率进行可选 refinement。

实现依据： pair representation 见 symfold/models/flow_matching_model.py:28-119；模型组装、patch/unpatch 与 logits 输出见 symfold/models/flow_matching_model.py:180-307；Bernoulli bridge、BCE/Dice/degree loss 与 CTMC 采样见 symfold/models/flow_matching.py:72-188。

---

3. 训练、解码与指标

3.1 损失

直接判别式训练使用 masked BCE-with-logits，并可附加：

• 正样本权重 pos_weight；
• focal reweighting；
• Dice loss；
• soft degree penalty（抑制一个碱基配给多个 partner）。

Flow Matching 使用对应的 masked flow loss。

实现依据： 直接模型损失见 symfold/train_supervised_pair.py:61-99；Flow Matching 损失见 symfold/models/flow_matching.py:78-131。

3.2 Greedy 结构投影

默认评估可开启 greedy projection：

1. 排除 padding 和小于 min_sequence_separation 的 pair；
2. 取概率不低于 threshold 的候选边；
3. 按概率降序；
4. 每个碱基最多保留一个 partner。

这保证了 at-most-one-partner，但不保证 non-crossing，也不会强制 canonical pairing。

实现依据： 解码见 symfold/metrics.py:21-51；Precision、Recall、F1、MCC、Accuracy 计算见 symfold/metrics.py:54-86。

3.3 Flow Matching 评估

Flow 路线评估时先执行 CTMC 多步采样，再根据一个或多个阈值计算指标；如果提供 threshold grid，会选验证 F1 最优阈值。

实现依据： 采样评估、阈值扫描与 greedy decode 见 symfold/evaluate_flow_matching.py:21-150。

---

4. 数据集与实验设计

完整的数据说明、样本数、派生关系和使用边界见 data/README.md。核心数据如下：

4.1 结构去重实验的含义

structdedup098 使用 spot0 train 的全对全 bpRNA-align 相似度。所有 norm_score>=0.98 connected component 仅保留最长的代表序列：10,814 条训练样本变为 7,240 条，移除 3,574 条；validation/test 与原 spot0 完全一致。

实现与证据： 去重 manifest 为 data/bprna-spot0-structdedup098/deduplication_manifest.json:1-13；构建逻辑见 scripts/build_alignment_struct_dedup.py:50-125；全对全对齐分片格式和归一化得分计算见 scripts/run_bprna_align_full.py:132-242。

---

5. 工程进展与研究状态

本节记录仓库的研究资产和稳定结论；具体某次训练是否仍在运行，以对应 outputs/<run>/logs/train.log 和进程状态为准。

5.1 已完成的主要工程

• 完成 GB.RNA、RNA-FM、RiNALMo 的统一 encoder 接入；
• 实现直接判别式 contact-map 和离散 Flow Matching 两条训练路线；
• 实现 pair_dim=512、1D-only、2D-only、simple fusion、Cross-Gated 和 Multi-task 配置；
• 完成 spot0 train 的 bpRNA-align 全对全分析，以及 trainfilter、structdedup098、genfilter 和 full-diversity 数据构建；
• 完成阈值扫描、bad-case、模板转移、错误 pair、跨度、碱基类型和来源家族分析；
• 生成论文实验曲线、阈值汇总和跨数据集评测结果。

主要研究文档和结果入口：

• docs/论文写作数据/PAPER_AND_PAPER2_THRESHOLD_SUMMARY_20260830.md：paper_* 与 paper2_* 的训练曲线、validation threshold 和 locked-test 指标；
• docs/论文写作数据/paper_test_threshold_curves.png：Paper 实验 test F1-threshold 曲线；
• docs/论文写作数据/paper2_test_threshold_curves.png：Paper2 实验 test F1-threshold 曲线；
• docs/DISCRIMINATIVE_BADCASE_TEMPLATE_TRANSFER_REPORT.md：结构近邻 train/test 模板转移分析；
• docs/DISCRIMINATIVE_BADCASE_ERROR_DIAGNOSIS.md：密度、跨度、阈值和 decoder 诊断；
• docs/DISCRIMINATIVE_BADCASE_MISPAIR_CONTEXT_ANALYSIS.md：逐 pair 碱基、局部上下文与错误 partner 分析。

5.2 当前论文实验的统一评估协议

paper_* 与 paper2_* 的常规实验使用 best.pt，先在 validation 上以 0.01 步长扫描 0.00–1.00，再将 validation 选出的 threshold 锁定到 test；RNAStrAlign→ArchiveII 实验则分别扫描两个 test 数据集。阈值扫描实现见 scripts/scan_discriminative_threshold.py:1-100，汇总结果见 docs/论文写作数据/PAPER_AND_PAPER2_THRESHOLD_SUMMARY_20260830.md。

该协议区分三类数值：

1. 训练曲线中的 test F1：用于观察训练过程，不用于选择模型或 threshold；
2. validation-selected locked-test F1：正式泛化结果；
3. test 独立扫描的最高 F1：仅作后验敏感性分析，不能替代 locked-test 结果。

5.3 当前研究认识与限制

已有消融表明，1D/2D 表征均包含有效信息，但简单融合或完整 Multi-task 并不保证稳定提升；pairedness 通常比 pair type 更稳定，辅助监督可能存在任务竞争。该结论应结合 matched seed、跨数据集测试和训练协议解释，不能把单次结果写成普遍规律。

当前模型和评估仍有以下限制：

• F1 是严格 exact-pair 指标，stem 端点偏移也会同时产生 FP/FN；
• greedy decoder 只保证每个碱基最多一个 partner，不保证 non-crossing；
• structdedup098 只去除 train 内高相似结构，不等于 test 与 train 完全不相似；
• 配置中的本地模型路径、GPU、数据 split 和 threshold 必须与运行日志一起记录；
• outputs/ 和 .git/lfs/ 可能包含大量 checkpoint 与历史对象，清理前必须确认远程仓库、复现实验和 .codebuddy/ 数据不再需要。

错误模式的详细证据包括模板转移、stem register 偏移、长程 partner 漏检、稀疏结构过配以及 non-canonical pair 偏置，见上述 bad-case 文档和对应 outputs/ 分析目录。

---

6. 目录结构

symfold/
├── configs/                 # 可复现实验 YAML
│   ├── dis/                  # 直接判别式模型与消融
│   ├── flowmatching/         # 离散 Flow Matching
│   ├── paper/                # 第一组论文实验
│   ├── paper2/               # 第二组论文实验
│   └── archive/               # 历史/归档配置
├── data/                    # Parquet 数据、split、对齐和派生数据
│   └── README.md             # 数据边界、schema 和构建协议
├── models/                  # 本地 RNA encoder 权重
├── symfold/                 # 核心 Python 包
│   ├── data/                 # loader、dot-bracket/contact-map、sampler、增强
│   ├── models/               # encoder adapter、direct model、flow model、DiT
│   ├── train.py              # 单阶段/多阶段统一入口
│   ├── train_staged.py       # 多 config 顺序训练编排器
│   ├── train_supervised_pair.py  # 判别式 trainer
│   ├── train_flow_matching.py    # Flow Matching trainer
│   ├── evaluate_flow_matching.py # Flow Matching 评估
│   ├── metrics.py            # decode 和指标
│   └── visualize.py          # 曲线和样例可视化
├── scripts/                 # 数据构建、bpRNA-align、评估和诊断 CLI
│   └── README.md             # 脚本用途与保留/归档建议
├── docs/                    # 架构、数据、训练、bad-case 和论文资料
├── outputs/                 # 日志、checkpoint、曲线和分析产物
├── tests/                   # 基础测试
├── examples/                # 最小使用示例
├── .external/               # 外部依赖或模型相关源码
├── README.md                # 项目全貌
├── CLAUDE.md                # 项目上手与 AI 协作规范
└── requirements.txt         # 精确 pip 依赖

outputs/ 和 models/ 可能占用远大于源代码的磁盘空间；.git/lfs/ 还可能保留多个历史大文件版本。删除实验结果或 Git LFS 缓存前，先确认 checkpoint、远程仓库和复现实验不再需要；不要删除 .codebuddy/。

统一入口会根据 YAML 中的 trainer.type 调用：

• flow_matching → symfold.train_flow_matching；
• direct_contact_map → symfold.train_supervised_pair。

实现依据： symfold/train.py:1-70。

---

7. 从零复现

7.1 前置条件

• Linux x86_64；
• Python 3.10；
• NVIDIA GPU；
• 对 GPU 训练，使用兼容 PyTorch CUDA 13.0 wheel 的驱动；
• 本地预训练权重目录，例如 models/gbrna1.6B/；
• 本地 Parquet 数据目录 data/。

当前 requirements.txt 固定了实际运行环境版本，包括 torch==2.12.1+cu130、transformers==5.13.0、multimolecule==0.2.0、numpy==2.2.6、pandas==2.3.3 和 pyarrow==24.0.0。

7.2 安装

cd /path/to/symfold
python3.10 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

快速验证：

python - <<'PY'
import torch, transformers, multimolecule, pandas, pyarrow
print('torch:', torch.__version__)
print('cuda build:', torch.version.cuda)
print('cuda available:', torch.cuda.is_available())
print('transformers:', transformers.__version__)
print('pandas:', pandas.__version__, 'pyarrow:', pyarrow.__version__)
PY

requirements.txt 使用 PyTorch CUDA 13.0 的官方 wheel index。没有 GPU 或驱动不兼容时，请按目标平台的 PyTorch 官方安装方式替换 PyTorch 相关行，再安装其余依赖。

7.3 准备本地资源

至少确认：

models/gbrna1.6B/config.json
data/bprna-spot0/train.parquet
data/bprna-spot0/validation.parquet
data/bprna-spot0/test.parquet

配置中的 model.rna_encoder_path 必须指向真实权重目录。当前 GB.RNA 实验配置使用绝对路径 /efs/dannyyan/symfold/models/gbrna1.6B；迁移到新机器时请将其改为本地实际路径。

7.4 运行直接判别式训练

冻结 GB.RNA 的结构去重对照：

python -m symfold.train \
  --config configs/discriminative_contact_map_gbrna_spot0_structdedup098_cov_pair512_cuda0_400.yaml

解冻 GB.RNA 的结构去重实验：

python -m symfold.train \
  --config configs/discriminative_contact_map_gbrna_spot0_structdedup098_cov_pair512_cuda1_unfrozen_400.yaml

开始前请将 YAML 中的 experiment.device 改为本机可用 GPU。解冻 GB.RNA 显存与计算开销明显更高；当前配置使用 FP32 和 gradient checkpointing，因为长序列 GB.RNA 全量反向曾出现 BF16 non-finite gradient。

配置依据： 解冻设置、独立 encoder 学习率及 FP32 选择见 configs/discriminative_contact_map_gbrna_spot0_structdedup098_cov_pair512_cuda1_unfrozen_400.yaml:35-45,77-94。

7.5 运行 Flow Matching 训练

例如运行 GB.RNA、共变增强、pair_dim=512 的 Flow Matching 配置：

python -m symfold.train_flow_matching \
  --config configs/flow_matching_gbrna_spot0_covariation_pair512_unfrozen_400.yaml

也可以走统一入口：

python -m symfold.train \
  --config configs/flow_matching_gbrna_spot0_covariation_pair512_unfrozen_400.yaml

后者在没有明确 trainer.type 时，会因配置含 flow_matching 字段而选择 Flow Matching 路线。实现依据： symfold/train.py:25-52。

7.6 多阶段训练

多个 config 可以作为同一个训练实验顺序执行。所有 config 必须使用相同的 trainer.type，例如都使用 flow_matching，或者都使用 direct_contact_map。

python -m symfold.train \
  --config /path/to/phase1.yaml /path/to/phase2.yaml

也可以直接调用编排器：

python -m symfold.train_staged \
  --config /path/to/phase1.yaml /path/to/phase2.yaml

每个 config 的 train.num_epochs 表示该阶段新增的 epoch 数。比如两个 config 都是 400，实际执行为：

Phase 1: epoch 0–399
Phase 2: epoch 400–799

第二阶段自动从共享 run 目录中的 checkpoints/last.pt 恢复模型、optimizer、scheduler、epoch、global step 和 best metric。多个阶段共用：

outputs/<run>/
├── checkpoints/
├── logs/train.log
├── logs/history.json
├── dashboards/stage_01_*.png
└── dashboards/stage_02_*.png

每个阶段单独生成一个 dashboard：

• loss 只绘制当前阶段，不跨阶段连接；
• Val/Test F1、Precision、Recall 等评估指标按累计 epoch 接续；
• 所有阶段的训练历史写入同一个 history.json，并记录 stage 字段；
• 不在 outputs/ 顶层额外生成 train_*.log；
• 不再自动生成 logs/curves/ 明细目录。

Flow Matching 示例：

python -m symfold.train_flow_matching \
  --config configs/flow_phase1.yaml configs/flow_phase2.yaml

判别式示例：

python -m symfold.train_supervised_pair \
  --config configs/direct_phase1.yaml configs/direct_phase2.yaml

train.py 是推荐的统一入口；train_staged.py 是多阶段编排实现；两个具体 trainer 负责各自单阶段的模型训练。它们不是四套独立训练逻辑，使用其中一个入口即可。

实现依据： 统一入口见 symfold/train.py:18-66；多阶段编排见 symfold/train_staged.py:57-151；判别式阶段参数见 symfold/train_supervised_pair.py:32-51,170-240；Flow Matching 阶段参数见 symfold/train_flow_matching.py:43-64,81-145。

7.7 续训

单阶段或多阶段都可以通过 --resume-run-dir 继续写入已有 run。多阶段续训时，第二阶段仍会自动从该目录的 checkpoints/last.pt 接续。

python -m symfold.train \
  --config /path/to/continue.yaml \
  --resume-run-dir /path/to/existing_run

实现依据： checkpoint 保存与恢复字段见 symfold/utils.py:155-182。

---

8. 配置指南

8.1 训练范式

trainer:
  type: direct_contact_map  # 或 flow_matching

直接路线还须指定：

model:
  type: discriminative_contact_map  # 或 legacy supervised_pair

8.2 常用 encoder 配置

model:
  rna_encoder_path: /absolute/path/to/gbrna1.6B
  rna_encoder_freeze: false
  rna_encoder_num_attn_layers: 4
  rna_encoder_gradient_checkpointing: true

当设置 rna_encoder_lr 时，optimizer 会把 encoder 与下游模块拆成不同学习率 param group。

optim:
  lr: 2.0e-4
  rna_encoder_lr: 5.0e-6

实现依据： optimizer 分组见 symfold/utils.py:100-123；warmup/cosine scheduler 见 symfold/utils.py:126-152。

8.3 输出目录

每次训练默认写入：

outputs/<experiment.name>_<CST timestamp>/
├── logs/
│   ├── train.log
│   ├── history.json
│   └── events.out.tfevents.*
├── checkpoints/
│   ├── best.pt
│   └── last.pt
├── visualizations/
├── training_dashboard.png       # 单阶段兼容输出
└── dashboards/                  # 多阶段时每个 config 一个 dashboard
    ├── stage_01_*.png
    └── stage_02_*.png

用户当前约定是不创建运行目录之外的额外 train_*.log；请以 <run_dir>/logs/train.log 为唯一训练日志。

---

9. 结果解读与限制

1. F1 是严格 exact-pair 指标：stem 两端只偏移 1–2 nt 仍会同时计为 FP 与 FN。
2. 当前 greedy decoder 每个碱基最多一个 partner，但没有 non-crossing 约束；因此它可能放大 logits 中错误 partner 的排序。
3. 直接判别式主模型的 sequence pair feature 是对称平均，不是完整的四路 pair interaction；这正是当前 sequence-variant 泛化研究的重点。
4. structdedup098 只去除 train 内高相似结构，并不使 test 自动成为与 train 完全不相似的集合；应结合 bad-case、cluster 和外部集结果解释。
5. data/README.md、启动时使用的 YAML 副本，以及运行目录中的 logs/train.log 才是复现实验条件的最终事实来源；当前训练代码不会自动复制 YAML 到运行目录。

---

10. AI/研究助手实验操作手册

本节是给 AI 编程助手和研究协作者使用的实验 SOP。除非用户明确要求，助手只创建新配置、运行目录和分析结果，不覆盖正在使用的 YAML、checkpoint 或日志。

10.1 实验启动前的安全规则

1. 先查看 git status --short、目标 YAML 和 outputs/*/logs/train.log，确认当前是否有未提交改动或正在运行的实验。
2. 不要直接修改已有实验配置来做新实验；复制配置到 configs/dis/ablations/、configs/flowmatching/ 或其他明确的实验目录，并修改唯一的 experiment.name。
3. 不要复用正在写入的 experiment.name 或 --resume-run-dir，除非用户明确要求续训。
4. 新实验必须明确记录：数据 split、encoder checkpoint、是否冻结、设备、随机种子、训练 epoch、阈值策略和 checkpoint 路径。
5. 训练日志以 <run_dir>/logs/train.log 为准；不要在 outputs/ 顶层额外创建平行 train_*.log。

10.2 实验类型总览

统一入口按照 trainer.type 分发到两个 trainer，代码见 symfold/train.py:18-66；判别式模型类型分发见 symfold/train_supervised_pair.py:50-58。

10.3 推荐配置骨架

一个新的判别式实验至少应包含以下部分：

trainer:
  type: direct_contact_map

experiment:
  name: unique_experiment_name
  seed: 42
  output_dir: outputs
  device: cuda:0

data:
  max_length: 512
  train_datasets:
    - name: train
      path: data/bprna-spot0/train.parquet
  val_datasets:
    - name: val
      path: data/bprna-spot0/validation.parquet
  test_datasets:
    - name: test
      path: data/bprna-spot0/test.parquet

model:
  type: discriminative_contact_map
  rna_encoder_path: /absolute/path/to/encoder
  rna_encoder_freeze: true
  rna_encoder_num_attn_layers: 4
  pair_dim: 512

loss:
  pos_weight: 200.0
  focal_gamma: 1.0
  dice_weight: 0.05
  degree_weight: 0.02

optim:
  lr: 2.0e-5
  rna_encoder_lr: 5.0e-6
  weight_decay: 0.01
  scheduler: none

train:
  num_epochs: 400
  eval_every_n_epochs: 20
  test_every_n_epochs: 40
  amp: true
  amp_dtype: bfloat16

eval:
  threshold: 0.5
  min_sequence_separation: 4
  greedy_projection: true

路径和参数的实际解析位置如下：

• 数据读取、padding、length bucket：symfold/data/datasets.py:24-108,163-208；
• encoder 参数：symfold/models/rnafm_encoder.py:28-118,206-215；
• optimizer 和 scheduler：symfold/utils.py:100-152；
• checkpoint 和续训：symfold/utils.py:155-183；
• 判别式训练循环：symfold/train_supervised_pair.py:354-534；
• Flow Matching 训练循环：symfold/train_flow_matching.py:43-64,81-145,282-326。

10.4 现有配置模板如何选择

discriminative_contact_map 当前支持的 fusion_mode 为 1d_only、2d_only、simple_fusion 和 cross_gated，模型组装见 symfold/models/discriminative_contact_map_model.py:108-229。

10.5 如何开启 Multi-task Learning

Multi-task 默认关闭。只需在 model 下加入：

model:
  multitask:
    enabled: true
    pairedness:
      enabled: true
    pair_type:
      enabled: true
      num_classes: 4
      class_names: [AU, GC, GU, other]

并在 loss 下加入：

loss:
  multitask:
    pairedness_weight: 0.1
    pairedness_pos_weight: 1.0
    pairedness_focal_gamma: 0.0
    pair_type_weight: 0.2
    pair_type_class_weights: [1.0, 1.0, 1.0, 2.0]

当前实现的任务定义为：

• contact：位置对是否配对，仍是主任务和 checkpoint 选择指标；
• pairedness：每个 nucleotide 是否参与任意配对；
• pair_type：真实配对属于 AU、GC、GU 或 other。

辅助标签由 dot-bracket 和序列自动生成，见 symfold/data/dotbracket.py:61-81、symfold/data/datasets.py:57-78；联合 loss 和辅助评估见 symfold/train_supervised_pair.py:102-204。Multi-task 模型只在显式调用 return_auxiliary=True 时返回辅助 logits，默认 forward 接口保持兼容，见 symfold/models/discriminative_contact_map_model.py:189-229。

启动完整 Multi-task 实验：

python -m symfold.train \
  --config configs/dis/ablations/multitask_pair_type_cuda1_moderate2x_unfrozen_400.yaml

建议的消融顺序：

1. contact-only：不设置 model.multitask；
2. contact + pairedness：只打开 pairedness；
3. contact + pair_type：只打开 pair_type；
4. contact + pairedness + pair_type：使用完整配置。

10.6 如何运行单阶段、多阶段和续训

进入项目和环境：

cd /efs/dannyyan/symfold
source /efs/miniconda3/envs/symfold/bin/activate

单阶段：

python -m symfold.train --config configs/<experiment>.yaml

多阶段时，所有 YAML 必须使用相同的 trainer.type。每个阶段的 train.num_epochs 表示该阶段新增的 epoch 数：

python -m symfold.train \
  --config configs/phase1_frozen.yaml configs/phase2_unfrozen.yaml

如果阶段改变可训练参数或 optimizer 参数，必须明确决定是否重置 optimizer：

python -m symfold.train_supervised_pair \
  --config configs/phase2.yaml \
  --stage-reset-optimizer \
  --stage-resume-from outputs/<run>/checkpoints/last.pt

普通续训使用：

python -m symfold.train \
  --config configs/continue.yaml \
  --resume-run-dir outputs/<existing_run>

多阶段编排、阶段 dashboard 和 checkpoint 接续逻辑见 symfold/train_staged.py:1-151；命令行参数定义见 symfold/train_supervised_pair.py:32-47 和 symfold/train_flow_matching.py:43-60。

10.7 结果检查 SOP

每次实验完成后，AI 应按以下顺序检查：

1. outputs/<run>/logs/train.log：确认配置意图、设备、数据规模、loss、val/test 指标和是否早停；
2. outputs/<run>/logs/history.json：检查完整训练曲线和阶段字段；
3. outputs/<run>/checkpoints/best.pt：正式评估优先使用 validation F1 最优 checkpoint；
4. outputs/<run>/checkpoints/last.pt：续训使用最后状态；
5. outputs/<run>/dashboards/ 或 training_dashboard.png：检查 loss、F1、precision、recall 是否异常；
6. 使用 validation 选择 threshold，再在 test 上只评估一次；不要用 test 直接调 threshold。

判别式评估和 best checkpoint 保存见 symfold/train_supervised_pair.py:207-266,470-534；threshold scan 见 scripts/scan_discriminative_threshold.py:1-100。

Multi-task 实验除 contact F1/MCC 外，还应查看日志中的 pairedness_f1 和 pair_type_accuracy，但不能只凭辅助任务指标选择 checkpoint。

10.8 AI 修改或新增实验时的最小交付内容

每个新实验至少应包含：

• 一个独立 YAML；
• 唯一 experiment.name；
• 明确的 train/val/test 路径；
• 训练目标和主要改变点；
• 启动命令；
• 预期输出目录；
• 与 baseline 的对照指标；
• 若修改代码，文档中注明文件路径和行号。

不要把“修改了配置但没有启动训练”描述成实验结果；不要把 test threshold 选择结果当作正式泛化结果；不要在没有数据或日志证据时声称模型性能提升。

---

11. 相关文档

• data/README.md：各数据目录、规模、构建方式与实验边界；
• scripts/README.md：20 个脚本的用途、输入输出、保留/归档建议与删除前检查清单；
• docs/DISCRIMINATIVE_BADCASE_TEMPLATE_TRANSFER_REPORT.md：结构近邻 train/test 模板转移、序列差异与 bad case；
• docs/DISCRIMINATIVE_BADCASE_ERROR_DIAGNOSIS.md：判别式模型错误模式；
• docs/DISCRIMINATIVE_BADCASE_MISPAIR_CONTEXT_ANALYSIS.md：逐 pair 碱基与局部上下文分析；
• configs/：每个可复现实验的参数、数据路径和设备设置。