GO-TermFinder version 0.50
==========================

This set of modules can be have been developed under the auspices of
the GMOD project (http://www.gmod.org/), which seeks to create
software that may be generically useful for Model Organism Databases (MODs).

WHAT DO THEY DO?

These modules provide an object oriented set of libraries for dealing
with files produced by the Gene Ontology project (GO -
http://www.geneontology.org/).  In particular, the GO::TermFinder
object allows a client program to provide a list of genes, from which
it will determine p-values for the annotation associated with that
list of genes.  It does this using the hypergeometric distribution.
In addition, a corrected p_value is calculated, to correct for
multiple hypothesis testing.  In addition, this distribution contains
a version of Shuai Weng's GO::View module (and associated classes),
such that you can graphically display the output of the
GO::TermFinder.  Some simple clients of these modules are provided in
the examples directory.

INSTALLATION

To install this module type the following:

First decompress the gzipped tarfile, e.g:

   tar zxvf GO-TermFinder-0.5.tar.gz

Then cd into the created directory, e.g.:

   cd GO-TermFinder-0.5

Then actually install it:

   perl Makefile.PL
   make
   make test
   make install

The make install step will require, on most unix systems, that the
command be run with root privileges, as by default it will install the
libraries in a location (usually something like ${PERL5LIB}), which
requires root privileges to write there.  If you want to install the
libraries in an alternative place, such as your home directory, do:

perl Makefile.PL INSTALLDIRS=site INSTALLSITELIB=/home/your/private/dir

as the first step of the installation, where /home/your/private/dir is
obviously your target destination.  Note, for the example scripts to
work you will have to add:

use lib "/home/your/private/dir"

before the other use statements.  Also, during the 'make install'
stage, there will be some complaints about not be able to install man
pages, but you can happily ignore these.

In the case that you get any failures during 'make test', please send
me the full output of 'make test', and let me know what version or
perl you are using, and on what platform you are running.

DEPENDENCIES

This module requires these other modules and libraries:

	Storable - required for serializing objects to disk
	GD	 - used for creating images in GO::View
	GraphViz - used for graph layout in GO::View

Typically, Storable will be installed with Perl 5.6 and above.  If you
need to find it and install it yourself, you can grab it from:

http://search.cpan.org/dist/Storable/

GD is available from:

http://search.cpan.org/dist/GD/

Note that installation of the GD module itself has certain
requirements that you must deal with to install it.  GO::View should
be able to work with versions of GD that create png or gif images.

GraphViz is available from:

http://search.cpan.org/dist/GraphViz/

Note that Graphviz also has some tricky requirements, in that you also
need to install the C version of Graphviz, as noted in the README for
GraphViz.  There are precompiled binaries available for most platforms from :

http://www.research.att.com/sw/tools/graphviz/

On MacOSX, the easiest way to install GraphViz is to use fink
(http://fink.sourceforge.net/).

If you do not want to use GO::View, and its client batchGOView.pl
program, then you do not need either GD, or GraphViz.  In that case,
you can comment out their entries in the PREREQ_PM hash in
Makefile.PL, so that installation does not depend upon them.

CONTACT INFO

If you have any suggestions, bug fixes, etc, please post them to the
gmod site at http://www.gmod.org/, or send email to
sherlock@genome.stanford.edu.

NOTE

The ontology files in the t/ directory are solely for the purposes of
running the test suite.  You should get the latest versions from the
Gene Ontology website for your own analyses.

COPYRIGHT AND LICENCE (the 'MIT license')

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Copyright (C) 2003 Gavin Sherlock, Stanford University

