******************* * POAVIZ Online * ******************* Package installation notes, Nov. 2003. Available at http://www.bioinformatics.ucla.edu/poa (the POA website). I. INTRODUCTION ------------------ The POAVIZ Online package consists of several modules. The POAVIZ program, which is written in C, takes a multiple sequence alignment (MSA) file in CLUSTAL, PIR, or PO format as input. It represents the MSA as a partially-ordered graph, lays out the graph in the XY-plane, and writes the layout and connectivity information of the graph to an output file. POAVIZ can be run from the command line, or using the HTML/CGI interface included with this package. The source code for POAVIZ is distributed with this package; it can also be obtained separately from the POA website. You must compile POAVIZ on your machine in order to use a local copy of POAVIZ Online. The POA program, also implemented in C, generates multiple sequence alignments from sets of unaligned sequences in FASTA format. POA can be run from the command line, or using the HTML/CGI interface included with this package. POA is recommended but not required for local operation of POAVIZ Online, since POAVIZ can visualize MSA files from other sources. The source code for POA is available on the POA website. You must obtain and compile POA on your machine in order to use it with a local copy of POAVIZ Online. Finally, the HTML/CGI component of POAVIZ Online allows you to run POAVIZ and POA using a form-based interface. It also processes the plaintext output of POAVIZ in order to generate a GIF image of a multiple sequence alignment. The files distributed with this package will allow you to run POAVIZ Online and generate visualizations locally, without having to upload files to our server. II. PACKAGE INSTALLATION / ORGANIZATION ------------------------------------------ Unpacking the tar file poaviz_online_pkg.tar should produce the file tree below. The files 'poaviz' and 'poa' in poaviz_online/DB/ are placeholders for the POAVIZ and POA binaries, which you must build on your machine. To build the POAVIZ binary: cd poaviz_src/ make poaviz Then copy the resulting binary, replacing the placeholder: cp -f ./poaviz ../poaviz_online/DB/poaviz If you also downloaded the POA package, follow analogous steps to build the POA binary and copy it to poaviz_online/DB/poa. In order to use the HTML interface, you will need to have Perl and the Perl modules strict, CGI, GD, and FindBin installed on your machine. The contents of the poaviz_online/ directory need to be made accessible to a browser (e.g. by placing the directory inside public_html/), and CGI execution of the scripts in poaviz_online/DB/ and poaviz_online/POA_Online/ must be permitted. Finally, the binaries poa and poaviz, all .cgi scripts, and the directories data/ and poa_upload_data/ should be read-/write-/executable by everyone. POAVIZ Online file tree: poaviz_src/ -- POAVIZ source code directory *.c,*.h,Makefile -- source files README.txt -- the POAVIZ readme poaviz_online/ -- POAVIZ Online root directory README.txt -- the POAVIZ Online readme (i.e. this file) poaviz_readme.txt -- the POAVIZ readme poa_upload_data/ -- MSA directory (put your MSA files here) DB/ -- CGI/config/binaries directory db_def.cgi -- configuration file image.cgi -- Perl image functions misc.cgi -- misc Perl functions seq.cgi -- Perl interface to POA and POAVIZ blosum80.mat -- matrix file for POA splice2.mat -- matrix file for POA poa -- POA binary (optional) poaviz -- POAVIZ binary (required!) POA_Online/ -- POA_Online directory index.html -- HTML frame navigation.html -- HTML navigation bar Align.cgi -- MSA Visualization software Align.html -- HTML interface to POA Visualize.cgi -- HTML interface to POAVIZ data/ -- Temporary storage directory III. COMMAND-LINE OPERATION ------------------------------ The CGI alignment/visualization script (Align.cgi) can also be called from the command line, using the syntax: Align.cgi "HTML_STYLE_OPTIONS" HTML_STYLE_OPTIONS: "option=XXXXX&option=XXXXX&option=XXXXX" No spaces are allowed, and URL encoding is required. Output images are placed in the data/ directory, with dynamically generated names. An HTML page referencing the images will be printed to standard output; and the image names are clear from this output ('xxx.gif' for the visualization, and 'xxx.INDEX.gif' for the figure key). The allowed options are described below. Some affect the operation of Align.cgi directly, while others are passed on to POAVIZ or POA. Align.cgi options: filename File name of the file to align or visualize. The file must be located in the poa_upload_data/ directory. This filter is applied to the filename: $filename=~s/[^a-zA-Z0-9\.~\/_]//g; Only files with the suffix .fasta, .po, .pir, .pov, or .clustal are allowed. Required if 'sequence' is not given. sequence Contents of the file to align or visualize. This option is ignored if 'filename' is given, and is required otherwise. format This option specifies the type of the sequence. Required. Use UNKNOWN if input is an alignment, or FASTA if input is a set of unaligned sequences. outformat Specifies the format of the output sequence. Possible options are FASTA, PO, PIR, POAVIZ, CLUSTAL, or NONE. VIZ Determines whether visualization is required. Set VIZ=Yes if visualization is desirable. HTML Possible options are Yes or No. Set to Yes to output HTML. Default is Yes. block When block is set to No, individual sequences are shown. Default is Yes. In this case, when several sequences align to each other, they are shown as a red block. Optional. POAVIZ options (OPTIONAL): start_node Starting position of the aligned sequences to visualize. Defaults to first node. "start_node=10" end_node Ending position of the aligned sequences to visualize. Defaults to last node. "end_node=1000" show_consensus Show only consensus sequences (sequences whose names start with 'CONSENS'); useful for alignments generated with POA. "show_consensus=Yes" show_seqs Show only the sequences in the given comma- delimited list, in the specified order. "show_seqs=0,1,4,6" hier_order Visually order sequences on the basis of sequence similarity, using hierarchical clustering. "hier_order=Yes" show_bundle Show only the sequences from a particular bundle. Only applies to alignments in PO format. "show_bundle=1" smooth Smooth the visualization image, showing only features with more than the specified number of residues. "smooth=3" main_line Force a particular sequence to be straight. "main_line=0" POA options (OPTIONAL): to_aas Interpret all residues as amino acids. to_nucs Interpret all residues as nucleotides. ... default is to treat uppercase residues as amino acids and lowercase residues as nucleotides. "to_aas=Yes" hb Perform heaviest bundling. Default is no. "hb=Yes" hbmin Threshold value for heaviest bundling, if "hb=Yes" was specified. "hbmin=0.5" subset Filters PO-MSA to include only the list of sequences given in a comma delimited list. First sequence is indexed 0. No space is allowed in the list. "subset=0,5,6,8,7" remove Filters PO-MSA to exclude the list of sequences given in a comma delimited list. First sequence is indexed 0. No space is allowed in the list. "remove=1,2,3,4" best Restricts MSA output to the heaviest bundles. "best=Yes" fuse_all Aggressively fuse aligned nodes while building PO-MSA. "fuse_all=Yes" Examples: Align and visualize several sequences in a FASTA file (multidom.fasta) located in poa_upload_data/: Align.cgi "filename=multidom.fasta&format=FASTA&VIZ=Yes" Visualize a multiple sequence alignment in PO format, which is stored in poa_upload_data/koo.po: Align.cgi "filename=koo.po&format=UNKNOWN&VIZ=Yes" Align a FASTA file stored in poa_upload_data/koo.fasta, show output in CLUSTAL format: Align.cgi "filename=koo.fasta&format=FASTA&outformat=CLUSTAL" . LEGAL STUFF --------------- Copyright 2001-2003 to Christopher J. Lee. Property of the Regents of the University of California. This is free software, distributed under the GNU General Public License, as is, without warranty or guarantee of fitness for any particular purpose. You use it at your own risk, with the understanding that neither the author, nor any other person or institution, can be held responsible for any damage this software might cause.