1 /* $Id: blast_options_api.h,v 1.14 2007/03/08 14:57:31 kans 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 * Author: Ilya Dondoshansky 27 * 28 */ 29 30 /** @file blast_options_api.h 31 * Wrapper API around the core options structures used in BLAST. 32 */ 33 34 #ifndef _BLAST_OPTIONS_API_H_ 35 #define _BLAST_OPTIONS_API_H_ 36 37 #ifdef __cplusplus 38 extern "C" { 39 #endif 40 41 #ifndef NCBI_C_TOOLKIT 42 #define NCBI_C_TOOLKIT 43 #endif 44 45 #include <algo/blast/core/blast_options.h> 46 #include <algo/blast/api/blast_returns.h> 47 48 /** @addtogroup CToolkitAlgoBlast 49 * 50 * @{ 51 */ 52 53 /** Wrapper structure, containing all BLAST options. */ 54 typedef struct SBlastOptions { 55 EBlastProgramType program; /**< Type of BLAST program */ 56 QuerySetUpOptions* query_options; /**< Options for query sequence set up. */ 57 LookupTableOptions* lookup_options; /**< Lookup table options. */ 58 BlastInitialWordOptions* word_options; /**< Options for choosing and 59 extending initial seeds (words) */ 60 BlastScoringOptions* score_options; /**< Scoring options */ 61 BlastExtensionOptions* ext_options; /**< Gapped extension options */ 62 BlastHitSavingOptions* hit_options; /**< Hit saving options */ 63 BlastEffectiveLengthsOptions* eff_len_options; /**< Effective lengths 64 options */ 65 PSIBlastOptions* psi_options; /**< Options specific to PSI BLAST */ 66 BlastDatabaseOptions* db_options; /**< Structure containing database genetic 67 code */ 68 int num_cpus; /**< Number of CPUs to use for preliminary stage of the 69 search. */ 70 Boolean believe_query; /**< if TRUE then we are using user Query ID. */ 71 } SBlastOptions; 72 73 /** Allocates all core options structures and initializes them with default 74 * values. 75 * @param program BLAST program name. [in] 76 * @param options Resulting structure [out] 77 * @param extra_returns Extra returns structure, to put error message in [out] 78 */ 79 Int2 SBlastOptionsNew(const char* program, SBlastOptions** options, 80 Blast_SummaryReturn* extra_returns); 81 82 /** Frees the SBlastOptions structure and all core options. 83 * @param options Structure to free. 84 */ 85 SBlastOptions* SBlastOptionsFree(SBlastOptions* options); 86 87 /** Sets the expect value threshold option. 88 * @param options Options wrapper structure. [in] [out] 89 * @param evalue Value to set. [in] 90 */ 91 Int2 SBlastOptionsSetEvalue(SBlastOptions* options, double evalue); 92 93 /** Sets the word size option. 94 * @param options Options wrapper structure. [in] [out] 95 * @param word_size Value to set. [in] 96 */ 97 Int2 SBlastOptionsSetWordSize(SBlastOptions* options, Int4 word_size); 98 99 /** Sets parameters for discontiguous Mega BLAST. 100 * @param options Options wrapper structure. [in] [out] 101 * @param template_length Discontiguous word template length value to set. [in] 102 * @param template_type Discontiguous word template type value to set. 103 * (0 or 1) [in] 104 */ 105 Int2 SBlastOptionsSetDiscMbParams(SBlastOptions* options, Int4 template_length, 106 Int4 template_type); 107 108 /** Reset matrix name and gap costs to new values. 109 * 110 * @param options Options structure to update. [in] [out] 111 * @param matrix_name New matrix name [in] 112 * @param gap_open New gap existence cost. If zero default for matrix is used. [in] 113 * @param gap_extend New gap extension cost. If zero default for matrix is used. [in] 114 */ 115 Int2 SBlastOptionsSetMatrixAndGapCosts(SBlastOptions* options, 116 const char* matrix_name, 117 Int4 gap_open, 118 Int4 gap_extend); 119 120 121 /** Reset rewared, penalty and gap costs to new values. 122 * 123 * @param options Options structure to update. [in] [out] 124 * @param reward match score [in] 125 * @param penalty mismatch score [in] 126 * @param gap_open New gap existence cost. If -1, default for reward/penalty is used. [in] 127 * @param gap_extend New gap extension cost. If -1, default for reward/penalty is used. [in] 128 * @param greedy TRUE specifies that greedy algorithms will be used. [in] 129 */ 130 Int2 SBlastOptionsSetRewardPenaltyAndGapCosts(SBlastOptions* options, 131 Int4 reward, Int4 penalty, 132 Int4 gap_open, Int4 gap_extend, 133 Boolean greedy); 134 135 /** Set threshold value. 136 * @param options options Options structure to update. [in] [out] 137 * @param threshold New value to set, if zero default value for matrix 138 * will be used. [in] 139 * @return zero unless error (e.g., threshold is < zero) 140 */ 141 Int2 SBlastOptionsSetThreshold(SBlastOptions* options, 142 double threshold); 143 144 /** Set window size for two hit extension. 145 * @param options options Options structure to update. [in] [out] 146 * @param window_size New value to set, if zero default value for matrix 147 * will be used. [in] 148 * @return zero unless error (e.g., window_size is < zero) 149 */ 150 Int2 SBlastOptionsSetWindowSize(SBlastOptions* options, 151 Int4 window_size); 152 153 /** Reset database (subject) genetic code option to a new value. 154 * @param options Options structure to update. [in] [out] 155 * @param gc New genetic code value. [in] 156 * @return Status: non-zero if genetic code string cannotbe found for gc. 157 */ 158 Int2 SBlastOptionsSetDbGeneticCode(SBlastOptions* options, Int4 gc); 159 160 /** Reset the filter string option. 161 * @param options Options structure to update [in] [out] 162 * @param str New filter string. [in] 163 * @return Status. 164 */ 165 Int2 SBlastOptionsSetFilterString(SBlastOptions* options, const char* str); 166 167 /** Returns the mask-at-hash option value. 168 * @param options The options structure [in] 169 * @return Boolean value of the masking at hash option. 170 */ 171 Boolean SBlastOptionsGetMaskAtHash(const SBlastOptions* options); 172 173 174 /** sets believe_query flag on SBlastOptions. 175 * @param options Object to be modified [in] 176 * @param believe_query specifies that query ID was parsed [in] 177 * @return zero on success. 178 */ 179 Int2 SBlastOptionsSetBelieveQuery(SBlastOptions* options, Boolean believe_query); 180 181 /** Gets believe_query field of SBlastOptions. 182 * @param options Object to be queried for information [in] 183 * @return TRUE if query ID was parsed, otherwise FALSE. 184 */ 185 Boolean SBlastOptionsGetBelieveQuery(const SBlastOptions* options); 186 187 /* @} */ 188 189 #ifdef __cplusplus 190 } 191 #endif 192 193 #endif /* !_BLAST_OPTIONS_API_H_ */ 194