mmCIF in the CCP4 Suite
WA4 4AD, U.K.
The macromolecular Crystallographic Information File (mmCIF) format
was developed by a working group of the IUCr formed in 1990. It
represents an extension of the CIF format used by small molecule
crystallographers, and is the IUCr-recommended medium for electronic
transfer of macromolecular crystallographic data. Consequently, mmCIF
is likely to be encountered more and more by practising protein
crystallographers, and already occurs in a number of contexts in the
The aim of this article is to outline the mmCIF resources
currently available in CCP4, as well as plans for some future ones.
Some of these resources represent extra functionality of the suite,
while others are resources for the program developer. While the instances
of mmCIF described below vary widely in purpose, they are connected by
their use of the mmCIF format, and share the semantics implied by the
mmCIF dictionary, and it therefore useful to
consider them together.
Full details of the mmCIF format can be found on the
mmCIF Home Page or one of its mirrors. Links to the various
CCP4 resources are included below.
mmCIF files are text files with a flexible format
based around either <data_name> <data_value> pairs or a
loop structure (works like a table). A wide variety of
data items are supported, and these are defined in the associated
mmCIF dictionary. As well as listing the data items
that may be included in an mmCIF file, the dictionary details attributes
of each data item, such as type, allowed range, whether or not compulsory,
and to which other data items it is related. Data items are grouped
The standard mmCIF dictionary is maintained by the IUCr. However, the
dictionary is designed to be extensible, and local extensions are possible
which may then be
submitted for inclusion in the main dictionary.
An mmCIF dictionary is distributed with the CCP4 suite as
of version 1.0.00 of the mmCIF dictionary together with extensions
required for data harvesting. A binary symbol table
representation ($CCP4/lib/data/cif_mmdic.lib) of the dictionary
is built during compilation of the suite, and it is in fact this that is
used by the libccif library routines.
libccif: the core mmCIF library routines
Peter Keller's C language library of routines for reading and writing
mmCIF files was included in release 4.0 of the CCP4 suite. The source files
are held in $CCP4/lib/ccif, and when compiled give the separate
archive file libccif.a or the shared library libccif.so.
These routines are used by the CCP4 library routines harvlib.f
(used in data harvesting) and cciflib.f (see
below). For those wishing to use libccif to read/write
mmCIF files, there is a Fortran-callable
interface, which is described in $CCP4/doc/ccifdoc.ps.
Data Harvesting was introduced in CCP4 4.0, and the technique has been
Newsletter 37. The implementation of Data Harvesting uses mmCIF files
to store information from the programs SCALA, TRUNCATE, MLPHARE, REFMAC
and RESTRAIN for future transfer to the deposition site. These files
(which should not be edited!) can be found in directory
$HARVESTHOME/DepositFiles where $HARVESTHOME
defaults to the user's home directory.
mmCIF reflection files
MTZ reflection files can be converted to mmCIF format by the CCP4
MTZ2VARIOUS. The output file may then be used for the deposition
of structure factors to the PDB.
Version 2.7 of the popular molecular viewer Rasmol, which is included
in the CCP4 distribution, will display molecules input from CIF or mmCIF
format files (other formats are also supported). Some restrictions are imposed,
for example the chain identifier (_atom_site.label_asym_id) is restricted
to one character whereas there is no such restriction in the full mmCIF format.
See the program documentation for more details.
mmCIF major mode for Emacs
The editor Emacs can be run in various so-called "major modes" which allow
one to set colour schemes, key binding, etc. appropriately for a particular
file type. The standard Emacs distribution provides major modes for HTML,
Fortran and many others. In CCP4 4.0, a file cif.el is provided which
defines a major mode for mmCIF (see the top of the file for how to load it).
A simple colour scheme helps viewing of mmCIF
files, while a "CIF" menu provides some extra functionality, for example
finding the dictionary entry for a particular data item. I hope to extend
the functionality of cif.el in future.
cciflib.f: application interface for coordinate handling
It has been proposed that mmCIF should be used by CCP4 programs as a working
format for coordinate files, to replace the current use of PDB files. Just
as CCP4 currently only use a subset of the full PDB format, so only a subset
of the full mmCIF format would be used, nicknamed "ccif". As a step towards
this, a set of Fortran routines have been written (which in turn call
libccif routines) which provide an application interface
for CCP4 programs. This effectively replaces the rwbrook routines
currently used for PDB files.
These routines were included in CCP4 4.0, see the accompanying
A number of CCP4 programs have been converted to use these routines, and some
additional utilities are in development. Details can be found on the
developers' web pages.
Version 5.0 of REFMAC (at the time of writing, not yet released) will include
several new features, one of which is a completely new mechanism for handling
geometric restraints. Restraint information for residues, cofactors, etc. is
held in dictionary files mon_lib_*.cif, which is designed to be
easily extensible to include new chemical species. REFMAC will also be able
to read coordinate files in either PDB or mmCIF format.