IPSAE

Dunbrack Lab

License: IPSAE is open source and free for academic and commercial use under an MIT license. Please refer to the license for full terms.

Proto is not affiliated with the Dunbrack Lab. This toolkit is open source and builds on the implementation produced by this organization. Product names, logos, and trademarks are the property of their respective owners.

GitHub GitHub Preprint Preprint Cite Cite Tool Source Tool Source Open as Notebook Open as Notebook Open on Proto Open on Proto

DunbrackLab/IPSAE

View repo

R=es ipSAE loquuntur: What’s wrong with AlphaFold’s ipTM score and how to fix it

Roland L. Dunbrack

bioRxiv (2025)

Read preprint

@article{dunbrack_2025_ipsae,
  title={R\={e}s ipSAE loquuntur: What's wrong with AlphaFold's ipTM score and how to fix it},
  author={Dunbrack, Roland L.},
  journal={bioRxiv},
  year={2025},
  doi={10.1101/2025.02.10.637595},
  url={https://www.biorxiv.org/content/10.1101/2025.02.10.637595v2},
}

@article{zhu_2023_pdockq2,
  title={Evaluation of AlphaFold-Multimer prediction on multi-chain protein complexes},
  author={Zhu, Wensi and Shenoy, Aditi and Kundrotas, Petras and Elofsson, Arne},
  journal={Bioinformatics},
  volume={39},
  number={7},
  pages={btad424},
  year={2023},
  doi={10.1093/bioinformatics/btad424},
}

@article{bryant_2022_pdockq,
  title={Improved prediction of protein-protein interactions using AlphaFold2},
  author={Bryant, Patrick and Pozzati, Gabriele and Elofsson, Arne},
  journal={Nature Communications},
  volume={13},
  number={1},
  pages={1265},
  year={2022},
  doi={10.1038/s41467-022-28865-w},
}

@article{kim_2024_lis,
  title={Enhanced Protein-Protein Interaction Discovery via AlphaFold-Multimer},
  author={Kim, Ah-Ram and Hu, Yanhui and Comjean, Aram and Rodiger, Jonathan and Mohr, Stephanie E. and Perrimon, Norbert},
  journal={bioRxiv},
  year={2024},
  doi={10.1101/2024.02.19.580970},
  url={https://www.biorxiv.org/content/10.1101/2024.02.19.580970v1},
}

Copy citation

evo-design/proto-tools/proto_tools/tools/structure_scoring/ipsae

View source

Open Notebook

Open notebook

IPSAE Interface Scoring

Toolkit contributors

Function	Description
`run_ipsae_scoring()`	Score a cofolded protein complex with IPSAE (Dunbrack 2025), computing ipSAE, pDockQ2, LIS, pDock…	Docs Source

Background

IPSAE (Dunbrack, 2025) is a single program that computes five interface-quality scores for a cofolded protein complex from the structure together with its per-residue pLDDT and pairwise PAE matrix. The primary metric, ipSAE, recomputes an interface pTM-style score from PAE alone while replacing the chain-length-based reference distance with an adaptive reference distance derived from the size of the well-predicted interface. The published benchmark reports that ipSAE separates true and false complexes more efficiently than AlphaFold’s interface pTM, in particular for domain-domain and domain-peptide interactions inside larger constructs that contain disordered or accessory regions. Alongside ipSAE the program computes four additional interface-quality scores that the literature has converged on for cofolded complex assessment. The pDockQ2 score (Zhu et al., 2023) estimates the quality of each interface in a multimer from interface pLDDT and PAE-derived signal. The pDockQ score (Bryant et al., 2022) is an earlier variant that uses interface pLDDT and the logarithm of the number of contacts. The local interaction score (Kim et al., 2024) reports the fraction of interface residues with low mean cross-chain PAE. The interface pTM (iptm_d0chn) reports the original AlphaFold-style interface pTM recomputed from PAE with the chain-length reference distance.

Learning Resources

DunbrackLab/IPSAE (Dunbrack Lab, Fox Chase Cancer Center). Official repository and the source of the reference scoring script that this toolkit invokes.

Tools

IPSAE Interface Scoring (`ipsae-scoring`)

Scores a cofolded protein complex by computing ipSAE, pDockQ2, LIS, pDockQ, and interface pTM for a designated binder chain against one or more target chains. The tool takes a Structure with per-residue pLDDT in the B-factor column and the PAE matrix attached at structure.metrics["pae"], runs the IPSAE scoring program, and returns the headline scores together with a full per-chain-pair breakdown.

API Reference

Source

Input: IPSAEScoringInput

Structure

required

Cofolded complex with per-residue pLDDT in the B-factor column and the PAE matrix attached at structure.metrics['pae'] as a square list[list[float]].

Show Structure

string

required

Raw structure content in PDB or CIF format.

string

Format of the content string (auto-detected if omitted).

BFactorType

default:"unspecified"

What the B-factor column represents.

string

Optional source identifier (filepath or tool name).

Metrics

Associated metrics (e.g., pLDDT, pTM scores, per-chain lists, pairwise matrices). None values are stripped at construction.

SingleChainSelection

required

Single-character chain ID of the binder.

Show SingleChainSelection

string

required

The selected chain ID.

ChainSelection

required

Target chain ID(s).

Show ChainSelection

List[string]

required

Chain IDs in the selection.

Source

Config: IPSAEScoringConfig

number

default:"10.0"

PAE cutoff in Å for interface residue detection.

number

default:"10.0"

CA-CA distance cutoff in Å for contact detection.

integer

default:"0"

Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). True is coerced to 1 and False to 0.

string

default:"cpu"

Device to run the tool on.

integer

default:"3600"

Maximum execution time in seconds. None waits indefinitely.

integer

Random seed. When set, tools run reproducibly up to small GPU float noise (see BaseToolOutput.approx_equal), and the seed participates in cache keys. When None, cacheable seed-sensitive tools skip cache until seeded.

Source

Output: IPSAEScoringOutput

IPSAEMetrics

required

Scalar metrics plus per-chain-pair breakdown.

Show IPSAEMetrics

List[ChainPairScores]

Full per-chain-pair breakdown.

string

Name of the metric that best summarizes the result overall (e.g. "avg_plddt" for AlphaFold2). Used by downstream UI and reporting to pick a headline value.

string

Concrete Metrics subclass tag; enables typed reconstruction after a serialization round-trip.

Metrics

Metric	Type	Range	Availability
`ipsae`	float	0.0 to 1.0	always
`pdockq2`	float	0.0 to 1.0	always
`lis`	float	0.0 to 1.0	always
`pdockq`	float	0.0 to 1.0	always
`iptm_d0chn`	float	0.0 to 1.0	always

Applications

This tool is appropriate for ranking and filtering cofolded complexes from structure-prediction tools such as AlphaFold 3, Chai-1, Boltz, or Protenix. Representative applications include scoring candidate protein binders from a design pipeline, identifying the most promising poses in a multi-chain prediction ensemble, and any analysis that benefits from multiple complementary interface-quality scores in a single call rather than running several scoring programs in sequence.

Usage Tips

The PAE matrix is required and must be attached at structure.metrics["pae"] as a square list[list[float]]. The dimension should match the total residue count of the structure. The input is rejected when the matrix is missing or not square.
Per-residue pLDDT must be supplied via the B-factor column. Structure predictors in proto-tools return the correct b_factor_type automatically, and Structure.from_file() auto-detects it for AlphaFold DB and ModelArchive files. For manually provided structures from other sources, pass b_factor_type=BFactorType.PLDDT (raw 0 to 100) or BFactorType.NORMALIZED_PLDDT (0 to 1) explicitly. The input is rejected when b_factor_type is any other value, since pDockQ and pDockQ2 would otherwise be computed incorrectly.
Missing or duplicated chains are rejected. The binder chain must not also appear in target_chains, and every requested chain must be present in the structure. Single-character chain identifiers are also required because IPSAE reads PDB-format input. Multi-character mmCIF chain labels should be shortened with Structure.to_pdb_with_chain_mapping() before scoring.
The tool implementation does not check that the PAE matrix is aligned with the structure residue by residue. It only confirms the matrix is square and two-dimensional. The caller is responsible for ensuring the PAE rows and columns match the residue order in the structure. A misaligned PAE matrix produces silently meaningless scores rather than an error.
The top-level scores report the symmetric maximum value for the binder-target interface. The full directional and symmetric breakdown for every chain pair is available on result.metrics.chain_pair_results. When no symmetric pair matches the binder-target combination, the tool raises a ValueError listing the available chain pairs so the chain labels can be corrected.
pae_cutoff and distance_cutoff control the interface definition. Both default to 10.0 Å. Lower values define a tighter interface and reduce the number of residues contributing to each score. Use a tighter cutoff when comparing interfaces of similar overall size or when assessing buried interfaces.
An empty interface returns zeros for every score. When no residues fall within both cutoffs across the binder-target chain pair, every metric is 0.0. Verify the chain identifiers and cutoff values before interpreting an all-zero result as a poor interface.

Toolkit Notes

These apply to every IPSAE tool in this toolkit (ipsae-scoring).

Outputs are returned as typed metric objects. Each IPSAEMetrics result carries the five top-level scores, the chain_pair_results breakdown for every chain pair, and the headline primary_metric (ipsae). Results can be exported to JSON through the standard export method.

Example notebook: See the full working example for a copy-paste-ready walkthrough.

Infrastructure Guides

The following guides cover how to run tools efficiently and at scale.

Tool Persistence

Keep a tool’s model warm across calls instead of reloading it every invocation.

Device Management

How GPUs are allocated to tools and how to target specific devices.

Parallel Execution

Fan a batch of inputs out across multiple GPUs.

Tools

Guides

Tool Catalog

Concepts

Implementing a Tool

Background

Learning Resources

Tools

IPSAE Interface Scoring (`ipsae-scoring`)

API Reference

Applications

Usage Tips

Toolkit Notes

Infrastructure Guides

Tool Persistence

Device Management

Parallel Execution

​Background

​Learning Resources

​Tools

​IPSAE Interface Scoring (ipsae-scoring)

​API Reference

​Applications

​Usage Tips

​Toolkit Notes

​Infrastructure Guides

Tool Persistence

Device Management

Parallel Execution

Background

Learning Resources

Tools

IPSAE Interface Scoring (`ipsae-scoring`)

API Reference

Applications

Usage Tips

Toolkit Notes

Infrastructure Guides