The Ribosome Builder Project
Home - Command Reference - User Manual
[ Up ] [ Top ]

User Manual

Last Updated: 2004-11-28

[Top] [Up] [Prev] [Next]

Brief Contents

[Top] [Up] [Prev] [Next]

Detailed Contents

[Top] [Up] [Prev] [Next]


The Ribosome Builder software is a project designed to construct, view and simulate complex macromolecular systems. Although its initial focus is to simulate the Ribosome, it is intended to serve as a general purpose tool for other macromolecules.
[Top] [Up] [Prev] [Next]

The Application Workspace

[Top] [Up] [Prev] [Next]

Screenshot of the Application Workspace

[Top] [Up] [Prev] [Next]

Menus and Toolbars

The menus and toolbars at the top of the application window provide a number of common operations that can be selected by mouse or keyboard. Not all operations are available from the menus. For listing and entering all built-in commands, see the Command Input Box and Command Reference pages.

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.

[Top] [Up] [Prev] [Next]

File Menu and Toolbar

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.

[Top] [Up] [Prev] [Next]

Script Menu

The Script menu provides operations that are customizable by the user. Operations are organized by category into a hierarchy of submenus, as defined by the 'ScriptDefs.ini' file. Selecting menu items within the Script menu will cause execution of external script files that are written in the Lua scripting language. The section Scripting has more information on working with scripts. The Program Startup section has more information about the ScriptDefs.ini file.

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'.

[Top] [Up] [Prev] [Next]

Edit Menu

The Edit menu provides operations that affect the content of the current document. In addition to inserting PDB models (described below in Working with Files, models can be renamed or deleted. Currently, the copying and pasting of selected models is not implemented.
[Top] [Up] [Prev] [Next]

View Menu and Toolbar

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.

[Top] [Up] [Prev] [Next]

Select Menu and Toolbar

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.

[Top] [Up] [Prev] [Next]

Draw Menu and Toolbar

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.

[Top] [Up] [Prev] [Next]

Forcefield Menu and Toolbar

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.

[Top] [Up] [Prev] [Next]

Window Menu

The Window menu is used to control the display of the component windows and toolsbars in the application main window. The 3 component windows are the Graphics window, the Status window and the Pdb Tree window.
[Top] [Up] [Prev] [Next]

Help Menu

The Help menu provides commands for help information about the program. The first item, 'Html' is used to run a web browser and display the local html help files for the application. This command may not always work as expected, depending upon the configuration of the host computer or web browser .

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.

[Top] [Up] [Prev] [Next]

The Graphics Window

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.

[Top] [Up] [Prev] [Next]

The Status 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.

[Top] [Up] [Prev] [Next]

The Pdb Tree 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.

[Top] [Up] [Prev] [Next]

The Command Input Box

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.

[Top] [Up] [Prev] [Next]

Working with Files

PDB files

The Ribosome Builder program currently supports one external file format, the Protein Databank PDB file type. This file type specifies the 3 dimensional structure of molecules at atomic resolution. A large number of structures are publicly available at the Protein Data Bank website. A small selection of PDB files relating to ribosomes are included in the rbo distribution in the 'pdb' subdirectory.

Existing Limitations with PDB Files

Note: the complete PDB specification is not implemented in the Ribosome Builder program, and only a small subset of the models in the database have been tested. Consequently, not every model will load correctly. Below are some current limitations that exist for PDB files. Some or all of these limitations may be addressed in future versions of the program.


Another issue in using PDB files is that names are case sensitive. The convention with pdb files distributed with the program are to convert the pdb file names to lower case. If a model is created from a PDB file with a file name in upper case, by default the model will have the upper case name. For example, loading a model from '1TRA.pdb' will result in a model with the name '1TRA'. Trying to select the model with a command such as 'sel name 1tra' will not work. Instead, in this case, the user must specify 'sel name 1TRA'.

RBD documents

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.
[Top] [Up] [Prev] [Next]

Navigating in 3D Space

Frames of Reference

To examine a 3-dimensional object on a computer screen, molecular viewing programs typically provide operations to rotate, translate and zoom the view of the object with respect to the user. However, the Ribosome Builder program can be used to insert and position multiple objects inside of a 3-dimensional space. Consequently, it is useful to define an absolute frame of reference, called the 'world' frame, that is independent of the objects that it contains.

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.


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.


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, .
[Top] [Up] [Prev] [Next]

Selecting Objects

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

[Top] [Up] [Prev] [Next]

Displaying Objects

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.

[Top] [Up] [Prev] [Next]

Manipulating Objects

Manual Positioning

Using the Navigation Controls to Move Objects

One of the goals of the Ribosome Builder program is to be able to construct macro-molecular systems by inserting and arranging its molecular components within a 3D space. The manual positioning of PDB models is conveniently done using the same navigation controls that adjust the view, as discussed in the section Navigating in 3D Space. To move the current selection instead of the viewpoint, click the 'Move Selection' icon, or hold down the 'space' key while moving the mouse with left button down in the graphics window.

Manual Positioning of Static Models

For static models the entire PDB model must be selected before it can be moved. If only a subset of chains or residues is selected the message Error: Partial Selection will be displayed. Refer to the section Selecting Objects for more information on selecting a PDB model. If it is desired to change the position of only a subset of a static model, a dynamic model must first be created from the static one, as discussed in the section Forcefield and Dynamic Models. Then after modifying the position of the components of the dynamic model it can be exported to a pdb file as a new static model using the export command 'file exportToPdb' as described in the file commands group.

Manual Positioning of Dynamic Models

When moving dynamic models it is possible to translate or rotate one or more individual dynamic residues with the mouse. This is done by selecting the dynamic residues and then moving the mouse with left button down while in 'Move Selection' mode. The direction of translation or rotation is determined by the current mouse movement mode, which can be one of the four modes 'Rotate XY', 'Rotate Z', 'Translate XY', or 'Translate Z' (Zoom).

Rotating about Covalent Bonds

It is possible to manually rotate a dynamic residue and subsequent residues about a subset of its covalent bonds. This is done by selecting an individual node (as described in the section Selection By Mouse) within a dynamic residue and then moving the mouse up and down in the vertical direction while in 'Move Selection' mode. This will rotate the atoms of a node, all child nodes within the residue and all subsequent dynamic residues in the segment about the axis of the covalent bond between a node and its parent node. To rotate the ancestor nodes and previous dynamic residues instead, the user can hold down the SHIFT key while moving the mouse.

Defining a Center Point for Manual Rotation of a Selection

When rotating a model selection the default point around which rotation occurs is the center-of-mass of the selection. Sometimes it is desirable to specify a different center point of rotation. The command 'sel set rotCen' in the sel set command group can be used to define a different center point around which a selection is rotated. This is especially useful when it is desired to rotate a large model while keeping some point on its extremity at a fixed location.

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.

[Top] [Up] [Prev] [Next]

Forcefield and Dynamic Models

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.

Standard and Non-Standard Residues

The current implementation of the program only supports creation of dynamic segments from standard nucleic acid and amino acid residues, and a small selection of non-standard (heterogeneous) residues. However, there are thousands of heterogeneous residue types in the Protein Data Bank. Static heterogeneous residues that are not defined in the Ribosome Builder program will be automatically excluded from dynamic residue creation. Currently, support for heterogeneous residues must be implemented in the core C++ code, but future versions should provide for runtime definition of additional heterogeneous residue types.

Gaps Will Produce Multiple Dynamic Segments

When a sequential set of static residues in a chain are selected for creation as dynamic residues, the result will generally be a single dynamic segment with an equal number of residues. However if a dynamic residue cannot be created from a static residue (because it is a non-supported heterogeneous type), or if the residue is not bonded to the previous residue in the sequence (because of gaps in the static model), a gap will occur and a new dynamic segment will be created at the next eligible residue. For example, a sequence of residues in a static chain with 4 gaps would result in the creation of 5 dynamic segments.

Smallest Unit of Movement is the 'Node'

In a dynamic residue the smallest moveable component in the residue is termed a 'node'. Often a node consists of a single atom but in the case of rings (the aromatic base ring and ribose ring of nucleic acid residues, and the aromatic rings of certain amino acid residues), the atoms within a ring are consolidated into a single node and move together as a rigid body.

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.

Option to Create Single Atom Nodes

The consolidation of ring atoms into a single node can improve the performance of the simulation by reducing the number of interactions that are calculated, but sometimes it is desirable for every atom to move independently. For example, simulation of change of pucker in the ribose ring from 3' endo to 2' endo requires that the atoms in the ring do not move as a single rigid body. To enable creation of a single atom per node, the command 'ff fo createSingleAtomNodes' can be used. Once set, all subsequently created force objects will have a single atom per node until the option is turned off. This option is also useful because it enables the selection of individual atoms, which in turn allows the graphical display of dynamic models at the level of individual atoms (i.e. setting the color or spacefill value of a single atom).

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.

Distinguishing between Static and Dynamic Models in the Graphics Window

When static residues are converted to dynamic residues, the static model still remains. To avoid confusion, the display of the static residues may be turned off by the user, if desired.

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:

Forcefield Parameters

The activity of dynamic models in the forcefield is determined by a large number of user-modifiable parameters. These primarily consist of parameters to enable and adjust the strength and threshold of the different types of chemical forces. A complete and detailed description of the meaning of each parameter will be documented at some point in the future. Currently, refer to the complete syntax for the 'ff' command for brief description of each parameter that is adjustable by the user.

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.
[Top] [Up] [Prev] [Next]


Motivations and Definitions

The meaning of an annotation in the traditional sense can be considered to be some kind of text and/or graphics that provide supplementary or detailed information about the primary object being displayed. This meaning applies for the most part to annotations in the Ribosome Builder program, with a few elaborations.

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.

[Top] [Up] [Prev] [Next]


The Lua Scripting Language

The Ribosome Builder program comes with a built-in interpreter that can execute user-defined scripts written in the Lua scripting language. Lua is a small, robust and extensible cross-platform open source language with powerful data definition and object-orientation capabilities. At the same time, its syntax is simple and elegant and intended to appeal to the non-professional programmer.

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.

[Top] [Up] [Prev] [Next]

Web Browser Interface


To analyze and understand the activity of complex 3-dimensional structures such as molecules, an interactive graphical display of the structure is invaluable. Equally desireable however is a means of displaying tabular data, graphical 2D plots and hyper-linked supplementary information. Modern web browsers are a good choice for presenting these additional kinds of information because they are highly optimized, ubiquitous and use open, non-proprietary standards.

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 (, 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>

Script Request Syntax

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'.

[Top] [Up] [Prev] [Next]

Additional Tools and Features

[Top] [Up] [Prev] [Next]

Structural Alignment of Ribosomal Subunits

A built-in, general purpose tool to do structural alignment of nucleic acid and protein models remains to be implemented, but currently there is a more limited way to align certain RNA chains. A number of whole-subunit PDB models can be loaded into a document in a standard orientation so that they are aligned with a reference model. Several script items under the 'Script', 'Model', 'Large Subunit' and 'Small Subunit' menus are examples.

Sequence Alignment of a Chain to a Reference Sequence

The existing strategy for aligning two rRNA chains requires definitions of the helices of the chains as described below. In order to create a helix definition file for a new chain, a sequence alignment of the chain to a reference sequence is required. There are a number of predefined sequence map files that are included in the program distribution for some of the rRNA models. These files have a '.smap' extension and are located in the 'seq' subdirectory. They are named according to the associated chains. For example, the file 'E.coli.16S-1j5e.A.smap' provides a mapping between the reference E. coli 16S rRNA sequence and chain A of PDB model 1j5e.

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.

Helix Definitions

Once an alignment to the reference E. coli sequence exists, in the form of a .smap file, a helix definition file can be created for the new chain by running the script GenHelixFileForChain.lua. The reference helix definition files for the 16S RNA and 23S RNA, created from the standard E.coli secondary structure maps, consist of starting and ending residues for each helix. The script maps these endpoint residues to equivalent residues in the new chain, if they exist.

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.

Structural Alignment Using Two Helix Vectors

If equivalent helix definition files exist for two RNA chains, one chain can be superimposed upon the other by aligning two vectors of one chain onto two vectors of the other, where the vectors are defined by the direction of helices in the chains. The script FindBestHelixAlign.lua will exhaustively search for the pair of the helices that produce the best possible alignment between the two chains, as calculated by RMSD.
[Top] [Up] [Prev] [Next]

User-Defined Forces

The movement of dynamic residues in the forcefield is normally determined only by forces that represent chemical interactions. However sometimes it is useful to define and apply additional forces to guide the movement of dynamic objects toward some desired objective. The Ribosome Builder program provides for the input of user-defined forces on the set of dynamic residues. This input can be done by using script objects.

Script Object Force Input Event

The external force application is done by creating a script object and associated force input event script, which is named 'fiTick.lua' and located in the script object directory. In this script file forces can be applied to dynamic residues by calling the addNodeForce() and addNodeTorque() functions.

Forcefield Timestep Events

Before creating a script object to apply external forces, it is helpful to understand the sequence of events that occur during a forcefield timestep. The timestep is divided into two main phases: the force calculation phase and the timestep movement phase. During the force calculation phase the interaction forces between all objects in the forcefield are calculated and the total force and torque on each object are accumulated at the object's center of mass. Then during the timestep movement phase each object is translated and rotated according to its mass and total force and torque. Consequently any external force that is desired to be applied to a force object must be input before the timestep movement phase.

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().

Selective Simulation of Dynamic Residues

One of the advantages of scripted control of the forcefield is that it lets the user specify a subset of residues that can be active during the forcefield simulation. This can be useful when docking a sequence of residues in a chain, for example. Each residue can be enabled individually for forcefield interactions, both simplifying and speeding up the simulation. The remainder of the residues will be disabled, and will not interact or move. The following rbq lua api functions are useful for selective simulation of dynamic residues:

Scripted Movement of Inactive Dynamic Residues

When a single residue in a chain is being docked on some target and the subsequent residues have been set to an inactive state, it would be undesireable for the active residue to move some distance away from the adjacent residues without updating their position because the covalent bond limits would be violated.

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:

  • setForceObj_EnableRecordNodeMove()
  • getForceObjectRecordedNodeRotation()
  • getForceObjectRecordedNodeTranslation()
  • transformForceObject()

    Example of Scripted Force Input: mRNA alignment to a Path

    An example that uses script force input functions to align an mRNA molecule to a target path is located in the exp/dev/mrna/rkp experiment subdirectory. The script object 'basrAlign' is used to align a 27 dynamic residue mRNA from the a-form helix configuration to a configuration determined by PDB model 1jgo chain 1. The following script event files are used to do the alignment:

    In addition, a movie of the aligment can be viewed in the exp/demo/mrnaWrap demo directory.

    [Top] [Up] [Prev] [Next]

    User-Defined Forcefield Interactions

    In some simulations it is desireable to 'dock' a subset of dynamic residues into a larger subset. An example would be to simulate the docking of an mRNA chain into the channel of the 30S subunit. In the ideal case the interaction of all residues against all other residues would be simulated, with N * (N-1) interactions, where N is the number of dynamic residues. However this can impose a significant computational penalty for a large dynamic residue set.

    Reducing the Number of Dynamic Residue Interactions

    If we consider the larger subset of residues as largely 'fixed' in position, we can significantly reduce the number of interactions in a simulation by skipping interaction between these residues. In the example of an mRNA docking into the 30S, this would mean that the interactions between residues in the 30S are ignored.

    Definition of Force Groups

    'Force Groups' are used specify conditional interaction between dynamic residues. The user creates a force group and then adds a set of dynamic residues to the group. When the group is created, the user specifies whether intra-group force calculations are done for that group. In this way, two groups of residues can be created. In the example of the mRNA docking, the 30S residues are added to one group, with intra-group interactions disabled. In the second group, the mRNA residues are added, with intra-group interactions enabled. Then, when the custom force container option is enabled, force interactions will occur between mRNA residues and 30S residues, and between mRNA residues themselves, but 30S residue interactions will be skipped, allowing for a faster simulation of the mRNA docking. A list of the funtions used in user-defined force interactions is given below:
    [Top] [Up] [Prev] [Next]

    Distance-based Selection

    To simulate the interactions between a small model and a larger model, it is often only necessary to simulate a subset of the larger model that is within some close distance to the smaller model. For example, the simulation of an mRNA docked within a 30S subunit can be done by creating dynamic residues of the 30S from all static residues that are within some maximum distance from any residue in the mRNA. This will greatly reduce the number of dynamic residues in the simulation and allow it to run faster.

    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.

    [Top] [Up] [Prev] [Next]

    Program Startup

    This section documents some of the initialization steps of the Ribosome Builder program. Knowing the steps can be useful for customization of the startup process and to debug problems that occur. The following items will be discussed:

    DOS/Unix paths

    The Ribosome Builder program was initially developed in the Microsoft Windows environment but the eventual port to Unix was envisioned from an early state and some initial attempts at compatibility were done to ease the process. One of the most significant issues involves pathname separators, which use '\' in MS Windows and '/' in Unix. Much of the core and scripting code of the Ribosome Builder program attempts to convert to Unix path separators internally, for consistency and also because the Windows C APIs support this to some degree. However, support for the proper path separator is inconsistent at the current time and may serve as a prolific generator of annoying bugs in the future.

    Working Directories

    A resource that is closely related to proper path formation is the concept of the 'current working directory'. PDB files, Ribosome Builder Documents, Lua Script files and web interface html files will often be assumed to exist in the current working directory which at the current time defaults to the base application directory. This is the directory on the host machine that contains the executeable file that started the program. However, interpretation of the current working directory is also not entirely consistent and work must be done in the future to improve it, as well as to let the user specify a different working directory. A number of subdirectories are used in various operations of the program, some of which are listed below:

    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

    Creation of Console window

    The console window is the first window created when the program is run. Before the graphical interface window is constructed and displayed, any messages are displayed in this window.

    Creation of Logfile

    A text file called 'rbq.log', located in the 'log' sub-directory, is created at this point. All subsequent messages sent to the application standard output and error output will be echoed to the logfile, providing a permanent record of the user input and response from the application. This also allows a remote user with ftp access to the application directory to download the log file and follow the progress of the program remotely. Note: if a previous file with this name already exists, it will be renamed to rbq-NNNNNN.log where 'NNNNNN' is a numerical value needed to produce a free filename.

    Initialization of Lua Interpreter

    The embedded script processor is initialized at this point. The processor is used to interpret script files written in the Lua language. The current version of the lua interpreter and the amount of free stack space are reported to the console window. In addition, registration of rbq interface functions to the lua scripting context is done at this time. Refer to the Scripting section in this manual for more information about script processing.

    Reading of Menu Bitmaps from Resource Subdirectory

    The initialization of the menus and toolbars in the application main window involve the reading of bitmaps from the 'res' subdirectory. If for some reason the directory is missing, the icons displayed in the menus and toolbars will be blank.

    Creation of Status Window

    During the construction of the graphical interface window, a status window is created. Once created, it will display the contents of all user input from the console input dialog, and text responses from the program. The contents of the status window are also output to the logfile mentioned above.

    Execution of Lua Startup Script

    After construction of the graphical main window has been completed, a script in the lua subdirectory called 'Startup.lua' is executed. In this startup script, the following tasks are performed:

    Processing of rbq.ini file

    After construction of the graphical main window a number of window settings are applied such as window size, toolbars shown and listing of most-recently used files in the 'File' menu. These settings are read from a text file, 'rbq.ini', located in the application base directory.

    Display of Main Window

    The final step in initialization is the display of the main window, at which the point the program is ready for use.