File Coverage

blib/lib/Bio/Tools/Run/Phylo/QuickTree.pm
Criterion Covered Total %
statement 23 77 29.8
branch 3 32 9.3
condition 0 11 0.0
subroutine 7 14 50.0
pod 7 7 100.0
total 40 141 28.3


line stmt bran cond sub pod time code
1             #
2             # BioPerl module for Bio::Tools::Run::Phylo::QuickTree
3             #
4             # Please direct questions and support issues to
5             #
6             # Cared for by Sendu Bala
7             #
8             # Copyright Sendu Bala
9             #
10             # You may distribute this module under the same terms as perl itself
11              
12             # POD documentation - main docs before the code
13              
14             =head1 NAME
15              
16             Bio::Tools::Run::Phylo::QuickTree - Wrapper for rapid reconstruction of
17             phylogenies using QuickTree
18              
19             =head1 SYNOPSIS
20              
21             use Bio::Tools::Run::Phylo::QuickTree;
22              
23             # Make a QuickTree factory
24             @params = ();
25             $factory = Bio::Tools::Run::Phylo::QuickTree->new(@params);
26              
27             # Pass the factory an alignment
28             $inputfilename = 't/data/cysprot.stockholm';
29             $tree = $factory->run($inputfilename); # $tree is a Bio::Tree::Tree object.
30             # or get a Bio::Align::AlignI (SimpleAlign) object from somewhere
31             $tree = $factory->run($aln);
32              
33             =head1 DESCRIPTION
34              
35             This is a wrapper for running the QuickTree application by Kevin Howe. You
36             can download it here: http://www.sanger.ac.uk/Software/analysis/quicktree/
37              
38             Currently only input with alignments and output of trees is supported. (Ie.
39             no support for distance matrix in/out.)
40              
41             You will need to enable this QuickTree wrapper to find the quicktree program.
42             This can be done in (at least) three ways:
43              
44             1. Make sure the QuickTree executable is in your path.
45             2. Define an environmental variable QUICKTREEDIR which is a
46             directory which contains the 'quicktree' application:
47             In bash:
48              
49             export QUICKTREEDIR=/home/username/quicktree_1.1/bin
50              
51             In csh/tcsh:
52              
53             setenv QUICKTREEDIR /home/username/quicktree_1.1/bin
54              
55             3. Include a definition of an environmental variable QUICKTREEDIR in
56             every script that will use this QuickTree wrapper module, e.g.:
57              
58             BEGIN { $ENV{QUICKTREEDIR} = '/home/username/quicktree_1.1/bin' }
59             use Bio::Tools::Run::Phylo::QuickTree;
60              
61             =head1 FEEDBACK
62              
63             =head2 Mailing Lists
64              
65             User feedback is an integral part of the evolution of this and other
66             Bioperl modules. Send your comments and suggestions preferably to
67             the Bioperl mailing list. Your participation is much appreciated.
68              
69             bioperl-l@bioperl.org - General discussion
70             http://bioperl.org/wiki/Mailing_lists - About the mailing lists
71              
72             =head2 Support
73              
74             Please direct usage questions or support issues to the mailing list:
75              
76             I
77              
78             rather than to the module maintainer directly. Many experienced and
79             reponsive experts will be able look at the problem and quickly
80             address it. Please include a thorough description of the problem
81             with code and data examples if at all possible.
82              
83             =head2 Reporting Bugs
84              
85             Report bugs to the Bioperl bug tracking system to help us keep track
86             of the bugs and their resolution. Bug reports can be submitted via
87             the web:
88              
89             http://redmine.open-bio.org/projects/bioperl/
90              
91             =head1 AUTHOR - Sendu Bala
92              
93             Email bix@sendu.me.uk
94              
95             =head1 APPENDIX
96              
97             The rest of the documentation details each of the object methods.
98             Internal methods are usually preceded with a _
99              
100             =cut
101              
102             package Bio::Tools::Run::Phylo::QuickTree;
103 1     1   105092 use strict;
  1         2  
  1         23  
104              
105 1     1   458 use Bio::AlignIO;
  1         87604  
  1         25  
106 1     1   377 use Bio::TreeIO;
  1         13923  
  1         38  
107              
108 1     1   7 use base qw(Bio::Tools::Run::WrapperBase);
  1         1  
  1         411  
109              
110             our $PROGRAM_NAME = 'quicktree';
111             our $PROGRAM_DIR = $ENV{'QUICKTREEDIR'};
112              
113             =head2 program_name
114              
115             Title : program_name
116             Usage : $factory>program_name()
117             Function: holds the program name
118             Returns : string
119             Args : None
120              
121             =cut
122              
123             sub program_name {
124 7     7 1 27 return $PROGRAM_NAME;
125             }
126              
127             =head2 program_dir
128              
129             Title : program_dir
130             Usage : $factory->program_dir(@params)
131             Function: returns the program directory, obtained from ENV variable.
132             Returns : string
133             Args : None
134              
135             =cut
136              
137             sub program_dir {
138 4     4 1 336 return $PROGRAM_DIR;
139             }
140              
141             =head2 new
142              
143             Title : new
144             Usage : $factory = Bio::Tools::Run::Phylo::QuickTree->new(@params)
145             Function: creates a new QuickTree factory
146             Returns : Bio::Tools::Run::Phylo::QuickTree
147             Args : Optionally, provide any of the following (default in []):
148             -upgma => boolean # Use the UPGMA method to construct the tree [0]
149             -kimura => boolean # Use the kimura translation for pairwise
150             # distances [0]
151             -boot => int # Calculate bootstrap values with n iterations [0]
152              
153             =cut
154              
155             sub new {
156 1     1 1 664 my ($class, @args) = @_;
157 1         12 my $self = $class->SUPER::new(@args);
158            
159             # for consistency with other run modules, allow params to be dashless
160 1         8 my %args = @args;
161 1         6 while (my ($key, $val) = each %args) {
162 0 0       0 if ($key !~ /^-/) {
163 0         0 delete $args{$key};
164 0         0 $args{'-'.$key} = $val;
165             }
166             }
167            
168 1         9 my ($upgma, $kimura, $boot) = $self->_rearrange([qw(UPGMA
169             KIMURA
170             BOOT)], %args);
171            
172 1 50       7 $self->upgma(1) if $upgma;
173 1 50       4 $self->kimura(1) if $kimura;
174 1 50       2 $self->boot($boot) if $boot;
175            
176 1         3 return $self;
177             }
178              
179             =head2 upgma
180              
181             Title : upgma
182             Usage : $factory->upgma(1);
183             Function: Choose to use the UPGMA method to construct the tree.
184             Returns : boolean (default 0)
185             Args : None to get, boolean to set.
186              
187             =cut
188              
189             sub upgma {
190 0     0 1   my ($self, $bool) = @_;
191 0 0         if (defined ($bool)) {
192 0           $self->{upgma} = $bool;
193             }
194 0   0       return $self->{upgma} || 0;
195             }
196              
197             =head2 kimura
198              
199             Title : kimura
200             Usage : $factory->kimura(1);
201             Function: Choose to use the kimura translation for pairwise distances.
202             Returns : boolean (default 0)
203             Args : None to get, boolean to set.
204              
205             =cut
206              
207             sub kimura {
208 0     0 1   my ($self, $bool) = @_;
209 0 0         if (defined ($bool)) {
210 0           $self->{kimura} = $bool;
211             }
212 0   0       return $self->{kimura} || 0;
213             }
214              
215             =head2 boot
216              
217             Title : boot
218             Usage : $factory->boot(100);
219             Function: Choose to calculate bootstrap values with the supplied number of
220             iterations.
221             Returns : int (default 0)
222             Args : None to get, int to set.
223              
224             =cut
225              
226             sub boot {
227 0     0 1   my ($self, $int) = @_;
228 0 0         if (defined ($int)) {
229 0           $self->{boot} = $int;
230             }
231 0   0       return $self->{boot} || 0;
232             }
233              
234             =head2 run
235              
236             Title : run
237             Usage : $factory->run($stockholm_file);
238             $factory->run($align_object);
239             Function: Runs QuickTree to generate a tree
240             Returns : Bio::Tree::Tree object
241             Args : file name for your input alignment in stockholm format, OR
242             Bio::Align::AlignI compliant object (eg. Bio::SimpleAlign).
243              
244             =cut
245              
246             sub run {
247 0     0 1   my ($self, $in) = @_;
248              
249 0 0 0       if (ref $in && $in->isa("Bio::Align::AlignI")) {
    0          
250 0           $in = $self->_writeAlignFile($in);
251             }
252             elsif (! -e $in) {
253 0           $self->throw("When not supplying a Bio::Align::AlignI object, you must supply a readable filename");
254             }
255            
256 0           return $self->_run($in);
257             }
258              
259             sub _run {
260 0     0     my ($self, $file)= @_;
261            
262 0   0       my $exe = $self->executable || return;
263 0           my $param_str = $self->arguments." ".$self->_setparams;
264 0           my $command = $exe." $param_str ".$file;
265            
266 0           $self->debug("QuickTree command = $command");
267            
268 0 0         open(my $result, "$command |") || $self->throw("QuickTree call ($command) crashed: $?");
269 0           my $treeio = Bio::TreeIO->new(-format => 'nhx', -fh => $result);
270 0           my $tree = $treeio->next_tree;
271 0           close($result);
272            
273             # if bootstraps were enabled, the bootstraps are the ids; convert to
274             # bootstrap and no id
275 0 0         if ($self->boot) {
276 0           my @nodes = $tree->get_nodes;
277 0           my %non_internal = map { $_ => 1 } ($tree->get_leaf_nodes, $tree->get_root_node);
  0            
278 0           foreach my $node (@nodes) {
279 0 0         next if exists $non_internal{$node};
280 0 0         $node->bootstrap && next; # protect ourselves incase the parser improves
281 0           $node->bootstrap($node->id);
282 0           $node->id('');
283             }
284             }
285            
286 0           return $tree;
287             }
288              
289             =head2 _setparams
290              
291             Title : _setparams
292             Usage : Internal function, not to be called directly
293             Function: Creates a string of params to be used in the command string
294             Returns : string of params
295             Args : none
296              
297             =cut
298              
299             sub _setparams {
300 0     0     my $self = shift;
301 0           my $param_string = '-in a -out t';
302            
303 0 0         $param_string .= ' -upgma' if $self->upgma;
304 0 0         $param_string .= ' -kimura' if $self->kimura;
305 0 0         $param_string .= ' -boot '.$self->boot if $self->boot;
306            
307 0           return $param_string;
308             }
309              
310             =head2 _writeAlignFile
311              
312             Title : _writeAlignFile
313             Usage : obj->_writeAlignFile($seq)
314             Function: Internal(not to be used directly)
315             Returns : filename
316             Args : Bio::Align::AlignI
317              
318             =cut
319              
320             sub _writeAlignFile{
321 0     0     my ($self, $align) = @_;
322            
323 0           my ($tfh, $tempfile) = $self->io->tempfile(-dir=>$self->tempdir);
324            
325 0           my $out = Bio::AlignIO->new('-fh' => $tfh,
326             '-format' => 'stockholm');
327 0           $out->write_aln($align);
328 0           $out->close();
329 0           $out = undef;
330 0           close($tfh);
331 0           undef $tfh;
332 0           return $tempfile;
333             }
334              
335             1;