GO-TermFinder version 0.80 ========================== 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). The latest version of these modules should always be available from: http://search.cpan.org/dist/GO-TermFinder/ 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. This distribution also 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 Firstly, read all the installation instructions before you begin! To install this software, you will need some limited Unix experience, and some limited Perl experience. If in doubt, consult your local Perl guru or systems administrator. You also need access to a Unix machine, such as MacOSX, or a Windows machine running Cygwin, a Linux box, a Sun machine etc.. Note, that to install the GO-TermFinder distribution after version 0.70, you need a C++ compiler. We have tested installation on MacOSX, Linux, Solaris and Windows (using Cygwin), all using GCC as the compiler, and everything seems to work. The Makefile.PL in the native directory is hardcoded to look for g++, so if you have a different C++ compiler, you will need to edit that file. It should give you an error message indicating this, if unable to find g++. Thus far, we have not been successful installing under ActiveState Perl with Microsoft Visual C++, though we have not tried too hard. If you can provide a patch for the Makefile.PL that gets it to work in that environment, we'll happily accept it. To install the software do the following after downloading the distribution: First decompress the gzipped tarfile, e.g: tar zxvf GO-TermFinder-0.8.tar.gz or: gunzip GO-TermFinder-0.8.tar.gz tar xvf GO-TermFinder-0.8.tar Then change into the created directory: cd GO-TermFinder-0.8 Then actually install it, using the following commands: 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. In this case, you would use: sudo make install after which it will prompt you for you sudo password (ask you sysadmin to do this if you don't have privileges). If you want to install the libraries in an alternative place, such as your home directory, which won't require root privileges, do: perl Makefile.PL INSTALLDIRS=site INSTALLSITELIB=/home/your/private/dir as the first step of the installation, where /home/your/private/dir is 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', rerun the tests as 'make test TEST_VERBOSE=1' and send me the full output, 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 CGI - used by the GO::TermFinderReport::Html object Test::More - use for some of the tests Typically, Storable and CGI will be installed with Perl 5.6 and above. If you need to find it and install them yourself, you can grab them from: http://search.cpan.org/dist/Storable/ http://search.cpan.org/dist/CGI.pm/ Test::More is part of the Test-Simple distribution, and is available here: http://search.cpan.org/dist/Test-Simple/ 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. The Perl interface to 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 (specifically the dot binary), as noted in the README for the Perl version of 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 the C version of GraphViz is to grab the installer from: http://www.ryandesign.com/graphviz/ Note, e.g. for version 2.12, this will install the binaries under : /usr/local/graphviz-2.12/bin/ which the Perl Graphviz won't find, unless you add that to your PATH environment, or, make a link to the dot binary like: sudo ln -s /usr/local/graphviz-2.12/bin/dot /usr/local/bin/dot as /usr/local/bin/ is probably already in your PATH. You will still need to install the Perl interface to GraphViz manually though. Also not, if the graphvic output looks funky, then the versions of the Perl Graphviz and the dot binary may be incompatible - try updating both to the latest versions. The Perl version of GraphViz requires the following modules be installed: IPC::Run : http://search.cpan.org/dist/IPC-Run/ Math::Bezier : http://search.cpan.org/dist/Math-Bezier/ Graph : http://search.cpan.org/dist/Graph/ and in turn Graph requires: Heap : http://search.cpan.org/dist/Heap/ 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 send email to sherlock@genome.stanford.edu. NOTES 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 (http://www.geneontology.org/) for your own analyses. If you seem to be getting some odd behavior that you can't explain, make sure that the ontology and association files you downloaded from the Gene Ontology site have not had their line endings converted - the software is expecting them to be \n, which is what the files have on the GO ftp site. It is possible for ftp programs to sometimes mangle them into control-M's. 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-2007 Gavin Sherlock, Stanford University