About This Example:

This example is one of a few that shows how the PDBX library can be used to interface with Chimera, such that useful and interesting aspects of a molecule, obtainable via parsing CIF files, can be located and used as the subject of a Chimera render or animation. This particular example 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.

Build Instructions:

Files: Structures.py, 5HVP.cif, Structures.sh

Save Structures.py and the CIF data file. Run python Structures.py /path/to/file.cif, which generates a /path/to/5HVP.com file which you can open with chimera /path/to/5HVP.com Alternatively, you can save the script with Structures.py, set the Chimera path, and run ./Structures.sh /path/to/5HVP.cif, which will automate the process

Methods of Note

from pdbx.reader.PdbxContainers import ContainerBase
from pdbx.reader.PdbxContainers import DataCategory
  • getObj(self, name) Returns the DataCategory object specified by name.
  • getRowCount(self) Returns the number of rows in the category table.
  • getValue(self, attributeName=None, rowIndex=None) Returns the value of the attribute attributeName at row index rowIndex.

Example Source Code

"""
 Structures.py
 
 For some CIF file, generate a Chimera command (COM) file
 to iterate through and emphasize each structurally relevant site.

 Lines with superscriptions contain footnoted references or explanations.
"""

from os.path import splitext
from pdbx.reader.PdbxReader import PdbxReader
from pdbx.reader.PdbxContainers import *
from sys import argv, exit

def prepareOutFile(file, name) :
    file.write("windowsize 500 500\n") # Set the window size to 500 x 500px
    file.write("open %s\n" % name) # Open the CIF file
    file.write("preset apply pub 4\n") # Apply publication preset #4
    file.write("color white\n") # Color the molecule white
    file.write("set bg_color gray\n") # Color the background gray
    file.write("disp; repr bs; set silhouette\n") # Represent the atoms in ball-and-stick format
    file.write("savepos fullview\n") # Save this position (i.e., the full view of molecule)

def writeConnection(selection, file) :
    file.write("color green ligand\n")
    file.write("sel %s\n" % " | ".join(selection)) # Select the site members
    file.write("color blue sel\n") # Color them blue
    file.write("sel sel | ligand; wait 20\n") # Further select the ligand
    file.write("focus sel; wait 25; ~disp ~sel; wait 100\n") # Focus in on the selection and hide non-selected atoms
    file.write("disp ~sel; reset fullview 20\n") # Reset to the full molecule view
    file.write("color white sel; ~sel; wait 20\n") # Drop and uncolor the selection

# Check for improper usage
if len(argv) != 2 :
    exit("Usage: python Connections.py /path/to/file.cif")

# Open the CIF file
cif = open(argv[1])

# A list to be propagated with data blocks
data = []

# Create a PdbxReader object
pRd = PdbxReader(cif)

# Read the CIF file, propagating the data list
pRd.read(data)

# Close the CIF file, as it is no longer needed
cif.close()

# Retrieve the first data block
block = data[0]

# Retrieve the struct_site_gen category table, which delineates members of structurally relevant sites1
struct_site_gen = block.getObj("struct_site_gen")

# Use the CIF file pathname to generate the Chimera command file (.COM) pathname
(file, ext) = splitext(argv[1])
comFileName = file + ".com"

# Open the COM command file for writing
comFile = open(comFileName, 'w');

# Write out some basic Chimera initialization commands
prepareOutFile(comFile, argv[1])

# Store the site_id of the first row
currentSite = struct_site_gen["site_id"]

# A Chimera selection string list for the site
selection = []

# Iterate over the rows in struct_site_gen, where each row delineates a member of a structurally relevant site
for index in range(struct_site_gen.getRowCount()) :

    # Retrieve the site_id of the current row
    site = struct_site_gen.getValue("site_id", index)

    # Check for a new site
    if currentSite != site :

        # Write out commands for Chimera to customize the display of this site
        writeConnection(selection, comFile)

        # Set the current site_id to this site_id
        currentSite = site

        # Clear the selection string list
        selection = []

    # Append the latest site member2,3
    selection.append(":%s,%s.%s" % (struct_site_gen.getValue("auth_seq_id", index),
                                    struct_site_gen.getValue("auth_comp_id", index),
                                    struct_site_gen.getValue("auth_asym_id", index)))

# Write out commands for Chimera to customize the display of the last site
writeConnection(selection, comFile)

# Write out the Chimera close command, as all connections have been processed
comFile.write("stop\n")

# Close the COM file
comFile.close()

Example Images of the Structural Sites in 5HVP

Notes and References

  1. http://mmcif.wwpdb.org/dictionaries/mmcif_pdbx_v40.dic/Categories/struct_site_gen.html
  2. Note that for brevity we are assuming that author-provided values, which are non-mandatory but commonly present, exist for all of these attributes (viz., asym_id, comp_id, seq_id). In a more extensive program, their potential absence is easily accounted for with hasAttribute(self, attributeName), which returns a bool indicating the presence or absence of some attribute specified by attributeName. Note also that while some columns may be present, their values may be "?", which indicates a missing data item value, or ".", which indicates that there is no appropriate value for that data item or that it has been intentionally omitted.
  3. The form used here is :seq_id,comp_id.asym_id, based on the Chimera Atom Specification reference found here: http://www.cgl.ucsf.edu/chimera/1.2309/docs/UsersGuide/midas/frameatom_spec.html