PDBx/mmCIF file reader

For loading macromolecular structures stored in the PDBx/mmCIF format, the primary archive format of the Worldwide Protein Data Bank (wwPDB). Structure files in this format can be downloaded from the RCSB PDB and other wwPDB member sites and are also written by many structural biology and molecular modeling programs. OVITO can directly load gzipped mmCIF files (“.gz” suffix).

PDBx/mmCIF files share their syntax with the CIF format used for small-molecule and inorganic crystal structures, but describe atoms using a different dictionary (data items of the _atom_site. category, with a dot separator). OVITO automatically picks the right reader based on the file contents: files containing _atom_site. items are loaded by the mmCIF reader described here, files containing _atom_site_ items by the CIF reader. The legacy PDB text format is handled by yet another reader.

Imported data

Atoms

Each row of the _atom_site loop (ATOM and HETATM records) of the first model in the file is read as one atom. The file reader creates the following per-atom properties:

  • Position — the Cartesian coordinates (_atom_site.Cartn_x, _atom_site.Cartn_y, _atom_site.Cartn_z).

  • Particle Type — the chemical element (_atom_site.type_symbol). The atomic number of the element is used as numeric type ID, and OVITO assigns the standard CPK color and display radius of the element.

  • Atom Name — the atom identifier within its residue (_atom_site.label_atom_id), e.g. CA, N, or OD1.

  • Residue Type — the residue name (_atom_site.label_comp_id), e.g. ALA, GLY, or HOH, stored as a typed particle property with one named type per residue kind occurring in the file.

  • Sequence — the residue sequence number (_atom_site.label_seq_id). This property is only created if the file contains sequence numbers.

  • Occupancy — the occupancy value (_atom_site.occupancy). This property is only created if at least one atom in the file has an occupancy other than 1.

Unit cell

The cell parameters (_cell.length_a, _cell.length_b, _cell.length_c, _cell.angle_alpha, _cell.angle_beta, _cell.angle_gamma) are converted to a triclinic simulation cell with periodic boundary conditions enabled in all three directions. The cell vector \(\mathbf{a}\) is aligned with the Cartesian x-axis and \(\mathbf{b}\) lies in the x-y plane. Note that the atomic coordinates stay as they are and are not wrapped into the unit cell. If the file specifies no cell, an axis-aligned bounding box may be generated instead (see Generate bounding box if needed option below).

Metadata

The following data items are imported as global attributes named after the mmCIF tags, if present: _entry.id, _struct.title, _exptl.method, _cell.Z_PDB, _pdbx_database_status.recvd_initial_deposition_date, _struct_keywords.pdbx_keywords, and _struct_keywords.text.

Limitations

  • Only the first model (_atom_site.pdbx_PDB_model_num) of a multi-model file (e.g. an NMR ensemble) is imported. The reader does not support trajectories or animation sequences.

  • The asymmetric unit is imported as stored in the file. Symmetry-related copies (crystallographic unit cell contents) and biological assemblies (_pdbx_struct_assembly) are not generated.

  • Atoms with alternate conformations (_atom_site.label_alt_id) are all imported as separate atoms, i.e. the alternate locations are not merged or filtered.

  • Chain identifiers (_atom_site.label_asym_id), atom serial numbers (_atom_site.id), B-factors, anisotropic displacement parameters, formal charges, and all other categories of the file (entities, sequences, secondary structure, connectivity, etc.) are not imported.

  • Bonds stored in the file (_struct_conn and _chem_comp_bond categories) are ignored. OVITO can instead generate bonds based on interatomic distances during import using the Generate bonds option (see below), which is enabled by default for this format.

Options

Generate bounding box if needed

If this option is enabled and the mmCIF file does not specify the unit cell parameters, OVITO will generate an axis-aligned bounding box enclosing all atoms. This bounding box has open boundary conditions and serves as an approximate simulation cell.

Center simulation cell on coordinate origin

If enabled, OVITO shifts the simulation cell and all atom coordinates so that the geometric center of the cell coincides with the coordinate origin. Otherwise, the origin of the unit cell is placed at the coordinate origin.

Generate bonds

Lets OVITO create bonds between the atoms during import, using one of the parameter-free criteria of the Create bonds modifier. The Van der Waals radii criterion is selected by default when opening a file of this format.

Van der Waals radii

Two atoms are connected if their distance is smaller than 0.6 times the sum of their van der Waals radii. No bonds are created between two hydrogen atoms.

Covalent radii

Bonds are created based on the covalent radii and the maximum coordination numbers of the chemical elements.

VESTA-like

Bonds are created according to the built-in table of element-pair bond distances adopted from the VESTA program.

Alternatively, you can apply the Create bonds modifier to the loaded structure, which provides more control over the generation of bonds.

Python parameters

The file reader accepts the following optional keyword parameters in a call to the import_file() or load() Python functions.

import_file(location, bounding_box=False, centering=False, generate_bonds='vdw')
Parameters:

  • bounding_box (bool) – Generate an ad-hoc simulation cell as a bounding box around the imported atoms when the file contains no unit cell parameters.

  • centering (bool) – Translate atom coordinates and simulation cell to center them at the coordinate origin.

  • generate_bonds (str) – Controls the generation of ad-hoc bonds connecting the atoms loaded from the file. The bond criterion can be based on the van der Waals radii of the chemical elements ('vdw'), on their covalent radii and maximum coordination numbers ('covalent'), or on the built-in table of element-pair bond distances adopted from the VESTA program ('vesta'). 'off' disables bond generation. These criteria correspond to the modes of the CreateBondsModifier, which you can alternatively apply to the system after import for more control over the generation of bonds.

Changed in version 3.17.0: The generate_bonds parameter now selects the bond criterion. True is still accepted as an alias for 'vdw'.