parser#

Entrypoint for parsing and preparing atomic-level structures with AtomWorks.

We provide three public functions to cover the main use cases:

parse() — load a file and return a full result dictionary (chain_info, assemblies, metadata, etc.).
parse_atom_array() — process an existing AtomArray and return a result dictionary matching parse() output.
prepare_atom_array() — process an existing AtomArray with AtomWorks’ common annotations and return the processed atoms directly, without the surrounding metadata.

To control the options for parsing and preparing, either: (a) Use the config argument to pass a configuration object (e.g. ParseConfig) or preset name (e.g. "rcsb"). (b) (Legacy) Pass bare keyword arguments to parse() (e.g. add_missing_atoms=True)

class atomworks.io.parser.ParseConfig(add_missing_atoms: bool = True, add_bond_types_from_struct_conn: tuple[str, ...] = ('covale',), remove_ccds: tuple[str, ...] = ('SO4', 'GOL', 'EDO', 'PO4', 'ACT', 'PEG', 'DMS', 'TRS', 'PGE', 'PG4', 'FMT', 'EPE', 'MPD', 'MES', 'CD', 'IOD'), remove_waters: bool = True, fix_ligands_at_symmetry_centers: bool = True, fix_arginines: bool = True, long_bond_policy: Literal['keep', 'filter', 'warn', 'raise', 'filter_nonstandard_only', 'warn_nonstandard_only', 'raise_nonstandard_only'] = 'warn', struct_conn_distance_policy: Literal['keep', 'filter', 'warn', 'raise', 'filter_nonstandard_only', 'warn_nonstandard_only', 'raise_nonstandard_only'] = 'filter', add_id_and_entity_annotations: bool = True, convert_mse_to_met: bool = False, hydrogen_policy: Literal['keep', 'remove'] = 'keep', ccd_mirror_path: str | None = None, return_atom_array_plus: bool = False, model: int | None = None, build_assembly: Literal['all', 'first'] | list[str] | tuple[str] | None = 'all', extra_fields: list[str] | set[str] | frozenset[str] | dict[str, dict[str, Any] | None] | Literal['all'] | None = None, file_type: Literal['cif', 'pdb', 'bcif'] | None = None, altloc: Literal['first', 'random_per_chain', 'random_clash_aware'] | str = 'first', altloc_seed: int | None = None, load_standard_annotations: bool = False, keep_cif_block: bool = False, cache_dir: str | None = None, save_to_cache: bool = False, load_from_cache: bool = False, cif_ccd_on_mismatch: Literal['ignore', 'error_heavy', 'error'] = 'error_heavy')[source]#

Bases: PrepareConfig

Configuration for parse() when loading from files.

Extends PrepareConfig with file/parse-specific fields. Use get_config() or from_preset() to construct from a named preset with optional overrides:

config = ParseConfig.from_preset("rcsb")
config = ParseConfig.from_preset("rcsb", model=0, build_assembly="first")

Parameters:

model – Model number to parse for files with multiple models (e.g., NMR). None loads all models. Defaults to None.
build_assembly – Which biological assembly to build. Options: None (asymmetric unit only), "first", "all", or a list/tuple of assembly IDs as strings. Defaults to "all".
extra_fields – Extra CIF fields to include in the AtomArrayStack. None includes no extra fields; "all" includes all fields. Only supported for CIF files. Defaults to None.
file_type – File type of the structure file. If None, inferred automatically from the file extension. Defaults to None.
altloc – Which alternate conformer to select. "first" selects the alphabetically-first altloc per chain, "random_per_chain" selects a random altloc per chain, "random_clash_aware" selects one altloc per residue while avoiding steric clashes between nearby residues, or a specific letter (e.g. "A"). Only supported for CIF files; PDB files always use "first". Defaults to "first".
altloc_seed – Seed for deterministic random altloc selection when altloc="random_per_chain" or altloc="random_clash_aware". If None (default), selection is non-deterministic.
load_standard_annotations – Whether to deserialize StandardAnnotations from the CIF block. Incompatible with add_missing_atoms=True. Defaults to False.
keep_cif_block – Whether to include the raw CIF block in the result dictionary. Defaults to False.
cache_dir – Cache directory; auto-defaults to <tempdir>/atomworks_parse_cache when caching is enabled. Defaults to None.
save_to_cache – Whether to save results to cache after parsing. Defaults to False.
load_from_cache – Whether to load pre-compiled results from cache. Defaults to False.
cif_ccd_on_mismatch – How authored chem_comp_atom templates treat atoms absent from the bundled CCD: "error_heavy" (default) raises (curated inputs); "ignore" keeps them (custom ligands reusing real codes).

altloc: Literal['first', 'random_per_chain', 'random_clash_aware'] | str = 'first'#

altloc_seed: int | None = None#

build_assembly: Literal['all', 'first'] | list[str] | tuple[str] | None = 'all'#

cache_dir: str | None = None#

cif_ccd_on_mismatch: Literal['ignore', 'error_heavy', 'error'] = 'error_heavy'#

extra_fields: list[str] | set[str] | frozenset[str] | dict[str, dict[str, Any] | None] | Literal['all'] | None = None#

file_type: Literal['cif', 'pdb', 'bcif'] | None = None#

keep_cif_block: bool = False#

load_from_cache: bool = False#

load_standard_annotations: bool = False#

model: int | None = None#

save_to_cache: bool = False#

atomworks.io.parser.get_config(preset: str = 'default', *, cls: type[~atomworks.io.config.T] = <class 'atomworks.io.config.PrepareConfig'>, **overrides) → T[source]#

Build a config from a named preset with optional overrides.

Parameters:

preset – Preset name. Available: "default", "rcsb", "lightweight", "annotations_only", "minimal".
cls – Config class to instantiate. Defaults to PrepareConfig.
**overrides – Fields to override on the preset.

Parse structural files into an AtomArrayStack with standardized annotations and metadata.

Processing behaviour is controlled by ParseConfig. Legacy bare keyword arguments (e.g. add_missing_atoms=True) are still accepted but will emit a DeprecationWarning; prefer passing a config object.

Parameters:

source – Path or buffer to the structure file. May be any format of atomic-level structure (e.g. .cif, .bcif, .cif.gz, .pdb), although .cif files are strongly recommended.
config – Processing configuration. Pass a preset name ("default", "rcsb", "lightweight", "minimal"), a ParseConfig instance, or None for defaults.
filename – Deprecated alias for source. Cannot be used together with source.

Returns:

A dictionary containing the following keys:

chain_info: A dictionary mapping chain ID to sequence, type (as an IntEnum), RCSB entity, EC number, and other information.
ligand_info: A dictionary containing ligand of interest information.
asym_unit: An AtomArrayStack instance representing the asymmetric unit.
assemblies: A dictionary mapping assembly IDs to AtomArrayStack instances.
metadata: A dictionary containing metadata about the structure (e.g., resolution, deposition date, etc.).
extra_info: A dictionary with information for cross-compatibility and caching. Should typically not be used directly.

Return type:

dict

Mimic of parse() that operates on an AtomArray or AtomArrayStack instead of a file input.

Returns identical result dict to parse(), but takes an AtomArray or AtomArrayStack as input instead of a file path or buffer.

Parameters:

source – The AtomArray or AtomArrayStack to process.
config – Preset name ("default", "rcsb", "lightweight"), PrepareConfig, or None for defaults.

Perform standard AtomWorks preparation of an AtomArray, returning the processed atoms directly.

Runs the same core processing as parse() (standardize, add missing atoms, infer bonds, annotate) but returns the processed atoms instead of a full result dictionary. Single-model results are squeezed to AtomArray for conciseness.

For example, useful to add entity/molecule annotations to an AtomArray that already has a complete set of atoms and bonds.

Parameters:

source – The structure to process.
config – Preset name ("default", "rcsb", "lightweight"), PrepareConfig, or None for defaults.
cif_block – Optional CIF block for richer processing (struct_conn bonds, entity categories, custom bonds).
extra_fields – Extra CIF fields to preserve through processing.

parser#

This Page