|
|
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.
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.
.
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.
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.
.
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.
The current implementation of the Ribosome Builder program only provides for selection down to the 'Residue' level for static models.
, 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.
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
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.
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.
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, 
.
| 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.
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.
The current implementation of the program does not produce bonds that are specified by 'CONECT' records.
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.
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.
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.
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.
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.
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,
.
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).
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 |