wu-lab-uva / AMPHORA2

AMPHORA2 User Manual


An Automated Phylogenomic Inference Pipeline for Bacterial and Archaeal Sequences. 

COPYRIGHT 
2011 by Martin Wu
 
AMPHORA2 is free software: you may redistribute it and/or modify its under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or any later version.

AMPHORA2 is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details (http://www.gnu.org/licenses/).

For any other inquiries send an Email to Martin Wu: [email protected]
 

CITATION
When publishing work that is based on the results from AMPHORA2 please cite:
Wu M, Scott AJ. Phylogenomic analysis of bacterial and archaeal sequences with AMPHORA2. Bioinformatics 2012; 28(7):1033-1034.

 
DEPENDENCY
AMPHORA2 depends on several external programs.

1.	HMMER3 (http://hmmer.janelia.org/). Required for marker identification, sequence alignment and trimming. Earlier versions of HMMER will not work!
2.	RAxML version 7.3.0 or later (https://github.com/stamatak/standard-RAxML/downloads). Required for phylotyping.
3.	Bioperl 1.5.2 or later (http://www.bioperl.org/wiki/Getting_BioPerl).
4.	EMBOSS (http://emboss.sourceforge.net/download/). The 'getorf' program of the EMBOSS package is required only if you analyze DNA sequences using AMPHORA2

Make sure that these programs are installed and are in your system's executable search path. To test, in a terminal type

	raxmlHPC -version
	raxmlHPC-PTHREADS -version
	hmmsearch -h
	hmmalign -h
	getorf -help

If you see version or help messages, then these programs have been correctly installed. It is important to make sure they are the correct versions. 

A script named 'preinstall.pl' is also included with AMPHORA2 to check and install the dependencies automatically. You need the privilege of the system administrator to run the script. See below for instructions.
 	

INSTALLATION

1.Download AMPHORA2
2.Unpack AMPHORA2 
	tar -zxvf AMPHORA2.tar.gz
3.Install dependencies if they have not been installed
	cd AMPHORA2
	sudo perl preinstall.pl
4.Setup AMPHORA2. 
You need to set up the environment variable 'AMPHORA2_home' so the AMPHORA2 scripts know where to look for the phylogenetic marker database and the NCBI taxonomy information. Let's suppose your unpacked AMPHORA folder is at /home/foo/AMPHORA2. 
		
If you are using a bash shell, you can add the following lines to the end of the file ~/.bashrc

		export AMPHORA2_home=/home/foo/AMPHORA2

Then in the terminal, issue this command

		source ~/.bashrc
		
If you are using a C shell, you can add the following lines to the end of the file ~/.tcshrc. 

		setenv AMPHORA2_home /home/foo/AMPHORA2

Then in the terminal, issue this command

		source ~/.tcshrc

5.Make the AMPHORA2 scripts executable.   

		chmod +x /home/foo/AMPHORA2/Scripts/*

You should see five folders.

1. Marker 
This folder contains a seed alignment file in Stockholm format (*.stock), an alignment mask file (*.mask), a profile HMM file (*HMM) and a tree file in newick format (*.tre) for each marker gene.

For more information about the phylogenetic markers that are included in AMPHORA2, see the marker.list file in the Marker folder.

2. Scripts
This folder contains the scripts for marker identification, alignment, trimming and phylotyping.

3. Taxonomy
This folder contains the NCBI taxonomy database that is used by the Phylotyping.pl script for phylotyping.

4. Tree
This folder contains the bacterial and arachaeal genome trees in newick format. The genome trees are RAxML maximum likelihood trees made from concatenated protein sequences.

5. TestData
This folder contains the E. coli genome assembly (ecoli.fasta) and proteome sequences (ecoli.pep) for testing AMPHORA2.





RUNNING AMPHORA2

1. Marker identification
Use MarkerScanner.pl to identify bacterial and/or archaeal marker sequences. Given a sequence file, this program will identify markers from the input sequences and generate a protein fasta file for each marker gene in your working directory. For example, rpoB.pep, rpsJ.pep. When DNA input sequences are used, this program first identifies ORFs longer than 100 bp in all six reading frames, then scans the translated peptide sequences for the phylogenetic markers.

	perl MarkerScanner.pl sequence-file

Options:
	-DNA: input sequences are DNA. Default: no.
	-Evalue: HMMER evalue cutoff. Default: 1e-3 
	-Bacteria: input sequences are Bacterial sequences
	-Archaea: input sequences are Archaeal sequences
	-ReferenceDirectory: the file directory that contain the reference alignments, hmms and masks. Default: /home/foo/AMPHORA2/Marker
	-Help: print help	

Example:
1a. Identify phylogenetic markers from the E. coli proteome. 

	perl MarkerScanner.pl –Bacteria TestData/ecoli.pep

1b. Identify phylogenetic markers from the E. coli genome assembly
	
	perl MarkerScanner.pl -Bacteria -DNA TestData/ecoli.fasta

If AMPHORA2 has been installed correctly, at the end of the run for example 1a or 1b, you should see 31 marker protein sequences (*.pep) in your working directory.

1c. If you want to identify phylogenetic markers from metagenomic sequence reads (e.g., 454 reads) of a mixed bacterial and archaeal population,

	perl MarkerScanner.pl -DNA metagenomic.fasta

However, if you know your input sequences only contain bacterial or archaeal sequences, then use the -Bacterial or -Archaeal option. This makes the AMPHORA2 run faster and the results will be more accurate. 

2. Marker sequence alignment and trimming
This program will align, mask and trim the marker protein sequences. Output will be aligned/trimmed sequences. For example, rpoB.aln, rpsJ.aln and their corresponding alignment masks. The alignment masks can be used to weigh the alignment columns with the RAxML's -a option (for untrimmed alignment only).

	perl  MarkerAlignTrim.pl

Options:
	-Trim:	trim the alignment using masks embedded with the marker database. Default: no
	-Cutoff: the Zorro masking confidence cutoff value (0 - 1.0; default: 0.4);
	-ReferenceDirectory: the file directory that contain the reference alignments, hmms and masks. Default: /home/foo/AMPHORA2/Marker
	-Directory: the file directory where sequences to be aligned are located. Default: current directory
	-OutputFormat: output alignment format. Default: phylip. Other supported formats include: fasta, stockholm, selex, clustal
	-WithReference: keep the reference sequences in the alignment. Default: no
	-Help:	print help 

Example:

	perl MarkerAlignTrim.pl -WithReference -OutputFormat phylip

If AMPHORA2 has been installed correctly, at the end of the run, you should see an alignment file (*.aln) and a mask file (*.mask) for each of the 31 ecoli marker proteins in your working directory.

It is important to know that in order to run the Phylotyping.pl script properly, the MarkerAlignTrimp.pl needs to be run using  '-WithReference -OutputFormat phylip' options.

3. Phylotyping
Use Phylotyping.pl to assign phylotypes for each identified marker sequences. This program will assign each identified marker sequence a phylotype using parsimony method or the evolutionary placement algorithm of RAxML. The marker sequences need to be aligned first with the reference sequences using MarkerAlignTrim.pl (see above). The alignments should be in the phylip format. 

	perl Phylotyping.pl

Options:
	-Method: use 'maximum likelihood' (ml) or 'maximum parsimony' (mp) for phylotyping. Default: ml
	-CPUs: turn on the multiple thread option and specify the number of CPUs/cores to use. Important: Make sure raxmlHPC-PTHREADs is installed. If the number specified here is larger than the number of cores that are free and available, it will actually slow down the script.
	-Help: print help;  

Example: 
assign phylotypes using the maximum likelihood method

	perl Phylotyping.pl -CPUs 6 > phylotype.result

Again, if AMPHORA2 is installed correctly, you should see something like this as the output:

Query   Marker	Superkingdom    Phylum  Class   Order   Family  Genus   Species
NP_417776-NC_000913     rplB    Bacteria(0.96)  Proteobacteria(0.96)    Gammaproteobacteria(0.96)       Enterobacteriales(0.96) Enterobacteriaceae(0.96)        Escherichia(0.50)       Escherichia coli(0.48)
NP_417097-NC_000913     rplS    Bacteria(0.96)  Proteobacteria(0.96)    Gammaproteobacteria(0.96)       Enterobacteriales(0.96) Enterobacteriaceae(0.96)        Escherichia(0.80)       Escherichia coli(0.80)
NP_414711-NC_000913     rpsB    Bacteria(0.96)  Proteobacteria(0.96)    Gammaproteobacteria(0.96)       Enterobacteriales(0.96) Enterobacteriaceae(0.96)        Escherichia(0.80)       Escherichia coli(0.78)


The phylotyping results are tab-delimited. The numbers within the parentheses are the confidence scores of the assignment. 

If you see the following error message when you run Phylotyping.pl, you can delete the 'name2id' file in the folder AMPHORA2_home/Taxonomy/ and run the script again.

------------- EXCEPTION: Bio::Root::Exception -------------
MSG: No such file or directory AMPHORA2_home/Taxonomy/names2id
STACK: Error::throw
STACK: Bio::Root::Root::throw /lib/site_perl/5.16.3/Bio/Root/Root.pm:368
STACK: Bio::DB::Taxonomy::flatfile::_db_connect /lib/site_perl/5.16.3/Bio/DB/Taxonomy/flatfile.pm:463
STACK: Bio::DB::Taxonomy::flatfile::new /lib/site_perl/5.16.3/Bio/DB/Taxonomy/flatfile.pm:144
STACK: Bio::DB::Taxonomy::new /lib/site_perl/5.16.3/Bio/DB/Taxonomy.pm:116
STACK: AMPHORA2_home/Scripts/Phylotyping.pl:58

KNOWN ISSUES

Bioperl
AMPHORA2 has been tested on Bioperl 1.6.1. People have reported problems running AMPHORA2 on Bioperl 1.6.9. For example, the following error has been reported when running Phylotyping.pl:

------------- EXCEPTION: Bio::Root::Exception -------------
MSG: parse error: expected ; or ) or ,

STACK: Error::throw
STACK: Bio::Root::Root::throw 
/usr/local/share/perl/5.14.2/Bio/Root/Root.pm:472
STACK: Bio::TreeIO::NewickParser::parse_newick 
/usr/local/share/perl/5.14.2/Bio/TreeIO/NewickParser.pm:195
STACK: Bio::TreeIO::newick::next_tree 
/usr/local/share/perl/5.14.2/Bio/TreeIO/newick.pm:143
STACK: main::assign_phylotype 
/usr/local/Bioinf/AMPHORA2/Scripts/Phylotyping.pl:154
STACK: /usr/local/Bioinf/AMPHORA2/Scripts/Phylotyping.pl:70

This is because Bioperl module Bio::TreeIO::NewickParser.pm in 1.6.9 is unable to parse the RAxML output. To solve the problem, you can either downgrade Bioperl from 1.6.9 to 1.6.1 or modify the module as suggested by Bill Nelson (http://wcnjournalclub.blogspot.com/2014/02/getting-amphora2-to-work-with-bioperl.html).