neurosnap.algos.ipsae module#

neurosnap.algos.ipsae.calc_d0(L, pair_type)[source]#

Return type:: float

neurosnap.algos.ipsae.calc_d0_array(L, pair_type)[source]#

Return type:: ndarray

neurosnap.algos.ipsae.calculate_ipSAE(protein, plddt, pae_matrix, *, model=None, pae_cutoff=10.0, dist_cutoff=10.0, pDockQ_cutoff=8.0, return_pml=False)[source]#

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

Uses a Neurosnap Protein 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 structure (standard amino acids / nucleotides only; one representative atom per residue). If payload shapes do not match, it falls back to a token-expanded order where non-standard residues contribute one site per heavy atom. plddt (N,) and pae_matrix (N, N) must match whichever order is selected.

Parameters:

protein (Protein) – Neurosnap Protein containing the structure.
plddt (ndarray) – Per-site pLDDT aligned to the selected analysis order (normalized to [0-100] NOT [0-1]).
pae_matrix (ndarray) – Site-site PAE (Å) aligned to the same order.
model (Optional[int]) – Structure model ID to analyze. Defaults to the first model.
pae_cutoff (float) – PAE threshold (Å) for ipSAE and counting “valid” pairs.
dist_cutoff (float) – Distance cutoff (Å) for interface-restricted counts.
pDockQ_cutoff (float) – Distance cutoff (Å) used by pDockQ/pDockQ2 neighbor tests.
return_pml (bool) – If True, returns a PyMOL coloring alias script under pml.

Returns:

by_residue: Per-direction arrays (length N) for each chain pair. The key name is historical; entries are per analysis site and may include atom-level sites for non-standard residues in token-expanded mode: - iptm_d0chn: ipTM using d0 based on total residues in the pair. - ipsae_d0chn: ipSAE with PAE cutoff, same d0 as above. - ipsae_d0dom: ipSAE with PAE cutoff, d0 from count of residues

that have inter-chain PAE < cutoff (domain-level).
- ipsae_d0res: ipSAE with PAE cutoff, d0 per row from the number of valid partners in the other chain (residue-level).
- n0res_byres / d0res_byres: Companion per-row counts and d0.
asym: Best single-site values per direction (A→B, B→A) and the site identifier strings that achieve them: - iptm_d0chn, ipsae_d0chn, ipsae_d0dom, ipsae_d0res - *_res entries contain the winning residue labels.
max: Symmetric maxima for each metric across directions plus the site label responsible for the maximum: - iptm_d0chn, ipsae_d0chn, ipsae_d0dom, ipsae_d0res - *_res contain the max-residue labels.
min: Symmetric minima for each metric across directions plus the site label responsible for the minimum: - iptm_d0chn, ipsae_d0chn, ipsae_d0dom, ipsae_d0res - *_res contain the min-residue labels.
counts: Supporting counts and d0 companions: - n0chn, d0chn: Total residues and d0 for each chain pair. - n0dom, d0dom and their *_max/*_min counterparts. - n0res, d0res and their *_max/*_min counterparts. - Pair/unique-residue tallies with and without distance constraints.
scores: Interface-level auxiliary scores: - pDockQ, pDockQ2, LIS.
params: The parameters actually used (cutoffs, model).
pml: Optional PyMOL alias script string (if return_pml is True).
residue_order: Metadata for the selected analysis order: - names (3-letter codes), chains (chain IDs), numbers (seq IDs).

Return type:

A dictionary with the following top-level keys

Raises:

ValueError – If no usable analysis sites are found, or if plddt/pae_matrix shapes do not match either the residue-level or token-expanded order.

Notes

Representative atom for standard residues: * Proteins: Cβ (GLY→Cα; fallback to Cα if Cβ missing). * Nucleic acids: prefer C3′/C3*, then C1′/C1*, then P.
Non-standard residues are handled in two modes: * Residue-level mode (default): non-standard residues are removed from

pLDDT/PAE when payload length matches the raw polymer residue count.
- Token-expanded mode (auto fallback): if payload length instead matches one representative site per standard residue plus all heavy atoms for non-standard residues, those non-standard atoms are retained as sites.
Chain-type classification (protein vs nucleic acid) sets a minimum d0 (2.0 for any pair containing NA; 1.0 otherwise) and influences d0 via the standard length-based formula.
pDockQ neighbors use pDockQ_cutoff on the representative-atom distances.
LIS averages (12 - PAE) / 12 for PAE ≤ 12 Å over inter-chain pairs only.

neurosnap.algos.ipsae.contiguous_ranges(numbers)[source]#

Return type:: str

neurosnap.algos.ipsae.extract_interchain_metrics(res)[source]#

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(). Must contain “asym” and “scores” keys as returned by the main ipSAE computation.

Returns:

Nested dictionary of the form:

{: “iptm_d0chn”: {chain1: {chain2: float}}, “ipsae_d0chn”: {chain1: {chain2: float}}, “ipsae_d0dom”: {chain1: {chain2: float}}, “ipsae_d0res”: {chain1: {chain2: float}}, “pDockQ”: {chain1: {chain2: float}}, “pDockQ2”: {chain1: {chain2: float}}, “LIS”: {chain1: {chain2: float}},

}

Each key corresponds to a metric describing the confidence or stability of the interaction between two chains (e.g., “A”→”B” and “B”→”A”).

Return type: