BACKGROUND
numerous structured rnas have been identified in the last decade that are involved in a variety of biological processes  <cit> .
researchers are often aided by a graphical depiction of the consensus sequence and structural features of a given rna class.
unfortunately, few tools have been designed to create such consensus diagrams  <cit> , and available tools represent only sequence conservation or base-pairing probabilities in their output.
several programs have been created to draw individual rna molecules, and thus inherently address many of the issues associated with drawing a consensus diagram.
some programs implement algorithms that automatically determine a feasible layout of the rna molecule  <cit> , and several allow a user to adjust layouts interactively  <cit> .
the layouts generated by these approaches are of practical value, and the automated approaches require minimal human effort.
however, the resulting drawings are often not as readable or as aesthetic as those generated manually.
to prepare high-quality diagrams for publications, researchers often use general-purpose drawing programs such as adobe illustrator.
however, this approach is very time consuming.
the goal of r2r is to facilitate the creation of rna consensus diagrams by bioinformaticians that are comparable in quality to those produced using adobe illustrator, but take less time to create.
because consensus diagrams are generally derived from multiple-sequence alignments, r2r takes as input a multiple-sequence alignment in stockholm format  <cit>  with added annotation to direct the drawing.
r2r can also create depictions of single rna sequences.
because of the effort still required to draw highly aesthetic diagrams, r2r is not usually appropriate for drawing raw candidate rnas predicted by bioinformatics, but rather is intended primarily for use in preparing publications of rnas.
using r2r, we have created over  <dig> rna drawings in previous publications  <cit> .
r2r source code is freely available and is distributed with over  <dig> example input and output files in both pdf and svg format .
a user manual is also available .
RESULTS
an example consensus diagram
the crcb motif  <cit>  was used to provide an example of a consensus diagram drawn using r2r .
the consensus is a representation of conserved sequence and secondary-structure features, the degree of conservation of nucleotides and a summary of covarying positions that retain base-pair complementarity.
the output of r2r  was customized by using additional commands , and assembled using adobe illustrator into a finished diagram.
generic symbols and graphics used in finished diagrams are provided .
a complete example of r2r input and output is also given for a contrived rna class with two representatives .
multistem junctions
nucleotides within multistem junctions and internal loops are typically positioned along a circle .
like most rna-drawing programs, r2r supports manual layout of such loops, as well as a circular layout in which stems are oriented in whatever directions fit the circle.
r2r also supports the drawing of loops that approximately follow a circle, subject to constraints on the directions of their stems .
these constraints are specified by the user, and can be used to avoid overlapping nucleotides elsewhere in the diagram, to orient all stems in horizontal or vertical directions, or otherwise to promote symmetry in stem directions.
stems within the multistem junction can also be constrained to align horizontally, vertically or in an arbitrary axis.
the resulting problem is expressed as a non-linear program , and solved by cfsqp  <cit> .
this feature accelerates the determination of an approximately circular layout, compared to manual trial and error.
pseudoknot drawing styles
r2r supports two styles to show pseudoknots.
in an "in-line" style, pseudoknot pairings are drawn directly .
the pairing relationships are often most clear in the in-line style, but this layout is not possible for many rna secondary structures without making other compromises.
by contrast, the "callout" style  involves connecting distant base-paired regions with a line marked "pseudoknot".
the pseudoknot pairings can be shown explicitly in a small callout drawing.
the callout allows annotation of covariation data, and helps the reader to see precisely which nucleotides form base pairs.
modular structures
many rna motifs exhibit modular sub-structures that are present in only some motif representatives.
for example, in many rna motifs, certain hairpins are absent in some representatives, and some terminal loops frequently adopt one or more well-defined sequences .
to show a modular structure, the r2r user uses regular expressions or boolean logic to define which motif representatives exhibit the modular structure .
the occurrence frequency of the modular structure is automatically calculated by r2r .
drawing of individual rna molecules
although the primary goal during the design of r2r was to produce software to assist in drawing consensus diagrams, r2r can also be used to draw the sequences and structures of individual representatives of a noncoding rna class.
for example, figure  <dig> shows alternate structures possible in crcb rnas from acidothermus cellulolyticus and roseburia intestinalis that suggest a model for gene regulation.
we also previously used r2r to display structural probing data obtained by in-line probing experiments on a sam-iv riboswitch  <cit> .
design principles for rna secondary structural diagrams
r2r facilitates the application of the following design principles for rna secondary structure diagrams.
although little research has investigated practical benefits of different rna drawing styles  <cit> , the principles integrated into r2r are similar to broadly followed guidelines for rna depictions  <cit>  and some are related to ideas accepted in the field of graph layout  <cit> .
the principles are as follows.
first, nucleotides or other symbols should not overlap.
second, nucleotides within bulges and loops should ideally be drawn along circles.
such a layout leads to symmetry  <cit>  in the looped nucleotides, which share a common property.
the circular layout also avoids arbitrarily drawing attention to individual nucleotides that might otherwise be located on a corner.
third, stems should ideally run horizontally or vertically, to emphasize the common structural role of stems.
fourth, the distance between consecutive nucleotide positions along the rna backbone should be constant throughout the diagram.
this principle avoids inelegant bunching of nucleotides, or extra space between nucleotides that draws unwarranted attention or requires additional clarification for the user to follow the rna backbone.
finally, the diagram should be compact, which is both aesthetic and space-saving.
some of these principles often conflict, and the inference of an optimal solution may require some manual intervention.
consensus diagrams merit annotation to highlight the extent of nucleotide conservation and to feature evidence supporting the proposed structure.
this information, which is included in figure  <dig>  is automatically calculated by r2r .
other annotations useful in consensus diagrams are the depiction of variable-length, poorly conserved regions as well as modular structures.
r2r supports such annotations , based on the user's explicit judgment regarding the rna motif data.
automatically calculated consensus annotation
some annotations specific to consensus diagrams are automatically computed by r2r, using approaches described previously  <cit> .
r2r graphically depicts the extent of conservation at nucleotide positions within an rna.
to reduce bias caused by highly similar sequences, sequences are weighted by the gsc algorithm  <cit>  as implemented by the infernal software package  <cit> .
if the weighted frequency of a nucleotide exceeds 75%, r2r draws the nucleotide with a specific color  to indicate whether its frequency exceeds 75%, 90% or 97%, although these parameters can be adjusted.
otherwise, if the nucleotide is a purine or pyrimidine with a frequency above 75%, r2r indicates whether this frequency exceeds the same thresholds.
the conservation of purine or pyrimidine identity is often associated with structural constraints.
if a position does not meet the preceding criteria, r2r reports whether a nucleotide is present in the position with weighted frequency more than 50%, 75%, 90% or 97%, or otherwise does not show the nucleotide position.
r2r does not indicate other patterns of conservation.
for example, the nucleotide immediately 5' to the hammerhead ribozyme cleavage site must be a, c or u  <cit> , but this will not be indicated automatically by r2r.
however, we concluded that routinely annotating such conservation patterns would unduly complicate diagrams, and users could add such distinctions that are desired.
we also considered using entropy  <cit>  as a measure of conservation.
although entropy measures conservation in a more general manner, we found it difficult to develop an intuition for how specific levels of entropy relate to likely biochemical constraints.
r2r marks each predicted base pair to indicate covariation .
if two rnas can form a watson-crick or g-u base pair at equivalent locations, and the base pair identities differ at both positions , r2r classifies the base pair as covarying.
if they vary at only one position , the base pair is considered to carry a compatible mutation.
base pairs whose nucleotides are invariant have no mutational evidence for or against such base-pair predictions, and are marked accordingly.
each of these classifications is indicated unobtrusively by shading the base pairs with specific colors.
positions that contain non-canonical base pairs with a frequency exceeding 10% are not shaded.
this automated r2r annotation does not reflect the extent or confidence of covariation.
while such information can be useful, we believe that thorough evaluation of covariation evidence ultimately requires analysis of the full sequence alignment.
for example, misleading covariation can result from an incorrect alignment of sequences, or from alignments of sequences that do not function as structured rnas.
unfortunately, there is no accepted method to assign confidence that entirely eliminates the need to analyze the full alignment.
user effort required with r2r
since r2r's overriding goal is to facilitate highly aesthetic diagrams, it requires the user to give it explicit instructions to customize the rna layout , and to edit r2r's raw output in a general-purpose drawing program .
in our experience, this manual effort is usually modest.
the ~800-nucleotide golld rna  <cit>  structure took us roughly  <dig> hours to draw using r2r, mainly owing to the challenge of finding a layout that fits within a page.
however, most rnas are hairpin structures that do not require any kind of customization, and were easily drawn in minutes.
rnas with complex structural features  or annotations  were still usually completed within 30- <dig> minutes.
limitations
despite the capabilities offered by r2r, we see some areas for improvement.
first, a graphical user interface would allow additional researchers to more easily use r2r, and could help to make some tasks even faster for all users.
second, numerous features are possible to enrich diagrams with additional layout, particularly for rnas with unusual biochemical features.
third, further automation of layout selection would speed the use of r2r.
fourth, r2r is also not designed to implement schematic diagrams that display extensive tertiary interactions or to project diagrams that are positioned to better reflect positions of nucleotides or substructures in atomic-resolution models .
implementation
default layout of loops
by default, all nucleotides in a loop are positioned along a common circle.
r2r keeps the distance between consecutive nucleotides strictly constant.
previous solutions to this problem assumed that distance between base-paired nucleotides is equal to the distance between consecutive nucleotides  <cit> , but these distances are not assumed to be equal in r2r.
given a radius r, the angle between nucleotides along the circle is calculated based on the isosceles triangle with sides r, r and d, where d is the fixed distance between consecutive nucleotides or between base-paired nucleotides.
suppose r* is the radius of a suitable circle for a given loop.
if nucleotides are drawn with radius r <r*, the sum of angles will exceed  <dig> degrees, while r >r* will result in fewer than  <dig> degrees.
r2r uses binary search to solve for r*.
a similar approach was also developed for varna  <cit> .
for bulges or a side of an internal loop, the angles should sum to  <dig> degrees.
layout of multistem junctions expressed as a non-linear program
in many rna structures, it is desirable to arrange the nucleotides within a multistem junction on a circle, while constraining the stems on the junction to be oriented in specific directions .
these directions are typically dictated by a desire to avoid overlaps in other parts of the diagram, or to promote consistency or symmetry in overall stem directions.
the stem-direction constraints make it impossible in general to follow a perfect circle, but a close approximation is usually feasible.
in r2r, the stem directions are specified by the user, which avoids creating a much harder global optimization problem for the computer.
this layout problem is formulated in r2r in terms of a non-linear program , consisting of a non-linear objective function that is minimized subject to non-linear constraints.
the nlp is solved by cfsqp  <cit> .
gradients of objective or constraint functions, which are used by cfsqp, are calculated using automatic differentiation.
in automatic differentiation, mathematical functions are built using an abstract numeric data type that represents a symbolic expression, and the resulting symbolic expression is differentiated recursively.
r2r provides three different mathematical formulations to express the notion that the junction should approximate a circle.
all methods use highly non-linear functions, and the optimizer can get stuck in local minima.
therefore, it is sometimes useful to try multiple formulations, although the second formulation usually produces an acceptable layout .
in the first formulation, unpaired nucleotides in the junction are forced to lie on a common circle , and the radius of this circle is a variable in the problem.
the angle of the vector from the circle's center to the nucleotide 5' to the enclosing base pair  is also a variable.
base-paired nucleotides along the junction are not constrained to be on the circle, but the straight line connecting the two nucleotides in each base pair must intersect the circle .
these intersections are determined by variables ranging from  <dig>  to  <dig> .
the algorithm runs clockwise around the junction constraining nucleotides to lie on the circle, and positioning base pairs based on their intersections.
when a move from nucleotide point p <dig> to p <dig> is performed, we calculate the angle p1cp <dig>  where c is the circle center.
to force a full circle, the sum of these angles is constrained to be  <dig> degrees.
if the multistem junction contains any variable-length regions , the lengths of these regions are variables in the nlp, allowing some additional flexibility .
in formulating the objective function, we assume that it is sudden changes in radius that is most visually distracting.
for each base-paired nucleotide n, we calculate the distance dn between n and c , and the distance da between c and the nucleotide adjacent to n .
the objective function is the sum of squares of the differences dn-da, for all n.
the second and third formulations of multistem junction nlps are similar to one another.
in both, the radius of the circle is again a variable, but no points are explicitly constrained to lie on it .
variables are the x and y coordinates of the 5' nucleotides of each stem on the junction.
however, when two base-paired nucleotides are consecutive , only one variable is used: the angle of the vector from one base-paired nucleotide to the adjacent one.
for each junction of unpaired nucleotides between two stems, these nucleotides are drawn along a circle, but each junction's circle has its own independent center and radius .
the center and radius values of such circles are expressed as a constraint in terms of the positions of the base-paired nucleotides flanking the given junction and the constant distance between consecutive nucleotides .
the objective function for the second formulation measures the deviations of the junctions to the overall multistem junction circle.
to approximate the integral, evenly spaced points along each junction are used.
the number of points used is n+2+3v where n is the number of unpaired nucleotides, the number  <dig> reflects the two flanking paired nucleotides and v is the number of variable-length regions.
the objective function is the sum of the squared differences dpc-r, where dpc is the distance between a junction point p and the main circle's center c, and r is the radius of the main circle .
the third formulation's objective function uses the idea that it is deviations in slope that are most jarring.
thus, it measures the deviations at regularly spaced points between the vector from the point to the main circle's center and the vector from the same point to the junction's circle center.
the objective function is the sum of squared differences between the cosine of the angle between the two vectors and  <dig> .
nucleotides can be forced to align horizontally by constraining their x coordinates to be equal.
using scalar projections, r2r allows alignment at arbitrary angles , and also allows aligning the centroids of multiple nucleotides .
these features apply to all nlp formulations.
CONCLUSIONS
r2r has sufficient functionality to draw a wide variety of rna structures and greatly reduce the time necessary to create aesthetic and readable diagrams, which will become increasingly important as more noncoding rnas are discovered.
availability and requirements
• project name: r2r
• project home page: http://breaker.research.yale.edu/r2r
• operating system: platform independent.
note: r2r is only tested using the gnu c++ compiler.
• programming language: c/c++ and perl.
• other requirements: cfsqp is needed for some methods of automated layout of multistem junctions.
other aspects of r2r will function with or without cfsqp.
cfsqp is free for research and development purposes.
• license: gnu general public license.
• any restrictions to use by non-academics: none.
authors' contributions
zw created the software and drew consensus diagrams based on design principles initially articulated by rrb.
zw and rrb wrote the manuscript, and both authors read and approved its final version.
supplementary material
additional file 1
source code and example input and output files.
c++ and perl source code is provided.
installation and usage instructions are given in the user manual , which is also a part of this archive.
example input files for r2r are included in the "demo" subdirectory of this archive, and r2r's raw output on these examples in pdf and svg format is supplied in the "demo/output-pdf" and "demo/output-svg" subdirectories.
files can be retrieved from the tgz archive file using programs such as winzip , stuffit expander  or the tar/gzip commands .
click here for file
additional file 2
r2r user manual.
user manual explaining r2r installation and usage .
click here for file
additional file 3
generic annotations for use in drawings, pdf format.
this file contains a generic legend for r2r drawings and some annotations we frequently use, in pdf format.
it can be imported into adobe illustrator or coreldraw.
click here for file
additional file 4
generic annotations for use in drawings, svg format.
the same content as additional file  <dig>  but in svg format.
suitable for import into inkscape.
click here for file
acknowledgements
we thank attendees of the  <dig> computational methods for rna analysis meeting in benasque, spain, and carla weinberg, david weinberg and paul gardner for helpful comments.
we also thank jonathan perreault, phil mccown, tyler ames and other breaker lab members, for helpful discussions or for testing the r2r software.
rna science in the breaker lab is supported in part by howard hughes medical institute.

 numerous structured rnas have been identified in the last decade that are involved in a variety of biological processes. researchers are often aided by a graphical depiction of the consensus sequence and structural features of a given rna class. unfortunately, few tools have been designed to create such consensus diagrams, and available tools represent only sequence conservation or base-pairing probabilities in their output. several programs have been created to draw individual rna molecules, and thus inherently address many of the issues associated with drawing a consensus diagram. some programs implement algorithms that automatically determine a feasible layout of the rna molecule, and several allow a user to adjust layouts interactively. the layouts generated by these approaches are of practical value, and the automated approaches require minimal human effort. however, the resulting drawings are often not as readable or as aesthetic as those generated manually. to prepare high-quality diagrams for publications, researchers often use general-purpose drawing programs such as adobe illustrator. however, this approach is very time consuming. the goal of r2r is to facilitate the creation of rna consensus diagrams by bioinformaticians that are comparable in quality to those produced using adobe illustrator, but take less time to create. because consensus diagrams are generally derived from multiple-sequence alignments, r2r takes as input a multiple-sequence alignment in stockholm format with added annotation to direct the drawing. r2r can also create depictions of single rna sequences. because of the effort still required to draw highly aesthetic diagrams, r2r is not usually appropriate for drawing raw candidate rnas predicted by bioinformatics, but rather is intended primarily for use in preparing publications of rnas. using r2r, we have created over rna drawings in previous publications. r2r source code is freely available and is distributed with over example input and output files in both pdf and svg format. a user manual is also available.  an example consensus diagram the crcb motif was used to provide an example of a consensus diagram drawn using r2r. the consensus is a representation of conserved sequence and secondary-structure features, the degree of conservation of nucleotides and a summary of covarying positions that retain base-pair complementarity. the output of r2r was customized by using additional commands, and assembled using adobe illustrator into a finished diagram. generic symbols and graphics used in finished diagrams are provided. a complete example of r2r input and output is also given for a contrived rna class with two representatives. multistem junctions nucleotides within multistem junctions and internal loops are typically positioned along a circle. like most rna-drawing programs, r2r supports manual layout of such loops, as well as a circular layout in which stems are oriented in whatever directions fit the circle. r2r also supports the drawing of loops that approximately follow a circle, subject to constraints on the directions of their stems. these constraints are specified by the user, and can be used to avoid overlapping nucleotides elsewhere in the diagram, to orient all stems in horizontal or vertical directions, or otherwise to promote symmetry in stem directions. stems within the multistem junction can also be constrained to align horizontally, vertically or in an arbitrary axis. the resulting problem is expressed as a non-linear program, and solved by cfsqp. this feature accelerates the determination of an approximately circular layout, compared to manual trial and error. pseudoknot drawing styles r2r supports two styles to show pseudoknots. in an "in-line" style, pseudoknot pairings are drawn directly. the pairing relationships are often most clear in the in-line style, but this layout is not possible for many rna secondary structures without making other compromises. by contrast, the "callout" style involves connecting distant base-paired regions with a line marked "pseudoknot". the pseudoknot pairings can be shown explicitly in a small callout drawing. the callout allows annotation of covariation data, and helps the reader to see precisely which nucleotides form base pairs. modular structures many rna motifs exhibit modular sub-structures that are present in only some motif representatives. for example, in many rna motifs, certain hairpins are absent in some representatives, and some terminal loops frequently adopt one or more well-defined sequences. to show a modular structure, the r2r user uses regular expressions or boolean logic to define which motif representatives exhibit the modular structure. the occurrence frequency of the modular structure is automatically calculated by r2r. drawing of individual rna molecules although the primary goal during the design of r2r was to produce software to assist in drawing consensus diagrams, r2r can also be used to draw the sequences and structures of individual representatives of a noncoding rna class. for example, figure shows alternate structures possible in crcb rnas from acidothermus cellulolyticus and roseburia intestinalis that suggest a model for gene regulation. we also previously used r2r to display structural probing data obtained by in-line probing experiments on a sam-iv riboswitch. design principles for rna secondary structural diagrams r2r facilitates the application of the following design principles for rna secondary structure diagrams. although little research has investigated practical benefits of different rna drawing styles, the principles integrated into r2r are similar to broadly followed guidelines for rna depictions and some are related to ideas accepted in the field of graph layout. the principles are as follows. first, nucleotides or other symbols should not overlap. second, nucleotides within bulges and loops should ideally be drawn along circles. such a layout leads to symmetry in the looped nucleotides, which share a common property. the circular layout also avoids arbitrarily drawing attention to individual nucleotides that might otherwise be located on a corner. third, stems should ideally run horizontally or vertically, to emphasize the common structural role of stems. fourth, the distance between consecutive nucleotide positions along the rna backbone should be constant throughout the diagram. this principle avoids inelegant bunching of nucleotides, or extra space between nucleotides that draws unwarranted attention or requires additional clarification for the user to follow the rna backbone. finally, the diagram should be compact, which is both aesthetic and space-saving. some of these principles often conflict, and the inference of an optimal solution may require some manual intervention. consensus diagrams merit annotation to highlight the extent of nucleotide conservation and to feature evidence supporting the proposed structure. this information, which is included in figure is automatically calculated by r2r. other annotations useful in consensus diagrams are the depiction of variable-length, poorly conserved regions as well as modular structures. r2r supports such annotations, based on the user's explicit judgment regarding the rna motif data. automatically calculated consensus annotation some annotations specific to consensus diagrams are automatically computed by r2r, using approaches described previously. r2r graphically depicts the extent of conservation at nucleotide positions within an rna. to reduce bias caused by highly similar sequences, sequences are weighted by the gsc algorithm as implemented by the infernal software package. if the weighted frequency of a nucleotide exceeds 75%, r2r draws the nucleotide with a specific color to indicate whether its frequency exceeds 75%, 90% or 97%, although these parameters can be adjusted. otherwise, if the nucleotide is a purine or pyrimidine with a frequency above 75%, r2r indicates whether this frequency exceeds the same thresholds. the conservation of purine or pyrimidine identity is often associated with structural constraints. if a position does not meet the preceding criteria, r2r reports whether a nucleotide is present in the position with weighted frequency more than 50%, 75%, 90% or 97%, or otherwise does not show the nucleotide position. r2r does not indicate other patterns of conservation. for example, the nucleotide immediately 5' to the hammerhead ribozyme cleavage site must be a, c or u, but this will not be indicated automatically by r2r. however, we concluded that routinely annotating such conservation patterns would unduly complicate diagrams, and users could add such distinctions that are desired. we also considered using entropy as a measure of conservation. although entropy measures conservation in a more general manner, we found it difficult to develop an intuition for how specific levels of entropy relate to likely biochemical constraints. r2r marks each predicted base pair to indicate covariation. if two rnas can form a watson-crick or g-u base pair at equivalent locations, and the base pair identities differ at both positions, r2r classifies the base pair as covarying. if they vary at only one position, the base pair is considered to carry a compatible mutation. base pairs whose nucleotides are invariant have no mutational evidence for or against such base-pair predictions, and are marked accordingly. each of these classifications is indicated unobtrusively by shading the base pairs with specific colors. positions that contain non-canonical base pairs with a frequency exceeding 10% are not shaded. this automated r2r annotation does not reflect the extent or confidence of covariation. while such information can be useful, we believe that thorough evaluation of covariation evidence ultimately requires analysis of the full sequence alignment. for example, misleading covariation can result from an incorrect alignment of sequences, or from alignments of sequences that do not function as structured rnas. unfortunately, there is no accepted method to assign confidence that entirely eliminates the need to analyze the full alignment. user effort required with r2r since r2r's overriding goal is to facilitate highly aesthetic diagrams, it requires the user to give it explicit instructions to customize the rna layout, and to edit r2r's raw output in a general-purpose drawing program. in our experience, this manual effort is usually modest. the ~800-nucleotide golld rna structure took us roughly hours to draw using r2r, mainly owing to the challenge of finding a layout that fits within a page. however, most rnas are hairpin structures that do not require any kind of customization, and were easily drawn in minutes. rnas with complex structural features or annotations were still usually completed within 30- minutes. limitations despite the capabilities offered by r2r, we see some areas for improvement. first, a graphical user interface would allow additional researchers to more easily use r2r, and could help to make some tasks even faster for all users. second, numerous features are possible to enrich diagrams with additional layout, particularly for rnas with unusual biochemical features. third, further automation of layout selection would speed the use of r2r. fourth, r2r is also not designed to implement schematic diagrams that display extensive tertiary interactions or to project diagrams that are positioned to better reflect positions of nucleotides or substructures in atomic-resolution models. implementation default layout of loops by default, all nucleotides in a loop are positioned along a common circle. r2r keeps the distance between consecutive nucleotides strictly constant. previous solutions to this problem assumed that distance between base-paired nucleotides is equal to the distance between consecutive nucleotides, but these distances are not assumed to be equal in r2r. given a radius r, the angle between nucleotides along the circle is calculated based on the isosceles triangle with sides r, r and d, where d is the fixed distance between consecutive nucleotides or between base-paired nucleotides. suppose r* is the radius of a suitable circle for a given loop. if nucleotides are drawn with radius r <r*, the sum of angles will exceed degrees, while r >r* will result in fewer than degrees. r2r uses binary search to solve for r*. a similar approach was also developed for varna. for bulges or a side of an internal loop, the angles should sum to degrees. layout of multistem junctions expressed as a non-linear program in many rna structures, it is desirable to arrange the nucleotides within a multistem junction on a circle, while constraining the stems on the junction to be oriented in specific directions. these directions are typically dictated by a desire to avoid overlaps in other parts of the diagram, or to promote consistency or symmetry in overall stem directions. the stem-direction constraints make it impossible in general to follow a perfect circle, but a close approximation is usually feasible. in r2r, the stem directions are specified by the user, which avoids creating a much harder global optimization problem for the computer. this layout problem is formulated in r2r in terms of a non-linear program, consisting of a non-linear objective function that is minimized subject to non-linear constraints. the nlp is solved by cfsqp. gradients of objective or constraint functions, which are used by cfsqp, are calculated using automatic differentiation. in automatic differentiation, mathematical functions are built using an abstract numeric data type that represents a symbolic expression, and the resulting symbolic expression is differentiated recursively. r2r provides three different mathematical formulations to express the notion that the junction should approximate a circle. all methods use highly non-linear functions, and the optimizer can get stuck in local minima. therefore, it is sometimes useful to try multiple formulations, although the second formulation usually produces an acceptable layout. in the first formulation, unpaired nucleotides in the junction are forced to lie on a common circle, and the radius of this circle is a variable in the problem. the angle of the vector from the circle's center to the nucleotide 5' to the enclosing base pair is also a variable. base-paired nucleotides along the junction are not constrained to be on the circle, but the straight line connecting the two nucleotides in each base pair must intersect the circle. these intersections are determined by variables ranging from to. the algorithm runs clockwise around the junction constraining nucleotides to lie on the circle, and positioning base pairs based on their intersections. when a move from nucleotide point p to p is performed, we calculate the angle p1cp where c is the circle center. to force a full circle, the sum of these angles is constrained to be degrees. if the multistem junction contains any variable-length regions, the lengths of these regions are variables in the nlp, allowing some additional flexibility. in formulating the objective function, we assume that it is sudden changes in radius that is most visually distracting. for each base-paired nucleotide n, we calculate the distance dn between n and c, and the distance da between c and the nucleotide adjacent to n. the objective function is the sum of squares of the differences dn-da, for all n. the second and third formulations of multistem junction nlps are similar to one another. in both, the radius of the circle is again a variable, but no points are explicitly constrained to lie on it. variables are the x and y coordinates of the 5' nucleotides of each stem on the junction. however, when two base-paired nucleotides are consecutive, only one variable is used: the angle of the vector from one base-paired nucleotide to the adjacent one. for each junction of unpaired nucleotides between two stems, these nucleotides are drawn along a circle, but each junction's circle has its own independent center and radius. the center and radius values of such circles are expressed as a constraint in terms of the positions of the base-paired nucleotides flanking the given junction and the constant distance between consecutive nucleotides. the objective function for the second formulation measures the deviations of the junctions to the overall multistem junction circle. to approximate the integral, evenly spaced points along each junction are used. the number of points used is n+2+3v where n is the number of unpaired nucleotides, the number reflects the two flanking paired nucleotides and v is the number of variable-length regions. the objective function is the sum of the squared differences dpc-r, where dpc is the distance between a junction point p and the main circle's center c, and r is the radius of the main circle. the third formulation's objective function uses the idea that it is deviations in slope that are most jarring. thus, it measures the deviations at regularly spaced points between the vector from the point to the main circle's center and the vector from the same point to the junction's circle center. the objective function is the sum of squared differences between the cosine of the angle between the two vectors and. nucleotides can be forced to align horizontally by constraining their x coordinates to be equal. using scalar projections, r2r allows alignment at arbitrary angles, and also allows aligning the centroids of multiple nucleotides. these features apply to all nlp formulations.  r2r has sufficient functionality to draw a wide variety of rna structures and greatly reduce the time necessary to create aesthetic and readable diagrams, which will become increasingly important as more noncoding rnas are discovered. availability and requirements • project name: r2r • project home page: http://breaker.research.yale.edu/r2r • operating system: platform independent. note: r2r is only tested using the gnu c++ compiler. • programming language: c/c++ and perl. • other requirements: cfsqp is needed for some methods of automated layout of multistem junctions. other aspects of r2r will function with or without cfsqp. cfsqp is free for research and development purposes. • license: gnu general public license. • any restrictions to use by non-academics: none. authors' contributions zw created the software and drew consensus diagrams based on design principles initially articulated by rrb. zw and rrb wrote the manuscript, and both authors read and approved its final version. supplementary material additional file 1 source code and example input and output files. c++ and perl source code is provided. installation and usage instructions are given in the user manual, which is also a part of this archive. example input files for r2r are included in the "demo" subdirectory of this archive, and r2r's raw output on these examples in pdf and svg format is supplied in the "demo/output-pdf" and "demo/output-svg" subdirectories. files can be retrieved from the tgz archive file using programs such as winzip, stuffit expander or the tar/gzip commands. click here for file additional file 2 r2r user manual. user manual explaining r2r installation and usage. click here for file additional file 3 generic annotations for use in drawings, pdf format. this file contains a generic legend for r2r drawings and some annotations we frequently use, in pdf format. it can be imported into adobe illustrator or coreldraw. click here for file additional file 4 generic annotations for use in drawings, svg format. the same content as additional file but in svg format. suitable for import into inkscape. click here for file acknowledgements we thank attendees of the computational methods for rna analysis meeting in benasque, spain, and carla weinberg, david weinberg and paul gardner for helpful comments. we also thank jonathan perreault, phil mccown, tyler ames and other breaker lab members, for helpful discussions or for testing the r2r software. rna science in the breaker lab is supported in part by howard hughes medical institute.
with continuing identification of novel structured noncoding rnas, there is an increasing need to create schematic diagrams showing the consensus features of these molecules. r2r can be used to create consensus sequence and secondary structure models for novel rna structures or to revise models when new representatives for known rna classes become available. r2r makes it possible to obtain high-quality drawings of the consensus sequence and structural models of many diverse rna structures with a more practical amount of effort. we created r2r, a computer program that facilitates the generation of aesthetic and readable drawings of rna consensus diagrams in a fraction of the time required with general-purpose drawing programs. r2r software is available at http://breaker.research.yale.edu/r2r and as an additional file. since the inference of a consensus rna structure typically requires a multiple-sequence alignment, the r2r user annotates the alignment with commands directing the layout and annotation of the rna. additionally, most existing rna-specific applications are designed for drawing single rna molecules, not consensus diagrams. rna structural diagrams are typically made either with general-purpose drawing programs like adobe illustrator, or with automated or interactive programs specific to rna. although r2r does not currently have a graphical user interface, it has proven useful in our efforts to create schematic models of distinct noncoding rna classes. r2r creates svg or pdf output that can be imported into adobe illustrator, inkscape or coreldraw.
 with continuing identification of novel structured noncoding rnas, there is an increasing need to create schematic diagrams showing the consensus features of these molecules. rna structural diagrams are typically made either with general-purpose drawing programs like adobe illustrator, or with automated or interactive programs specific to rna. unfortunately, the use of applications like illustrator is extremely time consuming, while existing rna-specific programs produce figures that are useful, but usually not of the same aesthetic quality as those produced at great cost in illustrator. additionally, most existing rna-specific applications are designed for drawing single rna molecules, not consensus diagrams.  we created r2r, a computer program that facilitates the generation of aesthetic and readable drawings of rna consensus diagrams in a fraction of the time required with general-purpose drawing programs. since the inference of a consensus rna structure typically requires a multiple-sequence alignment, the r2r user annotates the alignment with commands directing the layout and annotation of the rna. r2r creates svg or pdf output that can be imported into adobe illustrator, inkscape or coreldraw. r2r can be used to create consensus sequence and secondary structure models for novel rna structures or to revise models when new representatives for known rna classes become available. although r2r does not currently have a graphical user interface, it has proven useful in our efforts to create schematic models of distinct noncoding rna classes.  r2r makes it possible to obtain high-quality drawings of the consensus sequence and structural models of many diverse rna structures with a more practical amount of effort. r2r software is available at http://breaker.research.yale.edu/r2r and as an additional file. 