Skill Complexa Evaluate-PDBs

Score un répertoire de fichiers PDB pré-existants selon les mêmes métriques utilisées en interne par Proteina-Complexa. Encapsule complexa analysis <evaluate_config> ++sample_storage_path=<dir> : le CLI exécute l'étape evaluate (refold + métriques d'interface + métriques de monomère) puis l'étape analyze (seuils de succès, diversité, CSVs de taux de réussite). Ne lancez pas complexa generate ici — les entrées existent déjà.

Ce que cette skill permet

• Re-plier un répertoire de PDBs conçus avec AF2 (colabdesign), RF3 (rf3_latest), ESMFold (esmfold), ou Boltz2 (boltz2_default).
• Calculer les métriques d'interface du binder : i_pAE, min_ipAE, i_pTM, pLDDT, binder/complex scRMSD.
• Calculer la désignabilité de monomère (ProteinMPNN-redesigned scRMSD) et la co-désignabilité (original sequence refold scRMSD).
• Pour les entrées motif : RMSD motif (CA + all-atom), désignabilité/co-désignabilité région-motif, récupération de séquence.
• Agréger en CSVs par PDB plus résumés de taux de réussite en utilisant les seuils par défaut pour le result_type.

Étape 1 : Pré-vol

Vérifiez toujours GPU / disque / binaires outils avant de lancer un job refold. RF3 et ColabDesign-AF2 sont volumineux.

bash scripts/preflight.sh

Surface depuis preflight.json :

• gpu.available et gpu.vram_gb — colabdesign/RF3 ont besoin de ≥40 GB ; ESMFold tolère ≥24 GB.
• env.missing_required — doit inclure les clés pour le backend de repliement choisi :
  • colabdesign → AF2_DIR
  • rf3_latest → RF3_CKPT_PATH, RF3_EXEC_PATH
  • esmfold → poids ESMFold résolubles
• tools.{foldseek,mmseqs} — requis par aggregation.compute_diversity / compute_mmseqs_diversity (tous deux par défaut true).

Si une clé requise manque, dirigez l'utilisateur vers la skill complexa-setup.

Étape 2 : Identifier le type de conception

Comme complexa design, l'évaluation a un flux par défaut (binder protéine) et deux extensions (binder ligand, AME). Le config d'évaluation que vous passez à complexa analysis décide tout le reste (quelles métriques, quels défauts refolder, quels seuils l'étape analyze applique).

Par défaut — binder protéine

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

Utilisez ceci quand les PDBs de l'utilisateur sont des conceptions de binder protéine (multi-chaîne, le binder est la dernière chaîne) ou des outputs tiers de BindCraft / AlphaProteo / RFdiffusion. Récupère les seuils pour protein_binder (i_pAE * 31 ≤ 7.0, pLDDT ≥ 0.9, scRMSD_ca < 1.5 Å).

Extensions — choisir le config correspondant

Extension vers ligand binder (même config evaluate que défaut, trois changements d'overrides) :

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

Extension vers AME (config différent ; piège d'auto-complétion ligand — voir Étape 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

Voir references/eval_configs.md pour la matrice complète (chaque result_type, chaque seuil par défaut, chaque backend de repliement supporté, variante motif-protein-binder).

Étape 3 : Rassembler les entrées (AskUserQuestion)

Demandez dans une seule AskUserQuestion par lot :

1. pdb_dir — chemin absolu du répertoire de PDBs à évaluer.
2. Type de conception — protein binder / ligand binder / AME (motif + ligand).
3. Backend de repliement — colabdesign (AF2, binders protéines), rf3_latest (ligand / AME), boltz2_default (alternative).
4. Cible / nom de tâche — doit correspondre à une clé dans configs/targets/targets_dict.yaml, configs/targets/ligand_targets_dict.yaml, ou configs/design_tasks/ame_dict_v2.yaml. Requis pour l'évaluation binder + AME (nécessaire pour identifier la référence cible et, pour AME, les contigs motif).
5. AME uniquement : confirmer que le nom du résidu ligand est déjà renommé en L:0 dans chaque PDB (voir Dépannage). Sinon, effectuez d'abord ce renommage.

Étape 4 : Lancer evaluate → analyze

Préférez complexa analysis (la chaîne evaluate→analyze) — il réutilise le même config pour les deux étapes et écrit un seul répertoire de log.

# Protein binder PDB dir, refold AF2
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

Pour les ligand binders, changez binder_folding_method=rf3_latest, inverse_folding_model=ligand_mpnn, result_type=ligand_binder. Pour AME utilisez configs/evaluate_ame_from_pdb_dir.yaml — voir references/eval_configs.md pour des exemples complets fonctionnels.

Si vous avez besoin d'inspecter la sortie entre les étapes, lancez-les séparément. Les configs ci-dessus sont partagés entre evaluate et 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

Faites un dry-run d'abord si l'utilisateur est incertain (aucun travail GPU n'arrive ; la marche sur fichiers planifiée + invocation s'affiche) :

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

Invocation de module directe (fallback débogage)

complexa evaluate / analyze sont des wrappers subprocess autour des modules Hydra avec logging + parallélisation de répartition de jobs. Pour attacher un débogueur ou lancer sous un profileur, invoquez le module directement :

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

Pour des runs normaux one-shot préférez complexa analysis — vous obtenez le répertoire de log partagé et une seule invocation rejouable, au lieu d'avoir à passer les mêmes overrides à travers deux appels python -m.

Étape 5 : Parser les résultats

La sortie se trouve sous ./evaluation_results/${run_name}/ :

• CSV métriques par PDB — *_results_*.csv (une ligne par PDB entrée × sequence_types).
• Résumés de taux de réussite — écrits par l'étape analyze (ex. res_designability.csv, res_filter_ligand_pass_*.csv, success_criteria_*.json).
• Sortie diversité — fichiers cluster FoldSeek/MMseqs2 quand aggregation.compute_diversity=true (défaut).

Résumez à l'utilisateur :

• Nombre de lignes par PDB et nombre de conceptions réussies vs total.
• Taux de réussite du seuil par défaut par result_type (ex. pour protein_binder : i_pAE*31 <= 7.0 AND pLDDT >= 0.9 AND scRMSD_ca < 1.5).
• Top 5 conceptions par métrique primaire (i_pAE pour protéine, min_ipAE pour ligand, motif_rmsd_pred_all pour binders motif).

Étape 6 : Émettre manifest

Capturez l'invocation résolue + outputs pour replay.

python3 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

Le manifest épingle : config résolue, git SHA, ckpt SHA-256s, chemins CSV de résultats, et le result_type énoncé par l'utilisateur pour replay.

Overrides les plus courants

Matériel

• GPU : ≥1 GPU CUDA. AF2 (colabdesign) et RF3 (rf3_latest) ont besoin de ≥40 GB VRAM (A100/H100/L40S). ESMFold tourne sur ≥24 GB. Multi-GPU via ++eval_njobs=N.
• CPU/disque : 24 CPUs par défaut (ncpus_: 24). Chaque PDB replié + sortie intermédiaire est ~1–5 MB ; keep_folding_outputs=true peut gonfler à des dizaines de GB pour des milliers d'entrées.
• Voir references/hardware.md pour tables wall-clock et VRAM par backend.

Dépannage

• Error: Config file not found — les chemins sont relatifs à la racine du repo ; cd au repo avant d'invoquer complexa analysis.
• compute_motif_binder_metrics=True mais result_type=protein_binder — result_type et les compute_*_metrics sous-jacents doivent s'accorder. Utilisez configs/evaluate_ame_from_pdb_dir.yaml pour entrées AME plutôt que de muter evaluate_from_pdb_dir.yaml.
• Erreurs de forme RF3 sur PDBs AME — RF3 essaie d'auto-compléter les atomes ligand depuis CCD. Renommez le résidu ligand en L:0 dans chaque PDB entrée avant évaluation ; voir le snippet dans README.md (atom_array.res_name[ligand_mask] = "L:0").
• Étape diversité échoue (foldseek not found) — FOLDSEEK_EXEC pas sur PATH. Soit fixez .env (préféré) soit désactivez : ++aggregation.compute_diversity=false ++aggregation.compute_mmseqs_diversity=false.
• Tous taux de réussite sont 0% — vérifiez que binder_folding_method correspond au type cible (RF3 pour ligand, AF2 pour protéine) et que ++dataset.task_name résout au bon PDB référence (complexa target show <name> pour vérifier).

Référence

Matrice config evaluate/analyze complète, chaque result_type supporté, defaults par seuil, et trois exemples fonctionnels (protein binder / ligand binder / AME) : voir references/eval_configs.md.