swainechen / slcview Goto Github PK

slcview.pl version 2.0 README file

0. Introduction
1. Requirements
2. Installation
3. Testing
4. Usage
5. Default options
6. References/Disclaimer


---------------
0. Introduction
---------------
slcview is a program that allows you to create clustergrams from the command
line.  Input files are the regular .cdt, .gtr, and .atr files generated by
Mike Eisen's Cluster and Gavin Sherlock's XCluster.  The output is similar to
that generated by Mike Eisen's TreeView.

---------------
1. Requirements
---------------
Perl 5.6.1 is required.  ImageMagick 5.4.1 is required.  For drawing any text
labels, Ghostscript 6.53 is required.  Some stuff may work with older versions
of these required packages, but I can't make any promises.

Using ImageMagick allows you to generate many different image output formats
simply by changing the extension of the output file you specify.  In all the
examples which follow I will use the .gif extension, but you can easily make
a .jpg, .tiff, .ps, .pdf, or some other image file type by just putting that
extension on the filename you specify.

---------------
2. Installation
---------------
Installation is relatively simple if you have all the required software.

First, you need to make sure that Slcview.pm is available to perl.
On a Debian system, a good directory to copy or link Slcview.pm to is
/usr/local/lib/site_perl.  On a Redhat system (I think) a good location is
/usr/local/lib/perl5/site_perl.  These locations may depend on your
configuration, though.  To find out where perl will look for module files, you
can run:

  $ perl -e 'print join ("\n", @INC), "\n"'

at a command prompt and see what directories it's looking in.  Slcview.pm needs
to be copied to one of those directories listed.

Second, make sure slcview.pl is somewhere on your path, or run it with
./slcview.pl or <absolute path>/slcview.pl.

----------
3. Testing
----------
There is a test.sh script, as well as a test directory.  Running the test.sh
script, i.e

  $ ./test.sh

should check for required libraries and then attempt to generate images and
compare them with images in the test directory.

Note that you can run the test script before you install slcview.pl and
Slcview.pm.

--------
4. Usage
--------
Running slcview.pl with no options will print out some help on usage syntax
and options.  It's a little long so you may want to pipe it through your
favorite pager or into a file.

The quick and dirty usage syntax is:

slcview.pl foo.cdt -o foo.gif

This runs it will all the defaults.  With a few common options:

slcview.pl foo.cdt -o foo.gif -xsize 3 -ysize 3 -gtrresolution 200 -atrresolution 100 -bgcolor white -linecolor black -poscolor red -negcolor 0,255,0

Note that the ImageMagick library which slcview.pl uses has green as
half-saturated, if you want a fully saturated green channel you can use
the rgb color designation as above or use the color 'lime'.  Also note
that xsize must be at least 6 for the program to think about drawing
array labels.  Similarly, ysize must be at least 6 for the program to
think about drawing gene labels.  This is so that the text will hopefully
come out big enough to be readable.

One other common example which gives you a legend image for the color
intensities used in the clustergram:

slcview.pl foo.cdt -o foo.gif -legend foo_legend.gif -legsize 20 -legnumber 10

This will create foo.gif as well as foo_legend.gif.  foo_legend.gif will give
you 10 boxes, each 20 pixels square, which span the range of colors used in
foo.gif.  Labels will be placed on the diagram to let you know how to translate
back from colors in foo.gif to the actual numbers in the .cdt file.

------------------
5. Default options
------------------
Version 2.0 now allows you to set system and user defaults, which override
the program default options.  The program will look for and read in options
from the following files, in the following order:

/etc/slcview.conf
/usr/etc/slcview.conf
/usr/local/etc/slcview.conf
~/.slcviewrc

This will allow system-wide default options to be set, which can then be
overridden by user-set defaults.  Finally, all command line options will
override the default value if it is specified in one of these files.

A sample slcview.conf file is included with all the program defaults, to help
you set up your own file.  The syntax is the same as that for perl, so comments
begin with the pound (#) sign.

------------------------
6. References/Disclaimer
------------------------
I hope this program does what you hope/want/need it to do.  If it helps you in
your research, I'd love to know about it.  If it needs improvement I'd love to
hear about that also.  I can be reached at:
  [email protected]
If you publish images you've used slcview.pl to create, please cite:
  Chen, S.L.  2003.  Slcview, Version 2.0.  Distributed by the author.  http://slcview.sourceforge.net

Perl:
  http://www.perl.org
ImageMagick:
  http://imagemagick.sourceforge.net
Ghostscript:
  http://www.ghostscript.com
Mike Eisen's Cluster and TreeView:
  http://rana.lbl.gov/EisenSoftware.htm
Gavin Sherlock's XCluster:
  http://genome-www.stanford.edu/~sherlock/cluster.html

slcview.pl Copyright (C) 2002,2003 Swaine Chen ([email protected])
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.  For details please see the accompanying
COPYING file.