Usage Notes

• Introduction
• The File Menu
• Load Functions
• Export Functions
• The View Menu
• State Diagrams
• Rate Matrices
• External Alignment Viewers
• The XRate Menu
• Configuring a Server
• Configuring Repositories
• Marking Up Grammars for xREI
• Adding New Visualization Tools

For the best user experience, we recommend the Firefox browser.

For information on XRate, see its Biowiki page or the XRate paper in BMC Bioinformatics.

xREI's main screen is divided in to four basic parts:


The first three are devoted to grammar visualization. 1 contains basic grammar information such as the current grammar path (unique for each grammar), the grammar name (may be shared by multiple grammars), and a description if available. Descriptions are embedded in the xrate grammar file in a (meta(description atom)) expression. More information on the xrate format can be found here. 2 and 3 contain State Diagrams and Rate Matrices, modifiable by their respective entries in the view menu. 4 contains the text of a loaded stockholm alignment (or database of stockholm alignments) to be annotated or trained over.

The local load functions should be familiar, as they just allow end users to browse their local filesystem for grammars and alignments. Grammars should be in XRate format while alignments should be in Stockholm format.

The remote load screens are a bit different:

To the left are a series of repositories dynamically loaded from the server. These can be configured by the installation administrator. The right side displays descriptive information about each grammar/alignment. Note that when loading both local and remote grammars there is an option to turn off the (default) automatic loading of state diagrams. This can be useful, especially for larger grammars if latency becomes an issue and a state diagram is not required.

Export Functions

Export functions operate by opening a new window with a data:URI scheme defining the raw text alignment or grammar. To save the alignment or grammar, simply export, then use the browser's File>Save As... menu option to save it locally. The export functions in the view menu work similarly

Note: Firefox 2 supports data:URIs up to 2GB in length. However, long URIs can cause the address bar to wrap over itself. This appears to be an entirely cosmetic issue, and does not interfere with saving files.

The state diagram viewer uses GraphViz's dot or neato to layout graphs of the transform rules in a grammar file. When neato is used, transitions are weighted by the probability associated with that transition. Automatic generation generally produces aesthetically pleasing results for graphs with <10 states and 1 - 4 transistions per state. For larger graphs the raw GraphViz can be exported and modified by hand. State Diagram conventions: ovals represent null states black rectangles represent bifurcations diamonds represent emitting states red rectangles represent substitution chains in the absence of a defined 'start' state, one will be drawn, pointing at the from state in the first transform rule. An end state will be drawn and will be the recieving state of transformations to empty lists. A note about neato layouts: Semi-experimental. Currently these layouts are randomly seeded, so every graph requested will be different. They also generally require more hand modification to be useful, though can provide good results for larger grammars where dot may not.

The rate matrix functionality is provided by a modified version of visualizeRates.pl from the DART package.

Options: Chain: Provides a list of the available markov chains for rate display Coloring: Shows the available colorings depending on the grammar alphabet and chain type. Several colorings are available for each of nucleotide, dinucleotide, codon, and protein substitution models. Figure Scale: Determines the size of the figure, defaulting to 1.5. This setting works best for nucleotide and dinucleotide chains. Codon and protein chains may need to be reduced to 1. Rate Scale: Scales the size of the rate bubbles, defaults to AUTO. Valid values are AUTO and positive real numbers. AUTO will generally provide a workable display, which can then be tweaked from the preferences menu. Probability Scale: Serves the same function as the rate scale, for the initial probability distribution. Defaults to 1. There is no autoscaling for probabilities. Show Rates Only: Hides the initial probability distribution

Currently Raton is available as an external viewer for annotated RNA alignments.

Provides access to XRate's training and annotation functions. For more information see the XRate Biowiki page or the XRate paper in BMC Bioinformatics.

Important notes:

• xREI was developed using Firefox. While it appears to work in several other browsers, Firefox is the only one that has been tested extensively.
• xREI was developed on OS X and Debian Linux using Apache 2. It may or may not work on OSes/webservers.
• xREI was developed with dojo 1.0.2. Future versions of dojo should be backwards compatible, however xREI uses the FloatingPane object for much of its interface, which is currently part of the experimental dojox and maybe be moved/removed. If xREI fails to run on your server, this would be a good first thing to check.
• The ajax-xrate utilities require Perl 5, the DART package, TeXlive, and GraphViz. Paths to TeX and GraphViz should be added to Apache's envvar file. The path to the metapost base distribution should be set as an environment variable MPINPUTS in httpd.conf (or the relevant configuration file). The path to DART Perl should be set as an environment variable PERL5LIB.

The path to the repository configuration file is found within the init() function as reposConfigFile. By default this is './ajax-xrate.json'. This file is in standard JSON format. id contains the displayed name of the repository. type should be either 'grammarRepos' or 'stockRepos' for grammar files and stockholm files, respectively. directory is the path to the repository directory. Relative paths are fine. Note that all .eg or .stock and only .eg or .stock files in these directories will be automatically displayed in the remote browse interface.

xREI uses the xrate meta tag to include description information. Descriptions should be in the following format:

(meta (description (a dinucleotide model based on (<a onclick="javascript:grammarDescriber('http://mbe.oxfordjournals.org/cgi/content/abstract/msh039')" href="#">Seipel and Haussler, 2003</a>)) ) )

Note the use of javascript and the href="#" to open links in a new window rather than in xREI's window.

xREI was designed from the ground up for modularity. Adding a new visualization tool consists of three parts:

• Creating a CGI interface for the tool
• Adding dojo IO for the interface
• Adding interface hooks