Bio::T...stPlus(3pm)

💖 Bio::Tools::Run::StandAloneBlastPlus 💖

okay bestie, so this is a page from User Contributed Perl Documentation, and the module we're fangirling over is Bio::T...stPlus(3pm) — yes the name got abbreviated all cute, but the real one is right there in a sec. 🌸

---

✨ NAME ✨

Bio::Tools::Run::StandAloneBlastPlus — it's giving "compute with NCBI's blast+ suite" energy. Oh and heads up: it's marked ALPHA, so we're all early adopters here, no cap. 👑

---

🦋 SYNOPSIS 🦋

okay so real talk first: this module is only related to Bio::Tools::Run::StandAloneBlast in name (and inspiration). That's it. You must use this module directly, no sneaky indirect vibes. 💅

Here's the whole mood board, literally the entire thing:

# 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

like… the range?? we got db creation, masking, metadata querying, AND actual blast runs in one file. main character energy fr fr. 🔥

---

💜 DESCRIPTION 💜

🌟 lowkey important: this module needs BLAST+ v. 2.2.24+ and higher. and until the API stabilizes for BLAST+, just… consider this module highly experimental. we're in our beta era, bestie. 🙈

So here's the tea. This module, along with its bestie Bio::Tools::Run::StandAloneBlastPlus::BlastMethods, lets you run BLAST functions using the external program suite "blast+" — which lives at:

ftp://ftp.ncbi.nlm.nih.gov/blast/executables/blast+/LATEST/

and it does all of that using BioPerl objects and Bio::SearchIO facilities. iconic. ✨

This wrapper can:

• prepare BLAST databases 🗂️
• run BLAST searches 🔍
• run "blast+" programs independently 🏃♀️

Basically it encapsulates object construction plus production of databases and masks. The actual blast analysis methods (blastp, psiblast, etc>) — yeah that stray > is in the original, we keep it exactly, no edits — live over in Bio::Tools::Run::StandAloneBlastPlus::BlastMethods. go check that one for the real fun. 🎀

---

(more coming, don't go anywhere — this is only part 1 of 3 💅)

💖 USAGE 💖

okay bestie, here's the whole vibe in two steps and honestly that's it:

1. make a BlastPlus factory with the new() constructor
2. run your BLAST analyses by calling the BLAST program you want by name, right off that factory object

The blast database itself + any masking data get attached to the factory (that's step 1). Your query sequences + any parameters that belong to a particular program go into the blast method call (that's step 2), and they get run against the database you already attached. 💅

🎀 Factory construction/initialization 🎀

The factory needs to know where your blast+ programs live. The BLASTPLUSDIR environment variable is checked for the default executable directory. You can set the program directory for individual factory instances with the PROG_DIR parameter. All the blast+ programs have to be reachable from that directory — as executable files or symlinks, either one is fine. 👑

Either the database or the BLAST subject data must be specified at object construction. Databases can be pre-existing formatted BLAST dbs, or built straight 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 on its own:

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

The directory can go in along with the basename, or you can pass it 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'
);

Wanna create a BLAST database de novo? skip on down to "Creating a BLAST database" 🦋

If you want to apply pre-existing mask data (like, the final ASN1 output from one of the blast+ masker programs) to the database before you query it, say so 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 out of attached data — both before and after factory construction. If you want a temporary database (one that cleanup() can delete), just leave out the -db_name parameter. If you do specify -db_name, the database gets preserved under the basename you gave it. 🫶

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

heads up bestie: the database is not created immediately on factory construction. It gets created if necessary on the first use of a factory BLAST method — or you can force database creation yourself 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 too. 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 all available to you. Masking can be rolled right into database creation, or run later. If your mask data is already made and sitting in ASN1 format, set the -mask_file attribute at construction (peep "Factory constuction/initialization").

To create a mask from raw data or an existing database and apply that mask on database creation, build 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 gets 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 isn't compatible with the masker you picked, an exception gets thrown with a message saying exactly that. 💀

To create a mask ASN1 file you can use in the -mask_file parameter separately from the attached database, call 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 holding useful metadata on an existing database (the kind you get 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 grab one 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. That instance is right there for peeking and poking in the StandAloneBlastPlus factory() attribute. And for convenience, BlastPlus methods can be run from the StandAloneBlastPlus object too — they're delegated to the factory() attribute. Like, to see which blast+ program is going to be executed, check either

$fac->factory->command

or

$fac->command

Same energy, the current parameters for the BlastPlus factory are:

@parameters = $fac->get_parameters

🧚 Cleaning up temp files 🧚

Temporary analysis files produced under a single factory instance can be unlinked by running

$fac->cleanup;

Tempfiles generally are not removed unless you explicitly call that method. cleanup() only unlinks "registered" files and databases. All temporary files are automatically registered — and in particular, "anonymous" databases (such as

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

with no -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 stop exceptions from being thrown by failed blast+ program executions by setting no_throw_on_crash. Then 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 responsive 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 💜

(no names listed in the original — this section is empty, bestie, no cap)

🌈 APPENDIX 🌈

okay bestie, here's the deep lore 💖 The rest of the docs break down every single object method one by one. And heads up: methods that are ~internal~ usually start with an underscore _, iykyk 🫶

---

✨ new ✨

• Title — new
• Usage —

my $obj = new Bio::Tools::Run::StandAloneBlastPlus();

• Function — builds a brand new Bio::Tools::Run::StandAloneBlastPlus object, main character energy fr
• 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 — holds 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 (a 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, no promises bestie)
• 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 🫶

bestie these are the backstage crew, don't touch unless you know what you're doing 💀

🦋 _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. slay ✨

---

aaaand that's the whole page bestie, we ate and left no crumbs 💅✨ this one's perl v5.36.0, dated 2023-01-22, and it's the Bio::T...stPlus(3pm) page — go forth and blast, mwah 💖🌸🦋