molsysmt.build.get_peptide_bond_candidates#

molsysmt.build.get_peptide_bond_candidates(molecular_system, selection='all', structure_indices='all', chemical_state='reference', max_bond_length='2 angstroms', pbc=False, syntax='MolSysMT', skip_digestion=False, *, method='adjacent_backbone_distance')[source]#

Getting bounded backbone C-N distance candidates without changing chemistry.

Parameters:

molecular_system (molecular system) – Molecular system in any supported form with atom names, elements and group/chain membership. PDB normalization disables reader inference.
selection (str, list, tuple or numpy.ndarray, default='all') – Atom selection. Integers are source atom indices. Both endpoints must be selected; containing groups are audited. Defaults to ‘all’.
structure_indices (int, list, tuple or numpy.ndarray, default='all') – Source structure indices (0-based). Select one when structures exist. Without coordinates, eligible links remain unassessed. Defaults to ‘all’.
chemical_state (str, int or None, default='reference') – Stored state to audit, or ‘structure’ for the selected structure’s association. Unresolved states block candidates. Defaults to ‘reference’.
max_bond_length (quantity or str, default='2 angstroms') – Positive finite scalar distance ceiling with length units. The effective ceiling also obeys the existing protein C-N threshold plus tolerance (0.153 nm). Defaults to ‘2 angstroms’.
pbc (bool, default=False) – Whether to use minimum-image distances when a valid box exists. Defaults to False; a crystallographic box does not imply a polymer link.
syntax (str, default='MolSysMT') – Syntax used for atom selection. Defaults to ‘MolSysMT’.
skip_digestion (bool, default=False) – Whether to skip MolSysMT’s internal argument digestion mechanism.
method (str, default='adjacent_backbone_distance') – Candidate policy. ‘adjacent_backbone_distance’ requires consecutive source groups. ‘unique_backbone_distance’ searches named C/N endpoints across the full source and rejects competing same-chain partners before applying the output selection. Defaults to ‘adjacent_backbone_distance’.

Returns:

Detached molsysmt.peptide_bond_candidates@1 report. Sorted source bonded_atom_pairs and directional group_pairs have shape (n, 2) and dtype int64. Carbon/nitrogen indices, missing masks and distance quantities align with candidate rows. links records reasons for rejection or unassessed links; group_coverage retains the supporting exact heavy-template report. Empty arrays retain shapes and dtypes.

Return type:

dict

Raises:

ArgumentError – If indices, state, flags or the length ceiling are invalid, or multiple structures are selected, or the method is unsupported.
NotWithThisFormError – If required group hierarchy is unavailable.
StructuralInconsistencyError – If stored domains or coordinate shapes are inconsistent.

Notes

The descriptive method adjacent_backbone_distance reuses exact group audits and structure.get_distances(pairs=True). Only consecutive source group indices in one defined chain are considered. Group IDs are labels. Supported groups must have unambiguous mapped C/N endpoints, compatible heavy chemistry and positive finite distances within the effective ceiling. An outgoing C in a group with OXT is excluded. Alternate-site evidence at either endpoint blocks this first policy rather than mixing conformers.

The optional unique_backbone_distance policy reuses the sparse Rust neighbor search in structure.get_neighbors. It does not sort group IDs or change source axes. Competition includes unselected and chemically unassessed named backbone endpoints. Non-finite or alternate backbone coordinates block uniqueness assessment throughout their source chain. discovery reports the full examined endpoint scope, status and reasons; group_coverage audits the full source for this method. Uniqueness is geometric evidence among existing named endpoints, not certified sequence order, peptide chemistry or evidence of missing atoms.

Native PDB conversion separates TER segments even when chain labels repeat and keeps insertion-code groups distinct. This tool respects those source indices; it cannot recover file evidence discarded by another adapter. Numeric/all H5MSM 0.5 queries read only one coordinate structure and its sparse alternate-site evidence. Rich selections may require broader access.

Terminal caps, nonpeptide polymer links, sequence completion, hydrogen placement, bond orders, valence and protonation are unassessed. Existing edges, coordinates and named interactions are unchanged. A candidate is inferred evidence, never a declaration of complete or validated chemistry.