|
|
The top-level menus reflect major categories of operations in the program. This section will just give brief descriptions of the menus and some of their commands. Comprehensive descriptions of operations is described in subsequent sections.
The File menu provides operations for opening, saving and closing PDB data files and RBD documents. The section Working with Files has more information about file operations.
The current definition of the Script menu is customized for working with Ribosomes and may change in the future. At this time, the submenu categories are 'Models', 'Features', 'Sequence', 'Geometry', 'Dynamics', 'Appearance' and 'Other'.
The View menu is used to control the viewpoint of the user in the graphics window, which displays the PDB models in 3D space. The menu includes commands to set the mouse movement mode to rotation, translation or zooming of the view, as well as options for controlling the rate of mouse movement. The section Navigating in 3D Space has more information on viewing operations.
Many operations require a current selection upon which to act. The Selection menu sets modes which combine with a mouse click in the graphics window to select or deselect objects. There are also commands to highlight the current selection using a color or box. The section Selecting Objects has more information on selection operations.
The Draw menu has commands to turn on and off the surface, backbone, covalent and spacefill presentation of molecules in the graphics window. It also provides commands for changing the color of objects. The section Displaying Objects has more information on display operations.
The Forcefield menu provides commands which relate to the molecular dynamics part of the program. There are commands for starting, stopping and single-stepping the forcefield, as well as toggle controls for the 5 component forces. There are also 2 submenus, 'Force Object' and 'Movie'. The section Forcefield and Dynamic Models has more information about forcefield operations.
The second item, 'Commands', will produce a text listing of the top level commands in the application status window.
The third item, 'Create HTML command reference', can be used to regenerate the local html files which describe the built-in commands, if they are missing for some reason. After executing the command, the user can run a web browser and manually open the 'cmd_index.html' file located in the 'doc/html/cmd_Index' subdirectory. However, these files only provide minimal syntax information for the commands, and more comprehensive information must be obtained from the main html documentation.
The Graphics window represents the PDB models in 3D space. The appearance is determined by the current viewpoint, which can be adjusted by mouse movement inside of the window with the left button held down. The section Navigating in 3D Space has more information on controlling the view of the graphics window.
The Status window displays information from the application in response to user commands, which may come from various sources including menu and toolbar clicks, console input and execution of scripts. The height of the Status window can be adjusted by moving the slider bar located between the Status window and the Graphics window.
The Pdb Tree window shows a hierarchical representation of PDB models which are loaded in the current document. The name of each PDB model will be listed on a item in the top listview box.
The contents of the lower listview boxes is determined by the selected state of the PDB models according to the following rules:
The selection of PDB components can be done by clicking with the mouse on items in the listview boxes, or by clicking parts of the model displayed in the Graphics window. The section Selecting Objects has more information on selection operations.
Note: currently, multiple selection of objects in the PDB window is not very functional. It should be improved at some point in the future.
The Pdb Tree window can be turned on or off by toggling the 'Pdb Tree Window' menu item in the Window menu. The width of the Pdb Tree window can be adjusted by moving the slider bar located between the Pdb Tree window and the Graphics window.
In addition to menu commands, the user can press the 'Enter' key, which brings up a dialog box where text commands can be given to the program. This 'console input' method provides more commands than are available through the graphical menus. The full set of console commands is documented in the Command Reference section, and can also be listed in the status window by entering 'help command' in the console input dialog. Responses to console input are sent to the Status Window.
A history of previously entered commands can be accessed using the 'UP' and 'DOWN' arrow keys when the command input dialog is shown.
When a pdb file is opened its first model becomes the current document in the Ribosome Builder program, replacing any previous model. This results in working with a single model at a time.
It is also possible to work with multiple PDB models in a document. This is done by inserting a PDB model instead of opening it. The 'Insert File' command in the 'Edit' menu is one way to do this.
If one or more PDB models have been loaded into a document, the geometrical
configuration and appearance of the models can be saved in an 'rbd' file
and easily restored at a later time. The rbd file stores only
the display state and position of the models; the original pdb files
are still needed for the structural data. In addition, the rbd file can contain
information needed to re-create force objects used in
Dynamic Modeling.
Saving Changes
After working with existing PDB models in a document, the user can save all or
part of the structural data into a new PDB file. This is done by selecting
the portion to be saved and choosing the 'Export Selection to PDB File' item
from the 'File' Menu.
Navigation refers to control of the viewpoint of this space. The user can transform the viewpoint, through translation and rotation, by providing input from mouse or keyboard.
Viewing in 3D space is more complex, not just from the added dimension,
but because there are multiple frames of reference. There is the frame
of reference that belongs to the user, as seen from the viewpoint, and
there is the world frame of the 3D space.
Rotation
When initially viewing a PDB model, the object is positioned in 3D space
so that it is entirely in view, and the center of rotation is at the center
of the model. Then, by holding the left mouse button down and moving the
mouse in the graphics window, the user can conveniently rotate the entire
object about the x and y axes of the view frame. The x-y rotation mode
is set by clicking the 'Rotate XY' icon, 
.
To rotate the model about the z axis, which points out of the screen, the
mouse movement mode is set by clicking the 'Rotate Z' icon,
, or by holding down the 'z' key, and
the rotation is done by moving the mouse, with left button down, in the
vertical direction.
Translation
To translate the model about the x and y axes, which point in the right and
top directions of the screen, the mouse movement mode is set by clicking
the 'Translate XY' icon, 
, or by holding
down the 'CTRL' key, and the translation is done by moving the mouse, with
left button down, in the horizontal and vertical directions.
To translate the model about the z axis, which points out of the screen,
the mouse movement mode is set by clicking the 'Translate Z' icon,
, or by holding down the 'SHIFT' key,
and the translation is done by moving the mouse, with left button down, in
the vertical direction.
Specifying a Rotation Center
When doing rotation, the center point of the rotation must be
specified in addition to the axis about which the rotation occurs. Typically
in molecular viewing programs the center point of rotation is fixed about some
point in the 3D space world frame, such as the center of a PDB model. This
is also the default behaviour of the Ribosome Builder program. However, there
is also a 'fly' mode, which is sometimes useful, where rotation occurs with
respect to the view frame.
When examining an object, it is often useful to specify that the center of
rotation should be at the geometrical center of the object. A convenient
way to do this is to select the object and click the 'set rotation center'
icon, 
, or press the 'g' key.
For example, if you want to examine a particular residue of a PDB model,
select the residue and click the 'set rotation center' icon. The rotation
center axes will appear at the center of the residue and subsequent mouse
movements will cause the view to rotate around this center.
More information on the details of selection is in the
Selecting Objects section below.
Adjusting the Mouse Movement Rate
When the view is very close to an object being examined, the default mouse
movement rate will produce excessive movement. The mouse movement rate
can be adjusted to a slower speed by choosing the 'Mouse', 'Move Slow' item
from the 'View' menu. Arbitrary adjustment of the mouse movement rate
can also be done using the 'mouse moveRate'
command.
Resetting the View
Because the user can navigate to any part of the 3D space, it is possible to
become 'lost', where the PDB models cannot be seen. If this occurs, there
are a couple of ways to restore the viewpoint to a known location. If the option
'Enable Center on Inserted Object' is checked in the View menu, the user can
press the 'F5' key or select 'Reset View' and the view will be re-centered on
the most recently inserted PDB model. Alternatively, the user can turn on the
forcefield volume, which is a graphical representation of a wireframe cube with
a solid floor, by pressing the 'l' key or selecting the 'Forcefield Volume' item
from the view menu. Display of the forcefield volume enables the user to navigate
back to a known location in the 3D space.
Flying Mode
Typically in molecular viewing programs the center point of rotation is fixed
about some point in the 3D space world frame, such as the center of a PDB model.
This is also the default behaviour of the Ribosome Builder program. However, there
is also a 'fly' mode, which is sometimes useful, where rotation occurs with
respect to the view frame. This mode is set by clicking the 'Fly Mode' icon,
.
Selection of objects is an important part of the program because many operations
only act upon the current selection. There are a variety of ways to select
objects and to indicate which objects are selected.
Object Hierarchy
The PDB models define and reflect a natural hierarchy in which objects are
organized according to different levels of size. In this program, there are
currently 4 levels which are defined for static models: Pdb, Chain, Residue and
Atom. The highest level in the hierarchy is 'Pdb', which consists of all the
chains in a model. The next lowest level is 'Chain', which consists of a set
of residues in a sequence. In most cases, a chain consists of a set of amino
acid or nucleic acid residues which make up a protein, DNA or RNA molecule.
However, it is also common to organize a set of metal atoms into a 'pseudo-chain'.
The next lowest level is 'Residue', and the final lowest level is 'Atom'.
The current implementation of the Ribosome Builder program only provides for
selection down to the 'Residue' level for static models.
Selection By Mouse
One of the easiest ways to select objects is to use the mouse. If the mouse
select mode is enabled by clicking the 'Mouse Selection' icon,
, or by holding down the 's' key, then
clicking the left mouse button in the graphics window will select an object
which is underneath the mouse pointer.
The type of object which is selected depends upon the current hierarchy level.
For static models the current level is set by clicking one of the 3 hierarchy level icons,
'Pdb' 
,
'Chain', 
, and
'Residue', 
. The levels can also be
set by pressing the 'p', 'c' and 'r' keys.
When selecting residues within a chain, a sequential range of residues can be conveniently selected by selecting a single residue at one end of the sequence, then holding down the SHIFT key and selecting the single residue at the other end of the sequence. This will cause all residues in between to be selected too.
Note: the 'Node' selection icon, 
,
and the 'n' key are used to select nodes, which only apply to dynamic models as
discussed in the section Forcefield and Dynamic Models.
Selection By Pdb Tree
The Pdb Tree window can also be used to select objects
at different levels in the hierarchy by clicking on an item in one of the listview
boxes. It is also possible to do range selection in this way,
by holding down the shift key while clicking a second item in a listview box.
Note however that if multiple items are selected at one level, this will
inhibit display of their component items at the lower levels.
Selection By Command
The Command Input Box provides a another way of selecting
objects, using the 'sel' command.
The complete syntax specification for this
command is given in the Command Reference pages.
The most common interactive way of using the 'sel' command is to select objects by name, using a hierarchical dot notation which has the following format: <sPdb>.<sChainId>.<sRes>
In this notation, <sPdb> refers to the name of the PDB model, <sChainId> refers to the chain ID and <sRes> refers to the name of a residue in the chain.
For example, to select the first residue of the first chain of PDB model 1tra, the following command could be used:
sel name 1tra.a.G1
Note that in general, all names, commands and keyboard shortcuts in the
Ribosome Builder program are case sensitive, so the following command would
NOT work: sel name 1tra.A.g1
To select a range of objects using the sel command, a beginning object name is given, followed by a space, a dash, a second space and an ending object name: 'sel name <objNameBegin> - <objNameEnd>'
For example, the command below selects the first 5 residues of the 1tra PDB model:
sel name 1tra.a.G1 - 1tra.a.A5
Selection By Geometry
Selecting all objects within a given radius can be done with a geometrical selection
tool called the 'selection sphere'. This tool is implemented in the
sel sphere commands that let the user define
the origin and radius of a selection volume. In addition a graphical display of the volume
is provided for additional feedback.
An example of selection with the selection sphere is shown below. The sphere is defined with a 20 A radius and is positioned at the center of residue C422 in PDB model 1j5e. The criterion for selection of a residue is for any of its atoms to intersect the boundary of the selection sphere. In the image below some selected residues appear to be outside of the selection sphere radius because only the backbone segment is drawn. In the spacefill representation one or more of the atoms of a selected residue would be seen to intersect the sphere.
Note: only static models are currently selected by the selection sphere.
Selection By Script
The Selection functions in the Script Api are
another way of selecting objects which are often more complex but can provide great power and flexibility.
An example of scripted selection that selects a set of residues based upon geometrical
distance to another set of residues is described below in the Additional Tools and Features section
in the example on Distance-based Selection.
Add/Remove Mode
The default behavior when doing a new selection is that the previous selection
is cleared. However, it is possible to set the selection mode to 'add/remove'
by clicking the 'Add/Remove' icon, 
or by pressing the 't' key. In this mode, newly-selected objects will be added
to the current selection. If a selected object is clicked, it will be removed
from the current selection.
Displaying the Current Selection
A special color can be used when drawing selected objects to identify them
from the non-selected set of objects. The 'Flash Selection' option in the
Select menu is normally set and results in newly-selected objects being
drawn with the selection color for a short period of time. Then the normal
color of the objects is restored. This behaviour is often desireable because
the constant display of selection color can be distracting.
There are times however when it is desireable to explicitly display the
selected objects with color. This is done by clicking the 'Color Selection' icon,
, or by pressing the 'h' key.
The geometrical boundaries of the current selection can be displayed by
clicking the 'Box Selection' icon, 
.
Reporting the Current Selection
When there are multiple PDB models in the current document and multiple
selected components, a summary report of the current selection can be
produced by choosing the 'Report', 'Summary' item from the select menu.
A typical summary report is shown below:
pdbObject 0:
| 1tra:
| 76 residue(s) selected.
| pdbObject 1:
| 1fka:
| 136 residue(s) selected.
| pdbObject 2:
| 1eft:
| 6 residue(s) selected.
| |
A detailed selection report can be also produced. The output includes sequence information in a format that enables sequence alignments to be done on PDB models:
--- Chain 1tra.a:
76 residue(s) selected: 1 ... 76 ( G1 ... A76 ):
G1 C2 G3 G4 A5 U6 U7 U8 A9 2MG10
C11 U12 C13 A14 G15 H2U16 H2U17 G18 G19 G20
A21 G22 A23 G24 C25 M2G26 C27 C28 A29 G30
A31 OMC32 U33 OMG34 A35 A36 YG37 A38 PSU39 5MC40
U41 G42 G43 A44 G45 7MG46 U47 C48 5MC49 U50
G51 U52 G53 5MU54 PSU55 C56 G57 1MA58 U59 C60
C61 A62 C63 A64 G65 A66 A67 U68 U69 C70
G71 C72 A73 C74 C75 A76
Sequence:
1 GCGGAUUUAG CUCAGUUGGG AGAGCGCCAG ACUGAA-AUC UGGAGGUCCU
51 GUGUUCGAUC CACAGAAUUC GCACCA
The structure of PDB models can be represented in various ways, including
display of the surface, backbone, covalent bonds and spacefilling atoms.
The commands to toggle these representations always act upon the
current selection. The commands are also defined as complementary
sets, as shown in the toolbar above. The first 4 icons turn ON display
of surface, backbone, covalent bonds and spacefill atoms. The next 4
icons turn these features OFF. The next 2 icons display the current
selection as 'ball-and-stick' and 'wireframe', respectively.
Surface Representation
The surface representation of a structure is only an approximate boundary around the vanderwaals radii of the atoms. It is designed for rapid computational generation and does not reflect the true solvent-accessible surface of a molecule. A single surface can be generated for an entire PDB model, or individual surfaces can be generated for each of the chains, as indicated in the 'Surface' submenu of the 'Draw' menu, and 'Surface' toolbar. It is also possible to display surfaces with transparency.
Currently, surfaces meshes are drawn in an order determined by the list of models in
the document. As a result, when displaying multiple transparent surfaces, the
clipping of obstructed surfaces is not correct and a transparent surface behind another
transparent surface may actually appear to be in front of it. At some point in the future
a proper sorting of all transparent surface triangles will be done to correct this problem.
Backbone Representation
The backbone representation of a structure consists of segments which are
drawn between the backbone atoms of residues. For nucleic acid chains,
these are the Phosphorus atoms. For protein chains, these are the alpha
Carbon atoms. In addition to the toolbar icons, the display of the
backbone can be toggled on and off using the 'b' and 'B' keys. The
thickness of the backbone can be set using the 'draw backbone <N>'
command, where N is a scaling factor which can range from [0,6].
Covalent Bonds
Covalent bonds can be drawn between pairs of atoms for which a bond
has been defined. When a model is loaded, the program attempts to
create a single bond between pairs of atoms based upon their relative
proximity and bonding availabilty. In addition to the toolbar icons,
the display of covalent bonds can be toggled on and off using the 'v'
and 'V' keys. The thickness of the bonds can be set using the
'draw covalent <N>' command, where N is a scaling factor that
can range from [0,6].
The current implementation of the program does not produce bonds that
are specified by 'CONECT' records.
Spacefill Atoms
The vanderwaals boundaries of atoms can be indicated by display of spacefilling
spheres drawn around the centers of the atoms. The radii of the spheres can be
scaled using the 'draw spacefill <N>' command, where N is a scaling
factor that can range from [0,6].
Changing Colors
The color of the current selection can be changed to any hue specified by 3 floating point values which range between [0,1], where the 3 values are the red, green and blue components of the color. This is done by entering the 'color rgb <r> <g> <b>' command.
There are also predefined colors which can be specified by name using the 'color name <colorName>' command. The 'Color', 'Name' submenu of the 'Draw' menu and the 'Color' toolbar also provide access to these predefined colors.
When displaying individual atoms or bonds, the CPK color can be specified, which will color each atom and its portion of its bonds with a color determined by its type of element.
Note: if the 'Color Selection' mode is on, the color of the current selection will be displayed with the bright yellow 'selected' color instead of the defined color of the objects.
or hold down the 'space' key
while moving the mouse with left button down in the graphics window.
For example, with the 1tra pdb model loaded, the command 'sel set rotCen 1tra.a.A76.P' will set to rotation center
at the center of the backbone phosphorus atom for the terminal A76 residue. Then, with the entire model selected,
it can be rotated around this phosphorus atom center point by holding down the 'space' key and moving the mouse
with left button down.
Displaying the Volume Boundary as an External Frame of Reference
When arranging models within the 3D space it can be convenient to show
a boundary representation of the space to provide a frame of reference. This can
be done by toggling the 'Forcefield Volume' item in the 'View' menu. The
size and other features of this volume boundary can also be adjusted with
the vol command.
Quantitative Positioning
The position of models can be adjusted quantitatively by using the
pos ,
rot and
trans commands. The pos command
is used to set the center of a selection to some absolute position
in the 3D space. The rot command is used to apply a rotation to the
current selection. The rotation axis can be relative to the view frame
('rot sel') or the world frame ('rot selAbsVec'). For these commands the center point
around which rotation occurs is the center of mass of the selection. An arbitrary world frame
rotation center can be specified with the commands 'rot selAbsCen' and 'rot selAbsVecAbsCen'.
The trans commands can apply a translation in the view frame ('trans sel') or
world frame ('trans selAbs'). The original position of a static PDB model can be restored with the
'pos sel resetTransform' command. The original position of a dynamic model can be restored with
the command 'ff fo reset'.
Programmed Positioning
More precise positioning of models can be achieved by the execution of
user-defined programs which can be written in the built-in scripting language,
Lua, which is discussed in more detail in the
Scripting section. The scripting API (Application
Programming Interface) has several categories of predefined functions
that are useful for programmed positioning of objects, including the
Selection Functions and
Geometry Functions and
Vector Functions.
Some examples of programmed positioning can be found in the 'Script', 'Geometry', 'Align' menu, such as 'Align Pdbs from Selected Residues' and 'Find Best Helix Alignment'. The source code for these scripts is located in the lua subdirectory in the files AlignSelectedResidues.lua and FindBestHelixAlign.lua.
Note: these scripts have not yet been 'cleaned up' to serve as nice pedagogical examples.
The simulation of forces and dynamic movement of molecules requires additional computational and data storage resources beyond what is needed for static models. For large models these additional resources may excessively reduce the performance and response of the program. For this reason the dynamic modeling of molecules is done on a subset of the static models that the user has converted into a dynamic representation.
The dynamic portion exists in a sort of parallel hierarchy with the static models,
and the current implementation of operations on dynamic models is incomplete, so
there is some potential for confusion and inconsistency.
Creation of Dynamic Segments
Dynamic models are created by selecting some portion of a static PDB model and
choosing the item 'Force Object', 'Create' from the 'Forcefield' menu. For
each contiguous set of residues in the selection, a 'Dynamic Segment' will
be produced.
The image above shows the numeric labels of nodes that compose a single dynamic residue. Node 0 consists of the Phosphorus atom and its two oxygens O1P and O2P. Node 1 consists of the single atom O5*. Node 2 consists of C5* and its two hydrogens. Node 3 consists of the atoms in the ribose ring, and their hydrogens. Node 4 consists of O3*. Node 5 consists of O2* and its hydrogen. Node 6 consists of the base ring atoms, excluding the exocyclic amine. Node 7 consists of N2 and its two hydrogens.
Note: in the current implementation, all dynamic models which are saved together as a single rbd document must be created in a uniform way, either as 'single-atom-nodes' or not. Loading of documents with heterogeneously-created models will fail. The state of this flag at the time the document is saved is what will determine which kind of node creation will occur when the document is reloaded.
Within a dynamic segment, the individual dynamic residues are currently designated as 'Force Objects', and the 'Force Object' submenu contains some operations that apply only to force objects. Force objects in general will be treated in the same way as static residues for many of the 'Select' and 'Draw' operations, but not all.
When a dynamic residue is created from a static one, hydrogen atoms and additional bonds are automatically added as needed. A dynamic residue can be distinguished from a static one by the appearance of pink and green 'bond vector' lines, which are drawn from the centers of hydrogen bond acceptor atoms and hydrogen atoms:
A full listing of the current values of the parameters can be produced in the status window with the
'ff paramsReport' command. The value of each parameter can also be displayed
and set individually. The values of all the parameters are reset to the default value with the 'ff reset'
command and also each time a new document is loaded. The parameters can be saved to and read from a file
with the 'ff paramsWrite' and 'ff paramsRead' commands. Note that these
parameters are global values that apply to all objects in the forcefield. There are also additional enabling
options that can be set for individual dynamic residues and nodes in the 'ff fo enable' command group.
Disabling Movement and Interaction of Force Objects
The movement of individual dynamic residues can be disabled using the 'ff fo enable move' command or clicking the corresponding icon on the forcefield toolbar. This is often useful when the user wishes to observe the forces acting on an object without letting its conformation be changed. In addition, intra-residue and inter-residue force calculations can be selectively disabled with the 'ff fo enable internalForceCalc' and 'ff fo enable externalForceCalc' commands or corresponding toolbar icons. By disabling all the force interactions for a dynamic residue, it can be effectively 'removed' from the forcefield on a temporary basis. If the disabled subset is large, this can significantly improve the performance of the forcefield simulation.
Note: disabling internal force calculations for a force object will disable all of the force interactions between the atoms of that force object. In addition, in the current implementation, it will also disable some force interactions between the atoms of that force object and the atoms of a bonded adjacent force object in the dynamic segment. Therefore, if a subset of a dynamic model has been 'locked down' by disabling movement for the force objects of that subset, then 'internal force calculations' can be safely disabled for all force objects of the subset except for those that are on the boundary. Boundary force objects are those that are directly connected to actively moving force objects. Internal force calcuations should not be disabled for these boundary residues.
All of these commands act upon the currently selected set of dynamic residues. See the sections User-Defined Forces and User-Defined
Forcefield Interactions in this manual for additional information on selective enabling of force objects.
Running the Forcefield
After dynamic segments have been created, their activity can be simulated
in the forcefield. The run state of the forcefield can be set by clicking
the 'Run' icon, 
or pressing the 'ALT-r' key.
When the forcefield is running, a green text label with the word "Running"
is displayed in the graphics window and a timestep count to the left is
incremented with each timestep. The 5 component forces, Steric, Covalent,
Electrostatic, Hydrogen-Bond and Ring-Stack, can be enabled or disabled
by toggling the icons to the right of the 'Run' icon. Many of the
parameters that are used in the forcefield can be viewed with the
'ff reportSettings' command. The values of individual parameters can
be viewed and set by
Note: the current implementation of the forcefield is at an early
stage of development and the parameters are still being refined. The
magnitudes of the forces and associated energies do not correspond to
empirical values like those found in other forcefields such as
AMBER or CHARMm.
Displaying Forces
The magnitude and direction of the component forces acting upon the dynamic residues can be displayed by clicking the icons in the 'Forcefield', 'Force Object', 'ForceDisplay' menu or the 'Force Display' toolbar. The icons are arranged in 2 complementary sets which toggle on or off, in the same way as the 'Draw' toolbar icons. The toggling of displayed forces applies only to the currently selected dynamic residues (force objects). At least 1 timestep is required after enabling the display of forces, because the information is only recorded as requested. There can be a significant performance penalty if forces are displayed for large numbers of objects.
For forces with very large magnitudes it is often useful to scale the
length of the force arrows by clicking the 'Log Scale' icon,
.
Recording and Playing Movies
One of the design goals of the Ribosome Builder program is to investigate long time scale activities such as hydrogen-bonding and large conformational changes, and to do so in a reasonable amount of real-time computation on conventional single-processor desktop computers.
Because the forcefield simulator is not constrained to realistic physical timescales (such as the femtosecond timesteps found in typical molecular dynamics engines), a greater degree of dynamic behaviour can be observed. However, the behavior still falls short of real-time interactive rates. To address this computational limitation the program provides for recording and playback of 'movies' of molecular activity.
To record a movie, choose the 'Record Icon', 
on the 'ForceField', 'Movie' menu or 'Movie' toolbar. The 'Recording' and
'Frame' indicators will be displayed in the graphics window. When the
forcefield is running a movie frame will be recorded for every N timesteps,
where N defaults to 100. The recording rate can be adjusted using the
'ff movie recordRate' command. To stop and playback the movie, the other
movie icons are used in a manner similar to typical recording/playback devices.
The default output filename is '~movie.coord.tmp' in the current working directory
and can be changed using the 'ff movie outfile' command. Previously recorded movies
can be loaded by using the 'ff movie infile' command. However, in order for the proper
playback to occur the configuration of the objects in the forcefield must
be the same as that when the movie was recorded. Ribosome Builder Document
files can save and restore the set of force objects that are associated with a particular movie.
Tip: continual development of the program has caused changes in the definition of dynamic models, and consequently, causes incompatibilities with movies recorded in older versions of the program. To address this problem, a script, 'ExportMovieFrames.lua', was created that lets the user export frames of a recorded movie to a set of .PDB files. This allows the user to apply other tools to analyze and view the data of the movie in a way that remains independent of changes in the Ribosome Builder program.
Tip: if the initial configuration of a model has large steric clashes, the threshold error for
covalent bonding may be exceeded, halting the forcefield simulation. This is a useful indication
to the user that a chemical constraint has been violated, but it can be annoying if the user
desires to do a long, unattended simulation and movie recording. To circumvent the covalent
bonding error threshold, the user can set the value to an arbitrarily high amount by entering a
command such as 'ff covalentFailDist 10' (sets the error threshold to 10 Angstroms).
Analyzing and Reporting Results
The analysis and reporting of data generated during forcefield simulations
is still under development. Total energies for each of the 5 types of
forces can be monitored and output each timestep (although only through the
script API at this time). Output of detailed interaction data for atom
and residue pairs can be enabled, and there are some preliminary scripts which
do energy analysis and reporting, such as the 'Steric Energy Report' item
in the 'Script', 'Energy' menu. An external web browser can be used to view
tabulated data and to interactively produce annotations for the dynamic models
in the graphics window of the Ribosome Builder program. Refer to the sections
Annotations and
Web Browser Interface for more information.
For example, we can consider an annotation such a text label and graphical arrow that describe the distance between 2 atoms in a printed picture of a molecule. The analogous annotation can be produced in a 3D graphics window that displays a molecule, but if the molecule is changing conformation the annotation must also change dynamically to reflect the changing distance between the atoms.
This dynamic property of annotations is implemented in the program through the use of 'Script Objects', which are chunks of executeable code and data that can receive processing time and produce graphical output. The objects are defined by writing code that is interpreted by the built-in scripting language, discussed in more detail in the section on Scripting.
An additional benefit of implementing annotations with scripting code is that
it allows for a much faster and greater degree of variability and customization
than would be possible if the annotation functionality had to be produced by the
core rendering and simulation software components. One drawback is
that the performance from scripted annotations is generally far less than
what can be achieved by core code. This is usually not a problem however,
since annotations are often needed only for small subsets of a model.
Also if performance for a particular kind of annotation is definitely required
it can added to the core engine as needed.
An Example Annotation
A concrete example of an annotation in the program is the 'Draw Atom Names'
item in the 'Script', 'Appearance' menu. Choosing this item when one or
more residues are selected will result in the drawing of text labels that show
the atom names of the selected residues. The scripting code for this annotation
is in DrawAtomNames.lua
and DrawAtomNames.draw.lua
files in the lua subdirectory. To delete the annotation, choose the
'Delete All Annotations' item from the 'Edit' menu.
From Annotations to Script Objects
The functionality of an annotation can evolve gradually from a purely descriptive role to one that actively monitors and influences a complex simulation. At this point the term 'Script Object' is a better way to refer to the functionality.
The development of scripts by the user does require some knowledge of basic programming concepts as well as a commitment to learning the syntax and usage of a particular language and supporting libraries and APIs . For the biological researcher, the benefits from learning basic programming skills can be expected to follow the growth of bioinformatics tools and applications.
The current version of the embedded Lua interpreter is 4.0.1 and the
reference manual for this version is available
online
and for downloading as a
PDF document.
Script API for Ribosome Builder
There is an API, which is a set of functions written in Lua, that provides
access to the operations and data in the Ribosome Builder program. The
functions are organized by category and documented in the
Index of Lua Library Functions. The source
code for the library is located in the lua subdirectory.
Before calling a function in the library, the code for the function must
be loaded. This can be done by putting the line 'load( <filename> );'
at some point in the script before the function is called. The filename
to use is mentioned in the API documentation for the function under the
'include' section.
Running Scripts
After creating a script in a text editor and saving it as a file, the
user can run the script by entering the command 'script run <scriptFile>'
in the Command Input dialog.
When running scripts that are located elsewhere from the default working directory
(which is the application base directory), the filename must be
preceded by the directory path. For example, on MS Windows platforms, a script
named 'scriptFile.lua' that is located in the lua subdirectory would be run
with the command 'script run lua\scriptFile.lua'. If the script is saved in some other
directory, that path should be prepended to the filename. To create paths portably
in scripts, the makePath() function can be used.
If an error occurs while running the script, the error information will be output to the application status window. For syntax errors, the script interpreter provides stack and line number information which is helpful in debugging the script. The API function stdOut() is also useful and can be embedded in a script to do 'printf()-style' debugging.
Another way that scripts can be run is to create an entry in the ScriptDefs.ini file that is used to define the user-customizable menu tree in the top-level 'Script' menu. After making the changes to the ini file, the program must be restarted for the menu entry to appear. In the current implementation these script files must be located in the lua subdirectory.
Note: when calling one script from another, use the 'runScript()' function instead of doing
'inputCommand( "script run <scriptFile>" )', as discussed in the
FAQ.
Script Objects
Many scripts are written to do a job that runs until done and then
the script execution terminates. However, there are situations where
a script needs to persist over time until the user is done with it.
An example would be the
annotation script mentioned in the Annotation section.
To acheive this persistence, two script files are used. One, 'DrawAtomNames.lua'
is an initialization script that creates the persistent script object (which is actually maintained
as an item in memory by the application core code). The other file
is a 'template' script, 'DrawAtomNames.draw.lua',
that is copied to a subdirectory created for the persistent script object.
This template script defines a 'draw()' function that is called periodically by the application.
In the draw() event the script object produces output in the graphics window according
to the user-defined code in the 'template' script. Writing code for
persistent script objects is more complicated than creating 'one-off'
scripts and additional documentation and examples will be developed.
Script Object Creation
A script object is created in an initialization script by calling the rbq lua api
function createScriptObject(). This
function requires a unique name for the script object. This name will
subsequently be used as a handle to refer to the script object in other script-related functions.
A unique name can be obtained with the getFreeGraphicObjectName()
function.
After creating the script object, the user can create and initialize persistent variables that are associated with the object. These variables can be read and written during the execution of script object event code using the Lua 'getglobal()' and 'setglobal()' functions. Variables are added by calling the addScriptObjectVar() function. The values of the variables can also be inspected and modified by the user through the command input dialog with the 'script so' command group. Scriptable access of the variables outside of an event script is done with the functions getScriptObjectVar() and setScriptObjectVar().
When a script object is created, a subdirectory with the same name as the script object is created
in the script object parent directory. The path for this parent directory can be obtained
by calling the getScriptObjectDir() function. Then,
a path to the subdirectory can be created, allowing for template script files to be copied to the
script object subdirectory where they will function as event scripts. For example, when the
lua/DrawAtomNames.lua script is run, a new script object name
'drawAtomNames' is created for it. In addition, an associated directory, 'lua/tmp/drawAtomNames' is created,
and it contains a single file, 'draw.lua', that contains the annotation code for the drawing event.
Script Object Events
The template script mentioned above is an example of an 'event' script. If
an event script with the appropriate name is created and copied to a subdirectory
associated with the script object, the event script will be executed by the
Ribosome Builder application when the event occurs. Currently there are 6
predefined events that can be handled by such scripts. The script filenames
for these events are listed below:
The draw.lua script and the drawTransparent.lua scripts are called during the drawing phase of the application. These scripts are typically used to display annotations and other graphical information.
The tick.lua script is called periodically with a frequency equal to the application main event loop. This is also the same frequency as the forcefield timestep event. Currently, script object tick event scripts are executed just prior to the forcefield timestep event. This periodic script is useful for things such as animation and monitoring forcefield activity.
To actually apply external forces from an event script however, the fiTick.lua script must be used ('force input' tick), because force input must occur at a point inside of the timestep event, prior to timestep movement. See the section User-Defined Forces for more information.
The keyDown.lua and keyUp.lua scripts allow for script handling of keystrokes. This allows
the user to customize the keyboard. However, the current functionality of these events is limited.
Script Object Deletion
Because script objects can execute code, it is possible for a script object to attempt to delete itself,
or some other script object, from within a block of executing script object code. To prevent such problems,
and others, the current implementation prevents attempts to delete script objects during the execution
of script object tick() event code, and the error 'Error: can't delete annotations during execution of script object events.'
will be reported. To safely delete a script object, the function
scheduleDeleteScriptObject() should be called instead.
Note: in the current implementation, script objects are deleted when the current document is closed. Consequently, attempts to close the document from within script object event code will fail with the error message 'Error: can't close current document during execution of script object events'. If it is desired to do scripted loading of new PDB models, they can just be inserted and deleted within the current document.
The Ribosome Builder program provides a means of interfacing with a web browser to display supplementary information. Html documents can be created to show a hyper-linked collection of textual and 2D graphical information. In addition, some of the links in the browser can be defined to send requests to the Ribosome Builder program, which can be configured to listen to HTTP GET requests on a pre-defined port number on the host machine. The program can then carry out the requests, which may be commands to load files, select objects or create annotations. In this way, a complex set of commands and configuration sequences may be conveniently organized as hyper-links in html documents.
Some preliminary examples of program-browser integration exist in the
'exp' subdirectory, such as 'exp/dev/sub30/1fka'. Combinations of Lua
and Perl scripts are used to generate html reports. Detailed
steric interaction reports can be created that list tables of atom-pair
interactions. Each entry in an html table can contain a hyperlink to produce an
annotation of the interaction in the Ribosome Builder graphics window.
The 'htsrv.exe' Utility
The implementation of response to browser GET requests is done by running a simple
http server process that listens for socket connections on a particular port number
of the host machine. This process is run automatically on startup of the rbq application
by executing the 'htsrv.exe' file, located in the application base directory. HTTP requests
and responses are echoed to the initial application console window.
Note: the htsrv process will only accept socket connections
originating from the localhost IP (127.0.0.1), but if a network configuration
permitted spoofing of the localhost IP, this would represent a potential security
vulnerability that might enable an attacker from an outside host to run arbitrary
code on the local host. If it is desired to eliminate any possibility of a network
vulnerability, the htsrv.exe application can be deleted or moved from the application
base directory prior to the application startup. The rbq application will run normally,
but the interface to the web browser will not be available.
Using Frames
For convenient use of a browser to request execution of scripts by the rbq application, the html documents are typically configured as frames in the browser, where a small status frame is displayed at the top of the browser window and the main content is displayed in another frame below it. This allows the status of a script request to be displyed to the user when they click on a script-request hyperlink in the main frame. The source of the 3 html files in 'exp/dev/ahelix/def' provides an example of defining status and main frames for browser script requests:
Note: if viewing these files in a web browser, choose the 'View Page Source' option to
see the actual html code.
Example: Loading a Document from the Browser
In the 'main.html' file, a script execution request is implemented as a hyperlink that requests a root pathname from the localhost with the actual script file specified as a CGI query string that follows the pathname. The request is made to a port number on the localhost where the rbq http server is listening. This port number is reconfigurable by the user, but the current port number is 25546. An example script request hyperlink is shown below:
<a target="status" href="http://localhost:25546/?scriptFile=lod_ahelix.lua">Load ahelix.rbd</a>
Currently, 3 keywords are defined for script requests: 'scriptPath', 'scriptFile' and 'absScriptFile'. 'scriptPath' is used to set a default path to a directory that contains lua script files for execution. Setting this path allows subsequent 'scriptFile' requests to specify the filename only. Alternatively, the absolute path of a filename can be specified using the 'absScriptFile' keyword.
In addition to specifying the filename of a lua script to be executed, the hyperlink can also contain optional parameters to be passed to the script. These are defined according to the CGI query format where parameters are separated by the '&' character and spaces and other special characters are encoded using the '%NN' codes (refer to CGI scripting specifications for more information). The entire query string following the 'scriptFile=<fileName>' parameter will be passed to a script and can be accessed using the rbq scripting API functions such as getCmdLine() and getCgiParamValues().
Note: currently, the only 'special' characters that are URL decoded are the path separator character '/', encoded as '%2F', and the space character ' ', encoded as '%20'.
However, if the user loads a pdb model which does not have any sequence maps defined for it, a new sequence alignment file must be created for an rRNA chain of that model. Such an alignment can created using an external tool such as 'globals' in the seqalign library. Then the sequence alignment must be converted into a special format called a 'sequence map', which is used by the Ribosome Builder program. This can be done by running the associated tool 'gensmap.exe'. These external tools are included in the normal distribution of the Ribosome Builder program. In addition, a script, CreateSeqMap.lua, can be run by the user to automatically perform these intermediate steps.
If the alignment between the chain and the reference sequence is poor, only a limited number of helix definitions may be produced. Sometimes, better results can be obtained by using a sequence map to a different pdb chain for which helix definitions have already been created. For example, generating helix definitions from the sequence map between E.coli 23S and the 23S chain of pdb model 1m90 only results in 49 helices for 1m90.A, but generating them from the sequence map between the 23S chains of pdb model 1ffk and 1m90 gives 81 helices for 1m90.A.
The fiTick event occurs after all internal force calculations in the forcefield have been done, but before the 'EndForceCalc()' function, where accumulated atom forces are transferred to nodes. This can be a possible source of confusion to the user. For example, if the user wishes to disable subsequent force production on an active dynamic residue, and disables internal and external force interactions for that residue in the fiTick event (through a call to setForceObj_EnableForceCalc()), there will still be a non-zero velocity and angular velocity produced for that residue in the remainder of that timestep, if forces were applied in that timestep. Then, in subsequent timesteps, the residue will 'drift' even if force calculation has been disabled for it. If it is desired to 'lock down' a residue, this can be done in one of two ways. First, in the timestep after the one in which all force calculations have been disabled, the user can explicitly set the velocities and angular velocities of the dynamic residue to zero (through calls to setForceObj_Velocity() and setForceObj_AngVelocity()). After this, no additional forces can be produced for that residue and it will not move. Alternatively the user can simply disable movement of all nodes of the residue by calling setForceObj_EnableNodeMove().
A set of rbq lua api functions addresses this problem. The procedure involves recording the rotation and translation of the terminal node of an active residue and then applying this movement to the subsequent inactive residues in the chain so that they will remain at the same orientation and distance with respect to the terminal node of the actively moving residue. These functions are listed below:
In addition, a movie of the aligment can be viewed in the exp/demo/mrnaWrap demo directory.
A number of scripts have been created that allow the user to select a subset of residues in a model based upon a distance constraint. The script OutputChainResAtDist.lua, accessible from the 'Script', 'Geometry', 'Distance' menu, will output to file a list of residues in a specified chain that are within a specified distance of the currently selected residues. The file is a simple text file with each line containing the fully-qualified name of a residue matching the distance constraint. The user may optionally edit the file, deleting, inserting or renaming lines, prior to subsequent use of the file for selection.
Note: currently, the script only supports distance-testing for a static residue selection. Support for dynamic residue selection will be added in the future.
A new selection can be created from this file by running the script SelectResFromFile.lua", available in the 'Script', 'Other' menu. Then this new selection of static residues is available for other operations, such as conversion into dynamic residues (using the 'Forcefield', 'Force Object', 'Create' menu command).
An display of distance-based selection is shown below, where residues of 1j5e chain A within 20 A of mRNA chain 1jgo.1 are shown in blue. Chain 1jgo.1 is shown in yellow.
| Subdirectory Name | Description |
|---|---|
| res | Resource directory containing menu bitmap files |
| lua | Script directory containing pre-defined Lua scripts and modules |
| lua/tmp | Base directory for script objects |
| doc/html | Base directory for html documentation |
| input | directory for input of external scripts (typically from the web interface) |
| exp | Base directory for supplemental experiments, demos and applications |
| seq | directory for sequence data |
| tmp | temporary directory used for work and output by various scripts |
| pdb | directory to hold a subset of PDB files involving Ribosome modeling |
| gnuplot | directory that holds a stripped-down version of GNUPlot, used in html reports |
| perl | directory that holds a stripped-down version of Perl, used in html reports |