PDBx/mmCIF
A Member of the wwPDB

CIFPARSE-OBJ C++ Parser Examples and Tutorial

INSTALL AND BUILD INSTRUCTIONS

  1. Download the latest library.
  2. Uncompress and unbundle it with the following command: zcat cifparse-obj-vxxx-prod-src.tar.gz | tar -xf -
  3. Move into the resulting cifparse-obj-vxxx-prod-src directory.
  4. Build the library with make
  5. To run built-in tests, execute make test. Test source code is located in cifparse-obj-vxxx-prod-src/parser-test-app-vxxx/src.
  6. To create your own test(s), place the source code in this folder, and add the file to the .ext list in the Makefile in cifparse-obj-vxxx-prod-src/parser-test-app-vxxx/
EXAMPLES
Connections.C
Uses the CIFPARSE-OBJ library to interface with Chimera. Shows how to retrieve and iterate over the struct_conn category, which delineates connections in a molecule, and locate connections of interest (in this case, covalent bonds) for Chimera to emphasize and animate.
Structures.C
Uses the CIFPARSE-OBJ library to interface with Chimera. Shows how to retrieve and iterate over the struct_site_gen category, which delineates members of structurally relevant sites in a molecule, and locate all structurally relevant sites for Chimera to emphasize and animate.
Search.C
This example shows how to use the Search function to fulfill a query of arbitrary complexity. In this case, we find the coordinates of every alpha carbon atom in chain A of the 5HVP molecule, using the atom_site category table.
Connections3.C
This example shows one way of using the information about a partner atom in a connection, detailed in the the struct_conn category, to identify the atom in the atom_site category, and, in this case, to determine the (x,y,z) Cartesian coordinates of said atom. In this case, we look for partner atoms involved in covalent bonds and report their (x,y,z) coordinates.
Connections2.C
Uses the CIFPARSE-OBJ library to interface with Chimera. Shows how to find connections of certain types that involve certain entities by retrieving and iterating over the struct_conn category, which delineates connections in a molecule, and using the struct_asym and entity categories to determine the entity types involved in each connection. In this case, polymer-polymer covalent bonds are sought for Chimera to emphasize and animate.
FASTA.C
This example shows how the (sequence) information contained in a CIF file can be readily accessed and transformed into another format. This particular example implements a FASTA converter, which reads the monomer sequences in the entity_poly_seq category and translates them into the single-letter FASTA format.
Assemblies.C
A more involved and extensive example that uses the CIFPARSE-OBJ library to generate a CIF file for each biological assembly listed in the pdbx_struct_assembly category of a CIF file. This example synthesizes information located in the pdbx_struct_assembly_gen, pdbx_struct_oper_list, and atom_site categories to accomplish this task.

Basic I/O Operations

Reading, with the assistance of the CifParse class, and writing are handled by the CifFile class, which descends from the TableFile class.

Reading

#include(s): "CifFile.h", "CifParserBase.h", "ISTable.h"
  1. Create a CIF file object 
    CifFile *cifFile = new CifFile;
  2. Create a CIF parser object, passing the CIF file object as a reference 
    CifParser *cifParserP = new CifParser(cifFile);
  3. Parse the CIF file and thus propagate the CIF file object, by passing the pathname of your .cif file and a string to hold diagnostics to the CifParser Parse routine 
    cifParserP->Parse("/path/to/file.cif", diagnostics);
  4. Barring any parse errors, your CifFile object will now be propagated with Block objects, to which data blocks map, and you will be able to delete your CifParser object, as it is no longer needed 
    delete cifParserP;
  5. To retrieve a reference to the first data block, couple the CifFile GetFirstBlockName() method with the GetBlock(const string& blockName) method 
    Block& block = cifFile->GetBlock(cifFile->GetFirstBlockName());
  6. To retrieve a reference to a category table, use the Block GetTable(const string& tableName) method 
    ISTable& struct_conn = block.GetTable("struct_conn");
  7. To retrieve a value stored in a category table, e.g., the connection type of the first linkage described in the struct_conn category table, use the operator()(const unsigned int rowIndex, const string colName) method 
    string connType = struct_conn(0, "conn_type_id");
  8. See below for other methods to access blocks, and, subsequently, the contents of the category tables they contain.

Writing

#include(s): "CifFile.h", "ISTable.h"
  1. Create a CIF file object 
    CifFile *cifFile = new CifFile;
  2. Depending on what you intend to write, you will need to create some number of Block(s) and ISTable(s). Note that ISTable objects must be allocated from the heap, since their memory ownership is passed to the CifFile object.
  3. To add a Block to a CifFile object, call the AddBlock method with whatever name you want to give the block 
    cifFile->AddBlock("block");
  4. Retrieve a reference to the Block with the GetBlock method, using the name you specified when you added it 
    Block& block = cifFile->GetBlock("block");)
  5. To write an ISTable to a Block, call the WriteTable method with the ISTable pointer as an argument 
    block.WriteTable(ISTablePtr);
  6. When you are ready to write out the CIF file object to a CIF file, call the Write method, specifying a .cif file pathname 
    cifFile->Write("/path/to/file.cif");

Containers and Methods of Note

The three major classes which function as containers of sorts are CifFile, Block, and ISTable, where CifFile objects contain Block objects which, in turn, contain ISTable objects. Data blocks map to Block objects, while categories map to ISTable objects. The methods below are predominantly for the purposes of parsing and reading CIF files. The listed headers can be consulted for a full delineation of methods.

CifFile (see TableFile.h & CifFile.h)

Block (see TableFile.h)

ISTable (see ISTable.h)