Skip to content

Latest commit

 

History

History
152 lines (94 loc) · 6.85 KB

mmcif.md

File metadata and controls

152 lines (94 loc) · 6.85 KB
Raw

How to Parse mmCIF Files using BioJava

A quick tutorial how to work with mmCIF files.

What is mmCIF?

The Protein Data Bank (PDB) has been distributing its archival files as PDB files for a long time. The PDB file format is based on "punchcard"-style rules how to store data in a flat file. With the increasing complexity of macromolecules that are being resolved experimentally, this file format can not be used any more to represent some or the more complex structures. As such, the wwPDB recently announced the transition from PDB to mmCIF/PDBx as the principal deposition and dissemination file format (see here and here).

The mmCIF file format has been around for some time (see Westbrook 2000 and Westbrook 2003 ) BioJava has been supporting mmCIF already for several years. This tutorial is meant to provide a quick introduction into how to parse mmCIF files using BioJava

The Basics

BioJava provides you with both a mmCIF parser and a data model that reads PDB and mmCIF files into a biological and chemically meaningful data model (BioJava supports the Chemical Components Dictionary). If you don't want to use that data model, you can still use BioJava's file parsers, and more on that later, let's start first with the most basic way of loading a protein structure.

First Steps

The simplest way to load a PDB file is by using the StructureIO class.

    Structure structure = StructureIO.getStructure("4HHB");
    // and let's print out how many atoms are in this structure
    System.out.println(StructureTools.getNrAtoms(structure));

BioJava automatically downloaded the PDB file for hemoglobin 4HHB and copied it into a temporary location. This demonstrates two things:

  • BioJava can automatically download and install files locally
  • BioJava by default writes those files into a temporary location (The system temp directory "java.io.tempdir").

If you already have a local PDB installation, you can configure where BioJava should read the files from by setting the PDB_DIR system property

    -DPDB_DIR=/wherever/you/want/

From PDB to mmCIF

By default BioJava is using the PDB file format for parsing data. In order to switch it to use mmCIF, we can take control over the underlying AtomCache which manages your PDB (and btw. also SCOP, CATH) installations.

        AtomCache cache = new AtomCache();
            
        cache.setUseMmCif(true);
            
        // if you struggled to set the PDB_DIR property correctly in the previous step, 
        // you could set it manually like this:
        cache.setPath("/tmp/");
            
        StructureIO.setAtomCache(cache);
            
        Structure structure = StructureIO.getStructure("4HHB");
                    
        // and let's count how many chains are in this structure.
        System.out.println(structure.getChains().size());

As you can see, the AtomCache will again download the missing mmCIF file for 4HHB in the background.

URL based parsing of files

StructureIO can also access files via URLs and fetch the data dynamically. E.g. the following code shows how to load a file from a remote server.

        String u = "http://ftp.wwpdb.org/pub/pdb/data/biounit/mmCIF/divided/nw/4nwr-assembly1.cif.gz";
        try {
            Structure s = StructureIO.getStructure(u);

            System.out.println(s);
        } catch (Exception e) {
            e.printStackTrace();
        }

Local URLs

BioJava can also access local files, by specifying the URL as

    file:///path/to/local/file

Low Level Access

If you want to learn how to use the BioJava mmCIF parser to populate your own data structure, let's first take a look this lower-level code:

        InputStream inStream =  new FileInputStream(fileName);
 
        MMcifParser parser = new SimpleMMcifParser();
 
        SimpleMMcifConsumer consumer = new SimpleMMcifConsumer();
 
        // The Consumer builds up the BioJava - structure object.
        // you could also hook in your own and build up you own data model.          
        parser.addMMcifConsumer(consumer);
 
        try {
            parser.parse(new BufferedReader(new InputStreamReader(inStream)));
        } catch (IOException e){
            e.printStackTrace();
        }
 
        // now get the protein structure.
        Structure cifStructure = consumer.getStructure();

The parser operates similar to a XML parser by triggering "events". The SimpleMMcifConsumer listens to new categories being read from the file and then builds up the BioJava data model.

To re-use the parser for your own datamodel, just implement the MMcifConsumer interface and add it to the SimpleMMcifParser.

        parser.addMMcifConsumer(myOwnConsumerImplementation);

I Loaded a Structure Object, What Now?

BioJava provides a number of algorithms and visualisation tools that you can use to further analyse the structure, or look at it. Here a couple of suggestions for further reads:

Further reading

See the http://mmcif.rcsb.org/ site for more documentation on mmcif.

Navigation: Home | Book 3: The Structure Modules | Chapter 6 : Work with mmCIF/PDBx Files

Prev: Chapter 5 : Chemical Component Dictionary

Next: Chapter 7 : SEQRES and ATOM Records