Provided by: libbio-perl-run-perl_1.7.3-9_all bug

NAME

       Bio::Tools::Run::StandAloneBlastPlus - Compute with NCBI's blast+ suite *ALPHA*

SYNOPSIS

       NOTE: This module is related to the Bio::Tools::Run::StandAloneBlast system in name (and
       inspiration) only. You must use this module directly.

        # existing blastdb:
        $fac = Bio::Tools::Run::StandAloneBlastPlus->new(
          -db_name => 'mydb'
        );

        # create blastdb from fasta file and attach
        $fac = Bio::Tools::Run::StandAloneBlastPlus->new(
          -db_name => 'mydb',
          -db_data => 'myseqs.fas',
          -create => 1
        );

        # create blastdb from BioPerl sequence collection objects
        $alnio = Bio::AlignIO->new( -file => 'alignment.msf' );
        $fac = Bio::Tools::Run::StandAloneBlastPlus->new(
          -db_name => 'mydb',
          -db_data => $alnio,
          -create => 1
        );

        @seqs = $alnio->next_aln->each_seq;
        $fac = Bio::Tools::Run::StandAloneBlastPlus->new(
          -db_name => 'mydb',
          -db_data => \@seqs,
          -create => 1
        );

        # create database with masks

        $fac = Bio::Tools::Run::StandAloneBlastPlus->new(
         -db_name => 'my_masked_db',
         -db_data => 'myseqs.fas',
         -masker => 'dustmasker',
         -mask_data => 'maskseqs.fas',
         -create => 1
        );

        # create a mask datafile separately
        $mask_file = $fac->make_mask(
          -data => 'maskseqs.fas',
          -masker => 'dustmasker'
        );

        # query database for metadata
        $info_hash = $fac->db_info;
        $num_seq = $fac->db_num_sequences;
        @mask_metadata = @{ $fac->db_filter_algorithms };

        # perform blast methods
        $result = $fac->tblastn( -query => $seqio );
        # see Bio::Tools::Run::StandAloneBlastPlus::BlastMethods
        # for many more details

DESCRIPTION

       NOTE: This module requires BLAST+ v. 2.2.24+ and higher.  Until the API stabilizes for
       BLAST+, consider this module highly experimental.

       This module along with Bio::Tools::Run::StandAloneBlastPlus::BlastMethods allows the user
       to perform BLAST functions using the external program suite "blast+" (available at
       <ftp://ftp.ncbi.nlm.nih.gov/blast/executables/blast+/LATEST/>), using BioPerl objects and
       Bio::SearchIO facilities. This wrapper can prepare BLAST databases as well as run BLAST
       searches. It can also be used to run "blast+" programs independently.

       This module encapsulates object construction and production of databases and masks. Blast
       analysis methods ("blastp, psiblast", etc>) are contained in
       Bio::Tools::Run::StandAloneBlastPlus::BlastMethods.

USAGE

       The basic mantra is to (1) create a BlastPlus factory using the "new()" constructor, and
       (2) perform BLAST analyses by calling the desired BLAST program by name off the factory
       object. The blast database itself and any masking data are attached to the factory object
       (step 1). Query sequences and any parameters associated with particular programs are
       provided to the blast method call (step 2), and are run against the attached database.

   Factory construction/initialization
       The factory needs to be told where the blast+ programs live. The "BLASTPLUSDIR"
       environment variable will be checked for the default executable directory.  The program
       directory can be set for individual factory instances with the "PROG_DIR" parameter. All
       the blast+ programs must be accessible from that directory (i.e., as executable files or
       symlinks).

       Either the database or BLAST subject data must be specified at object construction.
       Databases can be pre-existing formatted BLAST dbs, or can be built directly from fasta
       sequence files or BioPerl sequence object collections of several kinds. The key
       constructor parameters are "DB_NAME", "DB_DATA", "DB_DIR".

       To specify a pre-existing BLAST database, use "DB_NAME" alone:

        $fac = Bio::Tools::Run::StandAloneBlastPlus->new(
            -DB_NAME => 'mydb'
        );

       The directory can be specified along with the basename, or separately with "DB_DIR":

        $fac = Bio::Tools::Run::StandAloneBlastPlus->new(
            -DB_NAME => '~/home/blast/mydb'
        );

        #same as

        $fac = Bio::Tools::Run::StandAloneBlastPlus->new(
            -DB_NAME => 'mydb', -DB_DIR => '~/home/blast'
        );

       To create a BLAST database de novo, see "Creating a BLAST database".

       If you wish to apply pre-existing mask data (i.e., the final ASN1 output from one of the
       blast+ masker programs), to the database before querying, specify it with "MASK_FILE":

        $fac = Bio::Tools::Run::StandAloneBlastPlus->new(
            -DB_NAME => 'mydb', -MASK_FILE => 'mymaskdata.asn'
        );

   Creating a BLAST database
       There are several options for creating the database de novo using attached data, both
       before and after factory construction. If a temporary database (one that can be deleted by
       the "cleanup()" method) is desired, leave out the "-db_name" parameter. If "-db_name" is
       specified, the database will be preserved with the basename specified.

       Use "-create =" 1> to create a new database (otherwise the factory will look for an
       existing database). Use "-overwrite =" 1> to create and overwrite an existing database.

       Note that the database is not created immediately on factory construction. It will be
       created if necessary on the first use of a factory BLAST method, or you can force database
       creation by executing

        $fac->make_db();

       •   Specify data during construction

           With a FASTA file:

            $fac = Bio::Tools::Run::StandAloneBlastPlus->new(
              -db_name => 'mydb',
              -db_data => 'myseqs.fas',
              -create => 1
            );

           With another BioPerl object collection:

            $alnio = Bio::AlignIO->new( -file => 'alignment.msf' );
            $fac = Bio::Tools::Run::StandAloneBlastPlus->new(
              -db_name => 'mydb',
              -db_data => $alnio,
              -create => 1
            );
            @seqs = $alnio->next_aln->each_seq;
            $fac = Bio::Tools::Run::StandAloneBlastPlus->new(
              -db_name => 'mydb',
              -db_data => \@seqs,
              -create => 1
            );

           Other collections (e.g., Bio::SeqIO) are valid. If a certain type does not work,
           please submit an enhancement request.

           To create temporary databases, leave out the "-db_name", e.g.

            $fac = Bio::Tools::Run::StandAloneBlastPlus->new(
              -db_data => 'myseqs.fas',
              -create => 1
            );

           To get the tempfile basename, do:

            $dbname = $fac->db;

       •   Specify data post-construction

           Use the explicit attribute setters:

            $fac = Bio::Tools::Run::StandAloneBlastPlus->new(
              -create => 1
            );

            $fac->set_db_data('myseqs.fas');
            $fac->make_db;

   Creating and using mask data
       The blast+ mask utilities "windowmasker", "segmasker", and "dustmasker" are available.
       Masking can be rolled into database creation, or can be executed later. If your mask data
       is already created and in ASN1 format, set the "-mask_file" attribute on construction (see
       "Factory constuction/initialization").

       To create a mask from raw data or an existing database and apply the mask upon database
       creation, construct the factory like so:

        $fac = Bio::Tools::Run::StandAloneBlastPlus->new(
          -db_name => 'my_masked_db',
          -db_data => 'myseqs.fas',
          -masker => 'dustmasker',
          -mask_data => 'maskseqs.fas',
          -create => 1
        );

       The masked database will be created during "make_db".

       The "-mask_data" parameter can be a FASTA filename or any BioPerl sequence object
       collection. If the datatype ('nucl' or 'prot') of the mask data is not compatible with the
       selected masker, an exception will be thrown with a message to that effect.

       To create a mask ASN1 file that can be used in the "-mask_file" parameter separately from
       the attached database, use the "make_mask()" method directly:

        $mask_file = $fac->make_mask(-data => 'maskseqs.fas',
                                     -masker => 'dustmasker');
        # segmasker can use a blastdb as input
        $mask_file = $fac->make_mask(-mask_db => 'mydb',
                                     -masker => 'segmasker')

        $fac = Bio::Tools::Run::StandAloneBlastPlus->new(
          -db_name => 'my_masked_db',
          -db_data => 'myseqs.fas',
          -mask_file => $mask_file
          -create => 1
        );

   Getting database information
       To get a hash containing useful metadata on an existing database (obtained by running
       "blastdbcmd -info", use "db_info()":

        # get info on the attached database..
        $info = $fac->db_info;
        # get info on another database
        $info = $fac->db_info('~/home/blastdbs/another');

       To get a particular info element for the attached database, just call the element name off
       the factory:

        $num_seqs = $fac->db_num_sequences;
        # info on all the masks applied to the db, if any:
        @masking_info = @{ $fac->db_filter_algorithms };

   Accessing the Bio::Tools::Run::BlastPlus factory
       The blast+ programs are actually executed by a Bio::Tools::Run::BlastPlus wrapper
       instance. This instance is available for peeking and poking in the StandAloneBlastPlus
       "factory()" attribute. For convenience, "BlastPlus" methods can be run from the
       "StandAloneBlastPlus" object, and are delegated to the "factory()" attribute. For example,
       to get the blast+ program to be executed, examine either

        $fac->factory->command

       or

        $fac->command

       Similarly, the current parameters for the "BlastPlus" factory are

        @parameters = $fac->get_parameters

   Cleaning up temp files
       Temporary analysis files produced under a single factory instances can be unlinked by
       running

        $fac->cleanup;

       Tempfiles are generally not removed unless this method is explicitly called. "cleanup()"
       only unlinks "registered" files and databases. All temporary files are automatically
       registered; in particular, "anonymous" databases (such as

        $fac->Bio::Tools::Run::StandAloneBlastPlus->new(
          -db_data => 'myseqs.fas',
          -create => 1
        );

       without a "-db_name" specification) are registered for cleanup. Any file or database can
       be registered with an internal method:

        $fac->_register_temp_for_cleanup('testdb');

   Other Goodies
       •   You can check whether a given basename points to a properly formatted BLAST database
           by doing

            $is_good = $fac->check_db('putative_db');

       •   User parameters can be passed to the underlying blast+ programs (if you know what
           you're doing) with "db_make_args" and "mask_make_args":

            $fac = Bio::Tools::Run::StandAloneBlastPlus->new(
              -db_name => 'customdb',
              -db_data => 'myseqs.fas',
              -db_make_args => [ '-taxid_map' => 'seq_to_taxa.txt' ],
              -masker => 'windowmasker',
              -mask_data => 'myseqs.fas',
              -mask_make_args => [ '-dust' => 'T' ],
              -create => 1
            );

       •   You can prevent exceptions from being thrown by failed blast+ program executions by
           setting "no_throw_on_crash". Examine the error with "stderr()":

            $fac->no_throw_on_crash(1);
            $fac->make_db;
            if ($fac->stderr =~ /Error:/) {
               #handle error
               ...
            }

SEE ALSO

       Bio::Tools::Run::StandAloneBlastPlus::BlastMethods, Bio::Tools::Run::BlastPlus

FEEDBACK

   Mailing Lists
       User feedback is an integral part of the evolution of this and other Bioperl modules. Send
       your comments and suggestions preferably to the Bioperl mailing list.  Your participation
       is much appreciated.

         bioperl-l@bioperl.org                  - General discussion
       http://bioperl.org/wiki/Mailing_lists  - About the mailing lists

   Support
       Please direct usage questions or support issues to the mailing list:

       bioperl-l@bioperl.org

       rather 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.

   Reporting Bugs
       Report bugs to the Bioperl bug tracking system to help us keep track of the bugs and their
       resolution. Bug reports can be submitted via the web:

         http://redmine.open-bio.org/projects/bioperl/

AUTHOR - Mark A. Jensen

       Email maj -at- fortinbras -dot- us

CONTRIBUTORS

APPENDIX

       The rest of the documentation details each of the object methods.  Internal methods are
       usually preceded with a _

   new
        Title   : new
        Usage   : my $obj = new Bio::Tools::Run::StandAloneBlastPlus();
        Function: Builds a new Bio::Tools::Run::StandAloneBlastPlus object
        Returns : an instance of Bio::Tools::Run::StandAloneBlastPlus
        Args    : named argument (key => value) pairs:
                  -db : blastdb name

   db()
        Title   : db
        Usage   : $obj->db($newval)
        Function: contains the basename of the local blast database
        Example :
        Returns : value of db (a scalar string)
        Args    : readonly

   factory()
        Title   : factory
        Usage   : $obj->factory($newval)
        Function: attribute containing the Bio::Tools::Run::BlastPlus
                  factory
        Example :
        Returns : value of factory (Bio::Tools::Run::BlastPlus object)
        Args    : readonly

   program_version()
        Title   : program_version
        Usage   : $version = $bedtools_fac->program_version()
        Function: Returns the program version (if available)
        Returns : string representing location and version of the program
        Note    : this works around the WrapperBase::version() method conflicting with
                  the -version parameter for SABlast (good argument for not having
                  getter/setters for these)

   package_version()
        Title   : package_version
        Usage   : $version = $bedtools_fac->package_version()
        Function: Returns the BLAST+ package version (if available)
        Returns : string representing BLAST+ package version (may differ from version())

DB methods

   make_db()
        Title   : make_db
        Usage   :
        Function: create the blast database (if necessary),
                  imposing masking if specified
        Returns : true on success
        Args    :

   make_mask()
        Title   : make_mask
        Usage   :
        Function: create masking data based on specified parameters
        Returns : mask data filename (scalar string)
        Args    :

   db_info()
        Title   : db_info
        Usage   :
        Function: get info for database
                  (via blastdbcmd -info); add factory attributes
        Returns : hash of database attributes
        Args    : [optional] db name (scalar string) (default: currently attached db)

   set_db_make_args()
        Title   : set_db_make_args
        Usage   :
        Function: set the DB make arguments attribute
                  with checking
        Returns : true on success
        Args    : arrayref or hashref of named arguments

   set_mask_make_args()
        Title   : set_mask_make_args
        Usage   :
        Function: set the masker make arguments attribute
                  with checking
        Returns : true on success
        Args    : arrayref or hasref of named arguments

   check_db()
        Title   : check_db
        Usage   :
        Function: determine if database with registered name and dir
                  exists
        Returns : 1 if db present, 0 if not present, undef if name/dir not
                  set
        Args    : [optional] db name (default is 'registered' name in $self->db)
                  [optional] db directory (default is 'registered' dir in
                                           $self->db_dir)

   no_throw_on_crash()
        Title   : no_throw_on_crash
        Usage   : $fac->no_throw_on_crash($newval)
        Function: set to prevent an exeception throw on a failed
                  blast program execution
        Example :
        Returns : value of no_throw_on_crash (boolean)
        Args    : on set, new value (boolean)

Internals

   _fastize()
        Title   : _fastize
        Usage   :
        Function: convert a sequence collection to a temporary
                  fasta file (sans gaps)
        Returns : fasta filename (scalar string)
        Args    : sequence collection

   _register_temp_for_cleanup()
        Title   : _register_temp_for_cleanup
        Usage   :
        Function: register a file for cleanup with
                  cleanup() method
        Returns : true on success
        Args    : a file name or a blastdb basename
                  (scalar string)

   cleanup()
        Title   : cleanup
        Usage   :
        Function: unlink files registered for cleanup
        Returns : true on success
        Args    :

   AUTOLOAD
       In this module, "AUTOLOAD()" delegates Bio::Tools::Run::WrapperBase and
       Bio::Tools::Run::WrapperBase::CommandExts methods (including those of Bio::ParamterBaseI)
       to the "factory()" attribute:

        $fac->stderr

       gives you

        $fac->factory->stderr

       If $AUTOLOAD isn't pointing to a WrapperBase method, then AUTOLOAD attempts to return a
       "db_info" attribute: e.g.

        $fac->db_num_sequences

       works by looking in the $fac->db_info() hash.

       Finally, if $AUTOLOAD is pointing to a blast query method, AUTOLOAD runs "run" with the
       "-method" parameter appropriately set.