Installing Laj as an Applet

TABLE OF CONTENTS

• Introduction
• Installation
• Data Files
• Web Page
• HTML Conversion

Introduction

This document provides instructions for people who want to set up Laj as an applet on their own web site, in order to display their data for viewing by others. Both forms of Laj (applet and stand-alone application) are distributed together, so the initial download and unpacking instructions are the same. Installing it as an applet, however, requires some additional steps: ensuring that Laj and the data files you want to display are accessible to your web server, and building a web page to run the applet.

Installation

Laj is available for download as a compressed zip archive,  laj.zip . This was created with the Java jar tool, but the format is compatible with PKUnzip and many other unzip programs. Unzipping the archive will produce laj.jar (a jar file containing the program itself) and a docs subdirectory containing some documentation files in HTML format. If your unzipper program does not preserve the directory structure and complete file names from the archive, you may need to move and/or rename the documentation files manually in order for the applet's help function to work. Note that the laj.jar file does not need a second round of unzipping -- Java will access it "as is". Be sure to unzip the archive in a directory/folder that will be accessible to your web server, e.g., a new laj directory somewhere in the server's space.

Since Java applets are run by the user's web browser, you do not need to have Java itself installed on your server. Users, however, will need browsers that reliably support at least Java 1.2, and preferably Java 1.3 or higher. For best compatibility we recommend Sun's free Java Plug-in software; the file java_plugin_help.html that comes with Laj contains more information, and you may want to include a link to this file on your Laj web page.

Data Files

Laj can make use of several kinds of data, including alignments, original sequences, exons, repeats, annotation links, color underlays, and text highlights. Only the alignment file is required; the others are optional. For detailed descriptions of these files and their format requirements, please see Input File Formats for Laj. These files must be accessible to your web server. We find it convenient to group the files for each invocation (e.g., each genomic region) in a separate subdirectory of the laj directory. Any of these files can be compressed with GZIP, if the file name ends with ".gz".

Web Page

The last step is to create a web page on your server that invokes the applet with the appropriate parameters for loading your data files. The applet normally appears as a labeled button that opens an Laj window when the user clicks on it; thus you can have several buttons on the same page, each set up to display a different set of data. The basic format of the HTML code looks like this:

  <applet code="edu.psu.cse.bio.laj.LajApplet.class"
          archive="laj.jar"
          width="200" height="30">
  <param name=buttonlabel    value="BTK">
  <param name=title          value="BTK region, human (x) vs. mouse (y)">
  <param name=alignfile1     value="/java/laj/BTK/blastz.out">
  <param name=exonfile       value="/java/laj/BTK/exons">
  <param name=repeatfile     value="/java/laj/BTK/repeats">
  <param name=annotationfile value="/java/laj/BTK/annotations">
  <param name=underlayfile   value="/java/laj/BTK/underlays">
  <param name=highlightfile  value="/java/laj/BTK/highlights">
  </applet>

• If the laj.jar file is not in the same directory as your web page, you'll need to supply the path to it in the archive attribute.
• The width and height attributes are for the button, not the Laj window.
• The 1 in alignfile1 is not an error; it is left over from the stand-alone form of Laj, which can display two alignment files simultaneously.
• Any file name ending with ".gz" will be assumed to be in GZIP format.
• This example assumes that the names of the original sequence files used to create the alignments are specified within the alignment file, which is the default. In this case the sequence files should normally be placed in the same directory as the alignment file. Laj needs these in order to display the text view of the alignments in the bottom panel.
• To create several buttons, just repeat this entire block of code (with new parameter values, of course).

Additional Parameters

• <param name=nobutton value="true">
  Open the Laj window immediately, instead of displaying a start button.

• <param name=pane value="pip">
  Display just the dotplot ("dot") or just the pip panel ("pip"); the default is "both". This parameter does not affect the other panels.

• <param name=file1seq1 value="/java/laj/BTK/human">
<param name=file1seq2 value="/java/laj/BTK/mouse">
  Override the sequence file names given in the alignment file (e.g., in case PipMaker has substituted its own names for them).

• <param name=file1seq1serv value="/cgi-bin/get-subseq?org=hum&db=1">
<param name=file1seq2serv value="/cgi-bin/get-subseq?org=mus&db=1">
  Instead of reading the sequences from files, request them from server scripts. Laj will append query fields to the URLs you supply, to specify the contig header and endpoints of the subsequence it needs. E.g.,
      http://yourserver/cgi-bin/get-subseq?org=hum&db=1&hdr=%3Echr22&start=100&end=9999
  Thus your script must recognize the hdr, start, and end fields, in addition to any that you specify here. Note that the FASTA contig header will be URL-encoded, so the leading ">" becomes "%3E". Aside from the HTML header (use content type "text/plain"), the output from your script must consist of exactly two lines: a FASTA header (which must begin with ">" but is then ignored) followed by the requested nucleotide sequence on a single (possibly very long) line of its own.

• <param name=noseq value="true">
  Don't read sequences at all; just omit the text view panel entirely.

• <param name=xclip value="85000 90000">
<param name=yclip value="1 3000">
  Limit the region displayed (i.e., the maximum unzoom) in the horizontal and vertical dimensions, respectively. If the alignments' second sequence contains multiple contigs, then the yclip range refers to the virtual coordinate system formed from the catenated contigs, as shown in the dotplot.

HTML Conversion

Now for the bad news. The relatively simple HTML code listed above may cause the user's browser to invoke its own internal version of Java, which is likely to be outdated and buggy. Some newer browsers will automatically invoke the Java Plug-in if it is installed, but creating a single web page that will coax a variety of browsers on a variety of platforms to use the Java Plug-in if possible, and only fall back to the internal Java as a last resort, is an exercise in hairy kludges (as discussed at http://java.sun.com/products/plugin/1.2/docs/tags.html ).

Fortunately, Sun provides a handy HTML Converter program, available for download at http://java.sun.com/products/plugin/1.2/converter.html , that takes care of this for you. [Note: as of this writing, this page contains an HTML bug which may cause the main content to be omitted; click on the "Print-friendly" link to see it.] However, this program is itself written in ... you guessed it ... Java, so if you want to use it you'll have to install Java after all. You don't really need a full-fledged Java development kit for this; a simple runtime environment such as Sun's free JRE should be fine. (Much of the information in Installing the Java Plug-in also applies to obtaining the JRE/JDK.) A few tips:

• Always keep a backup of your original web page file, and run the HTML Converter on a copy. This makes it much easier to make changes later.
• I use a command like the following to do my conversions:
    [path1]java -cp [path2] HTMLConverter laj.html -template extend.tpl
  where [path1] and [path2] are the locations where Java and the HTML Converter were installed, respectively, and laj.html is the name of the web page file to be converted. Note that [path2] ends with a directory name, not a slash or backslash, and it is followed by a space.
• Of course, you should also read the documentation that comes with Java and the HTML Converter.
• Although newer versions of the HTML Converter are available, they are set up to insist that the user obtains the corresponding newer version of the Java Plug-in, which is not really necessary for Laj.