Get peptide bond candidates#

Inspecting bounded backbone C–N evidence without changing the system.

Use molsysmt.build.get_peptide_bond_candidates() to review an experimental, bounded peptide-link report before choosing a reconstruction policy.

Added in version 1.0.0.

API documentation

See molsysmt.build.get_peptide_bond_candidates() for arguments and errors.

Choosing a scope#

Integer selections are source atom indices. Both candidate endpoints must be selected. Choose one structure with structure_indices when the system contains several; structure IDs remain separate labels. The stored chemical state can be chosen explicitly, or associated with the selected structure using chemical_state='structure'. Unresolved chemistry remains unassessed.

The method adjacent_backbone_distance reuses the heavy-template report and molsysmt.structure.get_distances() with explicit pairs. It examines only consecutive source group indices in one defined chain. A selection cannot make groups consecutive, and equal or nonconsecutive group IDs do not establish a link.

Native PDB conversion creates different chain indices across TER, even if the chain labels repeat. Insertion-code groups remain distinct even when their group IDs are equal. The report respects those axes. An adapter that discarded a file boundary cannot supply it later merely through a group or chain label.

Inspecting groups stored out of polymer order#

Choose method='unique_backbone_distance' when source group order may differ from the polymer’s physical order:

report = msm.build.get_peptide_bond_candidates(
    molsys, structure_indices=0, method='unique_backbone_distance')

This optional policy searches close named C/N endpoints within each defined source chain using molsysmt.structure.get_neighbors(). It keeps atom and group indices unchanged and never sorts group IDs. A carbon with multiple nearby incoming groups, or a nitrogen with multiple nearby outgoing groups, leaves those proposals unassessed with competing_backbone_partners. Competition includes endpoints outside your output selection and endpoints in chemically unassessed groups. Selecting two atoms cannot hide a competing third atom and make a proposal unique.

The same template, terminal, stored-edge and distance checks still apply. Discovery checks the entire source backbone; group_coverage therefore audits all source groups for this policy. Outer atom_indices still describes your output selection. links lists nearby proposals between selected groups, rather than every distant group pair. No dense atom-pair matrix is constructed.

The extra discovery record contains the examined source atom_indices, status, reason_codes, blocked_chain_indices and unassessed_group_indices. Its pbc_applied records whether periodic images were used during discovery, including an evaluated search with no output candidates; the outer flag describes the subsequent eligible-pair distance evaluation. An assessed empty search differs from unassessed missing coordinates or an invalid requested periodic box. A partial search identifies unresolved chain memberships or chains with non-finite/alternate backbone geometry. This first conservative policy blocks uniqueness throughout a chain with incomplete backbone geometry, including evidence outside your selection. Side-chain alternates do not block it.

Uniqueness is geometric evidence among existing named endpoints. It does not recover an independently declared sequence, infer missing atoms, establish valence or certify peptide chemistry. The default remains adjacent_backbone_distance; the PDB reader is unchanged.

Reviewing the result#

The detached dictionary uses schema molsysmt.peptide_bond_candidates@1.

Field

Meaning

bonded_atom_pairs

Sorted source atom pairs, shape (n_candidates, 2), dtype int64.

group_pairs

Aligned, directional source group pairs: outgoing C group, incoming N group.

carbon_atom_indices, nitrogen_atom_indices

Roles remain explicit even when source atom order differs.

distances

Aligned length quantities honoring the active output-unit policy.

missing_mask

True if no stored edge has these endpoints. Existing edges are preserved.

links

Examined selected group proposals, status, reasons and measured distance when evaluated.

group_coverage

Exact heavy-template report, including template hashes and unassessed groups.

parameters

Requested and effective length ceilings, with units, and the PBC flag.

pbc_applied

Whether a periodic box was used to evaluate the eligible pairs.

software, method, rule_version

Original producer version and executed descriptive rule.

All candidates have inferred_candidate evidence. candidate means the bounded criteria passed; rejected means an evaluated distance exceeded the ceiling; unassessed means required evidence is missing, ambiguous or conflicting. Empty arrays retain their types and shapes.

Respecting geometric and chemical limits#

Groups need compatible exact heavy-template mappings and unique C/N endpoints. Missing other heavy atoms may leave a partial group without blocking a known endpoint. Contradictory stored peptide edges or an already linked external backbone endpoint block the affected proposal. Unknown bond orders remain unknown. An outgoing group with OXT is excluded by this first terminal policy.

The positive finite C–N distance must not exceed either max_bond_length or the existing protein C–N reference plus its tolerance: 0.153 nm. The default requested ceiling is 2 angstroms. This is a heuristic candidate criterion, not a validated bond-energy or valence calculation. Coordinates and ceilings can use other length units; numerical delegation names nm explicitly.

PBC is disabled by default. With pbc=True, a valid available box enables minimum-image distances; a missing box leaves Cartesian geometry. A present invalid box leaves eligible links unassessed. Crystallographic periodicity alone does not declare a polymer bond. Alternate-site evidence at either backbone endpoint also leaves that link unassessed: this first policy does not select or combine alternate conformers. Alternate side-chain atoms do not block a unique backbone pair.

Without coordinates, eligible links remain unassessed. Terminal caps, other polymers, sequence completion, hydrogen edges, bond-order assignments, valence and protonation are outside this method. The source, declared file edges and named interaction analyses are unchanged; this does not change the PDB reader.

Reading from disk#

Native H5MSM 0.5 numeric/all queries read chemical/topological layers and one coordinate structure, its box and sparse alternate-site evidence through the existing adapter iterator. They do not load all coordinate structures. Rich selections retain their source behavior and may need broader access. Legacy H5MSM files retain their adapter route and deprecation warning. Legacy alternate-location label arrays without the native sparse-site contract leave affected calculations unassessed; they are not treated as absent evidence.

See also