Advanced usage and customization¶

pidibble is driven by a declarative description of the PDB and mmCIF formats, and several constructor arguments let you extend or override it.

Custom field mappers¶

Every field in the format specification names a type, and each type maps to a callable that turns the raw column text into a Python value. The built-in types are String, Integer, Float and HxInteger (the hexadecimal-aware atom-serial type), plus a family of list parsers.

You can add or override these with the mappers argument — a dict from type name to a one-argument callable. This is the hook for a custom type used by a custom format, or for changing how an existing type is coerced:

def tenths(text):
    return round(float(text), 1)

p = PDBParser(source_db='rcsb', source_id='4zmj',
              mappers={'Float': tenths}).parse()

Your mappers are merged over the defaults, so you only supply what you want to change.

Comment characters¶

By default, lines beginning with # are treated as comments and skipped. Pass comment_chars to change that set — for example, to also ignore ! lines:

p = PDBParser(filepath='annotated.pdb', comment_chars=['#', '!']).parse()

Overriding the format specification¶

The PDB and mmCIF record definitions are shipped as YAML resources (pdb_format.yaml and mmcif_format.yaml). To parse a nonstandard dialect or add a record type, point the parser at your own files:

p = PDBParser(filepath='custom.pdb',
              pdb_format_file='my_pdb_format.yaml').parse()

c = PDBParser(filepath='custom.cif', input_format='mmCIF',
              mmcif_format_file='my_mmcif_format.yaml').parse()

The format-specification schema¶

Each record type in pdb_format.yaml is described by a small set of keys:

type: The record’s cardinality/shape: one-time-one-line, one-time-multiple-lines, multiple-times-one-line, multiple-times-multiple-lines, grouping, or other.
fields: A mapping of field name to a [type, [start, end]] pair giving the field’s data type and its (1-based, inclusive) column range.
continues: The fields that a continuation record appends to or extends.
token_formats: How a field’s text is broken into named tokens (with optional determinants that group token/value pairs) — this is what produces the token groups of COMPND and SOURCE.
concatenate: New fields built by list-concatenating other fields.
allowed: Per-field lists of allowed values, for validation.
determinants: The fields whose values decide whether a line starts a new record instance or continues the current one.
subrecords: How to parse variant sub-formats, selected by the value of a branchon field.
tables: How embedded tables (such as the BIOMT matrices) are parsed out.

Reusable sub-formats (for example the Residue variants and the Biomt row) live under custom_formats and are referenced by name from field definitions.