用途
RFD4-Proteína Evaluate 用于对已经存在于磁盘上的蛋白质设计结构进行事后（post-hoc）打分，而无需重新运行生成流程。evaluate.py 与生成阶段共享完全相同的指标栈和 Hydra 配置，因此任何 metrics_tags 或自定义指标配置在在线（生成时）和离线（事后）场景下行为一致。该技能重点解决两件事：一是为设计任务选择正确的指标标签，并了解哪些标签会静默依赖 AF3 容器；二是在读取结果之前，将并行的逐作业 CSV 聚合为一张表。
所有命令都从仓库根目录（包含 .project-root 的目录）运行。所有参数均为 Hydra 的 key=value 形式，而非 --key value。
在线与事后评估的区别
- 在线（生成期间）：向 generate.py 传入 metrics_tags，指标在每个设计完成后立即运行，并写入 CIF 旁边的 per_example_metrics.csv。适合已经明确要测量什么的情况。参见 rfd4-proteina-generate。
- 事后（本技能）：对已生成的 CIF 文件夹打分，补上忘记开启的指标，或用不同标签重新打分。配置相同，输出相同。
前置条件
需要已配置的模型环境和已有的设计 CIF 文件。重折叠（refolding）还需要其选定的 oracle 后端；多样性聚类需要 FoldSeek。
模型命令、配置和上游手册使用用户在 RFPROTEINA_ROOT 处选定的模型检出（checkout）。本目录包含的是技能，而非该检出。在辅助示例中，当目录与模型检出分离时，需将 open-models-skills/rfd4-proteina/<name>/... 解析为其绝对安装路径。
输入
必需：用户的结构目录、指标标签、输出目录。可选：任务 CSV、自定义指标配置、聚类。阈值应读取实际使用的配置，而非无关的默认值。
使用方式
第 1 步 — 对结构文件夹运行 evaluate.py
rfd4-evaluate \
inputs=/path/to/structures \
metrics_tags='[design]' \
out_dir=/path/to/eval_output
- inputs：递归扫描 CIF 类文件的目录。必需。要评估单个结构，请将其放入专用目录。
- metrics_tags：方括号引用的 Hydra 列表，如 '[design]'、'[unconditional_refolding]'，或多个，如 '[design, unconditional_refolding]'。必需（configs/evaluate.yaml 中无默认值）。
- out_dir：必需；evaluate.py 没有可推导的运行目录。结果写入 out_dir/evaluation_metrics/。
- task_csv=<csv>：可选；当不同结构需要不同的标签/通过标准处理时，提供包含 designed_structure_path 和 task 列的 CSV。否则所有结构以相同方式打分。
设计标签与重折叠标签是独立的命名空间——若希望两者都运行，需同时传入两个系列。完整标签表和语义见 references/metrics.md。
调度器意图
对于任何批处理运行，在构造命令前先阅读选定的 scripts/.user_info_<cluster> 和启动器。保留用户的分区、账户、QoS/优先级选项、GPU 请求、运行时间、内存和 CPU 设置。仅在用户明确要求时使用资源覆盖。提交前说明解析后的调度器值；验证工作流时使用 dry-run 或不提交的测试。
第 2 步 — 跨并行作业聚合
大型评估会拆分为 SLURM 数组作业；每个作业写入自己的 per_example_metrics_job{N}.csv。所有作业完成后，执行：
python -m rfproteina.inference_utils.aggregate_metrics /path/to/eval_output/evaluation_metrics/
指标目录是第一个位置参数。该命令拼接逐样本作业 CSV，写入 aggregated_metrics.csv 和 per_task_metrics.csv，并将各作业文件移入 individual_job_results/。聚合会移动这些源 CSV，并可能替换已有的聚合输出。重复执行前请保留先前结果；使用新的 --output_dir 生成单独的聚合（源 CSV 仍会被移动）。标志：--output_dir <dir> 写入其他位置，--cluster_with_foldseek 进行多样性聚类（第 3 步）。使用 scripts/launch_evaluate.sh（或 launch_generate.sh）时，该聚合会作为依赖的 SLURM 作业自动运行——默认开启 foldseek；用 --no-foldseek 禁用。
第 3 步 — FoldSeek 多样性聚类（可选）
python -m rfproteina.inference_utils.aggregate_metrics /path/to/eval_output/evaluation_metrics/ \
--cluster_with_foldseek
添加 foldseek_cluster_id 列，以便按任务统计结构上不同的设计数量。聚类范围限定为设计链（chain_of_interest，从条件注释中识别并存储在指标 CSV 中），TM-score 阈值为 0.5。活动环境中的 FOLDSEEK_EXEC 必须指向 FoldSeek 可执行文件。事后 evaluate.py 会写入其聚合步骤所需的设计链 CIF。生成时聚合则要求 save_chain_of_interest=true，以便生成过程写入这些链 CIF。
第 4 步 — 自定义指标（不编辑受跟踪文件）
两个自定义指标目录均被 git 忽略，因此在此添加的内容永远不会被提交：
- src/rfproteina/metrics/custom_metrics/ — 你的 Python Metric 子类。
- configs/metrics/custom_metrics/all_custom_metrics.yaml — Hydra 注册（首次运行时由 setup.sh 生成脚手架；# @package metrics）。
它们会被自动识别（无需额外标志），结果写入 per_example_metrics.csv，并以配置键为前缀（例如 residue_count.n_residues）。通常甚至不需要新的 Python——一个现成但需选择启用的类（界面 ddG、原子对距离约束、电荷互补性等）只需几行 YAML。参见 docs/workflow/custom-metrics.md 和 references/metrics.md。
AF3 容器注意事项
重折叠指标（refolded_backbone_rmsd、refolded_motif_*_rmsd 等）和重折叠 oracle（oracle、oracle_ppi、oracle_dna——AF3 变体）会运行 AF3 结构预测器，而后者仅在通过集群环境文件配置的 apptainer/docker 容器内运行。普通（非重折叠）设计指标如 [design] 不需要容器。如果在没有容器的情况下请求重折叠标签，这些指标会静默不运行——你不会得到 oracle 列，也不会报错。请先配置容器（参见 rfd4-proteina-setup、RFD4-Proteína 安装指南），或使用 scripts/launch_evaluate.sh ...，它会自动接入容器。
指标标签参考
导入的指标、oracle、通过标准和过滤器条目，其类别与配置路径，标签语义（required_tags_any / required_tags_all / prohibited_tags），以及需选择启用的类，均以紧凑表格形式列于 references/metrics.md。完整权威来源是 docs/workflow/metrics.md。
输出
| 文件 | 写入者 | 内容 |
|---|---|---|
| per_example_metrics.csv（或 per_example_metrics_job{N}.csv） | evaluate.py / generate.py | 每个设计一行；指标列以配置键为前缀 |
| aggregated_metrics.csv | aggregate_metrics | 所有逐样本行拼接；使用 --cluster_with_foldseek 时添加 foldseek_cluster_id |
| per_task_metrics.csv | aggregate_metrics | 按任务汇总（通过率、均值、聚类数） |
| individual_job_results/ | aggregate_metrics | 原始逐作业 CSV，被移入此处 |
故障排除
| 症状 | 修复 |
|---|---|
| 无 oracle / 重折叠列，也无错误 | 重折叠需要 AF3 容器——配置它或使用 launch_evaluate.sh；普通 [design] 指标不需要容器 |
| metrics_tags 指标被静默跳过 | 标签按集合交集匹配；传入指标声明的确切标签字符串（design 与 refolding 是独立命名空间） |
| foldseek 聚类无效果 | 设置 FOLDSEEK_EXEC；生成时聚合还需在生成前设置 save_chain_of_interest=true |
| out_dir 缺失 / 配置错误 | out_dir 对 evaluate.py 是强制的；没有可推断的运行目录 |
| Hydra "could not override" / 参数被忽略 | 使用 key=value，而非 --key value；列表值加引号，如 metrics_tags='[design]' |
| 只有作业 CSV，没有聚合 | 所有作业完成后运行 python -m rfproteina.inference_utils.aggregate_metrics <metrics_dir> |
更深入细节：指标参考 · docs/workflow/metrics.md · docs/workflow/custom-metrics.md · Evaluating Results。
限制
缺少重折叠列意味着结果未被测量。指标和通过率的解释取决于确切的模型修订版、提供者和标准配置。
示例
第 1 步命令使用 design 标签对已有 CIF 打分。第 2 步和第 3 步展示了带与不带 FoldSeek 的聚合；请选择所请求的操作和全新的结果目标位置。