Loading structures¶

Every use of pidibble starts by constructing a PDBParser and calling parse(). The constructor decides where the data comes from and what format it is in; parse() does the download (if needed), the read, and the parse in one step, returning the parser so calls can be chained:

>>> from pidibble.pdbparse import PDBParser
>>> p = PDBParser(source_db='rcsb', source_id='4zmj').parse()

Choosing a source¶

A remote source is selected with two arguments: source_db names the database and source_id is the entry’s accession code. Three databases are supported:

`source_db`	`source_id` is…	Notes
`'rcsb'`	a 4-character PDB id (e.g. `'4zmj'`)	The RCSB Protein Data Bank. Fetches `<id>.pdb` or, with `input_format='mmCIF'`, `<id>.cif`.
`'alphafold'`	a UniProt accession (e.g. `'O46077'`)	The AlphaFold model database. pidibble first fetches the entry metadata (JSON), then the predicted-model PDB it points to.
`'opm'`	a PDB id (e.g. `'7f1r'`)	The Orientations of Proteins in Membranes database. See OPM dummy atoms below.

# RCSB (the default database for the legacy PDBcode= shorthand)
p = PDBParser(source_db='rcsb', source_id='4zmj').parse()

# AlphaFold predicted model for odorant receptor OR2a from D. melanogaster
p = PDBParser(source_db='alphafold', source_id='O46077').parse()

# OPM entry (a sweet-taste receptor, with membrane dummy atoms)
p = PDBParser(source_db='opm', source_id='7f1r').parse()

An unrecognized source_db raises ValueError, and a source_db with no source_id raises ValueError as well.

The `PDBcode` shorthand¶

For backward compatibility, PDBcode='4zmj' is accepted as shorthand for source_db='rcsb', source_id='4zmj':

>>> p = PDBParser(PDBcode='4zmj').parse()

New code should prefer the explicit source_db/source_id form.

Reading a local file¶

To parse a file already on disk, pass filepath instead of a source:

p = PDBParser(filepath='mystructure.pdb').parse()
p = PDBParser(filepath='mystructure.cif', input_format='mmCIF').parse()

If the file does not exist, parse() raises FileNotFoundError. No network access is attempted when filepath is given.

Caching and re-downloading¶

For the RCSB and OPM sources, pidibble downloads into the current working directory and reuses an existing file rather than fetching again — so a second parse of the same entry is offline and instant. To force a fresh download (for example, if the local copy is stale or truncated), pass overwrite=True:

p = PDBParser(source_db='rcsb', source_id='4zmj', overwrite=True).parse()

If a download fails (network error, unknown id), fetch() logs a warning and parse() yields an empty parsed.

Choosing the input format¶

input_format selects the on-disk format and defaults to 'PDB'. Set it to 'mmCIF' to read a PDBx/mmCIF file:

p = PDBParser(source_db='rcsb', source_id='4tvp', input_format='mmCIF').parse()

The parsed record objects are the same either way; see PDBx/mmCIF parsing for the coverage and the handful of representational differences.

OPM dummy atoms¶

OPM structures embed dummy (DUM) atoms that mark the position of the membrane boundary. When fetching from OPM, pidibble strips blank and END lines and splits the dummy atoms into a companion file: parsing 7f1r writes both 7f1r.pdb (the structure) and 7f1r-dum.pdb (the membrane markers), so the coordinate parse is not polluted by the dummies.