neurosnap.io.pdb module

Parser and writer for PDB files.

This module provides Neurosnap-native parse_pdb() and save_pdb() helpers for reading and writing Structure, StructureEnsemble, and StructureStack objects.

neurosnap.io.pdb.parse_pdb(pdb, return_type='auto', malformed_conect='warn')

Parse a PDB file into Neurosnap structure containers.

Parsing follows the fixed-width PDB record layout used by BioPython’s parser but builds Neurosnap Structure entities.Parsed models are first collected into a StructureEnsemble and are optionally converted into a StructureStack at the end.

HETATM records and CONECT records are parsed directly so ligands and custom covalent bonds are preserved more faithfully than in the old BioPython-backed path.

Alternate locations are always ignored. When alternate locations are present, the parser keeps only the highest-occupancy conformer for each atom site and emits a logger.warning() so the user knows this happened.

If a residue contains duplicate atom names without altloc identifiers, the parser preserves all such atoms by automatically renaming later duplicates to unique PDB-style atom names and emits a logger.warning() describing the rename. This avoids incorrectly collapsing distinct ligand atoms that happen to share generic names such as C or O.

Repeated CONECT records are interpreted as higher bond order using a directed-count collapse:

bond_type = max(count(atom_i -> atom_j), count(atom_j -> atom_i))

This means repeated records in one direction can encode double or triple bonds, while mirrored CONECT entries from both atoms do not artificially inflate bond order.

Parameters:

• pdb (Union[str, Path, IOBase]) – PDB filepath or open file handle.

• return_type (Literal['ensemble', 'stack', 'auto']) – Output container type. "ensemble" always returns a StructureEnsemble, "stack" requires stack-compatible models, and "auto" returns a StructureStack when possible or falls back to a StructureEnsemble.

• malformed_conect (Literal['strict', 'warn', 'ignore']) – How malformed CONECT records should be handled. "strict" raises immediately, "warn" logs a warning and skips the bad record, and "ignore" silently skips it.

Return type:

Union[StructureEnsemble, StructureStack]

Returns:

A StructureEnsemble or StructureStack depending on return_type and model compatibility.

neurosnap.io.pdb.save_pdb(structure, pdb)

Save a Neurosnap structure container as a PDB file.

Parameters:

• structure (Union[Structure, StructureEnsemble, StructureStack]) – Structure container to write.

• pdb (Union[str, Path, IOBase]) – Output filepath or open file handle.

Notes

Multi-model outputs are written using MODEL / ENDMDL records. CONECT records are written for single-model outputs and for multi-model outputs only when all models share identical bonds and atom serials so the topology can be represented unambiguously in PDB format.