neurosnap.io.mmcif module

Parser and writer for mmCIF coordinate files.

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

Parsing follows the atom-site driven mmCIF loop structure while building Neurosnap structures directly in an array-oriented form.

neurosnap.io.mmcif.parse_mmcif(mmcif, return_type='auto')

Parse an mmCIF file into Neurosnap structure containers.

The parser reads the _atom_site loop directly, using author-provided chain IDs and residue numbering when available and falling back to label identifiers otherwise. Parsed models are first collected into a StructureEnsemble and are optionally converted into a StructureStack at the end.

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.

Unlike neurosnap.io.pdb.parse_pdb(), this first mmCIF implementation does not currently parse explicit bond tables such as _struct_conn. Parsed structures therefore keep full atom annotations but default to an empty bond list unless bonds are added later by other code.

Parameters:

• mmcif (Union[str, Path, IOBase]) – mmCIF 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.

Return type:

Union[StructureEnsemble, StructureStack]

Returns:

A StructureEnsemble or StructureStack depending on return_type and model compatibility.

neurosnap.io.mmcif.save_cif(structure, cif, minimal=False)

Save a Neurosnap structure container as an mmCIF file.

Parameters:

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

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

• minimal (bool) – If True, emit the legacy compact atom-site-only mmCIF output. If False (default), include entity/polymer/subchain metadata for broader downstream parser compatibility.

Notes

Multi-model outputs are represented using the _atom_site.pdbx_PDB_model_num column. The writer does not yet export bond tables such as _struct_conn.