NCBI C++ ToolKit
blast_options_handle.hpp
Go to the documentation of this file.

Go to the SVN repository for this file.

1 #ifndef ALGO_BLAST_API___BLAST_OPTIONS_HANDLE__HPP
2 #define ALGO_BLAST_API___BLAST_OPTIONS_HANDLE__HPP
3 
4 /* $Id: blast_options_handle.hpp 73100 2016-06-20 15:45:40Z boratyng $
5  * ===========================================================================
6  *
7  * PUBLIC DOMAIN NOTICE
8  * National Center for Biotechnology Information
9  *
10  * This software/database is a "United States Government Work" under the
11  * terms of the United States Copyright Act. It was written as part of
12  * the author's official duties as a United States Government employee and
13  * thus cannot be copyrighted. This software/database is freely available
14  * to the public for use. The National Library of Medicine and the U.S.
15  * Government have not placed any restriction on its use or reproduction.
16  *
17  * Although all reasonable efforts have been taken to ensure the accuracy
18  * and reliability of the software and data, the NLM and the U.S.
19  * Government do not and cannot warrant the performance or results that
20  * may be obtained by using this software or data. The NLM and the U.S.
21  * Government disclaim all warranties, express or implied, including
22  * warranties of performance, merchantability or fitness for any particular
23  * purpose.
24  *
25  * Please cite the author in any work or product based on this material.
26  *
27  * ===========================================================================
28  *
29  * Authors: Christiam Camacho
30  *
31  */
32 
33 /// @file blast_options_handle.hpp
34 /// Declares the CBlastOptionsHandle and CBlastOptionsFactory classes.
35 
37 #include <set>
38 
39 /** @addtogroup AlgoBlast
40  *
41  * @{
42  */
43 
44 
47 
48 // forward declarations
50 
51 /**
52 * Creates BlastOptionsHandle objects with default values for the
53 * programs/tasks requested. This factory is provided as a convenience
54 * to create CBlastOptionsHandles which are configured with default values for
55 * a given program/task and will NOT be modified before passing them to objects
56 * which will execute the BLAST algorithm. If you need to set options for the
57 * specific task at hand, please instantiate the appropriate CBlastOptionsHandle
58 * subclass.
59 *
60 * @sa @ref blast_opts_cookbook
61 *
62 * Example:
63 * @code
64 * ...
65 * CRef<CBlastOptionsHandle> opts(CBlastOptionsFactory::Create(eBlastn));
66 * CBl2Seq blaster(query, subject, *opts);
67 * TSeqAlignVector results = blaster.Run();
68 * ...
69 * opts.Reset(CBlastOptionsFactory::Create(eMegablast));
70 * blaster.SetOptionsHandle() = *opts;
71 * results = blaster.Run();
72 * ...
73 * opts.Reset(CBlastOptionsFactory::Create(eDiscMegablast));
74 * blaster.SetOptionsHandle() = *opts;
75 * results = blaster.Run();
76 * ...
77 * @endcode
78 */
79 
81 {
82 public:
83  /// Convenience define
84  /// @sa CBlastOptions class
86 
87  /// Creates an options handle object configured with default options for
88  /// the requested program, throws an exception if an unsupported program
89  /// is requested
90  /// @param program BLAST program [in]
91  /// @param locality Local processing (default) or remote processing.
92  /// @return requested options handle with default values set
93  /// @throw CBlastException in case of an unhandled program type
94  static CBlastOptionsHandle*
95  Create(EProgram program,
96  EAPILocality locality = CBlastOptions::eLocal);
97 
98  /// Creates an options handle object configured with default options for
99  /// the requested task, throws an exception if an unsupported task
100  /// is requested
101  /// @param task BLAST task [in]
102  /// @param locality Local processing (default) or remote processing.
103  /// @return requested options handle with default values set
104  /// @throw CBlastException in case of an unhandled program type
105  /// @sa GetDocumentation
106  static CBlastOptionsHandle*
107  CreateTask(string task,
108  EAPILocality locality = CBlastOptions::eLocal);
109 
110  /// Sets of tasks for the command line BLAST binaries
111  enum ETaskSets {
112  eNuclNucl, ///< Nucleotide-nucleotide tasks
113  eProtProt, ///< Protein-protein tasks
114  eMapping, ///< Mapping tasks
115  eAll ///< Retrieve all available tasks
116  };
117 
118  /// Retrieve the set of supported tasks
119  static set<string> GetTasks(ETaskSets choice = eAll);
120 
121  /// Return the documentation for the provided task
122  /// @param task_name Task name for which to provide documentation [in]
123  static string GetDocumentation(const string& task_name);
124 
125 private:
126  /// Private c-tor
127  CBlastOptionsFactory();
128 };
129 
130 /// Handle to the options to the BLAST algorithm.
131 ///
132 /// This abstract base class only defines those options that are truly
133 /// "universal" BLAST options (they apply to all flavors of BLAST).
134 ///
135 /// @sa @ref blast_opts_cookbook
136 /// @ref blast_opts_cpp_design
137 ///
138 /// @invariant Derived classes define options that are applicable only to
139 /// those programs whose options they manipulate.
140 
142 {
143 public:
144  /// Convenience define
145  /// @sa CBlastOptions class
147 
148  /// Default c-tor
149  CBlastOptionsHandle(EAPILocality locality);
150 
151  /// Validate the options contained in this object
152  /// @note This method is meant to be used before calling any code that
153  /// processes the BLAST options classes
154  bool Validate() const;
155 
156  /// Return the object which this object is a handle for. This method is
157  /// intended to be used when one wants to INSPECT the values of options
158  /// which are not exposed by the classes derived from
159  /// CBlastOptionsHandle.
160  const CBlastOptions& GetOptions() const { return *m_Opts; }
161 
162  /// Returns a reference to the internal options class which this object is
163  /// a handle for. Please note that using objects of type CBlastOptions
164  /// directly allows one to set inconsistent combinations of options.
165  ///
166  /// @note Assumes user knows exactly how to set the individual options
167  /// correctly. Calling CBlastOptions::Validate on this object is STRONGLY
168  /// recommended.
169  CBlastOptions& SetOptions() { return *m_Opts; }
170 
171  /// Resets the state of the object to all default values.
172  /// This is a template method (design pattern).
173  virtual void SetDefaults();
174 
175  /// Returns true if this object needs default values set.
176  void DoneDefaults() { m_Opts->DoneDefaults(); }
177 
178  /******************** Initial Word options **********************/
179 
180  /// Returns WindowSize
181  int GetWindowSize() const { return m_Opts->GetWindowSize(); }
182  /// Sets WindowSize
183  /// @param ws WindowSize [in]
184  void SetWindowSize(int ws) { m_Opts->SetWindowSize(ws); }
185  int GetOffDiagonalRange() const { return m_Opts->GetOffDiagonalRange(); }
186  void SetOffDiagonalRange(int r) { m_Opts->SetOffDiagonalRange(r); }
187 
188  /******************* Query setup options ************************/
189  /// Clears the filtering options
190  void ClearFilterOptions() { m_Opts->ClearFilterOptions(); }
191  /// Returns FilterString
192  char* GetFilterString() const;
193  /// Sets FilterString
194  /// @param f FilterString [in]
195  void SetFilterString(const char* f, bool clear = true);
196 
197  /// Returns whether masking should only be done for lookup table creation.
198  bool GetMaskAtHash() const { return m_Opts->GetMaskAtHash(); }
199  /// Sets MaskAtHash
200  /// @param m whether masking should only be done for lookup table [in]
201  void SetMaskAtHash(bool m = true) { m_Opts->SetMaskAtHash(m); }
202  /******************* Gapped extension options *******************/
203  /// Returns GapXDropoff
204  double GetGapXDropoff() const { return m_Opts->GetGapXDropoff(); }
205  /// Sets GapXDropoff
206  /// @param x GapXDropoff [in]
207  void SetGapXDropoff(double x) { m_Opts->SetGapXDropoff(x); }
208 
209  /// Returns GapTrigger
210  double GetGapTrigger() const { return m_Opts->GetGapTrigger(); }
211  /// Sets GapTrigger
212  /// @param g GapTrigger [in]
213  void SetGapTrigger(double g) { m_Opts->SetGapTrigger(g); }
214 
215  /// Returns GapXDropoffFinal
216  double GetGapXDropoffFinal() const {
217  return m_Opts->GetGapXDropoffFinal();
218  }
219  /// Sets GapXDropoffFinal
220  /// @param x GapXDropoffFinal [in]
221  void SetGapXDropoffFinal(double x) { m_Opts->SetGapXDropoffFinal(x); }
222 
223  /******************* Hit saving options *************************/
224  /// Returns HitlistSize
225  int GetHitlistSize() const { return m_Opts->GetHitlistSize(); }
226  /// Sets HitlistSize
227  /// @param s HitlistSize [in]
228  void SetHitlistSize(int s) { m_Opts->SetHitlistSize(s); }
229 
230  /// Returns MaxNumHspPerSequence
231  int GetMaxNumHspPerSequence() const {
232  return m_Opts->GetMaxNumHspPerSequence();
233  }
234  /// Sets MaxNumHspPerSequence
235  /// @param m MaxNumHspPerSequence [in]
236  void SetMaxNumHspPerSequence(int m) { m_Opts->SetMaxNumHspPerSequence(m); }
237 
238  /// Returns MaxHspsPerSubjectQueryPair
239  int GetMaxHspsPerSubject() const {
240  return m_Opts->GetMaxHspsPerSubject();
241  }
242  /// Sets MaxHspPerSubjectQueryPair
243  /// @param m MaxNumHspPerSequence [in]
244  void SetMaxHspsPerSubject(int m) { m_Opts->SetMaxHspsPerSubject(m); }
245 
246  /// Returns EvalueThreshold
247  double GetEvalueThreshold() const { return m_Opts->GetEvalueThreshold(); }
248  /// Sets EvalueThreshold
249  /// @param eval EvalueThreshold [in]
250  void SetEvalueThreshold(double eval) { m_Opts->SetEvalueThreshold(eval); }
251  /// Returns CutoffScore
252  int GetCutoffScore() const { return m_Opts->GetCutoffScore(); }
253  /// Sets CutoffScore
254  /// @param s CutoffScore [in]
255  void SetCutoffScore(int s) { m_Opts->SetCutoffScore(s); }
256 
257  /// Returns PercentIdentity
258  double GetPercentIdentity() const { return m_Opts->GetPercentIdentity(); }
259  /// Sets PercentIdentity
260  /// @param p PercentIdentity [in]
261  void SetPercentIdentity(double p) { m_Opts->SetPercentIdentity(p); }
262 
263  /// Returns QueryCovHspPerc
264  double GetQueryCovHspPerc() const { return m_Opts->GetQueryCovHspPerc(); }
265  /// Sets QueryCovHspPerc
266  /// @param p QueryCovHspPerc [in]
267  void SetQueryCovHspPerc(double p) { m_Opts->SetQueryCovHspPerc(p); }
268 
269  /// Returns MinDiagSeparation
270  int GetMinDiagSeparation() const { return m_Opts->GetMinDiagSeparation(); }
271  /// Sets MinDiagSeparation
272  /// @param d MinDiagSeparation [in]
273  void SetMinDiagSeparation(int d) { m_Opts->SetMinDiagSeparation(d); }
274 
275  /// Returns GappedMode
276  bool GetGappedMode() const { return m_Opts->GetGappedMode(); }
277  /// Sets GappedMode
278  /// @param m GappedMode [in]
279  void SetGappedMode(bool m = true) { m_Opts->SetGappedMode(m); }
280 
281  /// Returns Culling limit
282  int GetCullingLimit() const { return m_Opts->GetCullingLimit(); }
283  /// Sets Culling limit
284  /// @param s CullingLimit [in]
285  void SetCullingLimit(int s) { m_Opts->SetCullingLimit(s); }
286 
287  /// Returns MaskLevel -RMH-
288  int GetMaskLevel() const { return m_Opts->GetMaskLevel(); }
289  /// Sets MaskLevel -RMH-
290  /// @param ml MaskLevel [in]
291  void SetMaskLevel(int ml) { m_Opts->SetMaskLevel(ml); }
292 
293  /// Returns Complexity Adjustment Mode -RMH-
294  bool GetComplexityAdjMode() const { return m_Opts->GetComplexityAdjMode(); }
295  /// Sets ComplexityAdjMode -RMH-
296  /// @param m ComplexityAdjMode [in]
297  void SetComplexityAdjMode(bool m = true) { m_Opts->SetComplexityAdjMode(m); }
298 
299  /// Returns low score percentage for ungapped alignments.
300  double GetLowScorePerc() const {return m_Opts->GetLowScorePerc(); }
301  /// Sets low score percentage for ungapped alignments.
302  void SetLowScorePerc(double p) { m_Opts->SetLowScorePerc(p); }
303 
304  /******************** Database (subject) options *******************/
305  /// Returns DbLength
306  Int8 GetDbLength() const { return m_Opts->GetDbLength(); }
307  /// Sets DbLength
308  /// @param len DbLength [in]
309  void SetDbLength(Int8 len) { m_Opts->SetDbLength(len); }
310 
311  /// Returns DbSeqNum
312  unsigned int GetDbSeqNum() const { return m_Opts->GetDbSeqNum(); }
313  /// Sets DbSeqNum
314  /// @param num DbSeqNum [in]
315  void SetDbSeqNum(unsigned int num) { m_Opts->SetDbSeqNum(num); }
316 
317  /// Returns EffectiveSearchSpace
319  return m_Opts->GetEffectiveSearchSpace();
320  }
321  /// Sets EffectiveSearchSpace
322  /// @param eff EffectiveSearchSpace [in]
324  m_Opts->SetEffectiveSearchSpace(eff);
325  }
326 
327 protected:
328  /// Create Options Handle from Existing CBlastOptions Object
330 
331  /// Set the program and service name for remote blast.
332  virtual void SetRemoteProgramAndService_Blast3() = 0;
333 
334  /// Data type this class controls access to
336 
337  /// Set to true when 'remote' options should ignore setters.
339 
340  // These methods make up the template method
341  /// Sets LookupTableDefaults
342  virtual void SetLookupTableDefaults() = 0;
343  /// Sets QueryOptionDefaults
344  virtual void SetQueryOptionDefaults() = 0;
345  /// Sets InitialWordOptionsDefaults
346  virtual void SetInitialWordOptionsDefaults() = 0;
347  /// Sets GappedExtensionDefaults
348  virtual void SetGappedExtensionDefaults() = 0;
349  /// Sets ScoringOptionsDefaults
350  virtual void SetScoringOptionsDefaults() = 0;
351  /// Sets HitSavingOptionsDefaults
352  virtual void SetHitSavingOptionsDefaults() = 0;
353  /// Sets EffectiveLengthsOptionsDefaults
354  virtual void SetEffectiveLengthsOptionsDefaults() = 0;
355  /// Sets SubjectSequenceOptionsDefaults
356  virtual void SetSubjectSequenceOptionsDefaults() = 0;
357 };
358 
361 
362 
363 /* @} */
364 
365 #endif /* ALGO_BLAST_API___BLAST_OPTIONS_HANDLE__HPP */
void SetMaxHspsPerSubject(int m)
Sets MaxHspPerSubjectQueryPair.
const CBlastOptions & GetOptions() const
Return the object which this object is a handle for.
Int8 GetEffectiveSearchSpace() const
Returns EffectiveSearchSpace.
unsigned int GetDbSeqNum() const
Returns DbSeqNum.
void SetMaxNumHspPerSequence(int m)
Sets MaxNumHspPerSequence.
Int8 GetDbLength() const
Returns DbLength.
int GetMaskLevel() const
Returns MaskLevel -RMH-.
#define END_SCOPE(ns)
End the previously defined scope.
Definition: ncbistl.hpp:73
EAPILocality
Enumerates the possible contexts in which objects of this type can be used.
int GetMinDiagSeparation() const
Returns MinDiagSeparation.
EProgram
This enumeration is to evolve into a task/program specific list that specifies sets of default parame...
Definition: blast_types.hpp:56
CBlastOptions::EAPILocality EAPILocality
Convenience define.
#define NCBI_XBLAST_EXPORT
NULL operations for other cases.
Definition: blast_export.h:65
void SetComplexityAdjMode(bool m=true)
Sets ComplexityAdjMode -RMH-.
void SetCutoffScore(int s)
Sets CutoffScore.
void SetGapXDropoff(double x)
Sets GapXDropoff.
void SetMaskAtHash(bool m=true)
Sets MaskAtHash.
void SetMaskLevel(int ml)
Sets MaskLevel -RMH-.
double GetGapTrigger() const
Returns GapTrigger.
void SetMinDiagSeparation(int d)
Sets MinDiagSeparation.
signed NCBI_INT8_TYPE Int8
Signed 8 byte sized integer.
Definition: ncbitype.h:143
void DoneDefaults()
Returns true if this object needs default values set.
Creates BlastOptionsHandle objects with default values for the programs/tasks requested.
int GetHitlistSize() const
Returns HitlistSize.
bool GetGappedMode() const
Returns GappedMode.
void SetPercentIdentity(double p)
Sets PercentIdentity.
void SetCullingLimit(int s)
Sets Culling limit.
Declares class to encapsulate all BLAST options.
void ClearFilterOptions()
Clears the filtering options.
double GetGapXDropoff() const
Returns GapXDropoff.
double GetQueryCovHspPerc() const
Returns QueryCovHspPerc.
#define END_NCBI_SCOPE
End previously defined NCBI scope.
Definition: ncbistl.hpp:101
void SetDbSeqNum(unsigned int num)
Sets DbSeqNum.
int GetCullingLimit() const
Returns Culling limit.
double GetPercentIdentity() const
Returns PercentIdentity.
int GetWindowSize() const
Returns WindowSize.
int GetMaxNumHspPerSequence() const
Returns MaxNumHspPerSequence.
void SetEvalueThreshold(double eval)
Sets EvalueThreshold.
void SetHitlistSize(int s)
Sets HitlistSize.
ETaskSets
Sets of tasks for the command line BLAST binaries.
double f(double x_, const double &y_)
Definition: njn_root.hpp:188
CRef< CBlastOptions > m_Opts
Data type this class controls access to.
int g(Seg_Gsm *spe, Seq_Mtf *psm, Thd_Gsm *tdg)
Definition: thrddgri.c:44
void SetDbLength(Int8 len)
Sets DbLength.
int GetMaxHspsPerSubject() const
Returns MaxHspsPerSubjectQueryPair.
double GetEvalueThreshold() const
Returns EvalueThreshold.
void SetGapTrigger(double g)
Sets GapTrigger.
bool GetMaskAtHash() const
Returns whether masking should only be done for lookup table creation.
int len
CObject –.
Definition: ncbiobj.hpp:180
void SetQueryCovHspPerc(double p)
Sets QueryCovHspPerc.
Encapsulates ALL the BLAST algorithm's options.
Nucleotide-nucleotide tasks.
void SetLowScorePerc(double p)
Sets low score percentage for ungapped alignments.
bool m_DefaultsMode
Set to true when 'remote' options should ignore setters.
void SetGapXDropoffFinal(double x)
Sets GapXDropoffFinal.
double GetLowScorePerc() const
Returns low score percentage for ungapped alignments.
#define BEGIN_SCOPE(ns)
Define a new scope.
Definition: ncbistl.hpp:70
int GetCutoffScore() const
Returns CutoffScore.
void SetEffectiveSearchSpace(Int8 eff)
Sets EffectiveSearchSpace.
double r(size_t dimension_, const Int4 *score_, const double *prob_, double theta_)
CBlastOptions::EAPILocality EAPILocality
Convenience define.
void SetWindowSize(int ws)
Sets WindowSize.
void SetGappedMode(bool m=true)
Sets GappedMode.
double GetGapXDropoffFinal() const
Returns GapXDropoffFinal.
Handle to the options to the BLAST algorithm.
CBlastOptions & SetOptions()
Returns a reference to the internal options class which this object is a handle for.
#define BEGIN_NCBI_SCOPE
Define ncbi namespace.
Definition: ncbistl.hpp:98
To be used for running BLAST locally.
bool GetComplexityAdjMode() const
Returns Complexity Adjustment Mode -RMH-.
Modified on Sat Mar 25 15:49:30 2017 by modify_doxy.py rev. 506947