1 /* $Id: blast_engine.h 504861 2016-06-20 15:45:40Z boratyng $ 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_engine.h 31 * Function calls to actually perform a BLAST search (high level). 32 */ 33 34 #ifndef ALGO_BLAST_CORE__BLAST_ENGINE__H 35 #define ALGO_BLAST_CORE__BLAST_ENGINE__H 36 37 #include <algo/blast/core/ncbi_std.h> 38 #include <algo/blast/core/blast_export.h> 39 #include <algo/blast/core/blast_def.h> 40 #include <algo/blast/core/blast_program.h> 41 #include <algo/blast/core/blast_extend.h> 42 #include <algo/blast/core/blast_gapalign.h> 43 #include <algo/blast/core/blast_hits.h> 44 #include <algo/blast/core/blast_options.h> 45 #include <algo/blast/core/blast_parameters.h> 46 #include <algo/blast/core/blast_seqsrc.h> 47 #include <algo/blast/core/blast_diagnostics.h> 48 #include <algo/blast/core/blast_hspstream.h> 49 #include <algo/blast/core/na_ungapped.h> 50 51 #ifdef __cplusplus 52 extern "C" { 53 #endif 54 55 NCBI_XBLAST_EXPORT 56 extern const int kBlastMajorVersion; /**< Major version */ 57 NCBI_XBLAST_EXPORT 58 extern const int kBlastMinorVersion; /**< Minor version */ 59 NCBI_XBLAST_EXPORT 60 extern const int kBlastPatchVersion; /**< Patch version */ 61 /** Date of the most recent BLAST release (kept for historical reasons) */ 62 NCBI_XBLAST_EXPORT 63 extern const char* kBlastReleaseDate; 64 65 66 /** The high level function performing the BLAST search against a BLAST 67 * database after all the setup has been done. 68 * @param program_number Type of BLAST program [in] 69 * @param query The query sequence [in] 70 * @param query_info Additional query information [in] 71 * @param seq_src Structure containing BLAST database [in] 72 * @param sbp Scoring and statistical parameters [in] 73 * @param score_options Hit scoring options [in] 74 * @param lookup_wrap The lookup table, constructed earlier [in] 75 * @param word_options Options for processing initial word hits [in] 76 * @param ext_options Options and parameters for the gapped extension [in] 77 * @param hit_options Options for saving the HSPs [in] 78 * @param eff_len_options Options for setting effective lengths [in] 79 * @param psi_options Options specific to PSI-BLAST [in] 80 * @param db_options Options for handling BLAST database [in] 81 * @param hsp_stream Structure for streaming results [in] [out] 82 * @param rps_info RPS BLAST auxiliary data structure [in] 83 * @param diagnostics Return statistics containing numbers of hits on 84 * different stages of the search [out] 85 * @param results Results of the BLAST search [out] 86 * @param interrupt_search function callback to allow interruption of BLAST 87 * search [in, optional] 88 * @param progress_info contains information about the progress of the current 89 * BLAST search [in|out] 90 */ 91 Int4 92 Blast_RunFullSearch(EBlastProgramType program_number, 93 BLAST_SequenceBlk* query, BlastQueryInfo* query_info, 94 const BlastSeqSrc* seq_src, BlastScoreBlk* sbp, 95 const BlastScoringOptions* score_options, 96 LookupTableWrap* lookup_wrap, 97 const BlastInitialWordOptions* word_options, 98 const BlastExtensionOptions* ext_options, 99 const BlastHitSavingOptions* hit_options, 100 const BlastEffectiveLengthsOptions* eff_len_options, 101 const PSIBlastOptions* psi_options, 102 const BlastDatabaseOptions* db_options, 103 BlastHSPStream* hsp_stream, const BlastRPSInfo* rps_info, 104 BlastDiagnostics* diagnostics, BlastHSPResults** results, 105 TInterruptFnPtr interrupt_search, 106 SBlastProgress* progress_info); 107 108 /** Perform the preliminary stage of the BLAST search. 109 * @param program_number Type of BLAST program [in] 110 * @param query The query sequence [in] 111 * @param query_info Additional query information [in] 112 * @param seq_src Structure containing BLAST database [in] 113 * @param gap_align Structure containing scoring block and memory allocated 114 * for gapped alignment. [in] 115 * @param score_params Hit scoring parameters [in] 116 * @param lookup_wrap The lookup table, constructed earlier [in] 117 * @param word_options Options for processing initial word hits [in] 118 * @param ext_params Parameters for the gapped extension [in] 119 * @param hit_params Parameters for saving the HSPs [in] 120 * @param eff_len_params Parameters for setting effective lengths [in] 121 * @param psi_options Options specific to PSI-BLAST [in] 122 * @param db_options Options for handling BLAST database [in] 123 * @param hsp_stream Placeholder for saving HSP lists [in] 124 * @param diagnostics Return statistics containing numbers of hits on 125 * different stages of the search. Statistics saved only 126 * for the allocated parts of the structure. [in] [out] 127 * @param interrupt_search function callback to allow interruption of BLAST 128 * search [in, optional] 129 * @param progress_info contains information about the progress of the current 130 * BLAST search [in|out] 131 */ 132 Int4 133 BLAST_PreliminarySearchEngine(EBlastProgramType program_number, 134 BLAST_SequenceBlk* query, BlastQueryInfo* query_info, 135 const BlastSeqSrc* seq_src, BlastGapAlignStruct* gap_align, 136 BlastScoringParameters* score_params, 137 LookupTableWrap* lookup_wrap, 138 const BlastInitialWordOptions* word_options, 139 BlastExtensionParameters* ext_params, 140 BlastHitSavingParameters* hit_params, 141 BlastEffectiveLengthsParameters* eff_len_params, 142 const PSIBlastOptions* psi_options, 143 const BlastDatabaseOptions* db_options, 144 BlastHSPStream* hsp_stream, BlastDiagnostics* diagnostics, 145 TInterruptFnPtr interrupt_search, SBlastProgress* progress_info); 146 147 /** The high level function performing the BLAST search against a BLAST 148 * database after all the setup has been done. 149 * @param program_number Type of BLAST program [in] 150 * @param query The query sequence [in] 151 * @param query_info Additional query information [in] 152 * @param seq_src Structure containing BLAST database [in] 153 * @param score_options Hit scoring options [in] 154 * @param sbp Scoring and statistical parameters [in] 155 * @param lookup_wrap The lookup table, constructed earlier [in] 156 * @param word_options Options for processing initial word hits [in] 157 * @param ext_options Options and parameters for the gapped extension [in] 158 * @param hit_options Options for saving the HSPs [in] 159 * @param eff_len_options Options for setting effective lengths [in] 160 * @param psi_options Options specific to PSI-BLAST [in] 161 * @param db_options Options for handling BLAST database [in] 162 * @param hsp_stream Structure for streaming results [in] [out] 163 * @param diagnostics Return statistics containing numbers of hits on 164 * different stages of the search [out] 165 */ 166 Int2 167 Blast_RunPreliminarySearch(EBlastProgramType program, 168 BLAST_SequenceBlk* query, BlastQueryInfo* query_info, 169 const BlastSeqSrc* seq_src, const BlastScoringOptions* score_options, 170 BlastScoreBlk* sbp, LookupTableWrap* lookup_wrap, 171 const BlastInitialWordOptions* word_options, 172 const BlastExtensionOptions* ext_options, 173 const BlastHitSavingOptions* hit_options, 174 const BlastEffectiveLengthsOptions* eff_len_options, 175 const PSIBlastOptions* psi_options, const BlastDatabaseOptions* db_options, 176 BlastHSPStream* hsp_stream, BlastDiagnostics* diagnostics); 177 178 179 /** Same as above, with support for user interrupt function 180 * @param program_number Type of BLAST program [in] 181 * @param query The query sequence [in] 182 * @param query_info Additional query information [in] 183 * @param seq_src Structure containing BLAST database [in] 184 * @param score_options Hit scoring options [in] 185 * @param sbp Scoring and statistical parameters [in] 186 * @param lookup_wrap The lookup table, constructed earlier [in] 187 * @param word_options Options for processing initial word hits [in] 188 * @param ext_options Options and parameters for the gapped extension [in] 189 * @param hit_options Options for saving the HSPs [in] 190 * @param eff_len_options Options for setting effective lengths [in] 191 * @param psi_options Options specific to PSI-BLAST [in] 192 * @param db_options Options for handling BLAST database [in] 193 * @param hsp_stream Structure for streaming results [in] [out] 194 * @param diagnostics Return statistics containing numbers of hits on 195 * different stages of the search [out] 196 * @param interrupt_search User defined function to interrupt search [in] 197 * @param progress_info User supplied data structure to aid interrupt [in] 198 */ 199 Int2 200 Blast_RunPreliminarySearchWithInterrupt(EBlastProgramType program, 201 BLAST_SequenceBlk* query, BlastQueryInfo* query_info, 202 const BlastSeqSrc* seq_src, const BlastScoringOptions* score_options, 203 BlastScoreBlk* sbp, LookupTableWrap* lookup_wrap, 204 const BlastInitialWordOptions* word_options, 205 const BlastExtensionOptions* ext_options, 206 const BlastHitSavingOptions* hit_options, 207 const BlastEffectiveLengthsOptions* eff_len_options, 208 const PSIBlastOptions* psi_options, const BlastDatabaseOptions* db_options, 209 BlastHSPStream* hsp_stream, BlastDiagnostics* diagnostics, 210 TInterruptFnPtr interrupt_search, SBlastProgress* progress_info); 211 212 /** Gapped extension function pointer type */ 213 typedef Int2 (*BlastGetGappedScoreType) 214 (EBlastProgramType, /**< @todo comment function pointer types */ 215 BLAST_SequenceBlk*, 216 BlastQueryInfo*, 217 BLAST_SequenceBlk*, 218 BlastGapAlignStruct*, 219 const BlastScoringParameters*, 220 const BlastExtensionParameters*, 221 const BlastHitSavingParameters*, 222 BlastInitHitList*, 223 BlastHSPList**, 224 BlastGappedStats*, 225 Boolean * fence_hit); 226 227 /** Word finder function pointer type */ 228 typedef Int2 (*BlastWordFinderType) 229 (BLAST_SequenceBlk*, /**< @todo comment function pointer types */ 230 BLAST_SequenceBlk*, 231 BlastQueryInfo*, 232 LookupTableWrap*, 233 Int4**, 234 const BlastInitialWordParameters*, 235 Blast_ExtendWord*, 236 BlastOffsetPair*, 237 Int4, 238 BlastInitHitList*, 239 BlastUngappedStats*); 240 241 /** Short read mapper function pointer type */ 242 typedef Int2 (*JumperGappedType) 243 (BLAST_SequenceBlk*, 244 BLAST_SequenceBlk*, 245 BlastQueryInfo*, 246 LookupTableWrap*, 247 const BlastInitialWordParameters*, 248 const BlastScoringParameters*, 249 const BlastHitSavingParameters*, 250 BlastOffsetPair* offset_pairs, 251 MapperWordHits* mapper_wordhits, 252 Int4, 253 BlastGapAlignStruct*, 254 BlastInitHitList*, 255 BlastHSPList**, 256 BlastUngappedStats*, 257 BlastGappedStats*); 258 259 260 261 #ifdef __cplusplus 262 } 263 #endif 264 #endif /* !ALGO_BLAST_CORE__BLAST_ENGINE__H */ 265