neurosnap.algos.ipsae module

neurosnap.algos.ipsae.calc_d0(L, pair_type)

Return type:

float

neurosnap.algos.ipsae.calc_d0_array(L, pair_type)

Return type:

ndarray

neurosnap.algos.ipsae.calculate_ipSAE(structure, plddt, pae_matrix, *, input_format='auto', pae_cutoff=10.0, dist_cutoff=10.0, pDockQ_cutoff=8.0, return_pml=False)

Compute ipSAE/ipTM and related interface scores for all chain pairs.

Uses a Neurosnap structure container to derive an ordered analysis list and evaluates multiple interface confidence metrics between every ordered pair of chains: ipSAE (three d0 variants), inter-chain ipTM (d0chn), pDockQ, pDockQ2, and LIS. Symmetric summaries include both per-direction asymmetry and pairwise maxima and minima.

Alignment contract

The function first derives a residue-level order from the structure (standard amino acids or nucleotides only; one representative atom per residue). If the payload shapes do not match, it falls back to token-expanded orders where non-standard residues contribute one or more heavy-atom sites. plddt with shape (N,) and pae_matrix with shape (N, N) must match whichever order is selected. input_format can be used to select a specific alignment strategy for AF3-like payloads.

type structure:

Structure

param structure:

Single-model Neurosnap Structure containing the complex.

type plddt:

ndarray

param plddt:

Per-site pLDDT aligned to the selected analysis order and normalized to [0, 100].

type pae_matrix:

ndarray

param pae_matrix:

Site-site PAE matrix in angstroms aligned to the same order.

type input_format:

str

param input_format:

Payload layout selector. Supported values are "auto", "boltz2", "chai1", and "protenix". "auto" preserves the historical shape-based fallback behavior.

type pae_cutoff:

float

param pae_cutoff:

PAE threshold in angstroms for ipSAE and counting valid pairs.

type dist_cutoff:

float

param dist_cutoff:

Distance cutoff in angstroms for interface-restricted counts.

type pDockQ_cutoff:

float

param pDockQ_cutoff:

Distance cutoff in angstroms used by pDockQ and pDockQ2 neighbor tests.

type return_pml:

bool

param return_pml:

If True, include a PyMOL coloring alias script under pml.

returns:

Dictionary containing:

by_residue

Per-direction arrays for each chain pair, including iptm_d0chn, ipsae_d0chn, ipsae_d0dom, ipsae_d0res, n0res_byres, and d0res_byres.

asym

Best single-site values per direction and the residue labels that achieve them.

max

Symmetric maxima for each metric across both directions.

min

Symmetric minima for each metric across both directions.

counts

Supporting count and d0 summaries for chain, domain, and residue granularities.

scores

Auxiliary interface-level scores including pDockQ, pDockQ2, and LIS.

params

Effective cutoff parameters used for the calculation.

pml

Optional PyMOL alias script string when return_pml is True.

residue_order

Metadata describing the selected analysis order, with names, chains, and numbers arrays.

rtype:

dict

raises ValueError:

If no usable analysis sites are found, or if plddt and pae_matrix do not match any supported alignment order.

Notes

Standard residues use representative atoms. Proteins prefer C-beta (glycine uses C-alpha, and C-alpha is also the fallback if C-beta is missing). Nucleic acids prefer C3' or C3*, then C1' or C1*, then P.

Non-standard residues are handled in multiple modes. Residue-level mode removes them when the payload length matches the raw polymer residue count. Token-expanded fallback keeps one representative site per standard residue plus heavy atoms for non-standard residues. boltz2 uses one token per non-hetero residue and expands hetero residues to heavy atoms. chai1 uses representative sites for standard residues, expands modified residues inside protein chains to heavy atoms, and gives standalone non-standard chains both a residue-level site and heavy-atom sites. protenix uses the hetero-token-expanded site order for PAE and aggregates atom-level pLDDT onto the selected sites.

Chain-type classification sets the minimum d0 value to 2.0 for pairs containing nucleic acids and 1.0 otherwise, and still applies the standard length-based d0 formula. pDockQ neighbors use pDockQ_cutoff on representative-atom distances. LIS averages (12 - PAE) / 12 over inter-chain pairs with PAE <= 12 angstroms.

neurosnap.algos.ipsae.contiguous_ranges(numbers)

Return type:

str

neurosnap.algos.ipsae.extract_interchain_metrics(res)

Extracts major inter-chain confidence metrics from a calculate_ipSAE() result.

This helper flattens the most relevant directional interface metrics into a clean, consistent structure suitable for export or downstream analysis. It includes the primary ipSAE/ipTM scores and auxiliary interface predictors like pDockQ, pDockQ2, and LIS.

Parameters:

res (dict) – Output dictionary from calculate_ipSAE(). It must contain asym and scores entries.

Returns:

Nested dictionary keyed by metric name. Returned metrics are iptm_d0chn, ipsae_d0chn, ipsae_d0dom, ipsae_d0res, pDockQ, pDockQ2, and LIS. Each metric maps chain1 -> chain2 -> float.

Return type:

dict

neurosnap.algos.ipsae.extract_minimum_interchain_metrics(res)

Extracts minimum inter-chain confidence metrics from a calculate_ipSAE() result.

This helper returns the minimum values of the ipSAE and ipTM metric families representing the worst-case interface confidence between chain pairs.

Parameters:

res (dict) – Output dictionary from calculate_ipSAE(). It must contain the min entry.

Returns:

Nested dictionary containing iptm_d0chn, ipsae_d0chn, ipsae_d0dom, and ipsae_d0res as chain1 -> chain2 -> float mappings.

Return type:

dict

neurosnap.algos.ipsae.init_pairdict_array(chains, size)

Return type:

Dict[str, Dict[str, ndarray]]

neurosnap.algos.ipsae.init_pairdict_scalar(chains, init_val=0.0)

Return type:

Dict[str, Dict[str, float]]

neurosnap.algos.ipsae.init_pairdict_set(chains)

Return type:

Dict[str, Dict[str, set]]

neurosnap.algos.ipsae.ptm_func(x, d0)

Return type:

Union[ndarray, float]