File Coverage

blib/lib/Bio/Tools/Run/StandAloneBlastPlus/BlastMethods.pm
Criterion Covered Total %
statement 24 110 21.8
branch 0 46 0.0
condition 0 12 0.0
subroutine 8 14 57.1
pod 0 5 0.0
total 32 187 17.1


line stmt bran cond sub pod time code
1             # $Id$
2             #
3             # BioPerl module for Bio::Tools::Run::StandAloneBlastPlus::BlastMethods
4             #
5             # Please direct questions and support issues to
6             #
7             # Cared for by Mark A. Jensen
8             #
9             # Copyright Mark A. Jensen
10             #
11             # You may distribute this module under the same terms as perl itself
12              
13             # POD documentation - main docs before the code
14              
15             =head1 NAME
16              
17             Bio::Tools::Run::StandAloneBlastPlus::BlastMethods - Provides BLAST methods to StandAloneBlastPlus
18              
19             =head1 SYNOPSIS
20              
21             # create a factory:
22             $fac = Bio::Tools::Run::StandAloneBlastPlus->new(
23             -db_name => 'testdb'
24             );
25             # get your results
26             $result = $fac->blastn( -query => 'query_seqs.fas',
27             -outfile => 'query.bls',
28             -method_args => [ '-num_alignments' => 10 ] );
29              
30             $result = $fac->tblastx( -query => $an_alignment_object,
31             -outfile => 'query.bls',
32             -outformat => 7 );
33             # do a bl2seq
34             $fac->bl2seq( -method => 'blastp',
35             -query => $seq_object_1,
36             -subject => $seq_object_2 );
37              
38             =head1 DESCRIPTION
39              
40             This module provides the BLAST methods (blastn, blastp, psiblast,
41             etc.) to the L object.
42              
43             =head1 USAGE
44              
45             This POD describes the use of BLAST methods against a
46             L factory object. The object
47             itself has extensive facilities for creating, formatting, and masking
48             BLAST databases; please refer to
49             L POD for these details.
50              
51             Given a C factory, such as
52              
53             $fac = Bio::Tools::Run::StandAloneBlastPlus->new(
54             -db_name => 'testdb'
55             );
56              
57             you can run the desired BLAST method directly from the factory object,
58             against the database currently attached to the factory (in the
59             example, C). C<-query> is a required argument:
60              
61             $result = $fac->blastn( -query => 'query_seqs.fas' );
62              
63             Here, C<$result> is a L object.
64              
65             Other details:
66              
67             =over
68              
69             =item * The blast output file can be named explicitly:
70              
71             $result = $fac->blastn( -query => 'query_seqs.fas',
72             -outfile => 'query.bls' );
73              
74             =item * The output format can be specified:
75              
76             $result = $fac->blastn( -query => 'query_seqs.fas',
77             -outfile => 'query.bls',
78             -outformat => 7 ); #tabular
79              
80             =item * Additional arguments to the method can be specified:
81              
82             $result = $fac->blastn( -query => 'query_seqs.fas',
83             -outfile => 'query.bls',
84             -method_args => [ '-num_alignments' => 10 ,
85             '-evalue' => 100 ]);
86              
87             =item * To get the name of the blast output file, do
88              
89             $file = $fac->blast_out;
90              
91             =item * To clean up the temp files (you must do this explicitly):
92              
93             $fac->cleanup;
94              
95             =back
96              
97             =head2 bl2seq()
98              
99             Running C is similar, but both C<-query> and C<-subject> are
100             required, and the attached database is ignored. The blast method must
101             be specified explicitly with the C<-method> parameter:
102              
103             $fac->bl2seq( -method => 'blastp',
104             -query => $seq_object_1,
105             -subject => $seq_object_2 );
106              
107             Other parameters ( C<-method_args>, C<-outfile>, and C<-outformat> ) are valid.
108              
109             =head2 Return values
110              
111             The return value is always a L
112             object on success, undef on failure.
113              
114             =head1 SEE ALSO
115              
116             L, L
117              
118             =head1 FEEDBACK
119              
120             =head2 Mailing Lists
121              
122             User feedback is an integral part of the evolution of this and other
123             Bioperl modules. Send your comments and suggestions preferably to
124             the Bioperl mailing list. Your participation is much appreciated.
125              
126             bioperl-l@bioperl.org - General discussion
127             http://bioperl.org/wiki/Mailing_lists - About the mailing lists
128              
129             =head2 Support
130              
131             Please direct usage questions or support issues to the mailing list:
132              
133             L
134              
135             rather than to the module maintainer directly. Many experienced and
136             reponsive experts will be able look at the problem and quickly
137             address it. Please include a thorough description of the problem
138             with code and data examples if at all possible.
139              
140             =head2 Reporting Bugs
141              
142             Report bugs to the Bioperl bug tracking system to help us keep track
143             of the bugs and their resolution. Bug reports can be submitted via
144             the web:
145              
146             http://redmine.open-bio.org/projects/bioperl/
147              
148             =head1 AUTHOR - Mark A. Jensen
149              
150             Email maj -at- fortinbras -dot- us
151              
152             Describe contact details here
153              
154             =head1 CONTRIBUTORS
155              
156             Additional contributors names and emails here
157              
158             =head1 APPENDIX
159              
160             The rest of the documentation details each of the object methods.
161             Internal methods are usually preceded with a _
162              
163             =cut
164              
165             # Let the code begin...
166              
167             # note: providing methods directly to the namespace...
168             package Bio::Tools::Run::StandAloneBlastPlus;
169 1     1   3 use strict;
  1         1  
  1         20  
170 1     1   3 use warnings;
  1         0  
  1         18  
171              
172 1     1   410 use Bio::SearchIO;
  1         7153  
  1         24  
173 1     1   5 use lib '../../../..';
  1         0  
  1         4  
174 1     1   626 use Bio::Tools::Run::BlastPlus;
  1         3  
  1         7  
175 1     1   21 use File::Temp;
  1         1  
  1         62  
176 1     1   4 use File::Copy;
  1         1  
  1         34  
177 1     1   3 use File::Spec;
  1         1  
  1         6  
178             our @BlastMethods = qw( blastp blastn blastx tblastn tblastx
179             psiblast rpsblast rpstblastn );
180              
181             =head2 run()
182              
183             Title : run
184             Usage :
185             Function: Query the attached database using a specified blast
186             method
187             Returns : Bio::Search::Result::BlastResult object
188             Args : key => value:
189             -method => $method [blastp|blastn|blastx|tblastx|tblastn|
190             rpsblast|psiblast|rpstblastn]
191             -query => $query_sequences (a fasta file name or BioPerl sequence
192             object or sequence collection object)
193             -outfile => $blast_report_file (optional: default creates a tempfile)
194             -outformat => $format_code (integer in [0..10], see blast+ docs)
195             -method_args => [ -key1 => $value1, ... ] (additional arguments
196             for the given method)
197              
198             =cut
199              
200             sub run {
201 0     0 0   my $self = shift;
202 0           my @args = @_;
203 0           my ($method, $query, $outfile, $outformat, $method_args) = $self->_rearrange( [qw(
204             METHOD
205             QUERY
206             OUTFILE
207             OUTFORMAT
208             METHOD_ARGS
209             )], @args);
210 0           my $ret;
211 0           my (%blast_args, %usr_args);
212            
213 0 0         unless ($method) {
214 0           $self->throw("Blast run: method not specified, use -method");
215             }
216 0 0         unless ($query) {
217 0           $self->throw("Blast run: query data required, use -query");
218             }
219 0 0         unless ($outfile) { # create a tempfile name
220 0           my $fh = File::Temp->new(TEMPLATE => 'BLOXXXXX',
221             DIR => $self->db_dir,
222             UNLINK => 0);
223 0           $outfile = $fh->filename;
224 0           $fh->close;
225 0           $self->_register_temp_for_cleanup($outfile);
226             }
227              
228 0 0         if ($outformat) {
229 0 0         unless ($outformat =~ /^"?[0-9]{1,2}/) {
230 0           $self->throw("Blast run: output format code should be integer 0-10");
231             }
232 0           $blast_args{'-outfmt'} = $outformat;
233             }
234              
235 0 0         if ($method_args) {
236 0 0         $self->throw("Blast run: method arguments must be name => value pairs") unless !(@$method_args % 2);
237 0           %usr_args = @$method_args;
238             }
239             # make db if necessary
240 0 0 0       $self->make_db unless $self->check_db or $self->is_remote or $usr_args{'-subject'} or $usr_args{'-SUBJECT'}; # no db nec if this is bl2seq...
      0        
      0        
241 0           $self->{_factory} = Bio::Tools::Run::BlastPlus->new( -command => $method );
242 0 0         if (%usr_args) {
243 0           my @avail_parms = $self->factory->available_parameters('all');
244 0           while ( my( $key, $value ) = each %usr_args ) {
245 0           $key =~ s/^-//;
246 0 0         unless (grep /^$key$/, @avail_parms) {
247 0           $self->throw("Blast run: parameter '$key' is not available for method '$method'");
248             }
249             }
250             }
251              
252             # remove a leading ./ on remote databases. Something adds that in the
253             # factory, easier to remove here.
254 0           my $db = $self->db_path;
255 0 0         if ($self->is_remote) {
256 0           $db =~ s#^\./##;
257             }
258 0           $blast_args{-db} = $db;
259 0           $blast_args{-query} = $self->_fastize($query);
260 0           $blast_args{-out} = $outfile;
261             # user arg override
262 0 0         if (%usr_args) {
263 0           $blast_args{$_} = $usr_args{$_} for keys %usr_args;
264             }
265             # override for bl2seq;
266 0 0 0       if ($blast_args{'-db'} && $blast_args{'-subject'}) {
267 0           delete $blast_args{'-db'};
268             }
269 0           $self->factory->set_parameters( %blast_args );
270 0           $self->factory->no_throw_on_crash( $self->no_throw_on_crash );
271 0           my $status = $self->_run;
272              
273 0 0         return $status unless $status;
274             # kludge to demodernize the bl2seq output
275 0 0         if ($blast_args{'-subject'}) {
276 0 0         unless (_demodernize($outfile)) {
277 0           $self->throw("Ack! demodernization failed!");
278             }
279             }
280              
281             # if here, success
282 0           for ($method) {
283 0 0         m/^(t|psi|rps|rpst)?blast[npx]?/ && do {
284 0           $ret = Bio::SearchIO->new(-file => $outfile);
285              
286 0           $self->{_blastout} = $outfile;
287 0           $self->{_results} = $ret;
288 0           $ret = $ret->next_result;
289 0           last;
290             };
291 0           do {
292 0           1; # huh?
293             };
294             }
295            
296 0           return $ret;
297             }
298              
299             =head2 bl2seq()
300              
301             Title : bl2seq
302             Usage :
303             Function: emulate bl2seq using blast+ programs
304             Returns : Bio::Search::Result::BlastResult object
305             Args : key => value
306             -method => $blast_method [blastn|blastp|blastx|
307             tblastn|tblastx]
308             -query => $query (fasta file or BioPerl sequence object
309             -subject => $subject (fasta file or BioPerl sequence object)
310             -outfile => $blast_report_file
311             -method_args => [ $key1 => $value1, ... ] (additional method
312             parameters)
313              
314             =cut
315              
316             sub bl2seq {
317 0     0 0   my $self = shift;
318 0           my @args = @_;
319 0           my ($method, $query, $subject, $outfile, $outformat, $method_args) = $self->_rearrange( [qw(
320             METHOD
321             QUERY
322             SUBJECT
323             OUTFILE
324             OUTFORMAT
325             METHOD_ARGS
326             )], @args);
327              
328 0 0         unless ($method) {
329 0           $self->throw("bl2seq: blast method not specified, use -method");
330             }
331 0 0         unless ($query) {
332 0           $self->throw("bl2seq: query data required, use -query");
333             }
334 0 0         unless ($subject) {
335 0           $self->throw("bl2seq: subject data required, use -subject");
336             }
337 0           $subject = $self->_fastize($subject);
338              
339 0           my @run_args;
340 0 0         if ($method_args) {
341 0           @run_args = @$method_args;
342             }
343 0           return $self->run( -method => $method,
344             -query => $query,
345             -outfile => $outfile,
346             -outformat => $outformat,
347             -method_args => [ @run_args, '-subject' => $subject ]
348             );
349              
350             }
351              
352             =head2 next_result()
353              
354             Title : next_result
355             Usage : $result = $fac->next_result;
356             Function: get the next BLAST result
357             Returns : Bio::Search::Result::BlastResult object
358             Args : none
359              
360             =cut
361              
362             sub next_result() {
363 0     0 0   my $self = shift;
364 0 0         return unless $self->{_results};
365 0           return $self->{_results}->next_result;
366             }
367              
368             =head2 rewind_results()
369              
370             Title : rewind_results
371             Usage : $fac->rewind_results;
372             Function: rewind BLAST results
373             Returns : true on success
374             Args :
375              
376             =cut
377              
378             sub rewind_results {
379 0     0 0   my $self = shift;
380 0 0         return unless $self->blast_out;
381 0           $self->{_results} = Bio::SearchIO->new( -file => $self->blast_out );
382 0           return 1;
383             }
384              
385              
386             =head2 blast_out()
387              
388             Title : blast_out
389             Usage : $file = $fac->blast_out
390             Function: get the filename of the blast report file
391             Returns : scalar string
392             Args : none
393              
394             =cut
395              
396 0     0 0   sub blast_out { shift->{_blastout} }
397              
398             # =head2 _demodernize()
399              
400             # Title : _demodernize
401             # Usage :
402             # Function: Ha! Wouldn't you like to know!
403             # Returns :
404             # Args :
405              
406             # =cut
407              
408             sub _demodernize {
409 0     0     my $file = shift;
410 0           my $tf = File::Temp->new();
411 0           open (my $f, $file);
412 0           while (<$f>) {
413 0           s/^Subject=\s+/>/;
414 0           print $tf $_;
415             }
416 0           $tf->close;
417 0           copy($tf->filename, $file);
418             }
419             1;