1Basic Research Program, SAIC-Frederick, Inc., NCI-Frederick, Frederick, Maryland, USA
2Center for Cancer Research Nanobiology Program, NCI-Frederick, Frederick, Maryland, USA
This text serves as a user manual for the NanoTiler software. This software is a platform for the interactive or automated design of RNA structures on a nanoscale. It’s scientific motivation is described in more detail in the manuscript Bindewald E., Grunewald C., Boyle B., O’Connor M., Shapiro B.A.: “Computational Strategies for the automated design of RNA nanoscale structures from building blocks using NanoTiler”, Journal of Molecular Graphics and Modelling (accepted for publication). This user manual describes most of the current facilities of the software with the exception of the graphical user interface as well as features that are currently under development. The software offers a scripting language and a graphical user interface for the manipulation and generation of RNA structure models. The subject area and the chosen flexible approach makes a software like this inherently “complex”. This user manual emphasizes short demos, “quick start” items and sample sessions in order to make learning the software enjoyable. In case of questions please do not hesitate to contact the authors of the software.
Eckart Bindewald eckart@ncifcrf.gov
Bruce Shapiro bshapiro@ncifcrf.gov
Mark Jacob Pritt
Calvin Grunewald
Brett Boyle
Mary O’Connor
We thank Luc Jaeger for valuable suggestions and Christine Viets for contributions in terms of programming. We wish to thank the Advanced Biomedical Computing Center (ABCC) at the NCI for their computing support. This work has been funded in whole or in part with Federal funds from the National Cancer Institute, National Institutes of Health, under Contract No. N01-CO-12400. This research was supported by the Intramural Research Program of the NIH, National Cancer Institute, Center for Cancer Research.
The software requires the use of Java version 5 or higher. A basic installation of the NanoTiler software is straightforward. The steps are:
The NanoTiler software runs in its basic form (without graphics and some of its 3rd party helper programs) on virtually any computer platform that has Java (either Java 1.5 or Java 1.6) installed. This basic mode of operation has been tested on the following platforms:
Type the following command in a text terminal:
java -version
If the computer does not recognize the “java” command, it means that the Java Runtime Environment (JRE) has to be installed (skip to the next subsection). If the computer returns a text similar to:
java version "1.5.0_13"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_13-b05-241)
Java HotSpot(TM) Server VM (build 1.5.0_13-121, mixed mode)
or
java version "1.6.0_01"
Java(TM) SE Runtime Environment (build 1.6.0_01-b06)
Java HotSpot(TM) 64-Bit Server VM (build 1.6.0_01-b06, mixed mode)
it means that the installed Java Runtime Environment is of version 1.5 or 1.6 respectively and is sufficient. Note that these Java versions are also called by Sun “5” and “6” (see http://java.sun.com) . If Java 1.5 is installed, use a NanoTiler distribution with the name nanotiler_v0.9_j5.tar.gz. If Java 1.6 is installed, use the package with the name nanotiler_v0.9_j6.tar.gz. If the Java versions are not matching, the software will not execute. In this case it is preferrable to adjust either the nanotiler package or the Java Runtime Environment. Alternatively it is also possible to recompile the software, this is described shortly in the Developer Notes in the Appendix of this user manual.
If the result of the above java -version command is similar to:
gij (GNU libgcj) version 3.3.3 (SuSE Linux)
it means that the installed Java Runtime Environment is not based on the Sun, Inc. implementation but on the GNU (Free Software Foundation, Inc.) implementation. In this case the basic mode of operation of the NanoTiler software will be functional (executable nanoscript), however, the graphical user interface (executable nanotiler) is not available. It is recommended (but not required) to install the Sun, Inc. based Java Runtime Environment or Java Software Development Kit instead (see next section).
Linux One can install the Java Software Development Kit (recommended) or the Java Runtime Environment from the Sun web site. At the web address http://java.sun.com/javase/downloads click “JDK 6 Update X” (with X being the current update number, by the time of this writing this number was “6”). Follow the download instructions by choosing “Linux” as platform (we had problems choosing “Linux 64 Bit” even on 64Bit platforms). Download the package called “Linux self-extracting file”. Once the package is downloaded, it might (depending on Linux distribution and used Browser) be possible to double-click on the binary. Otherwise, using a terminal window, change the current working directory to the location where the binarary was downloaded. Issue the command
chmod +x jdk-6u6-linux-i586.bin
Run the self-extracting binary with the command:
./jdk-6u6-linux-i586.bin
Follow the installation instructions. After the installation is complete, test the Java version with the command:
java -version
If the java command is still not recognized or returns the result of the gij compiler mentioned above, then either an alias for the “java” and “javac” command has to be set, or (better), the PATH environment variable has to include the directory containing the newly installed Java related binaries. This can be accomplished by adding an appropriate command to the .cshrc (C-Shell) or .bashrc (Bash Shell) file in your home directory.
Macintosh OS X In the case of Macintosh OS X, the correct Java Runtime Environment and Java Software Development Kit should already by installed. It should be version 1.5 or higher. The Pull-down menu item Apple→Software Update should update the Java version to the most recent available version. If the Java version is 1.4 or lower even after a performing the automated software update, it means that the OS X version is outdated and cannot be used for the NanoTiler software.
Step 1: Download the file: nanotiler_v0.9_j6.tar.gz or nanotiler_v0.9_j6.tar.gz Open a terminal application. Macintosh OS X Users: the terminal application is located in the /Applications/Utilities directory.
Step 2: change the current working directory to the home directory or to a place where the software should be installed
cd ~
tar xvfz ~/Desktop/nanotiler_v0.9.tar.gz
cd nanotiler_v0.9
Step 4: Set two environment variables as follows:
Linux: Find out the type of default shell of the system with the command:
echo $SHELL
If the answer is /bin/csh or /bin/tcsh, the default shell is the C-Shell, if the result is /bin/bash, the default shell is bash. For other results like /bin/sh or /bin/bsh please refer to the shell documentation on how to set environment variables.
If using a C-shell add these commands to the ~/.cshrc file in your home directory using a text editor (instead of YOURPATH type the installation directory of the NanoTiler software):
setenv NANOTILER_HOME /YOURPATH/nanotiler_v0.9
setenv PATH ${PATH}":${NANOTILER_HOME}/bin"
If using a bash shell add this command to the .bashrc file in your home directory using a text editor:
export NANOTILER_HOME=/YOURPATH/nanotiler_0.9
export PATH=$PATH":${NANOTILER_HOME}/bin"
Macintosh OS X: Open the Terminal application. Open a new window in the Terminal application. Type:
cd
emacs .bash_profile
Add the following lines to the end of the edited file (instead of YOURPATH type the installation directory of the NanoTiler software):
export NANOTILER_HOME=/YOURPATH/nanotiler_0.9
export PATH=$PATH":${NANOTILER_HOME}/bin"
Save the file with control-x followed by control-s. Exit the emacs text editor with control-x followed by control-c.
One can obtain the software from http://ndbserver.rutgers.edu/services/download/.
Install the program as described in its documentation. Set the $RNAVIEW environment variable to the program installation directory. Add $RNAVIEW/bin to the path variable, so that the program is system-wide available under the name "rnaview".
The sequence optimization part requires that the RNAcofold program from the Vienna package is available under this name. Test the existence of the RNAcofold binary with the shell command:
$NANOTILER_HOME/bin/test_nanotiler_installation
This section can be skipped if the script test_nanotiler_installation in the $NANOTILER_HOME/bin directory marks the existence of “RNAcofold” with “ok” and not “failed”. Also, the NanoTiler software will work without the RNAcofold program except for the sequence optimization part (affecting the command optsequences).
Download the RNA Vienna package from http://www.tbi.univie.ac.at/~ivo. Install the software as described in their documentation. The program RNAcofold has to be in one of the directories of the $PATH variable (either add the Progs directory of the Vienna package to your path variable or install RNAcofold in a directory such as /usr/local/bin).
The topology classification of a structure is based on the tra program developed by Faulon et al. Test the existence of the tra binary with the shell command:
$NANOTILER_HOME/bin/test_nanotiler_installation
This section can be skipped if the script with the name test_nanotiler_installation in the $NANOTILER_HOME/bin directory marks the existence of “tra” with “ok” and not “failed”. Also, if the program is not installed, the NanoTiler software will still work with the exception of the topology signature generation (affecting the commands grow, growgraph and signature).
The program is very useful, as it computes a unique signature of a graph, thus allowing the reliable classification of assembled structures. It is available at http://www.cs.sandia.gov/~jfaulon/QSAR. Modify the PATH variable such that the tra program is system-wide available under this name.
Two graphical display systems are implemented in NanoTiler: one is based on the Java Foundation Classes, the other is based on OpenGL. After starting the program $NANOTILER_HOME/bin/nanotiler, the user is asked which of the two graphics systems should be used. The default option is to use the graphics based on the Java Foundation Classes (JFC). The NanoTiler implementation of this graphics style is less sophisticated, but the graphics system is compatible with more computer platforms and does not require the installation of platform-specific libraries. The other type of graphics of the NanoTiler program is based on the Java OpenGL binding called Jogl. This requires that appropriate Jogl shared libraries (filenames libgluegen-rt.so, lobjogl_awt.so and libjogl.so) are available in the $NANOTILER_HOME/lib directory. Also two Jogl jar file have to be located in $NANOTILER_HOME/jar: gluegen-rt.jar and jogl.jar. This can be accomplished by either using the pre-packaged appropriate NanoTiler version (recommended), or if you have a computer system not listed by obtaining the appropriate Jogl libraries and jar files from https://jogl.dev.java.net and placing them in $NANOTILER/lib and $NANOTILER/jar. We found that especially older Linux systems do not work with Jogl. If there are problems with the OpenGL style graphics (noticeable as exceptions thrown by the Java virtual machine at start-up time of the graphics window), we recommend using the simpler Java-style graphics or using a computer system that is either the most recent or the most similar to one of the NanoTiler distributions. The autors of this software would be most glad to obtain user feedback about succesfull or unsuccessful installation of the OpenGL graphics system on different compute platforms. We sucessfully installed the OpenGL graphics on RedHat enterprise edition 4 / 64 bit as well as OS X 10.4 (Intel).
The installation of the NanoTiler software package can be tested by running the command
$NANOTILER_HOME/bin/test_nanotiler_installation
This script tests for the proper setting of the NANOTILER_HOME variable, the existence of the nanotiler binary as well as the existence of the helper programs rnaview, and tra. If the script marks items as “failed”, please consult the previous section as well as sections 1.3,1.4 and 1.5 in order to install the complete system properly. The topology signature program tra as well as the secondary structure program RNAcofold are not mandatory, but without them the topology signature generation (tra) or the sequence optimization (RNAcofold) will not be functional. Note that the tra program is currently not available for Macintosh OS X.
Run the following command from the Unix shell:
$NANOTILER_HOME/bin/nanotiler
The command nanotiler should launch the graphical version of the NanoTiler software. An inital dialog window queries if the graphics display system should be based on the Java Foundation Classes (default, click “OK”) or OpenGL (click “Cancel”). The program now launches either an OpenGL based or a Java based graphics window of the NanoTiler software. If a graphical user interface window with a workspace with black (OpenGL) or white (Java) background appears, the installation was successful.
To become familiar with the software, please follow the instructions provided in the following Quick Start section.
Run the following command from the Unix shell:
$NANOTILER_HOME/bin/nanoscript
The command nanoscript should now launch the non-graphical version of the NanoTiler software. One should see a prompt "nano>".
One can obtain a non-OpenGL based graphics window (not containing pull-down menu items) using the following command:
graphics
To become familiar with the software, please follow the instructions provided in the following Quick Start section.
The easiest way to use the program package is to use scripts that are available for specific tasks. The are available in the $NANOTILER_HOME/bin directory.
The script junctionscan in $NANOTILER_HOME/bin directory reads a PDB file, detects, extracts and annotates RNA junctions, kissing loops, internal loops and bulges. The synopsis is: $NANOTILER_HOME/bin/junctionscan READDIRECTORY WRITEDIRECTORY FILENAME
Example:
In a scratch directory of your choice issue the following command:
$NANOTILER_HOME/bin/junctionscan $NANOTILER_HOME/test/fixtures . 2B8S_rnaview.pdb
Note that the “write directory” is indicated by a single dot (“.”), do not forget space characters before and after the dot.
After completion, the program should have generated the files 2B8S_rnaview.pdb_k2_A-G7_B-G7.pdb and 2B8S_rnaview.pdb_k2_A-G7_B-G7.db.txt. The generated PDB file is an extracted kissing loop (denoted by “k2” in the filename). The generated text file containts detailed annotation about the extracted structural element, such as the residue ids, sequences, as well as local coordinate systems of idealized helices fitted onto the detected helices. These generated files are equivalent to the content of the RNAJunction database available at http://rnajunction.abcc.ncifcrf.gov.
There are 3 modes of working with the NanoTiler software:
The easiest to use are the pre-made scripts as shown in the previous section. They require merely input and output filenames and no further user intervention. The graphics version has the advantage of instant user feedback about the state of the system.
Create a working directory at a place of your convenience:
mkdir nano_scratch
cd nano_scratch
Start the program nanoscript or (if available) nanotiler located in the directory $NANOTILER_HOME/bin. All commands that are available in the nanoscript program are also available in the graphics/GUI program nanotiler. A script command can be issued by typing into the text field in the bottom window and then pressing the nearby "run" button. Many script commands have a GUI equivalent. In most cases only the script command is described in this tutorial.
Start the program nanoscript or nanotiler. The list of available commands can be seen by issuing the command:
“Issuing the command ‘help‘” means to typing the word “help” at the prompt “nano>” of the program nanoscript. When using the GUI program nanotiler, it means entering the word “help” into the bottom text field with the title “Command:” and pressing the “Run” button at the lower right side of the text field. In both cases, a list of available commands is printed to the terminal window. A GUI alternative to the help command is to use the Pull-down menu item Help→Commands Help
There is a set of demo scripts available under $NANOTILER_HOME/demo/scripts. You can see the list of available demos by issuing the command:
or by viewing the pull-down menu item File→Demo. You can run the prepared demo scripts by issuing commands from within nanoscript/nanotiler like:
demo optbasepairs
The demo command starts running a script. The above command is equivalent to the commands:
clear all
source $NANOTILER_HOME/demo/scripts/optbasepairs.script
The same result can be achieved by selecting the pull-down menu item File→Run Script followed by the choice of script file from the file chooser or by selecting File→Demo→optbasepairs.
These scripts are also available as part of the graphical user interface at the welcome window of the NanoTiler program. The pull-down-menu item Help→Welcome Window regenerates this window.
You can run all demo scripts by issuing the command:
demo all
This might take several minutes to finish!
The demos show the major concepts of the program (e.g. basic molecular operations, building block libraries, constraint satisfaction and simulated self-assembly). It is very instructive to run the individual demos and, in addition, to read the corresponding scripts in the $NANOTILER_HOME/demo/scripts directory.
Change the current working directory or a Unix shell to a place of your convenience. Start the program nanoscript or nanotiler located in the directory $NANOTILER_HOME/bin. If the PATH environment variable is correctly set, the following Unix command should start the program independent of the current working directory:
nanotiler
or
nanoscript
From within the started application, issue the command:
to obtain a Java style graphics window. The previous section described what is meant by “issuing a command”; please refer to that section if necessary.
Generate an RNA double helix with the command:
View the resulting 3D structure in the graphics window.
View the generated objects by issuing the command:
View only the names of the generated RNA strands with the command:
tree strand
Similarly, view only atoms or only residues with the commands
tree atom
tree residue
Select the third residue of the first generated strand with the command:
View the selected 3D object with the command:
Move the selected residue 20Å in the x direction in 3D space with the shift command:
Rotate the selected residue 30 degrees around the z-axis:
Remove this residue:
Clear the work space with the command:
Verify that there are currently no building blocks read with the command:
Read a building block library with the command:
Verify that the previous command read one three-way junction:
status
Place the three-way junction at the origin:
Short explanation (more details in section 4.2): the “j” stands for “junction” (as opposed to “k” for kissing loop building blocks). The parameter “root” stands for the parent node of the scene graph, the parameter “myname” stands for the name the placed junction should have. Hence the tree name of the junction will after the command be “root.myname”. The parameter “3” stands for the order of the junction (a three-way junction), “1” means that the first loaded three-way junction should be used. The next three numbers indicate the x,y,z coordinates describing where the building block should be placed in the workspace. The last value “_1” is a suffix for copied RNA strands to ensure that no two RNA strands have the same name.
Place another copy of the same three-way junction at position 100.0, 0.0, 0.0:
place j root myname2 3 1 100.0 0.0 0.0 _2
View the available helix end connectors with the command:
tree helixend
The result should look like (the coordinates can be slightly different due to the fitting process):
root.myname.A_1_B_10 1.1.1 1 BranchDescriptor3D -1.993 -8.043 14.538
root.myname.C_1_A_9 1.1.4 1 BranchDescriptor3D 15.611 -2.989 -3.353
root.myname.B_1_C_11 1.1.6 1 BranchDescriptor3D -13.618 11.033 -11.185
root.myname2.A_1_B_10 1.2.1 1 BranchDescriptor3D 98.007 -8.043 14.538
root.myname2.C_1_A_9 1.2.4 1 BranchDescriptor3D 115.611 -2.989 -3.353
root.myname2.B_1_C_11 1.2.6 1 BranchDescriptor3D 86.382 11.033 -11.185
Specify a connection between two helices with a spacer helix of 15 base pairs by specifying two helix-end descriptors:
Connect both helices using this helix constraint:
Export the generated construct to a PDB file:
Clear the work space again:
Next, we perform two generations of a self-assembly simulation by using the loaded three-way junction as a building block. Let Helix 1 of this building block be connected to helix 2 to another copy of the same type of building block using a 6 base pair spacer helix:
Export the generated triangular ring structure:
exportpdb myring.pdb
View the commands issued so far:
Save the command history to file:
history file=mysession.script
Quit the program:
Congratulations! The first NanoTiler session is concluded, hopefully with two successfully generated initial RNA structures. More details about the commands and their motivation are presented in the following sections.
Two different Graphical user interfaces have been implemented. One is based on the Java Foundation Packages java.awt as well as java.swing using the 2D API. A second graphical user interface is based on the JOGL project, a Java binding of OpenGL. After launching the program with the command ${NANOTILER_HOME}/bin/nanotiler , the user is provided with a window asking which of the two graphics display systems should be used. The Java style graphics is compatible with a wide variety of computer systems without changes. The OpenGL system requires the correct Jogl library (a .so file) to be stored in the NANOTILER_HOME/lib directory (see section Installation). The OpenGL based graphics is more sophisticated, it allows, for example, the selection of 3D objects from the screen by mouse clicks.
A text version of the nanotiler software can be launched with the program nanoscript (available in the directory ${NANOTILER_HOME}/bin). A Java style graphics window can be launched by issuing the command:
This command launches a graphics window based on the Java graphics implementation mentioned first.
The nanoscript/nanotiler program provides one workspace that contains the information about the current molecular model. The data is stored or organized in the form of a hierarchical tree, also called a scene graph. This hierarchical organization reflects the hierarchy of biomolecules. For example, an RNA strand consists of several nucleotides which consist of several atoms and so forth. The scene graph can be displayed with the tree command;
# generate an example object:
# display all atoms:
# display strand names only:
tree strand
# display atoms only
tree atom
# full control, display everything but not atoms and nucleotides:
tree forbidden=Atom3D,Nucleotide3D
# display residues only:
tree residue
As a result of the last command, the program should print the following output:
root.helix_root.helix_forw.G1 1.1.1.1 22 Nucleotide3D 9.900 0.000 0.000
root.helix_root.helix_forw.G2 1.1.1.2 22 Nucleotide3D 8.383 5.267 2.700
root.helix_root.helix_forw.G3 1.1.1.3 22 Nucleotide3D 4.295 8.920 5.400
root.helix_root.helix_forw.G4 1.1.1.4 22 Nucleotide3D -1.108 9.838 8.100
root.helix_root.helix_forw.G5 1.1.1.5 22 Nucleotide3D -6.173 7.740 10.800
root.helix_root.helix_forw.G6 1.1.1.6 22 Nucleotide3D -9.344 3.270 13.500
root.helix_root.helix_forw.G7 1.1.1.7 22 Nucleotide3D -9.652 -2.203 16.200
root.helix_root.helix_forw.G8 1.1.1.8 22 Nucleotide3D -7.000 -7.000 18.900
root.helix_root.helix_forw.G9 1.1.1.9 22 Nucleotide3D -2.203 -9.652 21.600
root.helix_root.helix_forw.G10 1.1.1.10 22 Nucleotide3D 3.270 -9.344 24.300
root.helix_root.helix_back.C1 1.1.2.1 20 Nucleotide3D 9.161 3.754 20.100
root.helix_root.helix_back.C2 1.1.2.2 20 Nucleotide3D 9.754 -1.695 17.400
root.helix_root.helix_back.C3 1.1.2.3 20 Nucleotide3D 7.357 -6.624 14.700
root.helix_root.helix_back.C4 1.1.2.4 20 Nucleotide3D 2.705 -9.523 12.000
root.helix_root.helix_back.C5 1.1.2.5 20 Nucleotide3D -2.776 -9.503 9.300
root.helix_root.helix_back.C6 1.1.2.6 20 Nucleotide3D -7.406 -6.569 6.600
root.helix_root.helix_back.C7 1.1.2.7 20 Nucleotide3D -9.766 -1.622 3.900
root.helix_root.helix_back.C8 1.1.2.8 20 Nucleotide3D -9.132 3.823 1.200
root.helix_root.helix_back.C9 1.1.2.9 20 Nucleotide3D -5.699 8.095 -1.500
root.helix_root.helix_back.C10 1.1.2.10 20 Nucleotide3D -0.518 9.886 -4.200
This lists all residues in the workspace. For each listed 3D object, the program shows in order the name by which the object can be identified (called from now on the “tree name”), the indices by which the object can be identified (called from now on the “tree index name”), the class name and the cartesian coordinates. For example the tree name of the second residue is root.helix_root.helix_forw.G2, the tree index name of the second nucleotide is 1.1.1.2, the class name is Nucleotide3D.
One can specify individual objects with their tree name, for example:
or alternatively by their tree index name:
select 1.1.1.2
Note that both ways of specifying objects in the scene graph can be mixed:
select 1.1.1.G2
Any name combination that uniquely identifies a 3D object in the scene graph is from now on called a “qualifying name”. The last component of a tree name (in above example the part “G2”) is called the “name” of an object.
The command remove removes an object from the scene graph. For example the command
removes the last residue of the list shown above from the workspace.
Sometimes it is useful to clear all data from the workspace; this can be accomplished with the clear command:
Relationships that are not modeled as a hierarchy can be expressed as "links" between objects. One good example is a base pair interaction. One can view the set of links with the links command:
The first lines of the result output should look like:
LinkCount 1013
1 Link root.import.A.G1 root.import.A.C30 (RnaInteraction 1 WatsonCrick )
2 Link root.import.A.C2 root.import.A.G29 (RnaInteraction 1 WatsonCrick )
3 Link root.import.A.C2 root.import.A.C30 (RnaInteraction 1 WatsonCrick )
4 Link root.import.A.G3 root.import.A.C28 (RnaInteraction 1 WatsonCrick )
...
The command links lists all defined links. Each listed link is preceded by a counter id. Using this id, one can remove a link with the command:
The number is the same order number shown in the links command.
A link between two objects can be generated with the command
With name1 and name2 being qualifying names of 3D objects in the workspace. Covalent bonds and graph connectivity (see Section “3D graphs”) are modeled as simple links that can be generated with the genlink command mentioned above. Nucleotide base pairing as well as helix connections are modeled as special types of links (called constraints). This will be discussed in Section 7 (“Constraint Satisfaction”).
The command history is listed in the text output window using the command
To save the history to a file, specify a filename using the option
history file=myhistory.txt
A saved history file can be an excellent starting point for automating actions performed by the NanoTiler software.
Structures can be read using the import command. Currently two different data formats are recognized: PDB format, as well as a "points" format describing 3D graphs.
Quick Start: Type the following commands in the nanotiler shell:
import ${NANOTILER_HOME}/test/fixtures/triangles.points
tree
# look at the triangle graph structure in the graphics window
clear all
import ${NANOTILER_HOME}/resources/157D.pdb
tree
# look at the structure in graphics window before deleting it
What just happened? The import command reads PDB coordinate structures (with the ending .pdb) as well as 3D graph structures (with the ending .points). The coordinate data is converted to an internal representation and added to the workspace. The tree command lists the currently defined objects.
There is a peculiarity of the NanoTiler software that might cause confusion in the beginning. After importing a PDB structure, the program attempts to identify double-helices as well as structural elements (RNA junctions, internal loops and kissing loops as defined in the RNAJunction database). Identified objects are generated. This can lead to duplicated atom coordinates. If one does not want these additional data structures to be generated, one should use the import command with the option findstems=false .
Atom Coordinate Data can be exported in PDB file format using the command exportpdb.
Quick Start: Run the commands:
clear all
import ${NANOTILER_HOME}/resources/157D.pdb
exportpdb exportexample.pdb
What just happened? The exportpdb command writes atom coordinates to a file in PDB format.
The synopsis of the exportpdb command is:
Other options of the exportpdb command are:
: indices of exported residues are based on either consecutive counting, their name or their original PDB id.
: if false, do not export generated spacer helices.
: if false, do not export the atom coordinates part of a junction or kissing loop data structure.
: only export atom coordinates contained in the specified subtrees of the scene graph.
There is a peculiarity of the NanoTiler software that might cause confusion in the beginning. After importing a PDB structure, the program attempts to identify double-helices as well as structural elements (RNA junctions, internal loops and kissing loops as defined in the RNAJunction database). Identified objects are generated. By default, these structures are exported also. This can lead to duplicated atom coordinates. If one does not want these additional data structures to be exported, one should use the command exportpdb with the options helices=false as well as junction=false .
An important strength of the program is that it handles variables. They can be set using the set command:
# Set the variable "a" to the value "hello":
# Print the status of the variable "a":
echo ${a}
The ${NANOTILER_HOME} variable is set according to the NANOTILER_HOME environment variable.
The set of defined variables can be listed using the env command:
Setting variables is an especially useful concept in combination with the loop command foreach. Because the foreach command is initially not needed for following this user manual, it is described in chapter 10 (“Miscellaneous Command”).
The building block library is an important concept for the NanoTiler software. Building blocks are classified by class (either junction or kissing loop) and order (the number of helices). Internal loops and bulges are treated as "2-way junctions". There are pre-made sets of building blocks available in the directory $NANOTILER_HOME/db and subdirectories thereof. A building block library is a set of PDB files containing the coordinate data as well as text file (called "names file") containing the relative filenames of involved PDB files (one filename in each row). Ideally the names file specifies one PDB file for each building block, however a one-to-one correspondence between building blocks and PDB files is not a requirement. At the beginning it is easiest to use pre-made building block libraries located in the directories $NANOTILER_HOME/db/rnajunction and $NANOTILER_HOME/test/fixtures.
Quick start: Issue the command:
demo loadjunctions
After the demo finished, one can see from the text output or with an additional “status” command that one kissing loop structure was loaded.
What just happened? This very short script issues a loadjunctions command. The status command before and after the loadjunctions command monitors the difference.
A building block library can be loaded with the command:
For example:
loadjunctions ${NANOTILER_HOME}/test/fixtures/triangle.names
reads one building block because the file triangle.names contains the filename of one building block. Alternatively, one can read the library using the GUI: Building locks→Load Database
The loadjunctions command clears all currently loaded building blocks, reads a names file and reads the PDB files in one at a time.
One can see the number of building blocks using the command status.
A building block can be placed into the work space with the command place.
Quick start: Issue the command:
demo place
After the demo is finished, view the exported PDB structure place_demo.pdb with a visualization tool of your choice.
What just happened? The executed script place.script in the directory ${NANOTILER_HOME}/demo/scripts contains as a central command:
This command places the first 3-way junction at the xyz position 10, 0, 0 into the workspace (as a child node of the node called “root”). The placed junction will have the name “j1”. The last parameter “_1” specifies a suffix for the new strands to avoid RNA strands with a strand name that was previously generated.
The synopsis of the place command is:
place j|k parentname name order index x y z ending
The most important commands regarding building block libraries are called grow and growgraph; they are explained in the section about simulated self-assembly.
To define a custom building block library one has to have a set of PDB coordinate data files containing the building blocks as well as a text files with the ending ".names" that contains one relative PDB filename per line. The coordinate files containing the building blocks can be obtained either from the RNAJunction database (http://rnajunction.abcc.ncifcrf.gov, use the "download" link at individual entries), or they can be extracted from original PDB files using the provided junctionscan script located in $NANOTILER_HOME/bin
To extract the building blocks from a PDB file issue the following command from the outside shell (not nanoscript/nanotiler):
(notice the 2 dots separated by a space: they denote the read and write directories for the coordinate data)
In the current working directory there should be a set of extracted structural elements as well as a set of property files with the ending "_db.txt".
The names file specifies the set of PDB files that are part of the building block library; it can be generated using some Unix commands, for example
ls *.pdb | tr "\t " "\n" | tr -s "\n" > myjunctions.names
A names files generated in this fashion might need further editing or visual inspection steps.
Note that the junctionscan program uses several constants to determine what constitutes a helix or a structural element. These constants can be changed by modifying the file $NANOTILER_HOME/src/JunctionScanner.properties and re-building with the program ant (see the Developer Notes section in the Appendix). Depending on the setting of these constants, the requirements for detected helices are more or less strict. The constants used for the RNAJunction database (http://rnajunction.abcc.ncifcrf.gov/) are described in our publication: Bindewald E., Hayes R., Yingling Y., Kasprzak W. and Shapiro B.A.: RNAJunction: A Database of RNA Junctions and Kissing Loops For Three-Dimensional Structural Analysis and Nanodesign. Nucleic Acids Resarch, 2008, 36 (Database issue): D392-D397.
The program allows one to quickly generate 3D graphs using the command genshape.
Quick start: Issue the command:
What just happened? The command genshape initiates the generation of a 3D graph. If a graphics window is activated (for example running the nanotiler script instead of the na noscript script), one should immediately see the generated shape of a dodecahedron. Other modifiers are: tetrahedron, cube, octahedron, icosahedron. Regular polygons (rings) consisting of N points can be generated with the command genshape ringN (substitute the number for N). For example the command
genshape ring4
generates a square.
3D graph structures can be read from a file using the import command.
Quick start: Issue the command:
demo importgraph
The script lists the defined graph vertices and edges. The graph structure can be seen in a graphics window if one is active.
What just happened? The script consists essentially of the command:
Note that it is important that the file has the ending “.points”.
The 3D graph reads as follows:
6
1 0 43.3 0
2 50 -43.3 0
3 -50 -43.3 0
4 0 86.6 0
5 100 -86.6 0
6 -100 -86.6 0
6
1 2
2 3
1 3
1 4
2 5
3 6
The input data defines the set of vertices (including their respective x,y,z coordinates in space) as well as a set of edges connecting the vertices.
The format is:
number_of_points
point_id x y z
...
number_of_links
point_id point_id
...
The command grow generates for a specified set of building blocks and connectivity rules a corresponding “grown” structure.
Quick start: Issue the command:
demo grow
After the script is finished, check for generated PDB files in the current working directory containing an RNA triangular structure with the names grow_demo.pdb and grow_demo_nohelices.pdb
What just happened? The grow demo script reads as follows:
set outfile grow_demo
echo This demo script reads a junction library
echo and "grows" a ring structure
loadjunctions ${NANOTILER_HOME}/test/fixtures/triangle.names
grow blocks=j,3,1 connect=1,1,1,2,6 ring-export-limit=25
ring-export=${outfile}
echo Check for generated PDB files with the name base ${outfile}
The central command of the script is the line
grow blocks=j,3,1 connect=1,1,1,2,6 ring-export-limit=25
This command has the required keywords “blocks” and “connect”. In combination these two options specify the connectivity rules of the set building blocks of the self-assembly simulation. The blocks option is defined as:
blocks=j|k,order,index[;j|k,order,index[...]].
The specification “blocks=j,3,1” specifies the first three-way junction according to a prior loadjunctions command. Specifying for example “blocks=k,2,5” would specify the 5’th defined kissing loop structure according to a prior loadjunctions command. Building block specifications can be concatenated with a semicolon (for example blocks=j,3,1;k,2,5). The connect option specifies the helices that are connecting the different building blocks. Its synopsis is:
connect=index1,index2,helixid1,helixid2,basepairs .
For example, the option connect=3,4,1,2,6 means “connect helix 1 of the third read building block with helix 2 of the fourth building block using a 6 base pair spacer helix”. The building block id refers to the order of appearance in the required blocks option.
Other options of the grow command are:
: specifies the number of generations N of the self-assembly simulation. Default is gen=3
: specifies if atoms of spacer helices should be generated. Default is helices=true
: specifies a file name prefix for found ring structures for exporting them in PDB file format
: specifies an error threshold for what is considered a closed ring structure. Default is a value of 15.0
: specify if the grow-procedure should check for steric clashes. Default is steric=true
The challenge of the above mentioned “grow” command is that the user has to know in advance which combination of helix connections and spacer helix lengths will lead to the desired assembled structure. One way around that is to use the foreach command and loop over different spacer helix lengths. The growgraph command takes this programming burden from the user: it uses as input a set of building blocks as well as one defined 3D graph structure. The command then launches an algorithm that iterates over all combinations of helix connections and all combinations of spacer helix lengths. Structures whose topology is the same as the topology of the 3D graph structures are written to the file system.
Note: this command will only work properly if the topology signature program called “tra” is correctly installed. Consult the installation section for more information.
Quick start: Issue the command:
demo growgraph
After the script is finished, one can examine the triangular RNA structures with the name growgraph_demo_fr.pdb and growgraph_demo_fr_nohelices.pdb
What just happened? The corresponding script (growgraph.script located in the directory ${NANOTILER_HOME}/demo/scripts) reads after removing non-essential commands as follows:
loadjunctions ${NANOTILER_HOME}/test/fixtures/triangle.names
import ${NANOTILER_HOME}/test/fixtures/trianglestar.points scale=0.17
growgraph root=root.import gen=3 block-max=1 conn-max=1 var=3 name=growgraph_demo
The loadjunctions command reads one 3-way junction specified in the file triangle.names
The import command reads a 3D graph structure specifying a triangle with 3-way corners (see for more details section 10.2 Importing graph structures). The growgraph command has the following options:
: specifies the maximum number of different building blocks that can be used for each cycle of the grow simulation.
: specifies the maximum number of different connectivity rules that can be used for each cycle of the grow simulation.
: specifies the helix length variability. For N=3 the program searches for each spacer helix the lengths L-3,L-2,L-1,L,L+1,L+2,L+3 with L being the estimated ideal spacer helix length based on the graph edge length.
: specifies the maximum number of grow generations.
: specifies the output file name prefix.
: specifies the subtree containing the 3D graph used as a basis for the algorithm.
Quick start: Issue the command:
After the script is finished, one can examine the generated exported file with the name optbasepairs_demo.pdb
What just happened? The demo script (optbasepairs.script located in the directory $NANOTILER_HOME/demo/scripts) reads in one side of a triangular structure, generates two copies of it with the clone command, generates base pair constraints between specified bases on the building blocks and finally optimizes the orientation of the tree triangle sides such that the constraints describing the desired base pairing are as small as possible. The script reads as follows:
loadbasepairs ${NANOTILER_HOME}/resources/157D_rnaview_edit.pdb
import ${NANOTILER_HOME}/test/fixtures/trianglepart.pdb findstems=false
# generate two copies of the imported structure
# corresponding to the three sides of a triangle:
clone root.import root import_b
clone root.import root import_c
select root.import_b
# move objects to roughly meaningful initial positions
shift 40 0 0
select root.import_c
shift 0 40 0
# generate two constraints between strands import.A and import_b.A:
genbpconstraint root.import.A.11 root.import_b.A.47 2
# generate two constraints between strands import_b.A and import_c.A:
genbpconstraint root.import_b.A.11 root.import_c.A.47 2
# generate two constraints between strands import.A and import_c.A:
genbpconstraint root.import_c.A.11 root.import.A.47 2
# Start the optimization
optbasepairs blocks=root.import;root.import_b;root.import_c steps=20000 error=5
exportpdb optbasepairs_demo.pdb
The genbpconstraint command specified one or several base pairs to connect. The central command of the script is the optbasepairs command:
optbasepairs blocks=root.import;root.import_b;root.import_c steps=20000 error=5
This command specifies the movement of three rigid sub-trees (root.import, root.import_b and root.import_c) using 20000 optimization steps and an error threshold of 5.0.
The command fusestrands allows one to fuse two RNA strands together (creating one covalent bond) provided that the 3’ end of one strand is close to the 5’ end of the other strand. The synopsis of the command is:
fusestrands STRANDNAME1 STRANDNAME2
with STRANDNAME1 and STRANDNAME2 being the qualifying names of the two involved strands.
The command splitstrand allows one to split an RNA strand into two fragments.
Quick start: Issue the command:
After the script is finished running, one can view the generated structure on the graphics window or load the structure “testSplitStrand.pdb” into a molecular viewing program.
What just happened? The original structure with the filename 1LDZ_model1.pdb located in the directory ${NANOTILER_HOME}/test/fixtures consists of one strand, the command splitstrand has split this strand into two RNA strand fragments.
The script corresponding to the demo splitstrand command is located in ${NANOTILER_HOME}/demo/scripts/splitstrand.script
The content is:
import ${NANOTILER_HOME}/test/fixtures/1LDZ_model1.pdb findstems=false
echo Original strand(s):
tree strands
# split strand A at 12’th residue:
splitstrand root.import.A 12
echo Strand(s) after split:
tree strands
exportpdb testSplitStrand.pdb
The central command is
splitstrand root.import.A 12
This command tells the program to split the strand specified with its complete qualifying name at the n’th residue, n being 12 in this case.
If a raw ring was generated from fragments, the next step is to fuse the sequences in a meaningful way in order to generate “sticky tails”, that is overlapping strand ends so that the fragments will not fall apart.
Quick start: Within nanotiler or nanoscript application issue the command:
demo ringfuse
After the script is finished, one can view the generated fused structure on the screen or use a molecular viewer (like jmol or rasmol) and open the newly generated file ringFuseCommandTest.pdb
What just happened? The script reads a PDB structures, runs the ringfuse command and exports the result. The ringfuse command launches an algorithm (described in more detail in our publication) that consecutively connects RNA strands such that each strand contains no more than one copy of any type of structural element.
The script for the ringfuse demo can be found in the file ringfuse.script in the directory $NANOTILER_HOME/demo/scripts :
import ${NANOTILER_HOME}/test/fixtures/ringFixConstraintsCommandTest_fixed_all.pdb
echo Found junctions:
tree allowed=StrandJunction3D
tree strands
ringfuse root
echo Fused strands:
tree strands
exportpdb ringFuseCommandTest.pdb junction=false name=root.fused renumber=count
The central command is ringfuse root, with the option root specifying the subtree to apply the algorithm to.
Quick start: Issue the command:
or the GUI equivalent: File→Demo→mutate. After the script is finished, one can examine the generated modified PDB structure with the filename 1NBR_model1_A2A15U29.pdb and compare it to the original structure with the name 1NBR_model1.pdb in the directory $NANOTILER_HOME/test/fixtures/.
What just happened? NanoTiler allows for a fairly robust way of mutating single bases or base pairs. The command mutate simple takes a list of bases to be mutated.
The demo script consists in essence of the following two commands:
# findstems=false prevents generation of additional data structures:
import ${NANOTILER_HOME}/test/fixtures/1NBR_model1.pdb findstems=false
# mutate residues 2, 28 and 15 of strand A to residues A, U and A:
mutate A:A2,U28,A15
The algorithm works by trying to find a pre-loaded base or base pair that is consistent with the desired target bases(s). The algorithm checks if the newly inserted bases do not lead to large gaps in the backbone or steric clashes with neighboring bases. For this to work it is important that a table of bases is read beforehand. This happens with the command loadbasepairs FILENAME with FILENAME being the file name of a PDB coordinate structure of an RNA structure from which coordinates of paired and unpaired bases are to be taken. A loadbasepairs command is issued by default at startup-time of the nanotiler/nanoscript program due to the script defaults.script located in the directory ${NANOTILER_HOME}/resources .
By modifying this script it is possible to change the reference bases and base pairs. The two offered choices that can used as reference data defined in this script are the following two PDB files: 157D_rnaview_edit.pdb and 2J00_A_rnaview.pdb, both are located in the directory $NANOTILER_HOME/resources.
The secondary structure of the molecular model is represented as links between nucleotides. One can view the currently active secondary structure with the command:
The equivalent output can be seen in the window with the title “Secondary Structure” at the bottom of the NanoTiler graphical user interface. Additional base pair interactions can be generated with the command
with NAME1 and NAME2 being the qualifying names of two nucleotides. Unwanted interactions can be removed using the command rmlink (see section Basic Concepts).
The sequence optimization (command optsequences) has as its goal the modification of the strand sequences such that the predicted secondary structure interactions are as similar as possible to the specified secondary structure (output of command secondary). Before launching the optsequences command one has to tell the system which residues are allowed to be modified. We recommend using the graphical user interface for specifying what nucleotides to optimize using the pull-down menu item Launch→Sequence Optimization. The sequence optimization can be started from the same window.
The command foreach allows one to specify a loop with a variable set to different values at each iteration.
Quick start: Issue the command:
The result should look as follows:
This demo demonstrates how a foreach loop can set a variable
to any sequence of letters and numbers
The current value is: mercury
The current value is: venus
The current value is: earth
The current value is: 7
The current value is: 3.29
What just happened? The script foreach.script located in the directory $NANOTILER_HOME/demo/scripts reads as follows:
echo This demo demonstrates how a foreach loop can set a variable
echo to any sequence of letters and numbers
foreach a ( mercury venus earth 7 3.29 )
echo The current value is: ${a}
end
The command foreach VARNAME ( ITEM1 ITEM2 ... ) ... end specifies a loop with a variable with the name VARNAME having the values ITEM1, ITEM2, etc.
| chosen | Shows selected 3D object | View→Chosen |
| clear | Removes all objects from workspace | Edit→Clear All |
| clone | copies a 3D object | Edit→Clone |
| demo | Runs a demo script | File→Demo/Help→Welcome Window |
| env | Lists script variables | View→View Variables |
| exportpdb | Exports atom coordinates to PDB file | File→Export→PDB |
| foreach | Loops over different variable values | - |
| genbpconstraint | Generates base pair constraint | Generate→Basepair Constraint |
| genhelix | Generates RNA double helix | Generate→Helix |
| genhelixconstraint | Generates helix constraint | Generate→Helix Constraint |
| genlink | Generates link between 3D objects | Generate→Link |
| genshape | Generates 3D graph | Generate→Planar shape/Platonic Solid |
| graphics | Launches graphics window | - |
| grow | Starts simulated self-assembly | Build blocks→Grow |
| growgraph | Topology constrained self-assembly | Build blocks→Grow Graph |
| help | General or command-specific help | Help→Command Help |
| history | Shows command history | window “Command history” |
| import | imports PDB structure or graph | File→Import |
| links | Lists defined links between 3D object | View→Links |
| loadbasepairs | Loads reference base pairs | - |
| loadjunctions | Loads building block library | Building blocks→Load Database |
| mutate | Mutates residues in structure | - |
| optbasepairs | Opimizes RNA sequences | Launch→Sequence Optimization |
| opthelices | Optimizes helix constraints | Optimize→Helices |
| place | Places building block in workspace | Building blocks→Place |
| quit | Quits program | File→Quit |
| remove | Removes 3D object from workspace | - |
| ringfuse | Fuses strands | - |
| rmlink | Removes link | Edit→Remove Link |
| rotate | Rotates a selected 3D object | Edit→Rotate |
| secondary | Shows the defined secondary structure | Window “Secondary Structure” |
| select | select a 3D object | Edit→Select |
| set | set a script variable to a value | - |
| shift | Shifts selected 3D object | Edit→Shift |
| signature | Topology signature of graph | View→Generate Signature |
| splitstrand | Splits an RNA strand into two fragments | - |
| status | Show ref. base pairs, building blocks | Building blocks→Database Info |
| tree | Lists objects in scene graph | View→Tree |
The distribution contains the full source code as well as production data in the form of junctions and kissing loops from the RNAJunction database.
For modifying and compiling the source code, the Apache ant software has to be installed (http://ant.apache.org/). A Java version of Java 5 or higher is assumed (http://java.sun.com). The software was developed using test-driven development using the TestNG Unit testing framework (http://testng.org). The default working directory is $NANOTILER_HOME/src. In this directory, the following commands are available:
| Task | Command |
| Compile sources | ant |
| Clean Java sources | ant clean |
| Create JavaDoc Documentation | ant doc |
| Run unit tests | ./runtestng_notslow.sh |
| Name | Comment | |
| 0.9 | Initial version | |
| 0.9.1 | Removed rnaview binary | |
| 0.9.2 | Added test cases, junctionscan | |
demo, 14
env, 24
exportpdb, 18, 23
foreach, 37
genbpconstraint, 32, 36
genhelix, 15, 19
genhelixconstraint, 17
genlink, 21
genshape, 27
graphics, 15, 19
grow, 18, 29
growgraph, 30
help, 14
history, 18, 22
import, 21, 22, 28
junctionscan, 13, 26
JunctionScanner, 13, 26
links, 21
loadbasepairs, 32
loadjunctions, 16, 25
mutate, 35
optbasepairs, 32
opthelices, 18
place, 17, 26
quit, 18
remove, 16, 21
ringfuse, 34, 35
rmlink, 21
rotate, 16
secondary, 36
select, 16, 20
set, 24
shift, 16
splitstrand, 33
status, 16
tree, 15, 19