moleculekit.tools.autosegment module#

moleculekit.tools.autosegment.autoSegment(mol, sel='all', basename='P', fields=('segid',), protein_cutoff=2.0, nucleic_cutoff=2.2, ca_fallback_cutoff=5.0, nucleic_fallback_cutoff=3.2, single_other_segment=False, return_chain_map=False, _logger=True)#

Segment a Molecule by physical backbone continuity.

Walks the selected residues in file order and starts a new segment when the polymer type, chain or segid changes, or when the backbone link distance between consecutive residues exceeds the cutoff. Because continuity is decided from backbone geometry rather than resid numbering, residues deleted from a sequence with an intact backbone stay in one segment, and the whole-system bond graph is never built.

Water residues collapse to a single segment, ions to a single segment, lipids to a single segment, and remaining (“other”) molecules are split by bonded connected components.

Parameters:

  • mol (Molecule) – The Molecule object.

  • sel (str | ndarray) – Atom selection to segment. A selection string, a boolean mask, or an integer index array. Atoms outside the selection keep their existing chain/segid.

  • basename (str) – Base name for segment ids (e.g. ‘P’ -> ‘P0’, ‘P1’, …).

  • fields (tuple) – Fields to set: any combination of “segid” and “chain”.

  • protein_cutoff (float) – Max C(i)-N(i+1) distance (A) for two protein residues to be continuous.

  • nucleic_cutoff (float) – Max O3’(i)-P(i+1) distance (A) for two nucleic residues to be continuous.

  • ca_fallback_cutoff (float) – Max CA(i)-CA(i+1) distance (A) used when protein C/N atoms are missing.

  • nucleic_fallback_cutoff (float) – Max C3’(i)-P(i+1) distance (A) used when nucleic O3’ is missing.

  • single_other_segment (bool) – If True, all non-polymer, non-water, non-ion (“other”) residues are placed into a single segment. If False (default), they are split into separate segments by bonded connected components (one per molecule).

  • return_chain_map (bool) – If True, return a (newmol, chain_map) tuple instead of just newmol; see the dict format described under Returns.

Return type:

Any

Returns:

  • newmol (Molecule) – A copy of mol with the requested fields set. This is the entire return value when return_chain_map is False (the default).

  • chain_map (dict) – Returned together with newmol, as a (newmol, chain_map) tuple, only when return_chain_map is True. One entry per residue covered by sel, including water and ions: keyed by "chain:resid:insertion:segid" built from newmol’s own fields (so insertion is often an empty field, e.g. "E:1::P4"), and valued by the deposited chain name as a plain string, for example {"A:57::P0": "AP"}. A residue whose key is absent from the map was outside sel.

Example

>>> newmol = autoSegment(mol, fields=("chain", "segid"))
>>> newmol, chain_map = autoSegment(
...     mol, fields=("chain", "segid"), return_chain_map=True
... )
moleculekit.tools.autosegment.autoSegment2(mol, sel='(protein or resname ACE NME)', basename='P', fields=('segid',), residgaps=False, residgaptol=1, chaingaps=True, _logger=True)#

Deprecated alias of autoSegment().

Kept as a thin backward-compatible wrapper that forwards to autoSegment(). The residgaps, residgaptol and chaingaps arguments are accepted but ignored: autoSegment() decides continuity from backbone geometry rather than resid numbering.

Parameters:

  • mol (Molecule) – The Molecule object.

  • sel (str | ndarray) – Atom selection to segment. A selection string, a boolean mask, or an integer index array. Atoms outside the selection keep their existing chain/segid.

  • basename (str) – Base name for segment ids (e.g. ‘P’ -> ‘P0’, ‘P1’, …).

  • fields (tuple) – Fields to set: any combination of “segid” and “chain”.

  • residgaps (bool) – Ignored. Accepted only for backward compatibility.

  • residgaptol (int) – Ignored. Accepted only for backward compatibility.

  • chaingaps (bool) – Ignored. Accepted only for backward compatibility.

Returns:

newmol – A copy with the requested fields set, as produced by autoSegment().

Return type:

Molecule