The SPADE Molecular Viewer is a full featured 3D rendering tool for visualization of proteins and other macromolecules. Structure files can be downloaded from the public repository at the RCSB. Instructions for use are given in the walkthrough on this page. The rest of the documentation describes more detailed use of the MolecularViewer class, and re-programming the VTK graphics engine through the component class GraphicsVisitor.
The MolecularViewer object is a control class for rendering 3D molecular graphics. The code offers a set of high-level commands for controlling the representation and coloring of atoms, polymer traces, and molecular surfaces. These commands are enhanced with smart menu controls, image output, and undo/redo functionality. The viewer object is reused throughout the Structural Proteomics Application Development Environment (SPADE). It can also be run as a stand-alone application.
The MolecularSystem object is a data structure designed for general reuse in the SPADE context. MolecularSystem contains substructure classes that inherit from the two sources, class Atom and class Molecule, each of which contain their own rendering arguments. The .vtk_arg_dict attributes each index a set of standardized variable terms and values, that are collected by a GraphicsVisitor object and translated into 3D graphics. The class Atom .vtk_arg_dict contains color and opacity descriptors; .vtk_arg_dict from class Molecule \holds arguments covering whole-molecule details like specular and choice of representation (wireframe, space-fill, etc.). The .vtk_arg_dict from classes AminoAcid and Nucleotide handle color and opacity arguments for visualizing backbone traces. Class Polymer holds global arguments for trace renderings, like number of sides and number of splines to calculate between residues. See Appendix I for a complete listing and description of vtk_arg_list features.
GraphicsVisitor traverses the MolecularSystem component objects to collect visualization arguments (.vtk_arg_list attributes) for rendering. GraphicsVisitor uses these arguments to create VTK Actor objects. The Actors are then returned to the viewer object for rendering. This ‘visitor/mediator’ design pattern supports a high-level molecular graphics rendering command set, and separates the code for each of the viewer (MolecularViewer), its data source (MolecularSystem), and their visualization engine (GraphicsVisitor/VTK). This separation will support flexible development as the VTK and SPADE projects evolve.
A key feature that sets the SPADE Molecular Viewer apart is the MolecularSystem-based Undo/Redo functionality. Every time the MolecularViewer object updates its’ view, a copy of the graphics and selection parameters for each atom and molecule in the MolecularSystem is stored in a state that requires minimal memory. This simple system allows users to recover previous graphics states that may have taken substantial time to achieve. This also allows the “Restore Initial Memory” menu command in case the user wants to simply start over.
The MolecularSystem object is the ultimate data structure that the viewer uses to keep track of how to render and color each object. So, when these objects are stored (pickled, in python-speak) and reloaded, the viewer automatically regenerates the last representation. Users are consequently not forced to write or record scripts to regenerate graphical views.
Each Molecule and Atom object, and all of their children classes contain .features attributes, which provide a system for generating automatic “color-by-value” menu commands. Simply store a feature in any subset of residues or atoms .features attribute, under any title index (like “net charge”) and the viewer will automatically color the components in the range of blue to white, according to their values. If values are missing from some of the components, the viewer colors them green. See section 3 below for further details. These smart color-by menus are big time savers for common visualizations.
The entire python language and any importable libraries are available from the viewer’s command prompt, which can be opened or closed from the “Toggle Prompt” command available in the Viewer menu. The MolecularViewer instance and the currently loaded MolecularSystem are automatically available for use from the prompt, under specialized names. To affect the viewer itself, the variable name “viewer” is used. To reference the MolecularSystem object that is currently open in the viewer, the variable name “system” is available. A simple set of command keys (Ctrl-x = execute, Ctrl-n = open new script, etc.) are indicated in a label over the command prompt window. When the command prompt is open, all textual output is redirected from the python window to an output window in the viewer. Prompt usage is illustrated in sections 2 and 3 below.
Select mode allows graphics operations on subsets of the MolecularSystem objects that have been loaded. The Display and Options menus both allow the user to toggle selection mode. If selection mode is turned on, then before a command is executed, a popup allows the user to adjust which molecules, residues, and atoms are selected. The popup contains three columns, one for each level of structure. If the user selects one of the molecules from the first column, then clicks Select, the entire molecule is selected. If the Expand button is instead clicked, then a list of residues in the selected polymer is displayed in the second column for selection or further expansion into atom selection. The lower half of each column shows the current selection with a blue background, or if a polymer or residue contains partially-selected components it is colored light blue. The user closes the popup selection window to execute the command on the selected subset of the MolecularSystem object.
Academically produced, open source molecular viewers typically use exclusively-licensed software for production of molecular surface renderings. An alternative method has thus been implemented (and released under the BSD-license) which offers a pure Python implementation of an accurate and efficient solvent-excluded surface calculation, based on the work of Natsuhiko Futamura [IEEE Trans. Parallel Distrib. Syst. 13(6): 544-555 (2002)].
Programming with the MolecularViewer class is easy, as the following example illustrates. Open a Python interpreter in the SPADE home directory and enter the following commands. Alternatively, copy the commands to a script with a .py extension and execute it.
Open a viewer. A MolecularSystem object acts as a data structure for the MolecularViewer. Simply open a system with any PDB file, then open a Tkinter window and pass both as initial arguments to a new viewer. Additional code can then be added to adjust the rendering, before initiating the mainloop function of the viewer.
import MolecularViewer import MolecularSystem import Tkinter # # open a molecular structure system = MolecularSystem.System(‘any_pdb_file.pdb’) # open a molecular structure # # create a viewer window = Tkinter.Tk() viewer = MolecularViewer.MolecularViewer(window, system) # # show the window window.mainloop()Adjust the rendering by direct modification of vtk_arg_list values, from the viewer’s prompt. Once the mainloop function has been called, the python editor’s prompt is no longer available for scripting. Scripts can be entered and executed from a prompt loaded by the viewer instead. At the viewer’s prompt, the names ‘system’ and ‘viewer’ alias the viewer’s loaded MolecularSystem object and the viewer itself, which are the same aliases chosen for the first script. The following sections’ scripts could instead be placed just before the window.mainloop() statement of the previous script and still have their intended effects.
Open a prompt (Viewer>>Toggle Prompt) and enter the following scripts.
Adjust the trace representation and color by residue number.
chain = system.ProteinList[0] chain.vtk_arg_list['trace']['representation'] = 'tube' for resnum in range(len(chain.residues)): v = resnum/float(len(chain.residues)) chain.residues[resnum].vtk_arg_list['trace']['color'] = [v,v,1.0] viewer.update_view()Now hold down Control and hit ‘x’ (Ctrl+x) to save and execute the script.
Examine a variety of values. Explore rapidly with the Ctrl+X key combination.
system.ProteinList[0].vtk_arg_list['trace']['width'] = 0.4 system.ProteinList[0].vtk_arg_list['trace']['splines'] = 5 system.ProteinList[0].vtk_arg_list[‘trace’][‘sides’] = 5 viewer.update_view() # hit Ctrl+xNow adjust the values of the existing script and execute again.
system.ProteinList[0].vtk_arg_list['trace']['width'] = 0.8 system.ProteinList[0].vtk_arg_list['trace']['splines'] = 25 system.ProteinList[0].vtk_arg_list[‘trace’][‘sides’] = 25 viewer.update_view() # hit Ctrl+xUse the ‘color-by-feature’ automated menu system. The MolecularViewer comes with menus that are tailored to represent data specific to unique projects. Just add a numeric .features entry for all atoms or residues in a molecule. The viewer will normalize the values between zero and one and offer menu commands for automatic coloring. Values normalized close to zero are colored blue and those normalized near one are white. Enter the following script:
chain = system.ProteinList[0] for res in chain.residues: res.features[‘res_number’] = res.res_number for atom in res.atoms: atom.features[‘x_value’] = atom.x viewer.rebuild_color_menu()Execute with Ctrl+x. The .rebuild_color_menu command adds ‘x_value’ and ‘res_number’ entries to the submenus of the Color menu. Color the trace by the normalized residue number (Color >> Trace >> res_number_normalized). Now undisplay the trace (Display >> Trace >> Off), display atoms (Display >> Atoms >> On), and color them by their x-position (Color >> Atoms >> x_value_normalized).
File commands File >> Open PDB - open a PDB formatted structure file
File >> Save System - store the MolecularSystem object as a .sps file. This saves the current graphics arrangement, and all information in Molecule and Atom .features attributes, so that automatic menu commands show up upon reloading the MolecularSystem.
File >> Open System - open a SPADE .sps formatted structure file, including graphics and .features data.
File >> Open PDB - print out some basic information from PDB headers.
Viewer commands Display commands Display >> Display Atoms/Trace/Volume >> on/off
- turns the atom, trace, or volume renderings on or off. Coloring commands Color >> Color Atoms/Volume >> cpk
- colors atoms or volumes by the standard cpk color table, where carbon atoms are white, oxygen atoms are red, nitrogen atoms are blue, metals are pink, and sulfur atoms are yellow. Color >> Color Atoms/Trace/Volume >> type
- colors individual atoms, trace segments, or volume surfaces by a color table designed to enhance the intuitive grasp of the proteins structure. Essentially, atoms that carry charges or are adjacent to atoms that carry charges are colored yellow or red, where yellow represents a positive charge on arginine, lysine, and histidine, and red represents a negative charge on aspartic and glutamic acid. Orange is used to represent ‘sticky’ atoms that are polar but not charged. Cyan is used to represent the ‘cool’ hydrophobic atoms, and backbone atoms are colored dark blue to distinguish and hide them from the often more chemically interesting sidechain atoms.Color >> Color Trace >> Secondary
- colors the trace by secondary structure. Blue and red represent alpha helices and beta sheets, respectively. White is used for non-secondary structure regions. By default, the algorithm attempts to read the secondary structure assignments from the original pdb files. If this data is not available, the command transfers control to the assign_ss_from_alpha_carbon_distances function, located in the classProtein object. This algorithm assigns secondary structures from distances between alpha and beta carbon atoms. The algorithm will eventually be enhanced with hydrogen bonding terms.Color >> Color Atoms/Trace/Volume >> chain
- colors atoms, traces or volumes by the standard SPADE chain colors, as follow. If more than 12 chains are encountered, the colors simply repeat.1 [0.25,0.25,0.90], 2 [0.90,0.90,0.25], 3 [0.90,0.25,0.25], 4 [0.25,0.90,0.25] 5 [0.25,0.90,0.90], 6 [0.90,0.25,0.90], 7 [0.05,0.05,0.50], 8 [0.50,0.50,0.05] 9 [0.50,0.05,0.05], 10 [0.05,0.50,0.05], 11 [0.05,0.50,0.50], 12 [0.50,0.05,0.50]
Other menu commands are automatically generated by the following MolecularViewer commands:
color_atoms_by_atom_feature color_trace_by_atom_feature color_volume_by_atom_feature color_atoms_by_residue_feature color_trace_by_residue_feature color_volume_by_residue_feature
Each command collects values from .feature attributes from the target set (atoms or residues), and normalizes the values between zero and one. A color is then made between blue (for zero) and white (for one) to represent the value for each element. The .feature attribute is a dictionary, where keys like “burial” or “flexibility” index an atom or residue value for that feature.
Representation commands Options >> Atom Options >> wireframe/sticks/spheres
- adjusts Molecule objects’ vtk_arg_list to provide three rendering modes.Options >> Trace Options >> line/tube
- adjusts Polymer objects’ vtk_arg_list to provide two rendering modes.Options >> Trace/Volume Options >> transparency
- toggles between transparent and fully opaque renderingsOptions >> Volume Options >> surface/wireframe/points
- adjusts Molecule objects vtk_arg_list to provide three rendering modesOptions >> Trace/Volume Options >> transparency
- toggles between transparent and fully opaque renderingsClass Style Features Atom atoms color, opacity Atom volume color, opacity (not implemented) Residue trace color, opacity Molecule atoms visualize, currently_on, width, representation Molecule volume visualize, currently_on, specular, specular_power, representation Polymer trace visualize, currently_on, width, splines, sides, specular, specular_power
Atoms and residues store their own color (a three float list like [0.2,0.2,0.5]) and opacity (a float in range [0.0,1.0]) values. Atoms’ vtk_arg_list values are used to build renderings for both atoms and whole-molecule volumes. Residues’ values similarly inform the rendering of backbone traces.
Molecule and Polymer control global aspects of the three rendering styles. Specular (range [0,1]) and specular_power (range [0,500]???) control the reflectivity of the tube and volume surfaces. If ‘visualize’ is 1 for any style, the rendering is visualized at the next update_view call, else if 0, visibility is turned off. The ‘currently_on’ feature is automatically managed, and should not be manually modified. It indicates (by 1 or 0) whether the style’s rendering is currently visible. The ‘width’ feature for atoms style controls the width of atoms, and for the trace style controls the width of the tube representation, both in Angstroms. ‘splines’ and ‘sides’ features tell how many splines to interpolate between central atoms of residues, and how many sides to draw tubes with.
The representation feature selects a particular rendering mode. The different representations are listed in the following table.
Style Representations atoms wireframe, spheres volume line, tube, ribbon trace surface, wireframe, points
Download the file 1a0o.pdb from www.rcsb.org, or use the example (Telomere End-Binding Protein) PDB file in the Systems directory. Open the file from its current location and view the header information:
File >> Open PDB File >> Print System Info
Adjust the trace rendering and visualize secondary structure:
Options >> Trace Options >> Tube Color >> Trace >> Secondary
The system consists of two different proteins bound to each other. Orient the view so that the interface is clear. Open the prompt and calculate solvent accessibilities, in order to emphasize the interface:
Viewer >> Toggle Prompt Calculate >> Solvent Accessibility
Use the color-by-feature menu command:
Color >> Trace >> A binary_dif_asa Color >> Trace >> B binary_dif_asa
Visualize the atoms:
Display >> Display Atoms >> on Display >> Display Trace >> off Color >> Color Atoms >> A binary_dif_asa Options >> Atom Options >> Spheres
Visualize surfaces and color the interface:
Options >> Atom Options >> sticks Display >> Display Volumes >> on Color >> Color Volumes >> A binary_dif_asa
The “type” coloring scheme intuitively displays the surface properties of proteins, and offers rapid identification of amino acid types. Yellow atoms are positively charged, red atoms are negative, orange atoms are polar, and hydrophobic atoms are colored cyan. Visualize types information on surfaces:
Color >> Color Volumes >> type Display >> Display Volumes >> off Color >> Atoms >> type