| name | analyze-ipsae |
| description | Score predicted protein complex interfaces with molecular-simulations' ipSAE — computes ipSAE, ipTM, pDockQ, pDockQ2, and LIS per chain pair from a predicted structure plus its pLDDT/PAE confidence arrays. Use when ranking or filtering AlphaFold-Multimer / Boltz / Chai docking predictions by interface confidence, or batch-scoring many predicted models. |
ipSAE interface scoring
molecular_simulations.analysis.ipSAE scores a predicted multi-chain structure
using the predictor's confidence outputs. For each chain pair it computes pDockQ,
pDockQ2, LIS, ipTM, and ipSAE, returns a Polars DataFrame, and writes
ipSAE_scores.parquet.
Usage
from molecular_simulations.analysis import ipSAE
scorer = ipSAE(
structure_file='model.pdb',
plddt_file='plddt.npz',
pae_file='pae.npz',
out_path='scores/',
skip_chains={'C'},
)
scorer.run()
print(scorer.scores)
Inputs
structure_file — the predicted model (.pdb/.cif). Chains are parsed
and classified (protein vs. nucleic) internally.plddt_file — .npz containing a plddt array (length = number of
tokens/residues). Values are auto-scaled: if they look like 0–1 fractions they
are multiplied by 100, so either scale works.pae_file — .npz containing a pae array, the residue×residue predicted
aligned error matrix (N×N).out_path — output directory (created if absent). Defaults to the parent
of plddt_file.skip_chains — set/list of chain IDs to drop before scoring (e.g. ligand
or glycan chains). Their pLDDT/PAE tokens are inferred from the remaining
tokens and removed so the matrices stay aligned to the scored chains.
Token-count alignment matters: the plddt length and pae dimensions must
correspond to the structure's residues (after skip_chains removal). Mismatches
produce wrong scores or indexing errors — confirm your predictor exports pLDDT
and PAE in the same residue/token order as the structure file.
Output
scorer.scores is a Polars DataFrame with one row per ordered chain pair plus a
max-value summary (ipSAE is asymmetric, so A→B and B→A both appear). Persist it
yourself with scorer.scores.write_parquet(...), or read the auto-written
ipSAE_scores.parquet.
Interpreting the metrics (higher = more confident interface):
- ipSAE — interface score from aligned errors (the headline metric here).
- ipTM — interface predicted TM-score.
- pDockQ / pDockQ2 — predicted DockQ-style interface quality.
- LIS — local interaction score.
Batch scoring
Loop over prediction directories and collect the parquet outputs:
from pathlib import Path
from molecular_simulations.analysis import ipSAE
for d in Path('/path/to/predictions').glob('model_*'):
ipSAE(d / 'model.pdb', d / 'plddt.npz', d / 'pae.npz', out_path=d).run()
For many models, wrap ipSAE(...).run() in a CPU @python_app and fan out with
the parsl-hpc skill, then concatenate the per-model parquet files with Polars
for ranking/filtering.
See also: analyze-sasa (per-residue solvent accessibility / interface burial).
