Java TreeView User's Manual

Once you have downloaded and unpacked the distribution, you should be confronted with a set of files similar to those listed in Figure 1.1, “Contents of Java TreeView Distribution Archive”. Before reading further, you should run the TreeView.jar program to make sure your installation works. At this point, you might want to view a sample cdt or pcl file to get the hang of how it works. You can grab one from the examples section of the website or skip ahead to the file formats section (Chapter 2, Feature Reference, the section called “File Formats”) if you aren't sure whether your file is properly formatted.

Java TreeView offers many views of the data which are linked together.

In all these views there are visual cues to show which genes are selected. Any operation which selects genes in one view, either due to genome ordering, hierarchical clustering, or per-gene statistics, selects the genes in all views. This is because the application only maintains one list of selected genes. This list of selected genes can also be used to create exported images and data files such as gene lists and sub-pcl files using the Export features, documented in chapter 2.

The amount of memory can be specified using the standard arguments to the jvm, i.e. for 500 MB, use java -jar -Xmx500m TreeView.jar

Be aware that for windows, you may need to use javaw instead of java.

The main program options have a short and long form. An example command line to open a specified file using the "linked view" style would be java -Xmx500m -jar TreeView.jar -r http://jtreeview.sourceforge.net/examples/DLim_color.cdt

When export to dendrogram is indicated using "-x Dendrogram", main program arguments can be terminated with "--" and additional dendrogram plugin arguments can be specified. An example complete command line would be:

java -jar TreeView.jar -r ./spellman.cdt -x Dendrogram -- -o /tmp/spellman.png -s 10x1 -a 0 -c 1

Note: Setting the contrast or logcenter values will modify the .jtv file and have a persistent effect when the file is reopened in java treeview

All document settings are stored in a document-specfic .jtv file. These settings always take precendence over the presets. If you want to reset a document so that it uses all presets, just delete the .jtv file. At some point, a menu option to do this might get added.

Currently, there are two program-wide settings: the presets and the most recently used list of files. Program-wide settings are stored in a global configuration file whose location is platform dependant. To be exact, the following code is run to determine what file to use:

    private String globalConfigName()
    {
        String dir = System.getProperty("user.home");;
        String fsep = System.getProperty("file.separator");;
        String os = System.getProperty("os.name");;
        String file;
        if (os.indexOf("Mac") >= 0)
            file = "JavaTreeView Config";
        else if (fsep.equals("/"))
            file = ".javaTreeViewXmlrc";
        else if (fsep.equals("\\"))
            file = "jtview.xml";
        else
        {
            System.out.println("Could not determine sys type! using name jtview.cfg");
            file = "jtview.xml";
        }
        return dir + fsep + file;
    }

On unix, this resolves to a .javaTreeViewXmlrc file in your home directory. On OSX, it resolves to a JavaTreeView Config in your home directory. On PC, it resolves to a jtview.xml file, although I'm not sure where windows considers your home directory to be.

Figure 2.1. Url Presets Dialog

Url Presets are the only presets which apply to many views, since url linking is a view-independant process. Java TreeView stores the url presets for arrays and genes separately, thus there are two sets of url presets, gene url presets and array url presets, which are treated essentially the same.

Java TreeView supports linking to external databases. In a Dendrogram or Karyoscope, clicking on a gene will cause a corresponding database page to be loaded in an external browser. Dendrogram also supports linking by array. Exactly what database page gets loaded depends on the Url Settings. The exact mechanism for load depends on the operating system, and can be a source of url bugs (see Chapter 3).

URL Presets allow you to store presets for databases you may wish genes and arrays to link to. There are several default presets which come with Java TreeView. You can delete or modify all of them, as well as add additional presets.

There is a special preset which disables linking. You can set this as the default url preset to avoid spurious linking.

Figure 2.2. Dendrogram Color Presets Dialog

This set of presets allow you to configure preset color schemes for the dendrogram component. It is also referred to as just color presets in TreeView, since there's no other views which could have color settings.

Figure 2.3. Karyoscope Coordinates Presets Dialog

Stores a list of frequently used coordinates files. In addition to using a particular preset,it is also possible to parse the pcl or cdt file itself for the coordinates. Selecting "None" makes this the default behavior.

Figure 2.4. Url Settings Dialog

Url Settings allow you to select from one of the presets, or to directly edit the url string. There is a special substring of the url string, "HEADER", which is replaced by a partcular gene or url header which you select from the pulldown. The default is to either use the first column for a pcl, or the second column for a cdt. In the original Eisen layout, this is the YORF column.

There is also a checkbox which allows you to disable url linking entirely. Whether this box is checked initially is determined by the default url presets.

What exactly the url settings are used for depends on the view. Generally, clicking on a gene will cause the url for that gene to be loaded in an external browser.

Figure 2.5. Dendrogram Font Settings Dialog

Choose the font used to render gene or array names and annotation.

Figure 2.6. Dendrogram Pixel Settings Dialog

This fairly complicated dialog has three major parts. The first part allows you to set the pixel scaling for the global and zoom views. The second part allows you to set the contrast. The third part allows you to set the color settings for the dendroview.

The pixel scaling determines how tall and wide the boxes are in both the zoom and global views. Basically, the larger the pixel scaling, the bigger the box. If the pixel scaling is less than one, the rows are averaged. This can make your data look better, since missing values disappear.

The contrast is the expression value which corresponds to fully induced. Any values greater than this will appear to be the induced color, and values between this and zero will appear to be a color between the zero and up color. The contrast is similarly used to color repressed boxes.

The color part allows you to set the up, down, zero and missing colors. You can double-click the boxes to get a color selection dialog, click a preset to load a color, and load and store color sets to files.

In LinkedView, a dendrogram must be active in order for this option to appear on the settings menu. Any settings made only apply to the active dendrogram.

Figure 2.7. Karyoscope Settings Dialog

Coordinates may be parsed from the current file, if it is formatted properly, or parsed from an external file. The proper formatting is discussed in the File Formats section. The settings files provided with Java Treeview are nothing more than minimal PCL files, which contain no data but have annotation columns for chromosome, arm and position. The coordinates in an external files are matched up with the loci in the current file using either the first column, or if the first column has the header GID the second column. This gives the expected result when operating on PCL or CDT files, provided that the id column is unique.

Loci which do not have coordinates are not displayed. However, loci which have coordinates but not expression data associated with them do affect the extent of the chromosome displayed.

Figure 2.8. Karyoscope Averaging Settings Dialog

Allows one to average genes with their genomic neighbors using one of several algortihms.

Selected genes and data can be exported to tab delimited text using "Export->Export to Text File...". The export dialog allows you to select which annotation columns you would like to include, whether you want to include the expression data, and whether you want to include a header line. The default is to print out a simple gene list with no header.

Figure 2.9. Dendrogram Export Dialog

The dendrogram can be exported to either image files or editable Postscript for publication purposes. Postscript can be edited as objects in programs such as Adobe Illustrator, but can get prohibitively large with many genes and arrays. Image files are simply pixels, but can take up less space. To export to Postscript, select "Export->Export to Postscript" off the menubar. To export to images, select "Export->Export to Image". The following sections apply to both types of export. Although the above image is a screenshot of Postscript export, the only difference with image export is that there is no Bounding Box option. The purpose of the bounding box is discussed in the section called “Bounding Box”.

The Bounding Box is a part of the PostScript standard which informs postscript renderers of non-standard page sizes. If you have problems seeing all of an exported postscript image then including the bounding box or making it bigger might help. Due to the vagaries of font rendering, there is no easy way for me to predict how long a particular text string is going to be. I take a decent guess, but sometimes the text will get clipped.

Corel Draw, Adobe Photoshop, and Adobe Illustrator all support the Bounding Box, and will correctly render exported postscript from Java TreeView.

Adobe Distiller ignores the Bounding Box and produces incorrect output on some platforms.

The status panel displays different information depending upon which component the mouse is over. The hint panel displays hints on how to use the component.

Genes can be selected in the dendrogram by either clicking and dragging on the global pixels or by clicking on a node in the gene or array trees. A zoomed in view of the selected genes will appear in the Zoom Pixels pane, a yellow rectangle will appear on the global view indicating which genes are selected, and a blue rectangle will appear inside the yellow rectangle indicating which genes are currently visible in the Zoom Pixels pane.

Holding down the shift key while dragging on the global pixels will cause the exact range of arrays to be selected; by default all arrays are selected. Once a range is selected, pressing the arrow keys moves the selected rectangle around. Holding down the control key while pressing the arrow keys will grow and shrink the selected rectangle.

Clicking on a node in the array or gene trees will select all descendants of the node. The selected node and descendants will be colored in red. At this point, pressing the arrow keys will change which genes are selected. Up will select the parent of the current node, left and right will select the left and right children, and down will select the child with more descendants.

Provided the url link settings (described in the section called “Url Settings”) are set appropriately, clicking on a gene annotation or an array name will cause a browser window to open with details on the gene or array.

Figure 2.12. Creating a Scatterplot

To create a scatterplot, select "Analysis->Create Scatterplot..." from the menubar. You will then be confronted with the dialog in Figure 2.12, “Creating a Scatterplot”. The two pulldown menus determine what will be plotted on each axis. There options include the various arrays, the actual row number of the gene (called INDEX), and any annotation columns.

Moving the mouse around the screen in the Karyoscope will cause information for the nearest gene to be displayed in the info panel. There will be a bright yellow line connecting the cursor to the nearset gene, so you know which one the info applies to. Clicking will activate the url link associated with the gene.

The layout of the genes in the Karyoscope is determined by the Coordinates Settings and the Parameter Panel. The coordinates settings specify the chromosome, arm and position of each gene. The Parameter panel specifies exactly how to translate this information into an on-screen location.

The Pixels Per Map specifies how many pixels each position unit stands for. Making this number larger will stretch out the chromosomes.

The Pixels Per Value specifies how many pixels each value unit from the data matix gets. Making this number larger will make the bars higher in the karyoview.

The width and height specify the actual width and height of the canvas on which the karyoscope will be drawn. Making these values larger will space out the chromosomes without actually changing the spacing of the bars or their height.

Since setting these values manually is tedious, there are two additional ways to navigate, which are preferred for general use. Clicking the "Auto" button in the parameter panel will set the width and height to match the available screen real estate, and then scale the pixels per map and pixels per value appropriately. Selecting a rectanglar region in the Karyoscope causes the screen to zoom in on that location. Technically speaking, it causes the selected region to exactly fill the screen, increasing the pixel per map and pixels per value proportionately.

Although there is currently no way to select genes in the Karyoscope, genes which have selected in other views are visibly marked. The type of marking is determined by the settings in the Parameter Panel. You can choose the type and size in pixels of the highlighting from the pulldown menus to the right of "Highlight Selectd with:".

In order to view data in Java Treeview, there must be a Generalized CDT file. All other files are optional. The minimal GCDT file has a header row which contains the name of the unique id column, the name of the annotation column, and the names of the experiments, followed by one or more rows of per-gene data. Such a file can be created in Excel, and then saved as tab-delimited text.

Figure 2.16. Screenshot of Generalized CDT file in Excel

The generalized CDT file is a straightforward generalization of the CDT and PCL file formats. In addition to expression data, this file can contain additional per-gene and per-array annotation in columns before the GWEIGHT column or in rows before the EWEIGHT row. For backwards compatibility, if the GWEIGHT column is missing Java TreeView assumes the data starts on the third column, or the fourth column if the first column has the header GID. Similarly, if the EWEIGHT row is missing Java TreeView assumes the data starts on the second row. As a general practice, it is a good idea to include the GWEIGHT column and EWEIGHT row.

In addition, Java TreeView does special things with the first two or three columns. If the first column is GID, the second and third are assumed to be the unique ID and NAME columns. If the first column is anything other than GID, the first and second columns are assume to be the unique ID and NAME columns. The unique ID is used for gene list export, and for some matching purposes when necessary. The NAME column is displayed as per-gene annotation in the dendrogram and other views.

There are annotation column names with special meaning to Java TreeView, and are used for coordinates or to set the color of gene names. These special columns are described after the basic file format, and should be avoided as annotation names unless you want that specific behavior.

In order for Karyoscope to correctly display gene expression data by chromosome location, it needs to know where exactly to position each unique ID. To this end, it looks for annotation columns with the names "CHROMOSOME", "ARM" and "POSITION", which designate the chromosome, arm and position of a particular gene. "CHROMOSOME" should be a natural number indicating which chromosome the unique ID is on, "ARM" should be either "R" or "L" indicating the arm, and "POSITION" should be a real number indicating how far from the centromere the unique ID is. There is really no restriction on the units for position; bp or kb are natural choices.

A coordinates file is simply a generalized CDT file which has such columns. The coordinates files supplied with Java TreeView do not contain any expression data; they consist entirely of the unique id column, the chromosome, arm and position columns, and the required GWEIGHT column. However, any other generalized CDT file with the correct columns can serve as a coordinates file.

Figure 2.17. Screenshot of a Tree File in Excel

Traditionally, tree files have no header, and consist of four columns. Each row represents a node in either a gene tree, for the GTR file, or an array tree in the ATR file. For each row, the first column is the identifier of the node, the second column is the left child of the node, the third column is the right child, and the fourth column is the correlation between the left and right child. This fourth column is used by Java TreeView to determine the height of the node when rendering a tree.

By analogy to the CDT file, the tree files have been generalized in Java Treeview. Generalized tree files have a header line identifying the different columns. All generalized GTR/ATR files must have NODEID as the name of the first column. Tree files with any other string in the first row of the first column will be treated as legacy tree files. All of the rows will be treated as defining nodes, and the headers will be assigned the headers "NODEID", "LEFT", "RIGHT" and "CORRELATION". The meaning of these headers, and others, are described in the section called “ Tree File Headers ”.

Some users have reported problems unzipping the distribution. The problems encountered range from all files getting dumped in the root directory to not being able to unzip the distribution at all. This stems from my approach of using a single, relatively platform independant format, the .tar.gz format. The solution is to just use an unzipping program which handles .tar.gz properly.

The most common problem I have seen is that java is not installed on the system. The symptom is that nothing happens, or something confusing happens, when you doubleclick the launcher. The solution is to install a recent version of the java runtime environment. For Windows or Unix systems, this involves a quick download from the sun website,

Mac OSX comes with java standard. For Mac OS9, you may need to get the Mac OS Runtime for Java (MRJ) from the apple website,

Clicking on a gene in the dendrogram and karyoscope views is supposed to open a web browser window to a relevant database entry. Unfortunately, there is no standard way to do this in windows. When the linking is bad, typically clicking a gene name launches a DOS terminal window where the window's title equivalent to the URL, but no browser window comes up.

I have tried several things, but nothing works for all versions, and if you are not lucky you will be using one for which the current incarnation does not. Luckily it is easily fixed. Go to start->execute.. and entry "cmd" to get a command line shell. Try the following variants to see how your version of windows likes to do linking:

By default, #2 is used in version 1.0.5. If you require something else, you can enter the entire command as the URL string in java treeview, i.e. start http://genome-www4.stanford.edu/cgi-bin/SGD/locus.pl?locus=HEADER Including the quotes should guard against forbidden characters in the HEADER, as explained in my code: // The problem with the above is that special shell characters, notably & | ( ) < > ^ , // need to be escape, or put in double quotes (which can be doubled to escape them, // but I don't think that's necessary.)

When OSX tries to open a bad url, sometimes something breaks in the native code. If you run the application from the command line, you will see errors like the following:

2003-03-18 21:41:23.197 java[3492] LSOpenCFURLRef() returned -50 for URL (null) in OsX

This output indicates that an underlying C function failed. The java thread running this just dies without throwing an exception, so there's no way for me to detect it. The symptoms on the user level is that clicking has no effect. If you think this might be the case, double check your Url settings, in particular the preview, and make sure that the url is well formed.

Problem: I want to display things that are similar by Genename. This fucntion is present in your program when you select genes that have the same annotation(Analysis->Find...) , and then show a summary of these genes (Analysis->Summary Window...). Is there any way to save an image from the summary window?

Solution: There may be a way in the future to directly export from the summary window. However, in the meantime you can export data for the selected genes to form a valid CDT file, which can then be opened with Java Treeview and used to form images, etc.

First, Select the genes using the annotation search as you described. Then, use Export->Data... to export the data just for the selected genes. If you accept all the defaults, it will make a well-formed CDT file that you can then reopen and export to an image.

If you output a giant Postscript file and then try to open with adobe illustrator and get the error "The MPS parser is unable to parse the file" it most likely means that the postscript file created by java treeview requires a bigger canvas to display than the maximum canvas size of illustrator. I don't have a good answer on how to fix this, other than lowering the xscale and yscale.

Symptom: Trying to export some big clusters with names and dendogram to GIF, but continually getting an 'Out of memory' error. Able to export results only if you scale down the cluster image (i.e. using low X & Y scale values).

Solution: The gif encoder in java treeview sucks. Use Export->Export to bitmap... (ppm) format and then convert to gif with some software with a better gif encoder. "GraphicConverter" which comes by default with Mac OS X works well. There are also various windows options, such as "Image Transformer", which is shareware.

Note- this section is deprecated, as the GIF encoder is no longer used.

Running out of memory is tough to detect and deal with in java, since most of memory allocation is hidden from the java developer. If you are working with large data sets, or on a computer with a small amount of RAM, it is easy to run out of memory because java is not very memory efficient, and more importantly most Java Virtual Machines (JVMs) are too stupid to grow to take up more memory than some default arbitrary maximum.

There are only two possible solutions to the out of memory problem in java. Either I write a platform-specific launcher for each platform that informs the JVM of the extra ram, or you run the application from the command line and tell the JVM about the RAM yourself. Currently, only the latter is supported.

To run the application from the command line, first get to a terminal. This should be obvious to someone on a unix machine. On Mac OS X, run the Terminal program which is in the utilities folder. On Windows, select Start->run... and then type cmd <return> . Curously, on Mac OS 9, this problem does not seem to arise. I suspect this is because the OS 9 JVM is smart enough to use the per-file memory settings.

Next, switch to the directory containing the java treeview distribution (using either cd or chdir or whatever), and then type

java -Xmx###m -jar TreeViewLauncher.jar

Where the number following Xmx is the maximum amount of memory in megabytes that the JVM is to use. You may as well specify the available system RAM; the JVM won't take it unless it needs it. Also, make sure that you're in the directory with the jar files so that the command will work. Check out Figure 3.1, “Screenshot of Running Java TreeView from the Command Line with 800 Megs of RAM” for an example.

Figure 3.1. Screenshot of Running Java TreeView from the Command Line with 800 Megs of RAM

Question: I have two columns before I get to my data, the first being ID(containing accesion number), and the second is "NAME" (containing Unigene ID). The data follows in each column after these two. When treeview loads it up, it only displays the 2nd column "NAME", instead of both columns data when highlighting aspects of the cluster. Is this right?

Answer: Yes. TreeView used to display all annotations, but it annoyed some people. To specify the ones you want, use Settings->Annotations...

On the windows and mac platforms, the system default browser is used to open urls. In order to change it, you must muck around with your control panel.

On unix, there is no notion of a system default web browser, so I just hardcoded in a call to netscape. If you don't have netscape, or you want to use another browser, just alias netscape to that other browser from the shell in which you're launching java treeview. Something like the following should work:

alias netscape mosaic

java -jar TreeViewLauncher.jar

If the above doesn't work, then the JVM is spawning a sub-shell to run the call to netscape in. In that case, you need to add the alias to your .profile or equivalent, or perhaps just add a link to your preferred browser such as the following:

ln -s /usr/bin/mosaic netscape

Some people have been thrown off guard by dendrograms such as the one depicted above. The strange appearance of the tree, where the parent node of dpy-8 and col-67 has a lower correlation than its parent, is a correct representation of the clustering algorithm used to generate the tree. Indeed, the correlation between the two genes is .889, whereas the correlation of the next join up is .908. This simply means that the average of dpy-8 and col-67 is more similar to the next node up than they are to each other (and, by implication, than either dpy-8 or col-67 alone are to the next node up).

If such behavior disturbs you, please use a different correlation metric, such as complete linkage. Certain other visualization programs, such as the original Treeview, artificially force parent nodes to have a correlation equal to or less than that of their children, but I choose to accurately represent the information in the GTR and ATR files.

Typical symptoms are the application seems to lock up after a fairly innocuous user action, and then the application suddenly quits. If you ware running from the command line, you may see a report of a "bus error" or "segmentation fault". Running "Console", an application that comes with OSX and can be found in the Utilities subfolder of the Applications folder, should reveal something like

May 18 11:27:19 Alok-Saldanhas-Computer /Users/aloksaldanha/Desktop/code/java/LinkedView/bundle/TreeView/Java TreeView.app/Contents/MacOS/JavaApplicationStub: An error report file has been saved as /Users/aloksaldanha/Library/Logs/JavaNativeCrash_pid2964.log.  Please refer to the file for further information.

 
May 18 11:27:21 Alok-Saldanhas-Computer crashdump: Crash report written to: /Users/aloksaldanha/Library/Logs/CrashReporter/JavaApplicationStub.crash.log

May 18 11:28:03 Alok-Saldanhas-Computer WindowServer[188]: Reserved range exhausted. (0xbbf4b000 to 0xbc1d1000 goes out of bounds)

May 18 11:28:10 Alok-Saldanhas-Computer /usr/bin/java: An error report file has been saved as /Users/aloksaldanha/Library/Logs/JavaNativeCrash_pid2971.log.  Please refer to the file for further information.

as opposed to

[error] apple.awt.EventQueueExceptionHandler Caught Throwable : 
[error] java.lang.ArrayIndexOutOfBoundsException: Array index out of range: 52133
[error] 	at org.gjt.sp.jedit.Buffer.getLineOfOffset(Unknown Source)
[error] 	at xml.TagHighlight.updateHighlight(Unknown Source)
[error] 	at xml.TagHighlight.access$000(Unknown Source)
[error] 	at xml.TagHighlight$1.actionPerformed(Unknown Source)
[error] 	at javax.swing.Timer.fireActionPerformed(Timer.java:271)

In general, if Java Treeview crashes it is advisable to check the console for messages. The former indicates a bug in the JVM, not in Java Treeview, which at some point I should write up as a formal bug report. Something like the latter indicates a bug in Java Treeview, although this particular instance was another java program. There are at least two causes for the JVM crashes, one of which is somewhat understood. If you are launching Java Treeview by double-clicking a jar file, and you have multiple views open, you could be triggering a bug in the Mac OSX Java libaries related to font rendering. Either run Java Treeview with the following command line:

java -Xmx500m -Dapple.awt.TextAntialiasing=false Treeview.jar

or just use the double-clickable application that comes in the .dmg download.

Java Treeview may also crash when you select entries from the most recent file listing. It is not clear what causes this or how to fix it at the moment.