update svn ignore
[function2gene.git] / README
1 INSTALLATION 
2
3 Prerequisites
4
5 Function2Gene requires the following modules and programs to work
6 properly:
7
8   * perl http://www.perl.org/get.html
9   * HTML::TreeBuilder http://search.cpan.org/dist/HTML-Tree/
10   * HTML::ElementTable http://search.cpan.org/dist/HTML-Element-Extended/
11   * XML::Parser http://search.cpan.org/dist/XML-Parser/
12
13 The operating system-specific instructions below will help you to
14 install these modules.
15
16 Unix instructions
17
18 If you're running a reasonably modern Linux (or other UNIX variant,
19 like MacOS X) you already have perl and wget. If so, you can install
20 the remaining modules by doing the following:
21
22  cpan install HTML::TreeBuilder
23  cpan install HTML::Element::Extended
24  cpan install XML::Parser
25
26 If you are running Debian, you can just run the following:
27
28  aptitude install wget perl libhtml-element-extended-perl libxml-parser-perl
29
30 Windows
31
32 If you are using a windows-based machine, first consider switching to
33 (or dual-booting) Debian or Ubuntu or a similar Free Software
34 distribution. If switching isn't for you, you will need to install
35 cygwin (http://www.cygwin.com/) (a linux-like environment for
36 windows), which (by default) will install perl and wget.
37
38 You can then use the cpan commands listed below to install the required
39 modules (and any needed depependencies):
40
41  cpan install HTML::TreeBuilder
42  cpan install HTML::Element::Extended
43  cpan install XML::Parser
44
45 Other Operating Systems
46
47 If you are using another operating system (minux, MacOS 9, UNIVAX,
48 Plan9, OS/2, etc.) you'll need to refer to your operating system's
49 documentation for information on how to install the required modules.
50
51
52 USAGE
53
54 All of the programs are located within the bin directory of the tarball
55 which is downloadable above. First, change directories to the bin
56 directory (cd bin.)
57
58 Then create a kewyords file which contains kewyords separated by
59 newlines. You can optionally add a weight for each keyword separated by
60 a tab. (That is, the file will contain lines of
61 'keyword<tab>0.3<newline>', for example.) You can do this in any text
62 editor that is capable of saving text files, like vim or emacs.
63
64 Finally, make a results directory (mkdir keyword_results), and run
65 function2gene with the --keywords option specifying the keywords file
66 that you have created and the --results option specifying the results
67 directory you have created (./function2gene --keywords keywords.txt
68 --results keyword_results.)
69
70 The results will be in the keyword_results directory in a file called
71 combined_results.txt, and a sumary table will be there as well, called
72 combined_results_table.txt
73
74 The details of the operation of function2gene are explained in its
75 documentation; type ./function2gene --man; to see it.
76
77 As a demonstration, you can simply do the following, which creates a
78 keywords.txt file with a single keyword, 'transferrin', and runs the
79 keywords:
80
81   cd bin;
82   echo 'transferrin' > keywords.txt
83   mkdir keyword_results;
84   ./function2gene --keywords keywords.txt --results keyword_results;
85
86 which creates a keywords file with a single keyword, transferrin, and
87 runs the various subscripts, putting the results in a keyword_results
88 directory.
89