Using Royère

QuickStart Guide

To run Royere:

Running Royere is simplest with the use of the scripts provided in the scripts directory:

• Windows cygwin bash shell - If you have cygwin bash (best for developers), execute the run script from the scripts directory by typing "run". Make sure that "." is on your path. To get started with the bash shell on windows, do the following:
• Download cygwin for windows here. Add the package openssh during installation if you plan to use cvs from the commandline.
• The cygwin bin directory has to be on your PATH (See My Computer->Properties->Advanced button: Environment Variables)
• Put "." on your PATH: export PATH=".:$PATH" should make it possible to invoke run and other scripts by typing their name.
• Unix bash shell - First copy scripts from the unix directory, i.e. in the scripts directory, execute "cp unix/* .". Then, type "run".
• Windows DOS Shell - Edit the variables ROYERE_ROOT and JAVA_HOME in "setpaths.bat" to reflect their location in your file system. Type "run.bat".

Otherwise:

• Add the files in the JarFiles directory to your CLASSPATH environment variable. No compilation is necessary.
• Issue the following command from the top-level installation directory: "java royere.cwi.appl.Royere". Make sure that the Royere.pr file is in the same directory.
• OR Royere can be started with: "java royere.cwi.appl.Royere Graphs/Trees/Tree.xml"

Tips:

• The version information for Royere is available in the Help menu, in "About Royere".
• The "run" script for bash will take a filename as an argument. By default, it will look for the file in the Graphs directory. For example, "run Trees/Tree.xml" will read the file Tree.xml contained in Graphs/Trees.
• In cases where env is not located in /usr/bin, you might have to type "bash run". You can also edit the first line (starting with "#!") of the bash scripts to tell your system where to find bash.

More Information

For more information on how to use Royere, see the help menu or press F1. Sample graph files can be found in the Graphs directory.

More information on the design of Royere can be found in separate files in the Docs directory. The Javadoc documentation is also there. (<- these links only available in the distribution.)

If you plan to develop with Royere, please send a message to Scott Marshall. Please also see An object-oriented design for graph visualization (published in Software - Practice & Experience)

Please send feedback and questions to (remove the SPAM bomb first): mscottm@users.REMOVE.SPAM.sourceforge.net.

Installation Overview

Royere is built on the Java 2 platform, and has been tested with JDK1.3. For speed reasons we advise you to use JDK1.3.

The current directory structure is as follows:

• JarFiles is a directory that contains all the Jar files that are used to execute Royere.
• source contains the source code for Royere and helper packages.
  • source/royere contains the Royere source code
  • source/cwi contains the source code of two other packages developed at CWI (GraphXML and SVGGraphics) that are used by Royere.
  • Note, especially, the subdirectory source/cwi/GraphXML/XML, which contains the DTD files for the XML based graph formats.
• Graphs contains some example graph files
• scripts contains several scripts for building and maintenance
• Docs contains documentation for Royere and CWI helper packages. The on-line Help files for Royere are also contained here.
• bin is used to store class files produced by the scripts
• License.txt - the license
• Bugs.txt - incomplete list of bugs
• Royere.pr - Royere preferences file
• Readme.html - this file

In some situations, you will want to adapt the file Royere.pr to your local configuration, primarily the entries for the online help and the DTD file. The current setting uses relative paths but if you want to run from another directory you will need to change them to absolute paths. The Royere.pr file must be in the directory where java is invoked to run the application.

Royere can be started by "java royere.cwi.appl.Royere" with an optional file name for a graph file. The input can be in GML or in GraphXML formats (the Newick format for consensus trees is also supported). The GraphXML format is preferred and Royere demonstrates many of its features.

The GraphXMLDocs directory contains:

• An overview of GraphXML in PDF formats, and a longer description in HTML and in PDF formats
• The complete documentation of the API in Javadoc format
• Example Java file which shows how the parser should be embedded into a full application
• The GraphXML.dtd file and a simple graph example.

Note to Developers: External Packages

There are a few scripts that can be used to automate package builds: makeclean, makeall, makedocs, and makejar. They are all runnable from bash (you can get bash for windows at the Cygwin Project. There is also a build.bat for DOS-style builds.

We have removed support for magician and two extra parsers from Sun and IBM because of the complexity that they added. Java2D is fast enough at drawing as long as you have the latest JDK and the Xerces parser is sufficient.

We are currently using a test framework for Java called JUnit that you might want to download. For examples look in the source/test directory.

Royere includes an on-line help facility, which is implemented using Sun's JavaHelp sytem (see the javasoft pages for further details). Also, the generation of jpg, png, or bmp format images is made possible through Sun's JIMI package (see again the javasoft pages for further details). These facilities are not strictly necessary to run Royère, and the application will recognize if the packages are not available; however, they are handy. We have added the necessary (minimal) jar files to the JarFiles directory, although you should probably license those with Sun if you want to develop any serious products based on those.

Extending Royere

It is possible to add new layout, metric, clustering, and metric colouring classes to Royere by only compiling one file and editing Royere.pr.

To avoid confusion, we would prefer new packages and classes to be added in separate packages in the class hierarchy instead of being added to the current ones. At present, there is a royere and a cwi folder on the top. Forget about the top-level (cwi), this is for packages developed at CWI but which are not exclusively for Royère. Under royere there is a directory cwi which contains the various packages of Royere. If you want to add new packages, please make a new directory at the same level as cwi, labri, bath, and use the same structure as what can be found under cwi (structure, layout, view, etc., whichever you use). By doing so, we can keep our code compartmentalized.

The extension mechanism in Royère is based, internally, on a factory mechanism and, externally, on user property control. The factory mechanism means that there exists a LayoutFactory, MetricFactory, MetricVisualsFactory, and a ClusteringFactory object to generate new Metric, Layout, Clustering, MetricVisuals, and PanelEntry object instances. These factory objects, when properly initialized, build up an internal table containing the appropriate references (essentially the Class information) of all available classes.

Initilization of the factories is done by the application, making use of user properties. The properties would list the full classnames of the layout, metric, etc, objects which should replace and/or supplement the classes which are part of Royere by default. Because the Class objects are found and created dynamically at run-time, the average user does not have to recompile Royere to include a new layout object, for example, just to modify the property value.

Here are some more details:

How to extend Royere...

A new Parser:

Implement the class as a subclass of royere.cwi.input.Input. Do not forget to:

• See Common Steps
• Add the getName() and getSuffix() methods to give a meaningful name to the pull-down menu in the file input panel. The suffix will also be used to filter the view for files.
• Implement the parse() method, which should return a full Graph.

A new Metric:

Implement the class as a subclass of royere.cwi.structure.Metric. Do not forget to:

• See Common Steps
• Define the calculateValue() method, which will be called by Graph.calculateValue() to calculate the value at the Node (or Edge, thus Element) associated with the metric object. This is where the underlying algorithm for computing the metric is implemented. See the examples StrahlerMetric, EdgeCountMetric, etc.

A new metric colouring class:

Implement the class as a subclass of royere.cwi.view.metrics.MetricVisuals. Do not forget to:

• See Common Steps
• Reimplement the getName() method to give a meaningful name to the colouring in the menu;
• If you use one colour only, redefine the property NUMBER_OF_COLOURS_KEY to new Integer(1). This can be done by overriding the method by:

         
      protected void setProperties()
      {
          properties.setProperty(Keys.NUMBER_OF_COLOURS,new Integer(1));
      }
              

A new Layout:

Implement the class as a subclass of royere.cwi.layout.Layout. Do not forget to:

• See Common Steps
• Define the setNodeSize() method used when instantiating new objects. This value shoud be relevant to the layout algorithm and might be used by the View module to build the corresponding view.
• Define the setEnclosingBox() method used when instantiating new objects. This box is used by the view module to scale the layout to window coordinates.

Common Steps to extend Royere with a new Metric, Layout, Clustering:

1) Implement a subclass of the new type:

• Define a final static String Name.
• Add the getName() method to give a meaningful name to the colouring in the menu. This method should return Name.
• If your object depends on other objects, add them to dependentEntries.

  For example, if a particular metric instance is used, the system might require access to another metric class, too. To force the factory initialization to include those metrics as available metrics, you can override the dependentEntries method:

      public String  dependentEntries() {
        return "royere.cwi.structure.NeighborValueMetric:royere.cwi.structure.EdgeCountMetric";
      }
              

  instructs the factory to load the two additional metric classes when loading the current one. Note, however, that those classes will not appear in the application menu, unless they are listed in the properties (see below) on their own right.
• Implement the setRequirements() method, using other metrics, layouts, or clusterings as an example (StrahlerMetric, EdgeCountMetric, etc. See the javadoc documentation). These are usually graph-theoretic properties that are required by this algorithm.

2) Add the full classname to the property file as a possible value to the AdditionalOBJECTs key

(Replace OBJECT with one of: Layout, Metric, Clustering, or MetricVisual.)

If this is the only additional class, then the property file will include the line:

    AdditionalOBJECTs=your.package.path.classname
            

if you have several additional objects, then

    AdditionalOBJECTs=your.package.path.classname1:your.other.package.path.classname2
            

note that you can use a shorthand by defining the possible class names separately:

    OBJECTPackages=your.package.path:your.other.package
    AdditionalOBJECTs=classname1:classname2
            

See the Royere.pr file for examples.