complexa-evaluate-pdbs

Complexa Evaluate-PDBs スキル

既存の PDB ファイルが格納されたディレクトリを、Proteina-Complexa が内部で使用するものと同じ指標で評価します。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＋全原子）、モチーフ領域の設計可能性／共設計可能性、配列回復率を計算します。
• デフォルトの result_type しきい値を使用して、PDB ごとの CSV と合格率の集計を作成します。

ステップ 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 と同様に、評価にはデフォルトのフロー（タンパク質バインダー）と、2 つの拡張（リガンドバインダー、AME）があります。complexa analysis に渡す評価設定によって、その他すべて（対象となる指標、再フォールディングのデフォルト設定、analyze ステップで適用するしきい値）が決まります。

デフォルト — タンパク質バインダー

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 Å）を使用します。

拡張 — 該当する設定を選択

設計タイプ	タンパク質バインダーのデフォルトを使用するか	評価設定	Analyze 設定	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

リガンドバインダーへの拡張（デフォルトと同じ評価設定を使用し、3 つのオーバーライドを置き換える）：

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

全体の一覧（すべての result_type、各しきい値のデフォルト、サポートされているすべてのフォールディングバックエンド、モチーフタンパク質バインダー版）については、reference/eval_configs.md を参照してください。

ステップ 3：入力情報を収集する（AskUserQuestion）

AskUserQuestion でまとめて質問します。

1. pdb_dir — 評価する PDB が格納されたディレクトリの絶対パス。
2. 設計タイプ — protein binder／ligand binder／AME（モチーフ＋リガンド）。
3. フォールディングバックエンド — colabdesign（AF2、protein binders）、rf3_latest（ligand／AME）、boltz2_default（代替）。
4. ターゲット／タスク名 — configs/targets/targets_dict.yaml、configs/targets/ligand_targets_dict.yaml、または configs/design_tasks/ame_dict_v2.yaml のキーと一致する必要があります。バインダーと AME の評価では必須です（ターゲットの参照情報を特定するために必要で、AME ではモチーフのコンティグも特定します）。
5. AME のみ：すべての PDB でリガンドの残基名がすでに L:0 に変更されていることを確認してください（「トラブルシューティング」を参照）。変更されていない場合は、先に変更してください。

ステップ 4：evaluate → analyze を実行する

complexa analysis（evaluate→analyze の連続処理）を優先してください。両方のステップで同じ設定を再利用し、ログディレクトリも 1 つだけ作成します。

# 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 を優先してください。同じオーバーライドを 2 つの python -m 呼び出しに渡す必要がなく、共有ログディレクトリと再実行可能な呼び出しを 1 つ利用できます。

ステップ 5：結果を解析する

出力は ./evaluation_results/${run_name}/ 以下に保存されます。

• PDB ごとのメトリクス CSV — *_results_*.csv（入力 PDB 1 件 × sequence_types ごとに 1 行）。
• 合格率の要約 — 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とコンティグを特定します。
++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：CUDA GPUが1基以上必要です。AF2（colabdesign）とRF3（rf3_latest）には40 GB以上のVRAM（A100／H100／L40S）が必要です。ESMFoldは24 GB以上で動作します。++eval_njobs=Nで複数GPUを利用できます。
• CPU／ディスク：デフォルトではCPUを24基使用します（ncpus_: 24）。再フォールディング後のPDBと中間出力は、それぞれ約1～5 MBです。入力が数千件ある場合、keep_folding_outputs=trueを指定すると数十GBに膨らむことがあります。
• バックエンドごとの実行時間とVRAMの一覧は、_shared/reference/hardware.mdを参照してください。

トラブルシューティング

• Error: Config file not found — パスはリポジトリのルートからの相対パスです。complexa analysisを実行する前に、リポジトリに移動してください。
• compute_motif_binder_metrics=Trueだがresult_type=protein_binder — result_typeと、基盤となるcompute_*_metricsの設定を一致させる必要があります。evaluate_from_pdb_dir.yamlを変更するのではなく、AMEの入力にはconfigs/evaluate_ame_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、しきい値ごとのデフォルト値、3つの具体例（タンパク質バインダー／リガンドバインダー／AME）については、reference/eval_configs.mdを参照してください。