PDBx/mmCIF file reader

User interface of the PDBx/mmCIF file reader, which appears as part of a pipeline’s file source.

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.

• Cartoon Flags — marks each atom as part of the protein backbone, a side chain, or a hetero group. This property is only created if the file contains amino-acid or nucleotide residues.

• Residue Index — refers to the residue of the cartoon representation the atom belongs to (-1 for atoms not covered by the cartoon). This property is only created along with the cartoon representation.

Cartoon representation

If the structure contains amino-acid or nucleotide residues, the reader additionally builds a cartoon representation of the backbone, with one element per residue. It stores references to the alpha-carbon and carbonyl oxygen atoms of the residues together with the chain and the secondary-structure assignment, and the attached Cartoon visual element renders it as ribbons, arrows and tubes. The secondary structure is taken from the _struct_conf and _struct_sheet_range categories of the file and/or computed from the atomic coordinates, as controlled by the Secondary structure option (see below).

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.

• Atom serial numbers (_atom_site.id), B-factors, anisotropic displacement parameters, formal charges, and all other categories of the file (entities, sequences, connectivity, etc.) are not imported. Chain identifiers (_atom_site.label_asym_id) and the secondary structure are only used to build the cartoon representation of the backbone; they are not available as per-atom properties.

• 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.

Secondary structure

Controls where the secondary structure of the protein (helices and strands) is taken from:

Automatic (default)

The secondary structure is taken from the _struct_conf and _struct_sheet_range categories of the file. For chains that are not covered by any of these records, it is computed from the atomic coordinates using the DSSP algorithm (Kabsch & Sander, 1983). This handles files lacking these records as well as files in which only some of the chains are annotated.

From file

Only the records of the file are used. Chains without records are rendered as coil.

DSSP

The secondary structure of all chains is computed with the DSSP algorithm, ignoring the records of the file.

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', secondary_structure='auto')

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.

• secondary_structure (str) – Controls where the secondary structure assignment of the protein residues is taken from: 'auto' uses the _struct_conf/_struct_sheet_range records of the file and computes the secondary structure with the DSSP algorithm only for chains lacking such records; 'file' uses only the records of the file; 'dssp' computes the secondary structure of all chains from the atomic coordinates.

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