complexa-evaluate-pdbs

Complexa Evaluate-PDBs 技能

根据 Proteina-Complexa 内部使用的相同指标，为目录中已有的 PDB 文件评分。封装了 complexa analysis <evaluate_config> ++sample_storage_path=<dir>：CLI 会运行 evaluate 步骤（重新折叠 + 界面指标 + 单体指标），然后运行 analyze 步骤（成功阈值、多样性、通过率 CSV）。此处不要运行 complexa generate——输入文件已经存在。

此技能可实现的功能

• 使用 AF2（colabdesign）、RF3（rf3_latest）、ESMFold（esmfold）或 Boltz2（boltz2_default）重新折叠设计 PDB 文件目录。
• 计算结合体界面指标：i_pAE、min_ipAE、i_pTM、pLDDT、结合体/复合物 scRMSD。
• 计算单体可设计性（ProteinMPNN 重新设计后的 scRMSD）和协同设计性（原始序列重新折叠后的 scRMSD）。
• 对于基序输入：基序 RMSD（CA + 全原子）、基序区域可设计性/协同设计性、序列恢复率。
• 汇总为每个 PDB 对应的 CSV，以及使用 result_type 默认阈值生成的通过率摘要。

第 1 步：预检

启动重新折叠任务前，务必检查 GPU / 磁盘 / 工具二进制文件。RF3 和 ColabDesign-AF2 的体量都很大。

bash .claude/skills/_shared/scripts/preflight.sh

查看 preflight.json 中的信息：

• gpu.available 和 gpu.vram_gb——colabdesign/RF3 需要 ≥40 GB；ESMFold 在 ≥24 GB 时也能运行。
• env.missing_required——必须包含所选折叠后端对应的键：
  • colabdesign → AF2_DIR
  • rf3_latest → RF3_CKPT_PATH、RF3_EXEC_PATH
  • esmfold → 可解析的 ESMFold 权重
• tools.{foldseek,mmseqs}——aggregation.compute_diversity / compute_mmseqs_diversity 所需（两者默认均为 true）。

如果缺少任何必需键，请引导用户使用 complexa-setup 技能。

第 2 步：识别设计类型

与 complexa design 类似，评估有一个默认流程（蛋白质结合体）和两个扩展流程（配体结合体、AME）。传递给 complexa analysis 的评估配置决定其他所有事项（使用哪些指标、重新折叠器的默认设置，以及分析步骤应用哪些阈值）。

默认流程——蛋白质结合体

complexa analysis configs/evaluate_from_pdb_dir.yaml \
    ++sample_storage_path=/abs/path/to/pdbs \
    ++dataset.task_name=02_PDL1 \
    ++result_type=protein_binder \
    ++metric.binder_folding_method=colabdesign \
    ++metric.inverse_folding_model=soluble_mpnn \
    ++run_name=eval_pdl1_af2

当用户的 PDB 文件是蛋白质结合体设计（多链，结合体为最后一条链），或是来自 BindCraft / AlphaProteo / RFdiffusion 的第三方输出时，使用此流程。采用 protein_binder 的阈值（i_pAE * 31 ≤ 7.0、pLDDT ≥ 0.9、scRMSD_ca < 1.5 Å）。

扩展流程——选择匹配的配置

设计类型	使用蛋白质结合体默认配置？	评估配置	分析配置	result_type	默认后端
蛋白质结合体	是（默认）	configs/evaluate_from_pdb_dir.yaml	configs/analyze.yaml	protein_binder	colabdesign（AF2）
配体结合体（结合体 + 小分子）	使用相同评估配置，替换 3 个覆盖项	configs/evaluate_from_pdb_dir.yaml	configs/analyze.yaml	ligand_binder	rf3_latest
AME / 基序 + 配体（酶输出）	否——需要支持基序的配置	configs/evaluate_ame_from_pdb_dir.yaml	configs/analyze_motif_binder.yaml	motif_ligand_binder	rf3_latest
基序蛋白质结合体（独立类型）	否——没有 _from_pdb_dir 变体	configs/evaluate_motif_binder.yaml + ++input_mode=pdb_dir	configs/analyze_motif_binder.yaml	motif_protein_binder	colabdesign / rf3_latest

扩展为配体结合体（与默认流程使用相同的评估配置，替换三个覆盖项）：

complexa analysis configs/evaluate_from_pdb_dir.yaml \
    ++sample_storage_path=/abs/path/to/pdbs \
    ++dataset.task_name=39_7V11_LIGAND \
    ++result_type=ligand_binder \
    ++metric.binder_folding_method=rf3_latest \
    ++metric.inverse_folding_model=ligand_mpnn \
    ++run_name=eval_v11_rf3

扩展为 AME（使用不同配置；注意配体自动补全的陷阱，详见第 4 步）：

complexa analysis configs/evaluate_ame_from_pdb_dir.yaml \
    ++sample_storage_path=/abs/path/to/pdbs \
    ++dataset.task_name=M0096_1chm \
    ++run_name=eval_ame_chm

完整矩阵请参阅 reference/eval_configs.md（包括每种 result_type、每个阈值默认值、所有受支持的折叠后端，以及基序蛋白质结合体变体）。

第 3 步：收集输入信息（AskUserQuestion）

在一条批量 AskUserQuestion 中询问：

1. pdb_dir — 要评估的 PDB 文件所在目录的绝对路径。
2. 设计类型 — 蛋白质结合体 / 配体结合体 / AME（基序 + 配体）。
3. 折叠后端 — colabdesign（AF2，蛋白质结合体）、rf3_latest（配体 / AME）、boltz2_default（备选）。
4. 靶标 / 任务名称 — 必须与 configs/targets/targets_dict.yaml、configs/targets/ligand_targets_dict.yaml 或 configs/design_tasks/ame_dict_v2.yaml 中的键匹配。结合体和 AME 评估时必填（用于识别靶标参考；对于 AME，还用于识别基序 contig）。
5. 仅限 AME：确认每个 PDB 中的配体残基名称已重命名为 L:0（参见故障排除）。如果尚未重命名，请先完成重命名。

第 4 步：运行 evaluate → analyze

优先使用 complexa analysis（evaluate→analyze 链）——它会在两个步骤中复用同一份配置，并写入单个日志目录。

# Protein binder PDB dir, AF2 refold
complexa analysis configs/evaluate_from_pdb_dir.yaml \
  ++sample_storage_path=/abs/path/to/pdbs \
  ++dataset.task_name=02_PDL1 \
  ++metric.binder_folding_method=colabdesign \
  ++metric.inverse_folding_model=soluble_mpnn \
  ++result_type=protein_binder \
  ++run_name=eval_pdl1_af2

对于配体结合体，将 binder_folding_method=rf3_latest、inverse_folding_model=ligand_mpnn、result_type=ligand_binder。对于 AME，使用 configs/evaluate_ame_from_pdb_dir.yaml——完整示例请参阅 reference/eval_configs.md。

如果需要在阶段之间检查输出，请分别运行这两个步骤。上述配置由 evaluate 和 analyze 共用：

complexa evaluate configs/evaluate_from_pdb_dir.yaml ++sample_storage_path=/abs/path/to/pdbs ++run_name=eval_pdl1_af2
complexa analyze  configs/evaluate_from_pdb_dir.yaml ++run_name=eval_pdl1_af2

如果用户不确定，请先进行试运行（不会执行 GPU 任务；会打印计划执行的文件遍历和调用命令）：

complexa analysis configs/evaluate_from_pdb_dir.yaml ++sample_storage_path=/abs/path/to/pdbs ++dryrun=true

直接调用模块（调试备用方案）

complexa evaluate / analyze 是封装 Hydra 模块的子进程包装器，并附加了日志记录和并行任务拆分功能。若要附加调试器或在分析器下运行，请直接调用模块：

python -m proteinfoundation.evaluate \
    --config-path "$(realpath configs)" \
    --config-name evaluate_from_pdb_dir \
    ++sample_storage_path=/abs/path/to/pdbs \
    ++dataset.task_name=02_PDL1 \
    ++metric.binder_folding_method=colabdesign \
    ++run_name=eval_debug

对于常规的一次性运行，优先使用 complexa analysis——这样可以获得共享日志目录和单条可重放的调用命令，而不必在两次 python -m 调用中传递相同的覆盖参数。

第 5 步：解析结果

输出位于 ./evaluation_results/${run_name}/ 下：

• 每个 PDB 的指标 CSV — *_results_*.csv（每个输入 PDB × sequence_types 对应一行）。
• 通过率汇总 — 由 analyze 步骤写入（例如 res_designability.csv、res_filter_ligand_pass_*.csv、success_criteria_*.json）。
• 多样性输出 — 当 aggregation.compute_diversity=true（默认值）时生成 FoldSeek/MMseqs2 聚类文件。

向用户汇总：

• 每个 PDB 的行数，以及成功设计数 / 总数。
• 按 result_type 统计的默认阈值通过率（例如，对于 protein_binder：i_pAE*31 <= 7.0 AND pLDDT >= 0.9 AND scRMSD_ca < 1.5）。
• 按主要指标排名的前 5 个设计（蛋白质使用 i_pAE，配体使用 min_ipAE，基序结合体使用 motif_rmsd_pred_all）。

第 6 步：生成清单

记录解析后的调用信息和输出，以便重放。

python3 .claude/skills/_shared/scripts/write_manifest.py \
  --output-dir ./evaluation_results/${run_name} \
  --command "complexa analysis configs/evaluate_from_pdb_dir.yaml ++sample_storage_path=<dir> ++dataset.task_name=<task> ++metric.binder_folding_method=<backend> ++run_name=<run>" \
  --skill complexa-evaluate-pdbs \
  --out ./eval_manifest.json

清单固定记录：解析后的配置、git SHA、ckpt SHA-256 值、结果 CSV 路径，以及用户声明的 result_type，以便重放。

最常用的覆盖项

覆盖项	效果
++sample_storage_path=<dir>	要评估的 PDB 所在目录（必填）。
++dataset.task_name=<name>	目标 / AME 任务名称（binders、AME）。解析目标 PDB 和 contigs。
++metric.binder_folding_method=<backend>	colabdesign / rf3_latest / boltz2_default。
++metric.inverse_folding_model=<model>	protein_mpnn / soluble_mpnn / ligand_mpnn。
++metric.sequence_types=[self,mpnn,mpnn_fixed]	要重新折叠的序列类型。
++metric.num_redesign_seqs=N	ProteinMPNN/LigandMPNN 重新设计的数量。
++metric.compute_pre_refolding_metrics=true	为输入结构添加生物信息学/TMOL/HBPLUS 指标。
++metric.keep_folding_outputs=true	保存重新折叠后的 PDB（文件较大，但便于检查）。
++result_type=<type>	覆盖默认阈值：protein_binder / ligand_binder / motif_protein_binder / motif_ligand_binder。
++aggregation.success_thresholds.<…>	收紧或放宽特定阈值（参见 reference/eval_configs.md）。
++eval_njobs=N	评估步骤使用的并行 GPU 数量。
++dryrun=true	规划但不运行任何折叠。
++file_limit=N	限制输入 PDB 数量（适合首次快速冒烟测试）。

硬件

• GPU：至少需要 1 个 CUDA GPU。AF2（colabdesign）和 RF3（rf3_latest）需要至少 40 GB 显存（A100/H100/L40S）。ESMFold 可在至少 24 GB 显存的设备上运行。可通过 ++eval_njobs=N 使用多 GPU。
• CPU/磁盘：默认使用 24 个 CPU（ncpus_: 24）。每个重新折叠后的 PDB 和中间输出约为 1–5 MB；对数千个输入启用 keep_folding_outputs=true 可能会占用数十 GB 空间。
• 各后端的运行时间和显存表请参见 _shared/reference/hardware.md。

故障排除

• Error: Config file not found — 路径相对于仓库根目录；运行 complexa analysis 前，请先 cd 到仓库目录。
• compute_motif_binder_metrics=True 但 result_type=protein_binder — result_type 和底层的 compute_*_metrics 必须一致。对于 AME 输入，请使用 configs/evaluate_ame_from_pdb_dir.yaml，不要修改 evaluate_from_pdb_dir.yaml。
• AME PDB 出现 RF3 形状错误 — RF3 会尝试根据 CCD 自动补全配体原子。评估前，请将每个输入 PDB 中的配体残基重命名为 L:0；参见 README.md 中的代码片段（atom_array.res_name[ligand_mask] = "L:0"）。
• 多样性步骤失败（foldseek not found） — FOLDSEEK_EXEC 不在 PATH 中。请修正 .env（推荐），或禁用相关功能：++aggregation.compute_diversity=false ++aggregation.compute_mmseqs_diversity=false。
• 所有通过率均为 0% — 检查 binder_folding_method 是否与目标类型匹配（配体使用 RF3，蛋白质使用 AF2），并确认 ++dataset.task_name 解析到正确的参考 PDB（运行 complexa target show <name> 进行验证）。

参考资料

完整的评估/分析配置矩阵、所有受支持的 result_type、各阈值默认值，以及三个完整示例（蛋白质结合体 / 配体结合体 / AME），请参见 reference/eval_configs.md。