This DESCRIPTION only documents Bio::Tools::Run::StandAloneBlast, aBioperl object for running the NCBI standAlone BLAST package. Blastitself is a large & complex program - for more information regardingBLAST, please see the BLAST documentation which accompanies the BLASTdistribution. BLAST is available from ftp://ncbi.nlm.nih.gov/blast/.A source of confusion in documenting a BLAST interface is that theterm "program" is used in - at least - three different ways in theBLAST documentation. In this DESCRIPTION, "program" will refer to theBLAST routine set by the BLAST -p parameter that can be set to blastn,blastp, tblastx etc. We will use the term Blast "executable" to referto the various different executable files that may be called - ie.blastall, blastpgp or bl2seq. In addition, there are several BLASTcapabilities, which are also referred to as "programs", and areimplemented by using specific combinations of BLAST executables,programs and parameters. They will be referred by their specificnames - eg PSIBLAST and PHIBLAST.Before running StandAloneBlast it is necessary: to install BLAST on your system, to edit set the environmental variable $BLASTDIR or your $PATH variable to point to the BLAST directory, and to ensure that users have execute privileges for the BLAST program. If the databases which will be searched by BLAST are located in the data subdirectory of the blast program directory (the default installation location), StandAloneBlast will find them; however, if the database files are located in any other location, environmental variable $BLASTDATADIR will need to be set to point to that directory.The use of the StandAloneBlast module is as follows: Initially, alocal blast "factory object" is created. The constructor may be passedan optional array of (non-default) parameters to be used by thefactory, eg:

Any parameters not explicitly set will remain as the defaults of theBLAST executable. Note each BLAST executable has somewhat differentparameters and options. See the BLAST Documentation for a descriptionor run the BLAST executable from the command line followed solely witha "-" to see a list of options and default values for that executable;eg >blastall -.BLAST parameters can be changed and/or examined at any time after thefactory has been created. The program checks that anyparameter/switch being set/read is valid. Except where specificallynoted, StandAloneBlast uses the same single-letter, case-sensitiveparameter names as the actual blast program. Currently no checks areincluded to verify that parameters are of the proper type (e.g. stringor numeric) or that their values are within the proper range.As an example, to change the value of the Blast parameter 'e' ('e' isthe parameter for expectation-value cutoff)

$expectvalue = 0.01; $factory->e($expectvalue);

Note that for improved script readibility one can modify the name ofthe (ncbi) BLAST parameters as desired as long as the initial letter (andcase) of the parameter are preserved, e.g.:

$factory->expectvalue($expectvalue);

Unfortunately, some of the BLAST parameters are not the single letter one might expect (eg "iteration round" in blastpgp is 'j'). Again one can check by using, for example:

> blastpgp -

Wublast parameters need to be complete (ie. don't truncate them to theirfirst letter), but are case-insensitive.Once the factory has been created and the appropriate parameters set,one can call one of the supported blast executables. The inputsequence(s) to these executables may be fasta file(s) as described inthe BLAST documentation.

NOTE: Use of the BPlite method has been deprecated and is no longer supported.For blastall and non-psiblast blastpgp runs, report object is a Bio::SearchIOobject, selected by the user with the parameter _READMETHOD. The leadingunderscore is needed to distinguish this option from options which are passed tothe BLAST executable. The default parser is Bio::SearchIO::blast. In any case,the "raw" blast report is also available. The filename is set by the 'outfile'parameter and has the default value of "blastreport.out".For psiblast execution in the BLAST "jumpstart" mode, the program mustbe passed (in addition to the query sequence itself) an alignmentcontaining the query sequence (in the form of a SimpleAlign object) aswell as a "mask" specifying at what residues position-specific scoringmatrices (PSSMs) are to used and at what residues default scoringmatrices (eg BLOSUM) are to be used. See psiblast documentation formore details. The mask itself is a string of 0's and 1's which is thesame length as each sequence in the alignment and has a "1" atlocations where (PSSMs) are to be used and a "0" at all otherlocations. So for example:

For more examples of syntax and use of StandAloneBlast.pm, the user isencouraged to run the scripts standaloneblast.pl in the bioperlexamples/tools directory and StandAloneBlast.t in the bioperl t/ directory.

Essentially all BLAST parameters can be set via StandAloneBlast.pm.Some of the most commonly used parameters are listed below. Allparameters have defaults and are optional except for -p in those programs thathave it. For a complete listing of settable parameters, run the relevantexecutable BLAST program with the option "-" as in blastall -Note that the input parameters (-i, -j, -input) should not be set directly byyou: this module sets them when you call one of the executable methods.Blastall

Title : executable Usage : my $exe = $blastfactory->executable('blastall'); Function: Finds the full path to the executable Returns : string representing the full path to the exe Args : [optional] name of executable to set path to [optional] boolean flag whether or not warn when exe is not found

my($self, $executable, $input1, $input2) = @_;
my($seq, $temp, $infilename1, $infilename2,$fh) ;
# If $input1 is not a reference it better be the name of a file with# the sequence/ alignment data...$self->io->_io_cleanup();
SWITCH: {unless(ref$input1){$infilename1 = (-e $input1) ? $input1 : 0 ;
last SWITCH;
}# $input may be an array of BioSeq objects...if(ref($input1) =~ /ARRAY/i){($fh,$infilename1) = $self->io->tempfile();
$temp = Bio::SeqIO->new(-fh=> $fh, -format => 'fasta');
foreach$seq(@$input1){unless($seq->isa("Bio::PrimarySeqI")){return 0;}$seq->display_id($seq->display_id);
$temp->write_seq($seq);
}close$fh;
$fh = undef;
last SWITCH;
}# $input may be a single BioSeq object...elsif($input1->isa("Bio::PrimarySeqI")){($fh,$infilename1) = $self->io->tempfile();
# just in case $input1 is taken from an alignment and has spaces (ie# deletions) indicated within it, we have to remove them - otherwise# the BLAST programs will be unhappymy$seq_string = $input1->seq();
$seq_string =~ s/\W+//g; # get rid of spaces in sequence$input1->seq($seq_string);
$temp = Bio::SeqIO->new(-fh=> $fh, '-format' => 'fasta');
$temp->write_seq($input1);
close$fh;
undef$fh;
last SWITCH;
}$infilename1 = 0; # Set error flag if you get here}unless($input2){return$infilename1; }
SWITCH2: {unless(ref$input2){$infilename2 = (-e $input2) ? $input2 : 0 ;
last SWITCH2;
}if($input2->isa("Bio::PrimarySeqI") && $executableeq'bl2seq'){($fh,$infilename2) = $self->io->tempfile();
$temp = Bio::SeqIO->new(-fh=> $fh, '-format' => 'Fasta');
$temp->write_seq($input2);
close$fh;
undef$fh;
last SWITCH2;
}# Option for using psiblast's pre-alignment "jumpstart" featureelsif($input2->isa("Bio::SimpleAlign") && $executableeq'blastpgp'){# a bit of a lie since it won't be a fasta file($fh,$infilename2) = $self->io->tempfile();
# first we retrieve the "mask" that determines which residues should# by scored according to their position and which should be scored# using the non-position-specific matricesmy@mask = split("", shift); # get mask# then we have to convert all the residues in every sequence to upper# case at the positions that we want psiblast to use position specific# scoringforeach$seq($input2->each_seq()){my@seqstringlist = split("",$seq->seq());
for(my$i = 0; $i < scalar(@mask); $i++){unless($seqstringlist[$i] =~ /[a-zA-Z]/){next}$seqstringlist[$i] = $mask[$i] ? uc$seqstringlist[$i]: lc$seqstringlist[$i] ;
}my$newseqstring = join("", @seqstringlist);
$seq->seq($newseqstring);
}# Now we need to write out the alignment to a file # in the "psi format" which psiblast is expecting$input2->map_chars('\.','-');
$temp = Bio::AlignIO->new(-fh=> $fh, '-format' => 'psi');
$temp->write_aln($input2);
close$fh;
undef$fh;
last SWITCH2;
}$infilename2 = 0; # Set error flag if you get here}return($infilename1, $infilename2);

User feedback is an integral part of the evolution of this and otherBioperl modules. Send your comments and suggestions preferably to oneof the Bioperl mailing lists. Your participation is much appreciated.

Please direct usage questions or support issues to the mailing list:bioperl-l@bioperl.orgrather than to the module maintainer directly. Many experienced and reponsive experts will be able look at the problem and quickly address it. Please include a thorough description of the problem with code and data examples if at all possible.

Title : outfile_name Usage : my $outfile = $tcoffee->outfile_name(); Function: Get/Set the name of the output file for this run (if you wanted to do something special) Returns : string Args : [optional] string to set value to