NCBI C++ ToolKit
C++ BLAST Options Cookbook

The purpose of the C++ BLAST options APIs is to provide convenient access to the various algorithm options for a variety of users of BLAST as well as a means to validating the options, while isolating them from the details of the CORE BLAST implementation.

Please note that these objects are instantiated with the default options set and these defaults can be queried via the corresponding accessor method(s).

Basic usage

For users who only want to perform a single BLAST searches using default options for a specific task (EProgram) without modifying the options, one can let the BLAST search classes create and validate the appropriate BLAST options object internally:

try {
// Task is specified by the eBlastp argument
TSeqAlignVector results = bl2seq.Run();
} catch (const CBlastException& e) {
// Handle exception ...
}
vector< CRef< objects::CSeq_align_set > > TSeqAlignVector
Vector of Seq-align-sets.
@ eBlastp
Protein-Protein.
Definition: blast_types.hpp:59
Runs the BLAST algorithm between 2 sequences.
Definition: bl2seq.hpp:58
Defines BLAST error codes (user errors included)
static string subject
static string query

Using the approach above guarantees that the BLAST options will be valid.

An alternative to this approach is to use the CBlastOptionsFactory to create a CBlastOptionsHandle object, which allows the caller to set options which are applicable to all variants of BLAST (e.g.: E-value threshold, effective search space, window size). Furthermore, this approach allows the caller to reuse the CBlastOptionsHandle object with multiple BLAST search objects:

...
opts_handle.SetEvalueThreshold(1e-20);
CBl2Seq bl2seq(query, subjects, opts_handle);
...
opts_handle.SetEvalueThreshold(1e-10);
CLocalBlast blast(query_factory, opts_handle, seq_src);
@ eBlastn
Nucl-Nucl (traditional blastn)
Definition: blast_types.hpp:58
Class to perform a BLAST search on local BLAST databases Note that PHI-BLAST can be run using this cl...
Definition: local_blast.hpp:62
static CBlastOptionsHandle * Create(EProgram program, EAPILocality locality=CBlastOptions::eLocal)
Creates an options handle object configured with default options for the requested program,...

Options validation

The CBlastOptionsHandle classes offers a Validate method in its interface which is called by the BLAST search classes prior to performing the actual search, but users of the C++ BLAST options APIs might also want to invoke this method so that any exceptions thrown by the BLAST search classes can be guaranteed not originate from an incorrect setting of BLAST options. Please note that the Validate method throws a CBlastException in case of failure.

Intermediate options usage

For users who want to obtain default options, yet modify the most popular options, one should create instances of derived classes of the CBlastOptionsHandle, because these should expose an interface that is relevant to the task at hand (although not an exhaustive interface, for that see Advanced options usage):

CBl2Seq bl2seq(query, subject, opts_handle);
TSeqAlignVector results = bl2seq.Run();
Handle to the nucleotide-nucleotide options to the BLAST algorithm.
void SetTraditionalBlastnDefaults()
Sets TraditionalBlastnDefaults.
void SetStrandOption(objects::ENa_strand strand)
Sets StrandOption.
@ eNa_strand_plus
Definition: Na_strand_.hpp:66

By using this interface, the likelihood of setting invalid options is reduced, but the validity of the options cannot be fully guaranteed.

Note
BLAST help desk and developers reserve the right to determine which options are popular.

Advanced options usage

For users who want to have full control over setting the algorithm's options, or whose options of interest are not available in any of the classes in the CBlastOptionsHandle hierarchy, the GetOptions and SetOptions methods of the CBlastOptionsHandle hierarchy allow access to the CBlastOptions class, the lowest level class in the C++ BLAST options API which contains all options available to all variants of the BLAST algorithm. No guarantees about the validity of the options are made if this interface is used, therefore invoking Validate is strongly recommended.

try {
opts_handle.SetMatrixName("PAM30");
opts_handle.SetGapOpeningCost(9);
opts_handle.SetGapExtensionCost(1);
opts_handle.Validate();
CBl2Seq bl2seq(query, subject, opts_handle);
TSeqAlignVector results = bl2seq.Run();
} catch (const CBlastException& e) {
// Handle exception ...
}
Handle to the protein-protein options to the BLAST algorithm.
@ eCompositionBasedStats
Composition-based statistics as in NAR 29:2994-3005, 2001.
void SetGapExtensionCost(int e)
Sets GapExtensionCost.
void SetCompositionBasedStats(ECompoAdjustModes mode)
void SetGapOpeningCost(int g)
Sets GapOpeningCost.
CBlastOptions & SetOptions()
Returns a reference to the internal options class which this object is a handle for.
void SetMatrixName(const char *matrix)
Sets MatrixName.
bool Validate() const
Validate the options contained in this object.
See also
C++ BLAST Options Design.
Author
Christiam Camacho camac.nosp@m.ho@n.nosp@m.cbi.n.nosp@m.lm.n.nosp@m.ih.go.nosp@m.v
Modified on Fri Mar 01 10:05:34 2024 by modify_doxy.py rev. 669887