Two Sample Logo - TSL version 1.1 (November 2005)

Copyright (c) 2005 Vladimir Vacic, Lilia M. Iakoucheva, and Predrag 
Radivojac.

Two Sample Logo incorporates parts of code from the Cephes Math
Library and WebLogo sequence logo generator; detailed licensing 
information can be found in the LICENSE.txt file.


CONTENTS:

cgi-bin  - This directory contains Ruby scripts for generating two
           sample logos. The main script for the web (CGI) application
           is tsl.cgi, and the main script for the command line 
           application is tsl. 

datasets - Datasets used to build the examples on the web page.

html     - Help, examples and credits HTML pages. 

pvalue   - C code used to compute statistical significance of 
           the difference between two samples.



SYSTEM REQUIREMENTS:

Command line version of Two Sample Logo requires that you have a Ruby 
interpreter installed on your system, as well as GhostScript (a 
PostScript interpreter) and ImageMagick. All three programs are by
default installed on any Linux system; in case that they are not,
they can be downloaded free of charge from:

Ruby        - http://www.ruby-lang.org 
GhostScript - http://www.cs.wisc.edu/~ghost
ImageMagick - http://www.imagemagick.org

Ruby interpreter is normally in the system path; as far as GhostScript
and ImageMagick go, if they are not in the system path, the locations
of the binaries can be specified in the tsl.conf file.

In addition to those, the web version requires a running web server:
Two Sample Logo has been tested on Apache, using the Ruby module.



COMMAND LINE ARGUMENTS:

Usage: tsl -P <pos file> -N <neg file> -K[A|N] -O <out file> [options]

Mandatory arguments:
  -P <positive sample file>
  -N <negative sample file>
  -K <kind of data>          A for amino acid, N for nucleic acid.
  -O <output file>           Output file name.


Optional arguments:
  -A <box shrink factor>     Shrink factor of characters if option s 
                             (show box) is toggled. Defaults ot 0.5.
  -C <color scheme>          One of the following:        
                             amino_bw (Black and white)
                             amino_weblogo (WebLogo default colors)
                             amino_colors (Amino colors)
                             amino_shapley (Shapley colors)
                             amino_charge (Charge)
                             amino_hydro (Hydrophobicity)
                             amino_surface (Surface exposure)
                             amino_flex (Vihinen's flexibility)
                             amino_disorder (Disorder propencity)
                             nucleo_bw (Black and white)
                             nucleo_weblogo (WebLogo default colors)
                             nucleo_shapley (Shapley colors)
                             Defaults to amino_weblogo.
  -E <sequence end>          
  -F <format>                Format of output (EPS, GIF, PDF, PNG). 
                             Defaults to PNG.
  -H <logo height>           Height of output logo. Defaults to 5.
  -I <title>                 Text of title, enclosed in "" if more than one 
                             word.
  -M <first index>           Defaults to 1.
  -R <resolution>            Bitmap resolution. Defaults to 96.
  -S <sequence start>        Sequence start number. Defaults to 1.
  -T <statistical test>      T for t-test, B for binomial test.
                             Defaults to B.
  -U <units>                 Logo dimensions units (cm, inch, pixel, point).
                             Defaults to cm. 
  -V <p value>
  -W <logo width>            Width of output logo. Defaults to 8.
  -X <res units>             Resolution units when bitmap resolution is 
                             specified (ppi, ppc, ppp). Defaults to ppi.


Optional toggles (no values associated):
  -a                         Toggle antialiasing
  -b                         Toggle Bonferroni correction
  -f                         Toggle fixed height output characters 
  -o                         Toggle outlining of characters
  -s                         Toggle show box
  -x                         Toggle numbering along the x-axis
  -y                         Toggle labels on y-axis



COMMAND LINE EXAMPLE:

The Tyrosine Phosphorylation two sample logo was generated using the following
command line options:

./tsl -P ../datasets/phos_Y_pos.txt -N ../datasets/phos_Y_neg.txt -K A -F PNG 
-O testing.png -x -y -C amino_charge -M -12 -a



C EXECUTABLE:

The statistical tests code can be found in the /pvalue directory. Before
it can be used, it needs to be compiled on the computer on which it will be
run (a Makefile is provided; it suffices to type "make" on the command prompt 
in the /pvalue directory) and put in the directory with the Ruby scripts.



WEB APPLICATION SETTINGS:

Due to security concerns, we have separated the cgi scripts from the html
documents and images. Cgi scripts are in a subdirectory of cgi-bin, and html
documents are in a subdirectory of the Apache web document root. On Apache 
web server running on a Linux system, assuming the default Apache settings, 
those are "/var/www/cgi-bin/tsl" and "/var/www/html/tsl", respectively. 

For the Two Sample Logo cgi scripts to be able to link to html documents
(such as help files, etc.), relative path for the html documents in
relation to the cgi scripts directory has to be specified in tsl.cgi
"path" variable. For example:

path = "../../tsl/"

In addition to this, the tsl.cgi script needs to be configured to write
the output images into an Apache-writable directory under the Apache web
document root, so they can be displayed to the user. This is done using
the "temp" variable. For example:

temp = "/var/www/html/tsl/cache/"