For Java developpers: VARNAPanel API specifications

VARNA relies heavily on a custom Swing component, the RNA2DPanel. Developpers might be interested in using the VARNAPanel component as a fast and simple solution for the vizualisation aspects of their own secondary structure software GUI. The VARNAPanel component is free-software as defined by the GNU GPL.

The API for the VARNAPanel component is documented through an Javadoc-generated bunch of HTML files.

[Browse VARNAPanel API documentation]

Please let me know if you are using it, or request/suggest some fixes/additional features.

VARNA applet specifications

Description

You will find in the downloads section, a light applet that allows you to draw a single or multiple secondary structure. The secondary structure, as well as a bunch of additional display options, can be sent to the applet through the usual <param name=... value=...> tags.

References

The applet gets its options from the following name/value couples for the param tag.
Note: Parameters names are case-sensitive.

algorithm String
naview		 Redraws the current RNA secondary using one of the implemented algorithms.
Supported algorithms are line,circular,radiate and naview.
annotations String
"L1:anchor=19"		 Defines a set of annotations of the form
text1:opt1=val1,...;type=T2,opt2=val2;...
where texti is the annotation caption, and the options alter the way each annotation is rendered.
The first and most important one is the type=[P,B,H,L] one, which specifies whether the annotation is:
  • Static (P)
  • Anchored on a base (B)
  • Anchored on an helix (H)
  • Anchored on a loop (L)
For static annotations, a position needs be specified through options y and y. For every other type, a supporting base needs be specified through option anchor. The type default to L.
Additionally, cosmetic factors such as the font size (size=int) and color (color=#HHHHHH) can be specified to customize the rendering of annotations.
applyBasesStyleXon String
"1,2,5"		 Applies a custom base style to a list of bases.
E.g.: <parameter name="applyBasesStyle5on"
value="1,6,7,10"/>
will apply the 5th base style, defined with basesStyle5 to bases numbered 1, 6, 7 and 10.
autoHelices boolean
True		 Annotates each and every helix in the RNA with a unique "Hn" label.
autoInteriorLoops boolean
True		 Annotates each and every interior loop of the RNA with a unique "In" label.
autoTerminalLoops boolean
True		 Annotates each and every terminal loop of the RNA with a unique "Tn" label.
auxBPs String
"(1,10);(2,11)"		 Creates a set of additional base-pairs, possibly defining and using custom styles for the additional base-pairs.
E.g.: (1,10);(2,11):thickness=4
will create a base-pair (1,10) using current style and a base-pairs (2,11) with a thickness of 4 points. Admissible options for a base-pair custom style are:
  • edge5, edge3: Edge (5' or 3') used for interaction in non-canonical base-pairs, as defined by the Leontis/Westhof classification of base-pairs. Admissible values are wc (Watson/Crick edge), h (Hoogsteen edge) and s (Sugar edge).
  • stericity: Orientation of the strands. Admissible values are cis and trans
  • color: Base-pair color
  • Thickness: Base-pair thickness
backbone Color
#FF0000		 Lets the user pick a custom color for rendering the phosphate-sugar backbone (aka skeleton) of the RNA.
background Color
#99AA0F		 Defines the background color used within this panel.
baseInner Color
#334455		 Default value for inner base color
baseName Color
#334455		 Sets the color used to draw the nucleotide name
baseNum Color
#334455		 Sets the color used to draw base numbers
baseOutline Color
#334455		 Default value for outer base color
basesStyleX String
fill=#FF0000		 Defines a custom base-style, to be applied later to a set of bases (See applyBasesStyle). Styles are numbered starting from 1 using a specific syntax.
E.g.: <parameter name="basesStyle3"
value="fill=#FF0000,outline=#00FF00"/>
will create a base-style numbered 3, having red inner color and green outline.
For each base style, four parameters can be assigned:
  • fill colors the inner part of base
  • outline the outline of the base
  • label will color the base text
  • number color the base number
border Dimension
"20x30"		 Sets the width and height of the panel border, i.e. the gap between the panel boundaries and those of the surface used to draw the RNA.
bp Color
#334455		 Sets the default value for base-pair colors.
bpIncrement Double
1.3		 In linear drawing mode, defines the vertical increment used to separate two successive, nested base-pairs.
bpStyle String
lw		 Lets the user picks his/her favorite style for base-pairs rendering, chosen among:
  • none, base-pairs are not drawn, but can be implicitly seen from "ladders", ie helix structures
  • line (Line), a simple line is used to draw any base-pair, regardless of its type
  • rnaviz, a small square is drawn at equal distance of the two partners
  • lw (Leontis/Westhof), both canonical and non-canonical base-pairs are rendered according to the Leontis/Westhof nomenclature.
chemProb String
"11-12:glyph=dot;"		 Attaches a sequence of chemical probing annotations of the form:
a1-b1:opt1=v1,...;a2-b2:opt1=v1,...
where a1 and b1 are adjacent bases, and each option is chosen among:
  • glyph=[arrow|dot|pin|triangle]: Sets the shape of the annotation
  • dir=[in|out]: The direction of the annotation
  • intensity=real: The annotation intensity (i.e. thickness)
  • color=color: The color used to draw the annotation
colorMap List
"0.1;2;3.5"		 Assigns a list of real values, used for color map rendering, to the bases of an RNA. The values are assigned sequentially in the 5' to 3' order. If list is shorter than the list of bases, the remaining bases will remain unaffected. Default value for each base is 0.0.
colorMapCaption String
"Boltz. prob."		 Sets the caption of current color map. Setting the caption to the empty strings hides the color map caption (ie no space is used for the caption).
colorMapMax Real
"10.0"		 Sets the upper bound of the color map to a given value. That way, the color map can span between natural values (e.g. [0,10]) no matter what the actual values are.
colorMapMin Real
"0.0"		 Sets the lower bound of the color map to a given value. That way, the color map can span between natural values (e.g. [0,10]) no matter what the actual values are.
colorMapStyle String
heat		 Sets the color map palette to be used within a color map drawing. One can either choose a predefined palette of define a custom palette. Predefined palettes are: "red", "blue", "green", "heat", "energy", and "bw". A custom palette is defined as a semi-colon-separated sequence of (value/rgb color) couples (e.g. "0:#000000;1:#FFFFFF" for a black to white color map). The colors are obtained from a set of values through linear interpolations on each RGB component. For instance, a custom map "0:#000000;1:#808080" going from black (#000000) to gray (#808080) will assign a dark gray color (#404040) to a base of value "0.5". Also, the color map range is automatically scaled as to match the range of base values, so it should not be necessary to manually account for the range.
columns Integer
2		 Sets the number of columns in a multipanel layout
(See Multiple Panels section below).
comparisonMode Boolean
True		 Toggles on/off "comparison mode", where two previously aligned secondary structures can be jointly drawn within a single "super-secondary structure". Both sequences and structures MUST be specified within this mode, using the firstSequence, secondSequence, firstStructure and secondStructure applet parameters. Additionally, the merged secondary structures must currently be without any crossing interactions (e.g. pseudoknots), and merging them should give a secondary structure.
drawBackbone Boolean
false		 Toggles on/off backbone drawing.
drawBases Boolean
True		 Displays/hide the outline of a nucleotide base.
drawNC Boolean
False		 Switches on/off the display of non-canonical base-pairs.
drawTertiary Boolean
True		 Toggles on/off display of "non-planar" base-pairs, i.e. pseudoknots. Since there is no canonical definition of pseudoknotted portions, a maximal planar subset is extracted from the input structure, defined to be the planar portion, and used as a scaffold for the drawing algorithms. The remaining base-pairs can either be displayed or not with this option.
error Boolean
True		 Toggles on/off error messages, e.g. when unexpected values are encountered.
fillBases Boolean
True		 Displays/hide the outline of a nucleotide base.
firstSequence String
"GG.AG..C"		 Sets the gapped nucleotide sequence (gap character is ".") for the first RNA sequence/structure in comparison mode. Note that both sequences and structures MUST be specified, using the firstSequence, secondSequence, firstStructure and secondStructure applet parameters, and that the comparison mode must be activated using the comparisonMode parameter.
firstStructure String
"((...))"		 Sets the secondary structure for the first displayed RNA in Dot-Bracket Notation (DBN). The dot character "." is used both for unpaired nucleotides and for gaps. Pseudoknots are not currently supported in comparison mode (but they are supported for single structures). Note that both sequences and structures MUST be specified, using the firstSequence, secondSequence, firstStructure and secondStructure applet parameters, and that the comparison mode must be activated using the comparisonMode parameter. Also, the two structures must be compatible, i.e. their joint structure should represent a valid (e.g. pseudoknot-free) secondary structure .
flat boolean
true		 In radiate drawing mode, redraws the whole structure, aligning to a baseline the base featured on the exterior loops (aka "dangling ends") .
gapsColor Color
#8FFF00		 Defines and uses a special color to draw "Gaps" bases in comparison mode. "Gaps" bases correspond to insertion/deletions in one of the structures.
highlightRegion String
"10-16:fill=#FF0000"		 Highlights a region by drawing a polygon of predefined radius, fill color and outline color around it. The highlight can be further edited in the annotation submenu.
Each region consist in an interval followed by options. Some features can be customized for each region using the following, comma-separated, assignations:
  • radius=real: Thickness of the highlight
  • fill=color: The color used to fill the highlight
  • outline=color: The color used to draw the line around the highlight
modifiable Boolean
False		 If true, prohibits any modification performed by the user, except for basic cosmetic operations. Default to true.
nsBasesColor Color
#00FFFF		 Defines and uses a special color to render non-standard bases (Anything but A,C,G or U)
periodNum Integer
10		 Sets the interval between two successive base numbers. More specifically, if k is the period, then the first and last bases of the RNA are numbered, along with each base whose number is a multiple of k. The base number is used for this operation as opposed to the base index, which might differ if bases are missing in the RNA.
resolution Real
"2.0"		 Chooses the resolution of a bitmap export, i.e. the multiplier in the number of pixels in each dimension of the exported picture.
rotation Double
1.0		 Rotates the whole RNA of a certain angular increment. (Doesn't rotate the captions)
rows Integer
2		 Sets the number of rows in a multipanel layout
(See Multiple Panels section below).
secondSequence String
"G..G..C"		 Sets the gapped nucleotide sequence (gap character is ".") for the second RNA sequence/structure in comparison mode. Note that both sequences and structures MUST be specified, using the firstSequence, secondSequence, firstStructure and secondStructure applet parameters, and that the comparison mode must be activated using the comparisonMode parameter.
secondStructure String
"((...))"		 Sets the secondary structure for the second displayed RNA in Dot-Bracket Notation (DBN). The dot character "." is used both for unpaired nucleotides and for gaps. Pseudoknots are not currently supported in comparison mode (but they are supported for single structures). Note that both sequences and structures MUST be specified, using the firstSequence, secondSequence, firstStructure and secondStructure applet parameters, and that the comparison mode must be activated using the comparisonMode parameter. Also, the two structures must be compatible, i.e. their joint structure should represent a valid (e.g. pseudoknot-free) secondary structure .
sequenceDBN String
"GGAGUCC"		 Sets the raw nucleotide sequence for the displayed RNA Each base must be encoded in a single character. Letters others than [A,C,G,U] are tolerated
spaceBetweenBases Real
1.0		 Lets the user define the multiplier used for inter-base distance. Since the applet adapts it zoom factor to the dimension of the RNA bounding box, this option might be mistaken for a increase of the base radius.
spaceBetweenBases Real
"1.0"		 Set the distance between consecutive bases
structureDBN String
"((...))"		 Sets the secondary structure of the displayed RNA in Dot-Bracket Notation (DBN). Valid structures in DBN format are well-parenthesized words consisting of dots '.', opening '(' and closing ')' parentheses. Dotted positions will be unpaired, whereas matching parenthesized positions will represent base-pairing nucleotides. Pseudoknots can be specified by using the two alternative parentheses system '{}' and '[]'.
title String
"My RNA"		 Lets the user type a new title, displayed on the bottom of the panel.
titleColor Color
#808080		 Selects the color used for rendering the panel title.
titleSize Integer
10		 Lets the user select the font family, style and size used for displaying the title.
url String
"http://varna.lri.fr/ex1.ct"		 Loads and displays a file that describes a secondary structure of RNA in this panel. Supported files are in Vienna dot-bracket notation, MFold/Unafold Connect format, Gutell's BPSeq format, and RNAML as produced by RNAView.
warning Boolean
True		 Toggles on/off warning messages.
zoom Double
1.2		 Defines the level of zoom and zoom increment used to display the RNA within this panel. For zoom levels greater than one, the arrows or the mouse (middle button or both button simultaneously) can be used to scroll visible portion.

Multiple panels

Motivation

Certain websites, like webservers hosting applications that generate candidate secondary structures, might want to display several secondary structures in a single applet. This would allow users with limited ressources (memory especially, of which Java doesn't seem to get enough) to benefit from a graphical representation of their results.

Description/Examples

The VARNA applet addresses this issue through the rows and columns Applet parameters. When these values are assigned such that at least one differs from 1, the space occupied by the VARNA applet is plit as a grid. The set of rows*columns RNA, numbered from 1 to rows*columns is then displayed in the following way:

RNA1 RNA2 ... RNAcolumns
RNAcolumns+1 RNAcolumns+2 ... RNA2*columns
............
RNA(rows-1)*columns+1 RNA(rows-1)*columns+2 ... RNArows*columns

Each of the RNA drawing panels can be configured independently through the param tag, using some of the parameters names suffixed by the number n of the RNA.
For instance, the following parameters produces a grid having 3 columns and 2 rows.

<param name="rows" value="2">
<param name="columns" value="3">
 =>
     
     

We can color each panel the way we want to: 

<param name="rows" value="2">
<param name="columns" value="3">
<param name="background1" value="#000000">
<param name="background2" value="#303030">
<param name="background3" value="#606060">
<param name="background4" value="#909090">
<param name="background5" value="#C0C0C0">
<param name="background6" value="#F0F0F0">
=>
     
     

The same goes for every other parameters. Assigning different structures to each panel will be performed in the same way, through defining different values to parameters structureDBN1, structureDBN2, ...

Persistence

Although they can be assigned independantly for each panel, parameters are said to be persistent. This means that a value, assigned to a parameter in panel i, will be used for the subsequent panels i+1, i+2 ... unless explicitly re-assigned. That way, it is possible to define a common property, such that the background color through a single assignment of this property for panel 1: 

<param name="rows" value="2">
<param name="columns" value="3">
<param name="background1" value="#606060">
=>
     
     

It also makes it possible to split the set of displayed RNAs in two families, identified by different backgrounds. 

<param name="rows" value="2">
<param name="columns" value="3">
<param name="background1" value="#FF0000">
<param name="background4" value="#00FF00">
=>
     
     

^ Top

Previous page: Command-line Usage
Next page: Full Features List