XLANDSCAPE - X-window sequence landscape program May 1997 About Xland ----------- This file describes how to set up and how to run Xland. Xlandscape is a X windows based interface to landscape, a program developed some years ago at Molecular Cellular Developmental Biology, University of Colorado, Boulder under the direction of Gary Stormo. We assume you are familiar with landscape and refer you to the original paper describing it; Sequence Landscape, (1986) B. Cliff, D. Haussier, R. McConnell, T. D. Schneider and G. D. Stormo, Nucleic Acids Research, 14: 141-158. Also a paper describing this version of Xlandscape: Levy S, Compagnoni L, Myers EW and Stormo G.D. (1998) Xlandscape: The graphical display of word frequencies in sequences. Bioinformatics 14:74-80. System Requirements ------------------- Xlandscape requires at least Release 4 or 5 of the X window system, version 11. It uses the Athena Menu Sme object, the X toolkit intrinsics, and the X library. Xlandscape contains many dependencies on the Unix operating system. Xlandscape has been ported to the two following systems. * Sun Solaris version 2.4 - SPARCstations * ULTRIX V4.2 - Decstation While it is likely that higher releases of X11 (R6) will probably work with the Xlandscape source code, to date these have not been tested. Making Xlandscape ----------------- Mandatory Steps [1-5] [1] Uncompress the tar file by typing: zcat xland.tar.Z |tar xvf - [2] Edit the Makefile in the src subdirectory by modifying the lines that define the C compiler. ie. CC = gcc or CC= cc and add the path containing the X11 include file to the CFLAGS variable, ie. CFLAGS = -I/usr/openwin/include -I../w-libseq -I../SmeMenu -g where the path /usr/openwin/include would be replaced by the X11 include file location. In addition, the path to the X11 libraries needs to be modified for your system in the LOCAL_LIBRARIES variable. ie LOCAL_LIBRARIES = -L/usr/openwin/lib -lXaw -lXmu -lXt -lXext\ ../w-libseq/libseq.a -lm ../SmeMenu/SmeMenu.a Thus, modify the -L flag to point to the path where Xaw, Xmu, Xt Xext libraries reside. [3] Edit the Makefiles in the directories ../SmeMenu and ../w-libseq for the CC and CFLAGS variable in the same manner as in step [2]. [4] Type: cd xland/src make all This will produce the executable Xlandscape in the directory xland/src. Before running the program complete step [5] and the next section dealing with customization. Customization is needed for Xlandscape to work at all. [5] Make the application defaults file (XLand) known to X. There are several ways to do this however we suggest the following. type: setenv XENVIRONMENT ./xland/src/XLand which sets the environment variable XENVIRONMENT to the location of the file XLand. This had to be once per login session so you may want to add this line to your .cshrc file. Optional Step: If printing or saving region of landscape to postscript file. [6] To enable printing or saving the viewed region of a sequence landscape to a postscript file obtain a verion of PBMPLUS, build it and copy the programs 'pnmtops' and 'xwdtopnm' to the xland/src directory. Customization ------------- You need to edit the file Xlandscape to instruct the program to where to find some files it needs. Full innstructions are included at the beginning of the Xlandscape file. You can change the colortables used inside the program by making a new selection from the file 'ColorTable' and/or by making a new entry in the file ColorTable and setting the proper resources in the file 'XLand'. The 'ColorTable' file is supplied with 8 different color tables and any of these can be used for the different coloring requirements in Xland. Running Xland ------------- Run Xlandscape by typing xland After a few moments the main Xlandscape window will appear entitled 'Sequences' with six command buttons and an quit button positioned to the left hand side of the window. The normal flow of operation is as follows: To read in sequences to be used for source and target ---------------------------------------------------- Click on the 'File' button and this will popup a file browser. Select the appropriate sequence files (see Xlandscape File Format section below) to be used as both the source and target sequences. Select the file in the browser window and click on the 'Read' button. The files should appear in the Sequence panel of the main Xlandscape window. To move upwards in the directory structure in the file browser click on the 'Prev' button. Click on the image of a directory ie directory_name/ to move into a directory. Select as many files as required and click on the 'Close' button. To obtain a suffix array of the sequence necessary for landscape calcn. ---------------------------------------------------------------------- Create the indexes by selecting a file in the Sequence panel of the main Xlandscape window and clicking on the 'Index' button. When indexing is complete an * will appear beside the sequence in the Sequence panel of the main Xlandscape window. Index all selected sequences. To construct the landscape -------------------------- To construct a single sequence, single database landscape do the following: Create a landscape by clicking on the 'Landscape' button in the main Xlandscape window. This produces the LandSelector popup. Select a target or destination sequence by selecting a sequence in the Sequences panel of the main Xlandscape window and clicking on the 'Dest' button located in the LandSelector popup. The name of the sequence will appear in the window as the 'Destination sequence'. Using the same selection approach select a source sequence (which can be the same sequence as the destination, a different sequence or a databank of concatenated sequences). The sequence name or names will appear in the 'Source sequences' panel of the LandSelector popup. Provide a descriptive name for this landscape in the 'Landscape name' panel of the LandSelector popup. Click on the 'Done' button to close this window and accept the source/target sequence designation. The 'Landscape name' will appear in the 'Landscape' panel of the main Xlandscape window. The 'Delete' button allows to remove any source sequences by selecting them in the 'Source sequences' panel and clicking on 'Delete'. To modify the selection of a destination just choose another one and it will replace the previous sequence. To construct a difference or ratio landscape do the following: Follow the instructions in the previous section regarding single sequence, single database landscape production to select a target sequence and source sequences. For a ratio landscape there should be two source sequences. For a difference landscape there should at least two source sequences. For a ratio landscape select the source sequence that will constitute the landscape that is the denominator and 'pull down' (click and hold) the menu attached to 'Methods' button and select the 'Ratio' option. Click on the 'Done' button. For a difference landscape, select the landscape source sequence that will be subtracted from the original landscape and select either 'Sub' or 'Sub-scaled' from the 'Methods' pull-down To display a landscape ---------------------- Select the landscape to be display by clicking on the landscape name in the 'Landscapes' panel of the main Xlandscape window. This will produce a window that displays the landscape in the default viewing mode which maps the word frequencies to color blocks as determined by the color strip at the base of the window. The target sequence is shown at the base of the landscape array. The landscape may be scrolled horizontally by clicking the mouse buttons in the scroll bar region at the base of the window. The left mouse button moves the sequence-landscape combination to the left and the right mouse button move the sequence-landscape to the right. Selecting any cell in the landscape will position a cursor on that cell and displays in red-white video inverse the word starting at that point. The text at the base of the window shows the numeric position of the word, its length and its frequency. Selecting the 'Char' option in the 'Options' button pull-down menu switches the landscape mode from color to numerical values for frequencies. To view high frequency word values zoom in to the landscape region by clicking the (down-arrow), zoom out by clicking the (up-arrow). To output the sequence-landscape combination select 'Output whole landscape' in the 'Write' pull-down button. This writes an ascii text file with the name 'land.out'. This file contains on each line the sequence letter and frequency values of words beginning at that position. Further processing can be performed on this file. NOTE: PRINTING OR POSTSCRIPT FILE SAVING DOES HAVE SOME BUGS. PLEASE NOTE THAT THE PROGRAM IS UNSTABLE DURING THESE OPERATIONS. To print or save a region of landscape shown in the landscape window, select 'Send to printer' (for printing) or 'Write to file' (postscript file) from the 'Write' pull down. In the popup that appears either type in a networked printer name or a postscript file name. Make sure that neither the popup nor the main Xlandscape window obscure the landscape Display window before clicking on 'OK'. The landscape data can be filtered and then displayed in color mode. To produce a filtered display, select 'Filter' in the the 'Filters' button pull down. Currently, one filter is available and it represents the following algorithm: filter (i,j) = log (Obs(i,j) / Exp (i,j)) where Obs is the observed value and Exp is the expected values so computed: Exp (i,j) = Obs(i-1, j) * Obs (i-1, j+1) / Obs (i-2, j+1) where i is the row position and j the column in the 2D representation of the landscape To reverse back to "char mode" select the option NULL in the 'Filters' pull down. Xlandscape File Format ---------------------- The input file format for Xland. This can be text of any kind. Thus far DNA and protein sequences have been tried successfully. The following represents one format type that works with the program. name 1 (length of sequence) text....... For example if there is a file t2.seq then you may have the following. T2 1 200 AGTTAGTCGAGCTAGCCGTAGCTAGCTCCGGATCGATCTCTCGAGATATACCCCCAAATT CGAGCGGCGTATTATCGGCTAGGCTAGCGCGCTAGCGCGCGATCTCCTCG The name "T2" is mandatory. The integer 1 is also mandatory. The length is not needed but it is worthwhile putting some non-zero integer in this location. The above sequence is shorter than 200 but this number works. The sequence can be upper or lower case regardless if the the source and target sequences are of mixed case. Command-line options -------------------- There are three options that can be used when starting the program: -seq filename -ct colortablename -fltct colortable name The -seq option specifies a sequence file to read in while starting the program; the sequence will be automatically indexed and will appear inside the Sequences subwindow of the main menu. The presence of a `*' next to a sequence name inside this subwindow indicates that the sequence has been indexed. The -ct option specifies the colortable name of the colortable to be used while displaying the landscape in colormode with no filter applied. The -fltct option specifies the colortable name of the coloratble to be used while displaying the landscape with a filter applied. For any problems in compiling or using the program and for any comments send email to: Samuel.Levy@colorado.edu Gary.Stormo@colorado.edu