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

Go to the SVN repository for this file.

1 /* $Id: blast_types.hpp 84165 2018-10-23 12:07:38Z fongah2 $
2  * ===========================================================================
3  *
4  * PUBLIC DOMAIN NOTICE
5  * National Center for Biotechnology Information
6  *
7  * This software/database is a "United States Government Work" under the
8  * terms of the United States Copyright Act. It was written as part of
9  * the author's official duties as a United States Government employee and
10  * thus cannot be copyrighted. This software/database is freely available
11  * to the public for use. The National Library of Medicine and the U.S.
12  * Government have not placed any restriction on its use or reproduction.
13  *
14  * Although all reasonable efforts have been taken to ensure the accuracy
15  * and reliability of the software and data, the NLM and the U.S.
16  * Government do not and cannot warrant the performance or results that
17  * may be obtained by using this software or data. The NLM and the U.S.
18  * Government disclaim all warranties, express or implied, including
19  * warranties of performance, merchantability or fitness for any particular
20  * purpose.
21  *
22  * Please cite the author in any work or product based on this material.
23  *
24  * ===========================================================================
25  *
26  * Author: Ilya Dondoshansky
27  *
28  */
29 
30 /** @file blast_types.hpp
31  * Definitions of special type used in BLAST
32  */
33 
34 #ifndef ALGO_BLAST_API___BLAST_TYPE__HPP
35 #define ALGO_BLAST_API___BLAST_TYPE__HPP
36 
37 #include <corelib/ncbistd.hpp>
43 
45 BEGIN_SCOPE(blast)
46 
47 /// This enumeration is to evolve into a task/program specific list that
48 /// specifies sets of default parameters to easily conduct searches using
49 /// BLAST.
50 /// @todo EProgram needs to be renamed to denote a task (similar to those
51 /// exposed by the BLAST web page) rather than a program type
52 /// N.B.: When making changes to this enumeration, please update
53 /// blast::ProgramNameToEnum (blast_aux.[ch]pp), blast::GetNumberOfFrames
54 /// (blast_setup_cxx.cpp) and BlastNumber2Program and BlastProgram2Number
55 /// (blast_util.c)
56 enum EProgram {
57  eBlastNotSet = 0, ///< Not yet set.
58  eBlastn, ///< Nucl-Nucl (traditional blastn)
59  eBlastp, ///< Protein-Protein
60  eBlastx, ///< Translated nucl-Protein
61  eTblastn, ///< Protein-Translated nucl
62  eTblastx, ///< Translated nucl-Translated nucl
63  eRPSBlast, ///< protein-pssm (reverse-position-specific BLAST)
64  eRPSTblastn, ///< nucleotide-pssm (RPS blast with translated query)
65  eMegablast, ///< Nucl-Nucl (traditional megablast)
66  eDiscMegablast, ///< Nucl-Nucl using discontiguous megablast
67  ePSIBlast, ///< PSI Blast
68  ePSITblastn, ///< PSI Tblastn
69  ePHIBlastp, ///< Protein PHI BLAST
70  ePHIBlastn, ///< Nucleotide PHI BLAST
71  eDeltaBlast, ///< Delta Blast
72  eVecScreen, ///< Vector screening
73  eMapper, ///< Jumper alignment for mapping
74  eKBlastp, ///< KMER screening and BLASTP
75  eBlastProgramMax ///< Undefined program
76 };
77 
78 /** Convert a EProgram enumeration value to a task name (as those used in the
79  * BLAST command line binaries)
80  * @param p EProgram enumeration value to convert [in]
81  */
84 
85 /// Map a string into an element of the ncbi::blast::EProgram enumeration
86 /// (except eBlastProgramMax).
87 /// @param program_name [in]
88 /// @return an element of the ncbi::blast::EProgram enumeration, except
89 /// eBlastProgramMax
90 /// @throws CBlastException if the string does not map into any of the EProgram
91 /// elements
93 EProgram ProgramNameToEnum(const std::string& program_name);
94 
95 /// Validates that the task provided is indeed a valid task, otherwise throws a
96 /// CBlastException
97 /// @param task task name to validate [in]
99 void ThrowIfInvalidTask(const string& task);
100 
101 /// Convert EProgram to EBlastProgramType.
102 /// @param p Program expressed as an api layer EProgram.
103 /// @return Same program using the core enumeration.
107 
108 /// Error or Warning Message from search.
109 ///
110 /// This class encapsulates a single error or warning message returned
111 /// from a search. These include conditions detected by the algorithm
112 /// where no exception is thrown, but which impact the completeness or
113 /// accuracy of search results. One example might be a completely
114 /// masked query.
115 
116 class CSearchMessage : public CObject {
117 public:
118  /// Construct a search message object.
119  /// @param severity The severity of this message. [in]
120  /// @param error_id A number unique to this error. [in]
121  /// @param message A description of the error for the user. [in]
123  int error_id,
124  const string & message)
125  : m_Severity(severity), m_ErrorId(error_id), m_Message(message)
126  {
127  }
128 
129  /// Construct an empty search message object.
132  {
133  }
134 
135  /// Get the severity of this message.
136  /// @return The severity of this message.
138  {
139  return m_Severity;
140  }
141 
142  /// Adjust the severity of this message.
143  /// @param sev The severity to assign. [in]
144  void SetSeverity(EBlastSeverity sev) { m_Severity = sev; }
145 
146  /// Get the severity of this message as a string.
147  /// @return A symbolic name for the severity level (such as "Warning").
148  string GetSeverityString() const
149  {
151  }
152 
153  /// Get the symbolic name for a level of severity as a string.
154  /// @param severity The severity as an enumeration.
155  /// @return A symbolic name for the severity level (such as "Warning").
156  static string GetSeverityString(EBlastSeverity severity)
157  {
158  switch(severity) {
159  case eBlastSevInfo: return "Informational Message";
160  case eBlastSevWarning: return "Warning";
161  case eBlastSevError: return "Error";
162  case eBlastSevFatal: return "Fatal Error";
163  }
164  return "Message";
165  }
166 
167  /// Get the error identifier.
168  /// @return An identifier unique to this specific message.
169  int GetErrorId() const
170  {
171  return m_ErrorId;
172  }
173 
174  /// Set the error message.
175  /// @return A reference allowing the user to set the error string.
176  string& SetMessage(void) { return m_Message; }
177 
178  /// Get the error message.
179  /// @return A message describing this error or warning.
180  string GetMessage(bool withSeverity = true) const
181  {
182  if (withSeverity) {
183  return GetSeverityString() + ": " + m_Message;
184  }
185  return m_Message;
186  }
187 
188  /// Compare two error messages for equality.
189  /// @return True if the messages are the same.
190  bool operator==(const CSearchMessage& rhs) const;
191 
192  /// Compare two error messages for inequality.
193  /// @return True if the messages are not the same.
194  bool operator!=(const CSearchMessage& rhs) const;
195 
196  /// Compare two error messages for order.
197  /// @return True if the first message is less than the second.
198  bool operator<(const CSearchMessage& rhs) const;
199 
200 private:
201  /// The severity of this error or warning message.
203 
204  /// A unique identifier specifying what kind of error this is.
206 
207  /// A message describing the error to the application user.
208  string m_Message;
209 };
210 
211 /// Class for the messages for an individual query sequence.
212 class NCBI_XBLAST_EXPORT TQueryMessages : public vector< CRef<CSearchMessage> >
213 {
214 public:
215  /// Set the query id as a string.
216  /// @param id The query id.
217  void SetQueryId(const string& id);
218 
219  /// Get the query id as a string.
220  /// @return The query id.
221  string GetQueryId() const;
222 
223  /// Combine other messages with these.
224  /// @param other The second list of messages.
225  void Combine(const TQueryMessages& other);
226 
227 private:
228  /// The query identifier.
229  string m_IdString;
230 };
231 
232 /// typedef for the messages for an entire BLAST search, which could be
233 /// comprised of multiple query sequences
234 class NCBI_XBLAST_EXPORT TSearchMessages : public vector<TQueryMessages>
235 {
236 public:
237  /// Add a message for all queries.
238  /// @param severity The severity of this message. [in]
239  /// @param error_id A number unique to this error. [in]
240  /// @param message A description of the error for the user. [in]
241  void AddMessageAllQueries(EBlastSeverity severity,
242  int error_id,
243  const string & message);
244 
245  /// @return true if messages exist.
246  bool HasMessages() const;
247 
248  /// Converts messages to a string, which is returned.
249  /// @return A string containing all such messages.
250  string ToString() const;
251 
252  /// Combine another set of search messages with this one.
253  ///
254  /// Another set of messages is combined with these; each element
255  /// of the other set is combined with the element of this set
256  /// having the same index. The size of both sets must match.
257  ///
258  /// @param other_msgs Other messages to add to these.
259  void Combine(const TSearchMessages& other_msgs);
260 
261  /// Find and remove redundant messages.
262  void RemoveDuplicates();
263 };
264 
265 /// Specifies the style of Seq-aligns that should be built from the
266 /// internal BLAST data structures
268  eDatabaseSearch, ///< Seq-aligns in the style of a database search
269  eSequenceComparison /**< Seq-aligns in the BLAST 2 Sequence style (one
270  alignment per query-subject pair) */
271 };
272 
273 /// Vector of Seq-align-sets
274 typedef vector< CRef<objects::CSeq_align_set> > TSeqAlignVector;
275 
276 inline bool
278 {
279  if (m_Severity == rhs.m_Severity &&
280  m_ErrorId == rhs.m_ErrorId &&
281  m_Message == rhs.m_Message) {
282  return true;
283  } else {
284  return false;
285  }
286 }
287 
288 inline bool
290 {
291  return !(*this == rhs);
292 }
293 
294 inline bool
296 {
297  if (m_ErrorId < rhs.m_ErrorId ||
298  m_Severity < rhs.m_Severity ||
299  m_Message < rhs.m_Message) {
300  return true;
301  } else {
302  return false;
303  }
304 }
305 
306 /// Wrapper for BlastSeqLoc structure.
307 class CBlastSeqLocWrap : public CObject
308 {
309  public:
310 
311  /// Instance constructor.
312  /// @param locs pointer to the object to hold
313  CBlastSeqLocWrap( BlastSeqLoc * locs ) : locs_( locs ) {}
314 
315  /// Instance destructor.
317 
318  /// Get access to the held object.
319  /// @return pointer storred by the wrapping object
320  BlastSeqLoc * getLocs() const { return locs_; }
321 
322  private:
323 
324  BlastSeqLoc * locs_; ///< Wrapped pointer.
325 };
326 
327 END_SCOPE(blast)
329 
330 #endif /* ALGO_BLAST_API___BLAST_TYPE__HPP */
Definitions used throughout BLAST.
Defines to provide correct exporting from BLAST DLL in Windows.
#define NCBI_XBLAST_EXPORT
NULL operations for other cases.
Definition: blast_export.h:65
BLAST filtering functions.
BlastSeqLoc * BlastSeqLocFree(BlastSeqLoc *loc)
Deallocate all BlastSeqLoc objects in a chain.
Definition: blast_filter.c:737
Structures for BLAST messages.
EBlastSeverity
Blast error message severities .
Definition: blast_message.h:55
@ eBlastSevError
Definition: blast_message.h:58
@ eBlastSevInfo
Definition: blast_message.h:56
@ eBlastSevFatal
Definition: blast_message.h:59
@ eBlastSevWarning
Definition: blast_message.h:57
EBlastProgramType
Defines the engine's notion of the different applications of the BLAST algorithm.
Definition: blast_program.h:72
vector< CRef< objects::CSeq_align_set > > TSeqAlignVector
Vector of Seq-align-sets.
EResultType
Specifies the style of Seq-aligns that should be built from the internal BLAST data structures.
@ eDatabaseSearch
Seq-aligns in the style of a database search.
@ eSequenceComparison
Seq-aligns in the BLAST 2 Sequence style (one alignment per query-subject pair)
EProgram
This enumeration is to evolve into a task/program specific list that specifies sets of default parame...
Definition: blast_types.hpp:56
@ eBlastNotSet
Not yet set.
Definition: blast_types.hpp:57
@ eBlastProgramMax
Undefined program.
Definition: blast_types.hpp:75
@ eVecScreen
Vector screening.
Definition: blast_types.hpp:72
@ eTblastx
Translated nucl-Translated nucl.
Definition: blast_types.hpp:62
@ eBlastn
Nucl-Nucl (traditional blastn)
Definition: blast_types.hpp:58
@ eRPSBlast
protein-pssm (reverse-position-specific BLAST)
Definition: blast_types.hpp:63
@ ePHIBlastn
Nucleotide PHI BLAST.
Definition: blast_types.hpp:70
@ eBlastp
Protein-Protein.
Definition: blast_types.hpp:59
@ ePHIBlastp
Protein PHI BLAST.
Definition: blast_types.hpp:69
@ eMapper
Jumper alignment for mapping.
Definition: blast_types.hpp:73
@ ePSIBlast
PSI Blast.
Definition: blast_types.hpp:67
@ eTblastn
Protein-Translated nucl.
Definition: blast_types.hpp:61
@ eMegablast
Nucl-Nucl (traditional megablast)
Definition: blast_types.hpp:65
@ eDeltaBlast
Delta Blast.
Definition: blast_types.hpp:71
@ ePSITblastn
PSI Tblastn.
Definition: blast_types.hpp:68
@ eKBlastp
KMER screening and BLASTP.
Definition: blast_types.hpp:74
@ eDiscMegablast
Nucl-Nucl using discontiguous megablast.
Definition: blast_types.hpp:66
@ eRPSTblastn
nucleotide-pssm (RPS blast with translated query)
Definition: blast_types.hpp:64
@ eBlastx
Translated nucl-Protein.
Definition: blast_types.hpp:60
Wrapper for BlastSeqLoc structure.
CBlastSeqLocWrap(BlastSeqLoc *locs)
Instance constructor.
virtual ~CBlastSeqLocWrap()
Instance destructor.
BlastSeqLoc * locs_
Wrapped pointer.
BlastSeqLoc * getLocs() const
Get access to the held object.
CObject –.
Definition: ncbiobj.hpp:180
Error or Warning Message from search.
string m_Message
A message describing the error to the application user.
bool operator<(const CSearchMessage &rhs) const
Compare two error messages for order.
EBlastSeverity m_Severity
The severity of this error or warning message.
string & SetMessage(void)
Set the error message.
void SetSeverity(EBlastSeverity sev)
Adjust the severity of this message.
CSearchMessage()
Construct an empty search message object.
int m_ErrorId
A unique identifier specifying what kind of error this is.
string GetSeverityString() const
Get the severity of this message as a string.
bool operator!=(const CSearchMessage &rhs) const
Compare two error messages for inequality.
CSearchMessage(EBlastSeverity severity, int error_id, const string &message)
Construct a search message object.
bool operator==(const CSearchMessage &rhs) const
Compare two error messages for equality.
int GetErrorId() const
Get the error identifier.
string GetMessage(bool withSeverity=true) const
Get the error message.
EBlastSeverity GetSeverity() const
Get the severity of this message.
static string GetSeverityString(EBlastSeverity severity)
Get the symbolic name for a level of severity as a string.
Class for the messages for an individual query sequence.
string m_IdString
The query identifier.
typedef for the messages for an entire BLAST search, which could be comprised of multiple query seque...
Include a standard set of the NCBI C++ Toolkit most basic headers.
EBlastProgramType EProgramToEBlastProgramType(EProgram p)
Convert EProgram to EBlastProgramType.
Definition: blast_aux.cpp:709
string EProgramToTaskName(EProgram p)
Convert a EProgram enumeration value to a task name (as those used in the BLAST command line binaries...
Definition: blast_aux.cpp:676
EProgram ProgramNameToEnum(const std::string &program_name)
Map a string into an element of the ncbi::blast::EProgram enumeration (except eBlastProgramMax).
Definition: blast_aux.cpp:757
void ThrowIfInvalidTask(const string &task)
Validates that the task provided is indeed a valid task, otherwise throws a CBlastException.
Definition: blast_aux.cpp:662
string
Definition: cgiapp.hpp:687
#define END_NCBI_SCOPE
End previously defined NCBI scope.
Definition: ncbistl.hpp:103
#define END_SCOPE(ns)
End the previously defined scope.
Definition: ncbistl.hpp:75
#define BEGIN_NCBI_SCOPE
Define ncbi namespace.
Definition: ncbistl.hpp:100
#define BEGIN_SCOPE(ns)
Define a new scope.
Definition: ncbistl.hpp:72
Used to hold a set of positions, mostly used for filtering.
Definition: blast_def.h:204
string ToString(const wxRect &rc)
Definition: wx_utils.cpp:773
Modified on Mon Feb 26 04:03:29 2024 by modify_doxy.py rev. 669887