Manual for RNA-As-Graphs Topology (RAGTOP) software suite

Transcription

1 Manual for RNA-As-Graphs Topology (RAGTOP) software suite Schlick lab Contents 1 General Information Copyright statement Citation requirements Support Download instructions 2 3 Main features General tree graph definitions RNA 3D graph sampling with Monte Carlo F-RAG for RNA 3D structure prediction F-RAG for design of RNA-like motifs Other features Removal of pseudoknots from the 2D structure Generating loop and vertex information for RAG-3D External libraries used 12 1 General Information This is the user manual for the RNA-As-Graphs Topology (RAGTOP) software suite, developed in the lab of Prof. Tamar Schlick at New York University. The different features offered by this software include representing RNA secondary (2D) structure as three-dimensional (3D) tree graphs and sampling different graph topologies [1, 2]; fragment assembly for RNA graphs (F-RAG) to generate 3D atomic models of RNA for graphs [3], and design of sequences to fold onto RNA-like tree graph topologies [4]. 1.1 Copyright statement The RAGTOP software suite was developed in the lab of Prof. Tamar Schlick at New York University. The package is provided for use in research purposes only; for other applications please contact Prof. Tamar Schlick (schlick@nyu.edu). We require everyone who publishes or presents results from RAGTOP to please cite our program, names of individual components, and associated original publications, as below: 1

2 1.2 Citation requirements Please cite the papers below when using RAGTOP. Papers 1 and 2 are for RAGTOP s JunctionExplorer component to predict coaxial stacking and family for 3-way and 4-way junctions; papers 3 and 4 are for RAGTOP s Monte Carlo/Simulated Annealing component to sample 3D tree graph topologies; and papers 5 and 6 are for RAGTOP s F-RAG component to generate atomic models for RNA 3D structure prediction and design of RNA-like topologies. 1. C. Laing, D. Wen, J. T. L. Wang, and T. Schlick, Predicting coaxial helical stacking in RNA junctions., Nucleic Acids Res, vol. 40, no. 2, pp , C. Laing, S. Jung, N. Kim, S. Elmetwaly, M. Zahran, and T. Schlick, Predicting helical topologies in RNA junctions as tree graphs, PLoS ONE, vol. 8, no. 8, p. e71947, N. Kim, C. Laing, S. Elmetwaly, S. Jung, J. Curuksu, and T. Schlick, Graph-based sampling for approximating global helical topologies of RNA, Proc Natl Acad Sci USA, vol. 111, no. 11, pp , C. S. Bayrak, N. Kim, and T. Schlick, Using sequence signatures and kink-turn motifs in knowledgebased statistical potentials for RNA structure prediction., Nucleic Acids Res, vol. 45, no. 9, pp , S. Jain and T. Schlick, F-RAG: Generating atomic models from RNA graphs using fragment assembly, J Mol Biol, vol. 429, no. 23, pp , S. Jain, A. Laederach, S. B. Ramos, and T. Schlick, A pipeline for computational design of novel RNA-like topologies, Nucleic Acid Res, (In Revision), Support Please feel free to contact us by if you have questions. We are also planning to develop a RAGTOP webserver. The input for F-RAG requires running RAG-3D partitioning and search. Please contact us for RAG-3D scripts and database. 2 Download instructions RAGTOP executables (for Mac OS and Linux operating systems) are available to download from our website ( 1. Download the software package for your operating system and untar it: tar zxvf <package name> 2. Change directory to the package directory with the executable file: cd <package directory> The package directory contains: 1. The executable file RAGTOP 2

3 2. The parameter files for the scoring potential and alternate fragments (helices, hairpins, and internal loops for F-RAG) needed to run RAGTOP 3. Examples/ directory with sample input and output files for different features 4. Description files for external libraries used (see Section 5) Please refer to the sections below for instructions on how to run RAGTOP for different features. 3 Main features 3.1 General tree graph definitions The 2D structure of an RNA molecule can be represented in the form of an undirected tree graph G = (V, E) [5, 6]. Vertices V correspond to different loops: hairpin loops, internal loops and bulges (with at least two nucleotides in either strand), junctions, and dangling ends. A dangling end refers to exterior loop residues next to stems at the ends of the RNA sequence. Edges E correspond to helical stems, with at least two canonical base pairs (AU, GC, and GU wobble). Isolated single base pairs are ignored. We convert the 2D tree graph into a 3D tree graph with additional vertices and edges [1]. Two vertices are added to represent the 5 and 3 ends for each helix, along with vertices for internal loops and bulges that contain less than two nucleotides in either strand. The edges of the graph now connect the two vertices representing each helix, or the loop vertices to the proximal end helical vertices. The lengths of each edge are scaled by the number of residues in the corresponding helices and loops. Figure 1 shows the 2D and 3D tree graphs for a 57-residue fragment of rrna (PDB ID: 1DK1). Figure 1: 2D and 3D tree graphs for a 57-residue fragment of rrna (PDB ID: 1DK1) Our RAGTOP code takes the 2D structure as input and constructs the corresponding 3D tree graph. For the purposes of the code, the loops in the 2D structure are numbered as follows: the dangling ends are numbered first, followed by hairpins, internal loops and bulges, and then junctions. Within each loop category, the loops are numbered in the order their strands are encountered in the 5 to the 3 direction. The vertices of the 3D tree graph are numbered similarly, with the helical end vertices connected to the loop vertices being numbered along with their loop vertices (i.e., before the next loop is numbered). Figure 2 shows an example of numbering loops and vertices for a given 2D structure and the corresponding 3D tree graph. 3

4 Figure 2: Loop and vertex numbers used in the code for the 2D structure the corresponding 3D tree graph for a 57-residue fragment of rrna (PDB ID: 1DK1) 3.2 RNA 3D graph sampling with Monte Carlo This feature samples 3D tree graphs of known 2D structure and selects candidate graph topologies [1, 2] for further processing. The candidate graphs can serve as input for F-RAG (for building atomic models) for RNA 3D structure prediction (see Subsection 3.3). The input 2D structure is converted to a 3D tree graph (as described in Subsection 3.1) and the coaxial stacking and family for helical arrangements for RNA junctions are predicted using data mining tools [7, 8]. Next, Monte Carlo/Simulated Annealing (MC/SA) sampling is performed at flexible internal loop vertices of the 3D tree graph. For each move, an internal loop and one of its adjacent helices is randomly selected for rotation along a randomly selected axis (x, y, or z). For random moves (default), the range of angle is always full (i.e., 360 ). For local or restricted moves, the angle range is reduced gradually from 360 to 10. The SA protocol (default) involves cooling the system temperature by the effective term T i = c/log2(1 + i/s), where c is a constant, i is the iteration number, and s is the total number of MC moves specified a priori (50,000 steps). The junction orientation is fixed during the MC/SA simulation. All sampled graph topologies are scored by a knowledge-based scoring function derived from known RNA structures. Terms include bend and twist potentials of helices around internal loops (enhanced by identifying kink-turn sequence patterns), and radius of gyration measurements. The flags needed to run the MC/SA simulation for 3D tree graph topology sampling are: Required flags: -mcrun -file filename -inputdir path -outputdir path MC/SA run input 2D structure in bpseq format (without extension) input directory output directory 4

5 Optional flags: -mc nosa -mc restrict -ref -pdbdir path The input directory must contain: SA is not performed restricted moves are used (instead of random moves) during MC a reference structure will be read from path and the corresponding 3D tree graph will be used as the MC starting point 1. The input 2D structure (filename.bpseq) After the MC/SA run is completed, the output directory will contain: 1. The 3D tree graph constructed from the 2D structure after junction prediction and before the MC/SA sampling (filename Graph.pdb) 2. The accepted graph topologies from the MC/SA sampling (as a zipped file) along with their scores (graphs.zip and scores filename.txt) 3. Bend, twist, radius of gyration, total scores, and accept/reject decision for all 50,000 MC/SA sampling steps (bends filename.txt, twist filename.txt, radius filename.txt, scores all filename.txt, and RGsampling filename.txt) 4. Text file listing the parameters used in the MC/SA sampling (MC Params.txt) Examples/MCRun/ contains sample input and output directories for the following MC/SA run:./ragtop -mcrun -file 1DK1 -inputdir Examples/Graph/Input/ -outputdir Examples/Graph/Output/ 3.3 F-RAG for RNA 3D structure prediction Fragment-Assembly for RNA-As-Graphs (F-RAG) is used for generation of atomic models for a target RNA 2D structure and a 3D tree graph topology [3] obtained by MC/SA graph sampling (described in Subsection 3.2). This task is performed using fragment assembly, where the target graph is partitioned into subgraphs [9, 10], and the best matching atomic fragments are assembled using common graph vertices. This requires running RAG-3D search [10] to partition the target graph into subgraphs and return the best matching atomic fragments for each of those subgraphs that are then used as input for the F-RAG algorithm. All generated models are scored using the knowledge-based potential developed for 3D tree graph topology sampling [1, 2]. The flags needed to run F-RAG for generating atomic models for a 2D structure and a target 3D tree graph are: 5

6 Required flags: -atomcoords -file filename -inputdir path -outputdir path -graphname id -subgraph subfile -fragment dir path -libdir path Optional flags: run F-RAG for generating atomic models for a given 3D tree graph input filename identifier input directory output directory target 3D tree graph identifier subgraph information for target 3D tree graph fragment directory with atomic fragment files LibFiles directory (containing files used for mutating bases and alternate hairpin and internal loops) -ref -pdbdir path The input directory must contain: if specified, a reference structure will be read from the path and the corresponding 3D tree graph will be used as the target for atomic model generation 1. The input 2D structure (filename.bpseq) 2. The target 3D tree graph topology (filename idgraph.pdb) 3. The file containing the subgraph information of the target 3D tree graph (subfile) The subgraph information file should have the following format (see example subgraph file Examples/AtomCoords/Input/Subgraphs.txt for subgraph division shown in Figure 3): numsubgraphs numfragments numvertices subgraph0 subgraph1... subgraphn 1 subgraph 0 fragments subgraph 1 fragments... subgraph n-1 fragments n numfrags 0 numfrags 1... numfrags n 1 numvertices 0 numvertices 1... numvertices n 1 list of subgraph 0 vertices list of subgraph 1 vertices list of subgraph n-1 vertices (e.g., subgraph0 frag0, one fragment per line) where n is the number of subgraphs, numfrags i is the number of fragments for subgraph i, and numvertices i is the number of 3D tree graph vertices in subgraph i (not including vertices for single residue internal loops or bulges). 6

7 Figure 3: Subgraphs used in F-RAG for a 57-residue fragment of rrna (PDB ID: 1DK1). See Subsection 3.1 for how 3D tree graph vertices are numbered. The fragment directory must contain: 1. The PDB files for atomic fragments corresponding to different target subgraphs (e.g., subgraph0 frag0.pdb) 2. The 2D structure files for atomic fragments corresponding to different target subgraphs (e.g., subgraph0 frag0.bpseq) After the F-RAG run is completed, the output directory will contain: 1. The 3D tree graph constructed from the 2D structure after junction prediction (filename Graph.pdb) 2. Generated atomic models and associated 3D tree graphs (Model i.pdb and Graph i.pdb, where i is the atomic model number) 3. Text file with columns listing the atomic model number, graph RMSD of the atomic model 3D tree graph with the target 3D graph, score of the atomic model 3D tree graph, if the atomic model 3D tree graph contains a steric clash, and number of residues in the atomic model (ModelScores.txt) 4. Text file with columns listing the atomic model number and the fragments used to construct that atomic model (ModelFragments.txt) The atomic models generated by F-RAG are not optimized for energy or geometry and may contain missing residues and chain breaks. For best results, we recommend running F-RAG for multiple subgraph decompositions of the target 3D tree graph, selecting atomic models with the highest number of residues and lowest scores (lower scores are better), followed by geometry optimization and/or energy minimization before further use [3]. 7

8 Examples/AtomCoords/ contain sample input and output directories for F-RAG run for the target 2D structure and subgraph decomposition shown in Figure 3. The following command was used for the F-RAG run:./ragtop -atomcoords -file 1DK1 -graphname P2 -inputdir Examples/AtomCoords/Input/ -outputdir Examples/Graph/Output/ -subgraph Subgraphs.txt -fragment dir Examples/AtomCoords/Input/MATCHES/ -libdir LibFiles/ 3.4 F-RAG for design of RNA-like motifs This functionality is for Fragment-Assembly for RNA-As-Graphs (F-RAG) as used for designing sequences and plausible atomic models that fold onto a target RNA-like tree graph topology [4]. This task is performed using fragment assembly, where the target RNA-like topology [11] is partitioned into subgraphs, and the atomic fragments corresponding to those subgraphs are assembled using common loops and helices. F-RAG uses the atomic fragments in the RAG-3D database [10] for each of target subgraphs as input. All generated models are scored using the knowledge-based potential developed for 3D tree graph topology sampling [1, 2]. The flags needed to run F-RAG for generating atomic models to fold onto a target RNA-like topology are: Required flags: -design -file filename -inputdir path -outputdir path -subgraph subfile -fragment dir path Optional flags: run F-RAG for generating atomic models for a given RNA-like topology information for target RNA-like topology input directory output directory subgraph information for target RNA-like topology fragment directory with atomic fragment files -libdir path directory containing atomic fragments for restricted hairpins or internal loops (if restricted loops are specified in the target file) The input directory must contain: 1. The file describing the target RNA-like topology (filename) 2. The file containing the subgraph information of the target RNA-like topology (subfile) The file with the target RNA-like topology information should have the following format (see example target file Examples/Design/Input/Target.txt for RNA-like topology shown in Figure 4): 8

9 numloops looporder adjmatrix restrictloops restrictloopfiles n 5 to 3 order of loops adjacency matrix for the target graph (5 to 3 order) rloopnum restrictfrag where n is the number of loops in the target RNA-like topology, looporder specifies the order of loops in the 5 to 3 order, and adjacency matrix specifies the loop connections in the 5 to 3 order. The looporder and adjacency matrix specify the orientation of the target topology. If any loop is to be restricted to a specific fragment, rloopnum specifies the loop number, and restrictfrag specifies the name of the fragment to be used. The subgraph information file should have the same format as described in Subsection 3.3 (see example subgraph file Examples/Design/Input/Subgraphs.txt for subgraph division shown in Figure 4): Figure 4: Loop numbers, vertex numbers and subgraphs used in F-RAG for the RNA-like topology 8 9. See Subsection 3.1 for how the loops and 3D tree graph vertices are numbered. The fragment directory must contain: 1. The PDB files for atomic fragments corresponding to different target subgraphs (e.g., subgraph0 frag0.pdb) 9

10 2. The 2D structure files for atomic fragments corresponding to different target subgraphs (e.g., subgraph0 frag0.bpseq) If specified, the restricted fragment directory must contain: 1. The PDB file for the atomic fragment to be used for the restricted loop (e.g., restrictfrag.pdb) 2. The 2D structure file for the atomic fragment to be used for the restricted loop (e.g., restrict- Frag.bpseq) After the F-RAG run is completed, the output directory will contain: 1. Generated atomic models and corresponding 3D tree graphs and 2D structure files (Model i.pdb, Graph i.pdb, and Model i.bpseq, where i is the atomic model number) 2. Text file with columns listing the atomic model number, score of the atomic model 3D tree graph, if the atomic model 3D tree graph contains a steric clash, and number of residues in the atomic model (ModelScores.txt) 3. Text file with columns listing the atomic model number and the fragments used to construct that atomic model (ModelFragments.txt) The atomic models generated by F-RAG are not optimized for energy or geometry and may contain chain breaks. The sequences of the atomic models are not guaranteed to fold onto the target RNA-like topology with RNA 2D structure prediction programs. For best results, we recommend running F-RAG for multiple orientations and subgraph decompositions of the target RNA-like topology, selecting atomic models without chain breaks and lowest scores (lower scores are better), followed by further screening based on the graph topologies of the 2D structures predicted by at least two different structure prediction programs [4]. Examples/Design/ contain sample input and output directories for F-RAG run for the target RNA-like topology orientation and subgraph decomposition shown in Figure 4. The following command was used for the F-RAG run:./ragtop -design -file Target.txt -inputdir Examples/Design/Input/ -outputdir Examples/Design/Output/ -subgraph Subgraphs.txt -libdir LibFiles/InternalLoops/ -fragment dir Examples/Design/Input/Fragments/ 4 Other features 4.1 Removal of pseudoknots from the 2D structure RAGTOP can also be used to remove pseudoknots from an input 2D structure by using the following flags: 10

11 Required flags: -remove pk -file filename -inputdir path -outputdir path remove the pseudoknot from the input structure input 2D structure in bpseq format (without extension) input directory output directory The input directory must contain the input 2D structure (filename.bpseq). After the run is completed, the output directory will contain the 2D structure file without pseudoknots (filename nopk.bpseq). 4.2 Generating loop and vertex information for RAG-3D This feature is used to generate files containing description of the loops types in a given RNA 2D structure and the vertex types in its corresponding 3D tree graph. These files are used as input for RAG-3D search [10] to partition a 3D tree graph into subgraphs and return best matching fragments for each subgraph (used as input for F-RAG for 3D structure prediction as described in Subsection 3.3). The flags needed to generate loop and vertex information for a 2D structure are: Required flags: -graph -file filename -inputdir path -outputdir path generate the loop and vertex files input 2D structure in bpseq format (without extension) input directory output directory The input directory must contain: 1. The input 2D structure (filename.bpseq) After the run is completed, the output directory will contain: 1. The 3D tree graph constructed from the 2D structure after junction prediction (filename Graph.pdb) 2. Text file with loop numbers (dangling end, hairpin, internal loop, or junction) and corresponding residue numbers (Loopsfilename.txt) 3. Text file with vertex number for helical vertices in the tree graph, along with corresponding residue numbers (Verticesfilename.txt) 4. Text file with vertex number for loop vertices and corresponding loop type (VertexTypesfilename.txt) Examples/Graph/ contains sample input and output directories for the following run:./ragtop -graph -file 1DK1 -inputdir Examples/Graph/Input/ -outputdir Examples/Graph/Output/ 11

12 5 External libraries used 1. Template Numerical Toolkit (TNT) - an interface for scientific computing in C++. It is developed at the National Institute of Standards and Technology (NIST) and available to download from https: //math.nist.gov/tnt/index.html. 2. Mersenne Twister - a random number generator ( MT/emt.html). Please see the enclosed description file. 3. Random Forests with Artificial Construct Ensembles (rfacer) - developed by Timo Erkkila. Please see the enclosed description file. References [1] N. Kim, C. Laing, S. Elmetwaly, S. Jung, J. Curuksu, and T. Schlick, Graph-based sampling for approximating global helical topologies of RNA., Proc Natl Acad Sci USA, vol. 111, no. 11, pp , [2] C. S. Bayrak, N. Kim, and T. Schlick, Using sequence signatures and kink-turn motifs in knowledgebased statistical potentials for RNA structure prediction., Nucleic Acids Res, vol. 45, no. 9, pp , [3] S. Jain and T. Schlick, F-RAG: Generating atomic models from RNA graphs using fragment assembly, J Mol Biol, vol. 429, no. 23, pp , [4] S. Jain, A. Laederach, S. B. Ramos, and T. Schlick, A pipeline for computational design of novel RNA-like topologies, Nucleic Acid Res, p. In Revision, [5] H. H. Gan, S. Pasquali, and T. Schlick, Exploring the repertoire of RNA secondary motifs using graph theory; implications for RNA design, Nucleic Acids Res, vol. 31, no. 11, pp , [6] H. H. Gan, D. Fera, J. Zorn, N. Shiffeldrim, M. Tang, U. Laserson, N. Kim, and T. Schlick, RAG: RNA-As-Graphs database concepts, analysis, and features, Bioinformatics, vol. 20, no. 8, pp , [7] C. Laing, D. Wen, J. T. L. Wang, and T. Schlick, Predicting coaxial helical stacking in RNA junctions., Nucleic Acids Res, vol. 40, no. 2, pp , [8] C. Laing, S. Jung, N. Kim, S. Elmetwaly, M. Zahran, and T. Schlick, Predicting helical topologies in RNA junctions as tree graphs, PLoS ONE, vol. 8, no. 8, p. e71947, [9] N. Kim, Z. Zheng, S. Elmetwaly, and T. Schlick, RNA graph partitioning for the discovery of RNA modularity: a novel application of graph partition algorithm to biology, PLoS ONE, vol. 9, no. 9, p. e106074, [10] M. Zahran, C. S. Bayrak, S. Elmetwaly, and T. Schlick, RAG-3D: a search tool for RNA 3D substructures, Nucleic Acids Res, vol. 43, no. 19, pp ,

13 [11] N. Baba, S. Elmetwaly, N. Kim, and T. Schlick, Predicting large RNA-like topologies by a knowledgebased clustering approach, J Mol Biol, vol. 428, no. 5, pp ,