1 /* $Id: blast_api.h,v 1.11 2016/06/21 13:53:41 madden Exp $ 2 *************************************************************************** 3 * * 4 * COPYRIGHT NOTICE * 5 * * 6 * This software/database is categorized as "United States Government * 7 * Work" under the terms of the United States Copyright Act. It was * 8 * produced as part of the author's official duties as a Government * 9 * employee and thus can not be copyrighted. This software/database is * 10 * freely available to the public for use without a copyright notice. * 11 * Restrictions can not be placed on its present or future use. * 12 * * 13 * Although all reasonable efforts have been taken to ensure the accuracy * 14 * and reliability of the software and data, the National Library of * 15 * Medicine (NLM) and the U.S. Government do not and can not warrant the * 16 * performance or results that may be obtained by using this software, * 17 * data, or derivative works thereof. The NLM and the U.S. Government * 18 * disclaim any and all warranties, expressed or implied, as to the * 19 * performance, merchantability or fitness for any particular purpose or * 20 * use. * 21 * * 22 * In any work or product derived from this material, proper attribution * 23 * of the author(s) as the source of the software or data would be * 24 * appreciated. * 25 * ========================================================================= 26 * 27 * Author: Ilya Dondoshansky 28 * 29 */ 30 31 /** @file blast_api.h 32 * Functions for C toolkit applications to run BLAST searches using the 33 * rewritten BLAST engine. 34 */ 35 36 #ifndef _BLAST_API_H_ 37 #define _BLAST_API_H_ 38 39 #ifdef __cplusplus 40 extern "C" { 41 #endif 42 43 #ifndef NCBI_C_TOOLKIT 44 #define NCBI_C_TOOLKIT 45 #endif 46 47 #include <algo/blast/api/blast_tabular.h> 48 #include <algo/blast/api/blast_options_api.h> 49 #include <algo/blast/api/blast_seqalign.h> 50 #include <algo/blast/api/blast_input.h> 51 52 /** @addtogroup CToolkitAlgoBlast 53 * 54 * @{ 55 */ 56 57 /** Initialize the genetic code singleton. 58 * This function must be called before running any BLAST search with the new 59 * engine */ 60 void GeneticCodeSingletonInit(); 61 62 /** Uinitialize the genetic code singleton. 63 * This function must be called after running any BLAST search with the new 64 * engine */ 65 void GeneticCodeSingletonFini(); 66 67 /** Compares a list of SeqLoc's against a BLAST database using the 68 * BLAST algorithm. 69 * @param query_seqloc List of query Seq-loc's [in] 70 * @param psi_matrix_file a checkpoint file for PSSM searches [in] 71 * @param db_name Name of a BLAST database to search [in] 72 * @param masking_locs Locations in the queries that should be masked [in] 73 * @param options Search options [in] 74 * @param tf_data Structure to use for on-the-fly tabular formatting [in] 75 * @param seqalign_arr object that holds the array of SeqAligns [out] 76 * @param filter_out Filtering locations [out] 77 * @param extra_returns Additional information about the search [out] 78 */ 79 Int2 80 Blast_DatabaseSearch(SeqLoc* query_seqloc, 81 Blast_PsiCheckpointLoc * psi_checkpoint, 82 char* db_name, 83 SeqLoc* masking_locs, 84 const SBlastOptions* options, 85 BlastTabularFormatData* tf_data, 86 SBlastSeqalignArray* *seqalign_arr, 87 SeqLoc** filter_out, 88 Blast_SummaryReturn* extra_returns); 89 90 /** Compares a list of SeqLoc's against another list of SeqLoc's, 91 * using the BLAST algorithm, with all options preset. 92 * @param query_seqloc List of query Seq-loc's [in] 93 * @param subject_seqloc List of subject Seq-loc's [in] 94 * @param masking_locs Locations in the queries that should be masked [in] 95 * @param options Search options [in] 96 * @param tf_data Structure to use for on-the-fly tabular formatting [in] 97 * @param seqalign_arr object that holds the array of SeqAligns [out] 98 * @param filter_out Filtering locations [out] 99 * @param extra_returns Additional information about the search [out] 100 */ 101 Int2 102 Blast_TwoSeqLocSetsAdvanced(SeqLoc* query_seqloc, 103 SeqLoc* subject_seqloc, 104 SeqLoc* masking_locs, 105 const SBlastOptions* options, 106 BlastTabularFormatData* tf_data, 107 SBlastSeqalignArray* *seqalign_arr, 108 SeqLoc** filter_out, 109 Blast_SummaryReturn* extra_returns); 110 111 /** Compare a list of query SeqLoc's against a source of subject sequences. 112 * @param query_seqloc List of query sequences locations [in] 113 * @param psi_matrix_file a checkpoint file for PSSM searches [in] 114 * @param seq_src Source of subject sequences [in] 115 * @param masking_locs Locations where query sequences should be masked. [in] 116 * @param options Search options [in] 117 * @param tf_data Tabular formatting data [in] 118 * @param results Search results [out] 119 * @param filter_out Query locations that were masked (filtered) during the 120 * search [out] 121 * @param extra_returns Additional search statistits [out] 122 * @return 0 on success, -1 on failure. 123 */ 124 Int2 125 Blast_RunSearch(SeqLoc* query_seqloc, 126 Blast_PsiCheckpointLoc * psi_checkpoint, 127 BlastSeqSrc* seq_src, 128 SeqLoc* masking_locs, 129 const SBlastOptions* options, 130 BlastTabularFormatData* tf_data, 131 BlastHSPResults **results, 132 SeqLoc** filter_out, 133 Blast_SummaryReturn* extra_returns); 134 135 /** Run a PHI BLAST search for a query SeqLoc against a database. Return results 136 * in a list of ValNode pointers, containing Seq-aligns corresponding to 137 * different pattern occurrences in query. 138 * @param query_seqloc List of query sequences locations [in] 139 * @param db_name Name of database to search [in] 140 * @param masking_locs Locations where query sequences should be masked. [in] 141 * @param options Search options [in] 142 * @param phivnps List of ValNode pointers with search results, one ValNode per 143 * query pattern occurrence. 144 * ValNode data points to a Seq-align. [out] 145 * @param filter_out Query locations that were masked (filtered) during the 146 * search. [out] 147 * @param extra_returns Additional search statistits [out] 148 * @return 0 on success, -1 on failure. 149 */ 150 Int2 151 PHIBlastRunSearch(SeqLoc* query_seqloc, char* db_name, SeqLoc* masking_locs, 152 const SBlastOptions* options, ValNode* *phivnps, 153 SeqLoc** filter_out, Blast_SummaryReturn* extra_returns); 154 155 /* @} */ 156 157 #ifdef __cplusplus 158 } 159 #endif 160 161 #endif /* !_BLAST_API_H_ */ 162