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:

  using ncbi::blast;
  try {
      // Task is specified by the eBlastp argument
      CBl2Seq bl2seq(query, subject, eBlastp);
      TSeqAlignVector results = bl2seq.Run();
  } catch (const CBlastException& e) { 
      // Handle exception ... 
  }

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:

  using ncbi::blast;
  CRef<CBlastOptionsHandle> opts_handle(CBlastOptionsFactory::Create(eBlastn));
  ...
  opts_handle.SetEvalueThreshold(1e-20);
  CBl2Seq bl2seq(query, subjects, opts_handle);
  ...
  opts_handle.SetEvalueThreshold(1e-10);
  CLocalBlast blast(query_factory, opts_handle, seq_src);

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):

  using ncbi::blast;
  CBlastNucleotideOptionsHandle opts_handle;
  opts_handle.SetTraditionalBlastnDefaults();
  opts_handle.SetStrandOption(objects::eNa_strand_plus);
  CBl2Seq bl2seq(query, subject, opts_handle);
  TSeqAlignVector results = bl2seq.Run();

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.

  using ncbi::blast;
  try {
      CBlastProteinOptionsHandle opts_handle;
      opts_handle.SetMatrixName("PAM30");
      opts_handle.SetGapOpeningCost(9);
      opts_handle.SetGapExtensionCost(1);
      opts_handle.SetOptions().SetCompositionBasedStats(eCompositionBasedStats);
      opts_handle.Validate();

      CBl2Seq bl2seq(query, subject, opts_handle);
      TSeqAlignVector results = bl2seq.Run();
  } catch (const CBlastException& e) {
      // Handle exception ...
  }

See also:

C++ BLAST Options Design.

Author:

Christiam Camacho <camacho@ncbi.nlm.nih.gov>

---