S2S User's Guide

S2S User's Guide

Last update : 28th June 2005

Some details and screenshots used in this documentation can be not up to date with the last version of the software. Check the CHANGELOG file to have a look at the changes made for each version.

Introduction

S2S (for Sequence To Structure) is a Java framework providing several graphical tools to easily display and manipulate RNA data from the sequence to the structure. The tools provided are :

S2SViewer : the S2S core tool
Rnalign : a multiple alignment editor
Rna2DViewer : an RNA secondary structure editor
Rna3DViewer : an RNA tertiary structure viewer

S2S has been designed to construct multiple alignments against RNA molecules for which a tertiary structure is known. One starts by opening an RNA tertiary structure stored in a PDB file. S2S displays the tertiary structure with Rna3DViewer, automatically derives the corresponding RNA secondary structure with Rna2DViewer, and allows to construct multiple alignments against the RNA primary sequences with Rnalign. All these tools are interconnected. At any moment during the construction of the multiple alignment, S2S highlights the position where you are in the 2D and 3D structures. At any moment during the manipulation of the secondary structure, S2S highlights the position where you are in the multiple alignments and in the 3D structure. If you want to keep one view unchanged, each tool enables you to unlink it from the others.

If no 3D structures are available, S2S can be used to open an MFold secondary structure (stored in an RnaML file) and to make multiple alignments against the RNA sequence. Finally, Rnalign can be used to make multiple alignments against RNA sequences with unknown secondary and tertiary structures.

S2SViewer : the S2S core tool

S2S can read RnaML, FASTA and PDB files. S2S constructs a tree representation of the data stored in the file (named an S2SView). This tree can be displayed and manipulated within the S2SViewer core tool.

Within S2SViewer, launch the other tools by clicking the right mouse button : Rnalign, Rna2DViewer, and Rna3DViewer. Jython scripts can be launched too (see the Using scripts section of the "How to hack S2S?" documentation).

The S2SViewer core tool can be used to :

open, close and save files (File menu)
add, delete, copy and paste alignments (see the "The Rnalign tool" section in this documentation) (Edit menu)
precise the message to send to the 3D Viewer (select, zoom, hide or show the selection or do nothing)
shift+click on any tree element to select it within the other tools

The Edit menu proposes you to :

add new, copy/paste or delete alignments
display residues' absolute position starting from 1, or as defined in the original file
unlink S2SViewer from other tools so that it will not take care of events received. By default S2SViewer is unlinked.

The 3D menus (top and bottom ones) allow you to customize the interactions between the 3D Viewer and the other tools. You can :

Show all : show the complete molecule
Hide all : hide the complete molecule
Nothing : unlink the 3D Viewer from messages sent from the other tools
Select : select the corresponding 3D region in the 3D view
Zoom : zoom the 3D view on the corresponding 3D region
Show : show in the 3D view the corresponding 3D region and center the view on it
Hide : hide in the 3D view the corresponding 3D region

S2S saves data in an RnaML file (see S2S and the RnaML file format in the technical documentation for details). This file format is the only one able to save the various data formats used within S2S (list of single strands, list of basepairs, alignments,....).

If you originally opened a PDB file, S2S registers its name as a comment in the RnaML file. However, S2S doesn't save tertiary coordinates in the RnaML file. The next time you open an RnaML file containing this comment, S2S will refer to the corresponding PDB file. Therefore, you need to keep the original PDB file in the same location as the RnaML file. When S2S saves the RnaML file, it makes automatically a copy of the PDB file in the same location as the RnaML file.

The Rnalign tool

With this tool you can :

insert/remove gaps in one or several sequences
push/pull residues in one or several sequences
change sequence orders in the alignment
add/delete sequences
use structural masks to display basepair conservations for all sequences according to the bracket notations in the alignment
move quickly to a position in the alignment
display/hide sequence labels
save alignment in FASTA and SVG files
use several coloring modes
zoom in/out
calculate simple statistics on alignment
define a consensus secondary structure using a consensus bracket notation
display a second view for the current alignment

To use Rnalign within S2S, you need to have at least one alignment within the S2SViewer tree. To do so, you have two options :

open a PDB file and add a new alignment
open an existing alignment stored in a FASTA or in an RnaML file. In your existing alignment, the gaps defined within sequences need to be defined as '.' or '-' characters (Rnalign will use the '-' characters for its display). If you have a consensus bracket notation in your file, its name has to be defined as "SS_cons" :
```
>SS_cons
((((((......)))...)).)).((...)..((....).....
```

To add or delete alignments in your working session, you have to do it within S2SViewer. To add an alignment, select the "Chain" node against which you want to make the alignment and select "Add new alignment" in the S2SViewer Edit menu. To delete it, select its node within S2SViewer and select "delete" in the Edit menu. The changes you make within S2SViewer are automatically updated within Rnalign.
You can save your alignment in FASTA or SVG files. You need to precise the suffix for your file (.fasta or .svg). For the SVG format, Rnalign needs to know the first and last positions in the alignment, and how many residues per line you want to export. When you save your alignment as a FASTA file, you loose the connection to a corresponding 2D or 3D structure. To keep this connection, you need to save your multiple alignment as an RnaML file.

How does Rnalign display your alignment ?

When you open an alignment, in addition to the alignment itself, you will have :

a sequence meter which displays the alignment's absolute position
a "structure bracket notation (2D/3D) " which describes the secondary structure deduced from the 2D/3D structure stored stored in your original file (if any). If no 2D or 3D structure is available, each position will be defined as single-strand (with the '.' character)
a "consensus bracket notation (Consensus) " which defines a consensus secondary structure for all sequences in the alignment. If the original file did not contain any consensus bracket notation, S2S duplicates the structure bracket notation. A consensus bracket notation will be stored in a file labeled "SS_cons".

The bracket notations use the following characters to specify secondary structures :

'(' and ')' for canonical basepairs (AU and GC cWW, GU Wooble) within an intramolecular helix (both strands localized on the same RNA chain)
'<' and '>' for non-canonical basepairs within an intramolecular helix
'{' and '}' for basepairs within an intermolecular helix (both strands localized on different RNA chain).
'[' and ']' for pseudo-knots
'.' for single-strand residues
'-' for gaps

The structure bracket notation is linked to a sequence named the "reference sequence" in the alignment. Modifications to this sequence (insertion/deletion of gaps, moving residues,...) will also appear in the structure bracket notation. You cannot modify the structure bracket notation directly. The reference sequence is, for instance, the sequence for which a tertiary structure is stored in a PDB file, or the first sequence in a FASTA alignment. Gaps in the structure bracket notation highlights regions absent from the reference sequence, but observed for several other sequences in the alignment.

You can modify directly the consensus bracket notation (by clicking on the characters) to define a consensus secondary structure for all the sequences in your alignment. In contrast to the structure bracket notation, the consensus bracket notation is not linked to any sequences in the alignment. To link several sequences to the consensus structure when you insert/delete gaps or move residues, just select the sequences you want and insert/delete/move in the consensus structure, the same modifications will apply to the selected sequences.

In general, the consensus bracket notation should not contain a position defined as a gap. If you have a gap, check whether :

at least one sequence aligned under the gap contains a residue. In that case, the secondary structure of that residue should be specified
none of the sequences aligned under the gap contains any residue. This means that there is an empty column under that gap, which should possibly be removed

Each time the consensus bracket notation is changed, Rnalign recalculates all the helices defined and assigns a different color to each of them. You can define the colors chosen for the helices by clicking on the palette icon. The structure bracket notation uses the same colors already used in the 2D view.

WARNING : for now, the consensus bracket notation cannot deal efficiently with pseudo-knots. Introducing "crossed" pseudo-knots in your consensus structure may result in wrong color assignments with '[' and ']' characters.

How to manipulate your alignment ?

Rnalign provides four modes :

standard mode : select sequences, move view, ...
insert mode : insert gaps
delete mode : delete gaps
move mode : move residues

Within Rnalign, type :

'i' : toggle insert mode
'd' : toggle delete mode
'm' : toggle move mode
's' : return to standard mode

The current mode is highlighted at the bottom of Rnalign.

"Standard" mode :

select a column by clicking the sequence meter
change letter by clicking the consensus bracket notation (right or left button)
display the properties of the selected residue at the bottom of Rnalign by clicking elsewhere in the alignment :
```
Absolute position in alignment (alignment's total length)/ absolute position in reference sequence (position in reference sequence relative to the counting start) / absolute position in the sequence owning the residue just clicked (position relative to the counting start)
```
A mouse-click will highlight a residue in both the 2D and 3D views if they are available. Within Rna2DViewer, the display will be centered on the structure (if the "Structures" choice is validated in the Select list) or on the secondary interaction (for the "Interactions" choice) containing the residue selected. The display will be centered on the residue itself for the "Bases" choice. All the base-base interactions originating from this residue will be automatically displayed.
select/unselect a sequence by clicking a sequence label
change a sequence's properties (name, counting start, color, edit sequence) by double-clicking the sequence label
move view by dragging the cursor while keeping the mouse button pressed

"Insert gaps" mode :

insert a column filled with gaps by clicking the sequence meter
insert a gap by clicking the consensus bracket notation. A gap is inserted at the same position in each selected sequence
insert a gap left of a residue by clicking the residue. If several sequences are selected, a gap is inserted at this position in all selected sequences

"Delete gaps" mode :

delete a column containing gaps only by clicking the sequence meter
remove a gap in all selected sequences by clicking the consensus bracket notation
remove a gap in a single sequence by clicking it. If more than one sequence are selected, the gap disappears in all selected sequences.

"Move residues" mode :

drag a residue to its new position while keeping the mouse pressed. Depending on the dragging direction, contiguous residuesare pulled/pushed simultaneously. If more than one sequence are selected, do the same for all selected sequences in the alignment.

The pull/push function works for nucleotide sequences and for the consensus bracket notation.

When you click on the sequence meter, you select a complete column. Select a second column with the right mouse button. In the shell, Rnalign displays a table with statistics for each kind of basepair : number of basepairs observed versus number of basepairs expected inside brackets.

Coloring modes provided by Rnalign:

- Sequence : apply the same color to the complete sequence

- Bases : apply the same color to all residues of one kind (A,U,G,C)

- Structural masks : this mode checks for each sequence in the alignment whether the structure, as defined by the bracket notation, is conserved or not. Structural masks allow to highlight basepair conservation, base conservation or no conservation at all. Residues appear in the same color as in the corresponding position of the chosen bracket notation. Gaps are always displayed. Each residue is displayed with a character and a color according to either the consensus bracket notation or the structure bracket notation.

Structural masks against consensus bracket notation:

always display the first sequence in the alignment
basepair conservation: the original character of each unpaired residue is replaced with '.' if it is conserved in the first sequence in the alignment. The original character of each paired residue is replaced with '.' if the basepair interaction is canonical
base conservation: the original character of each residue is replaced with '.' if it is conserved in the first sequence of the alignment
without conservation: each residue keeps its original character.

Structural masks against structure bracket notation:

always display the reference sequence
basepair conservation: the original character of each unpaired residue is replaced with '.' if it is conserved in the reference sequence. The original character of each paired residue is replaced with '.' if the basepair interaction belongs to the same family of interactions as in the reference sequence. The families of interactions are classified according to the nomenclature published in "The non-Watson-Crick base pairs and their associated isostericity matrices". The residues paired with a gap are displayed with a lower-case character. Since the single H-Bond interaction observed in 3D structures doesn't have an associated isostericity matrix, they are highlighted with an 'h' character for each residue implied in such a kind of interaction.
base conservation: the original character of each residue is replaced with '.' if it is conserved in the reference sequence
without conservation: each residue keeps its original character.

Visualizing interaction partners

Structural masks are useful to display in which kind of interactions a residue is involved. However, Rnalign also provides a second view that allows to quickly visualize and manipulate the partners participating in this interaction. With a "structural mask" coloring mode selected and the second view opened, by clicking on any base, the other view highlights the basepaired residues as defined in the bracket notation for the structural mask.

The Rnalign toolbar (from left to right)

zoom in
zoom out
move selected sequences up
move selected sequences down
define a position and ...
move to this position relative to the multiple alignment
or move to this position relative to the reference sequence in the alignment
save the current alignment in a FASTA or an SVG file

If you delete sequences in an alignment or if you change the order with the arrows buttons, S2SViewer automatically keeps track of these changes.

Export secondary structures as .ct files

Rnalign is able to export the secondary structure for each sequence in a multiple alignment as a .ct file. The ".ct file" contains the nucleic acid sequence and base pairing information. Using the naview package, you can produce a postscript file for each .ct file and display the secondary structure drawing with PS viewers like GhostView. Rnalign exports in the .ct files only canonical basepairs as defined in the consensus bracket notation. The .ct files are stored in the "output" subdirectory within S2S.

Linking a tertiary structure to an alignment ? (still experimental)

Imagine that you have done (or found) a nice Rna alignment and you discover that a tertiary structure is available for one of the molecules in this alignment. To link this 3D structure, you need to follow these steps :

open your alignment stored in a FASTA file with S2S
select the alignment node in the S2SViewer tool and copy it
open your PDB file with S2S
select the RNA molecule you want in the S2SViewer and paste the alignment

The Rna2DViewer tool

Formely known as RnaMLView, this tool has been modified to be integrated easily within S2S and now provides more functionalities to the user. With Rna2DViewer, you can display and manipulate an RNA secondary structure. When a PDB file is opened, S2S calculates a secondary structure for each RNA molecule found, using a 3D=>2D algorithm defined in the S2S preferences. The secondary structure defines all the helices, single-strands and basepairs found in the tertiary structure. By default, S2S uses the RNAVIEW algorithm developed by the NDB laboratory. The RNAVIEW ouput in form of an RnaML file is parsed by S2S to construct and display a dynamic 2D view.

According to the output of the algorithm, Rna2DViewer displays :

modified nucleic acids are given as lower case letter
basepairs with a single hydrogen bond or with more than one hydrogen bond but with bad geometry as dotted lines
standard Watson-Crick basepairs as two close parallel lines for GC pairs and as single lines for AU or AT basepairs
GU wobble pairs as open circles
all other 12 types of non-Watson-Crick basepairs according to the Leontis-Westhof classification :
unknown interactions as crosses

Below are the correspondances between the symbols displayed in Rna2DViewer and their names in the S2SViewer core tool:

: c++ (AU cWW)
: c-- (GC cWW)
: cWW (GU wobble)
: cWW (all others)
: tWW
: cWS
: tWS
: cHH
: tHH
: cHS
: tHS
: cSS
: tSS
: cWH
: tWH
: !!!

Rna2DViewer provides an upper and a lower toolbar:

The upper toolbar (from left to right)

move the view
select elements
rotate selected elements
center view on the center of the secondary structure
mirror selection
change drawing style for the selection
change color for selected elements
number selected elements
zoom in
zoom 1:1
zoom out
lock/unlock interactions in the display
show/hide Leontis-Westhof symbols
export the display as an SVG file or a Jython script

Working with the 2D view

Moving elements

In the 2D view, only helices can move, the single-strands automatically follow their position. To select a helix, choose the "Structures" option in the Select list and click on the helix you want. You can select several helices using the Shift button and unselect them with the Ctrl button. By dragging the cursor while keeping the mouse button pressed, you can translate, rotate or flip any previously selected helix, depending on the mode chosen in the upper toolbar (see toolbar items above). Moving elements will change their coordinates. To "navigate" along the RNA secondary structure, you can move the view and/or zoom. This will not change the secondary structure's coordinates. Starting from the beta2 version, Rna2DViewer displays the origin of the view attached to each RNA secondary structure. When one saves the RNA secondary structure coordinates (in an RnaML or SVG file), these coordinates are recalculated relative to this origin and to the final zoom level of the current view.

Modifying the display

The brush icon allows to choose between a simplified line representation, or an explicit display of all bases. Any element can be colored differently by clicking on the palette icon. The Rna2DViewer sends a "color change" message to the other S2S tools. The PyMOL driver provided with S2S reads out this message to match the color in the corresponding 3D selection.

The residue number is displayed when clicking the yellow circle button in the upper toolbar. The numbering frequency can be defined in the Number list.

"Playing" with interactions

Rna2DViewer provides a number of buttons to easily visualize base-base interactions. The lower toolbar allows to display/hide temporarily all interactions corresponding to a specific family from the Leontis-Westhof classification. To display/hide temporarily all the interactions, click on the eye button in the lower toolbar. To permanently display/hide an interesting interaction, select it (choose "interactions" mode in the Select list) and press the lock/unlock buttons in the upper toolbar.

Exporting the display

Rna2DViewer allows to save any view on display either as an SVG file or as a jython script. Click the "disk" button in the upper toolbar and specify the type of file from the dropdown menu. Note that you MUST specify the corresponding suffix in the filename (.svg for SVG files or .py for jython scripts). SVG files can be read by standard applications like Adobe illustrator, but will lose the color information (this information will be exported in a future release). The jython script saves the user-defined colors, which tertiary interactions are highlighted, and which interactions display the Leontis-Westhof symbols. To restore the display saved in a script, just launch it as explained in the "Using scripts" section in the "How to hack S2S?" documentation. Starting from the beta2 version, we provide jython scripts that can render automatically your RNA secondary structure. Check here the jython script you need.

The topological view

To better manipulate large RNA structures we have added a topological viewer to Rna2DViewer.

This viewer displays rnas, helices and interactions as simple squares. The topological view is linked to the 2D view. If you double-click on a helix square, you can change its name (starting from beta2 version, this can be done for single-strand too and from the 2D view).

The Rna3DViewer tool

In contrast to Rnalign or Rna2DViewer, many tertiary viewers already exist. And in general, users prefer to display tertiary structures with their favorite tool. So, instead of creating a new tool from scratch, we therefore decided to allow integration of existing viewers. To connect your favorite tertiary viewer, you have to write a driver for this tool (see the "How to hack S2S ?" documentation for details).
By default, S2S provides a driver for the PyMOL application. Each selection made within Rnalign and/or Rna2DViewer creates the homologous selection, named "s2s", in the PyMOL application. S2S can zoom, show, hide the 3D view on this selection depending on the 3D mode chosen in the S2SViewer's 3D list. Once a selection has been made with S2S, you can continue to work with PyMOL and its built-in commands (save the selection as an object, modify color, change representation styles,...). I recommend to have a look at the PyMOL documentation for details.

At present, it's not possible to select objects within PyMOL and to see the homologous selection inside the other tools. The 3D Viewer can only receive events, not send them