1 /* $Id: blast_query_info.h 419604 2013-11-26 22:49:06Z rafanovi $ 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: Christiam Camacho 27 * 28 */ 29 30 /** @file blast_query_info.h 31 * Definitions and functions associated with the BlastQueryInfo structure 32 */ 33 34 #ifndef ALGO_BLAST_CORE__BLAST_QUERY_INFO__H 35 #define ALGO_BLAST_CORE__BLAST_QUERY_INFO__H 36 37 #include "ncbi_std.h" 38 #include "blast_def.h" 39 #include "blast_program.h" 40 41 #ifdef __cplusplus 42 extern "C" { 43 #endif 44 45 /** The context related information */ 46 typedef struct BlastContextInfo { 47 Int4 query_offset; /**< Offset of this query, strand or frame in the 48 concatenated super-query. */ 49 Int4 query_length; /**< Length of this query, strand or frame */ 50 Int8 eff_searchsp; /**< Effective search space for this context. */ 51 Int4 length_adjustment; /**< Length adjustment for boundary conditions */ 52 Int4 query_index; /**< Index of query (same for all frames) */ 53 Int1 frame; /**< Frame number (-1, -2, -3, 0, 1, 2, or 3) */ 54 bool is_valid; /**< Determine if this context is valid or not. 55 This field should be set only by the setup code 56 and read by subsequent stages of the BLAST search 57 */ 58 } BlastContextInfo; 59 60 /** Forward declaration of SPHIQueryInfo */ 61 struct SPHIQueryInfo; 62 63 /** The query related information 64 */ 65 typedef struct BlastQueryInfo { 66 Int4 first_context; /**< Index of the first element of the context array */ 67 Int4 last_context; /**< Index of the last element of the context array */ 68 int num_queries; /**< Number of query sequences */ 69 BlastContextInfo * contexts; /**< Information per context */ 70 Uint4 max_length; /**< Length of the longest among the concatenated 71 queries */ 72 struct SPHIQueryInfo* pattern_info; /**< Counts of PHI BLAST pattern 73 occurrences, used in PHI BLAST only. */ 74 } BlastQueryInfo; 75 76 77 /** Allocate memory for query information structure */ 78 NCBI_XBLAST_EXPORT 79 BlastQueryInfo* BlastQueryInfoNew(EBlastProgramType program, int num_queries); 80 81 /** Deallocate memory for query information structure */ 82 NCBI_XBLAST_EXPORT 83 BlastQueryInfo* BlastQueryInfoFree(BlastQueryInfo* query_info); 84 85 /** Duplicates the query information structure */ 86 NCBI_XBLAST_EXPORT 87 BlastQueryInfo* BlastQueryInfoDup(const BlastQueryInfo* query_info); 88 89 /** Given a context from BLAST engine core, return the query index. 90 * @param context Context saved in a BlastHSP structure [in] 91 * @param program Type of BLAST program [in] 92 * @return Query index in a set of queries or -1 on error 93 */ 94 NCBI_XBLAST_EXPORT 95 Int4 Blast_GetQueryIndexFromContext(Int4 context, EBlastProgramType program); 96 97 98 /** Return the query index (zero based), given the query offset 99 * in the initial HSP as the program. 100 * @param query_offset Offset of the query in the initial HSP [in] 101 * @param program EBlastProgramType [in] 102 * @param query_info information about all the queries [in] 103 * @return Query Index in a set of queries 104 */ 105 NCBI_XBLAST_EXPORT 106 Int4 Blast_GetQueryIndexFromQueryOffset(Int4 query_offset, EBlastProgramType program, const BlastQueryInfo* query_info); 107 108 109 /** Retrieve a query sequence's search space 110 * @param qinfo BlastQueryInfo structure [in] 111 * @param program CORE program type [in] 112 * @param query_index number of the query 113 * (query_index < BlastQueryInfo::num_queries) [in] 114 * @return the search space of the query sequence requested or 0 if this is not 115 * set */ 116 NCBI_XBLAST_EXPORT 117 Int8 118 BlastQueryInfoGetEffSearchSpace(const BlastQueryInfo* qinfo, 119 EBlastProgramType program, 120 Int4 query_index); 121 122 /** Set a query sequence's search space 123 * @param qinfo BlastQueryInfo structure [in] 124 * @param program CORE program type [in] 125 * @param query_index number of the query 126 * (query_index < BlastQueryInfo::num_queries) [in] 127 * @param eff_searchsp the effective search space to use [in] 128 */ 129 NCBI_XBLAST_EXPORT 130 void 131 BlastQueryInfoSetEffSearchSpace(BlastQueryInfo* qinfo, 132 EBlastProgramType program, 133 Int4 query_index, 134 Int8 eff_searchsp); 135 136 /** Obtains the sequence length for a given query in the query, without taking 137 * into consideration any applicable translations 138 * @param qinfo BlastQueryInfo structure [in] 139 * @param program CORE program type [in] 140 * @param query_index number of the query 141 * (query_index < BlastQueryInfo::num_queries) [in] 142 * @return the length of the query sequence requested 143 */ 144 NCBI_XBLAST_EXPORT 145 Int4 BlastQueryInfoGetQueryLength(const BlastQueryInfo* qinfo, 146 EBlastProgramType program, 147 Int4 query_index); 148 149 /** Create auxiliary query structures with all data corresponding 150 * to a single query sequence within a concatenated set. Allocates the 151 * structures if the pointers are NULL on input; otherwise only changes the 152 * contents. 153 * @param one_query_info_ptr Pointer to the query information structure for a 154 * single query. Allocated and filled here, so the 155 * caller of this function will be responsible for 156 * freeing it. [out] 157 * @param one_query_ptr Pointer to the query sequence block structure; allocated 158 * here, but the contents are not allocated; it is still 159 * safe to free by the caller after use. [out] 160 * @param query_info Query information structure containing information about a 161 * concatenated set. [in] 162 * @param query Query sequence block corresponding to a concatenated set of 163 * queries. [in] 164 * @param query_index Which query index to create the auxiliary structures 165 * for? [in] 166 * @return -1 if memory allocation failed; 0 on success 167 */ 168 NCBI_XBLAST_EXPORT 169 Int2 Blast_GetOneQueryStructs(BlastQueryInfo** one_query_info_ptr, 170 BLAST_SequenceBlk** one_query_ptr, 171 const BlastQueryInfo* query_info, 172 BLAST_SequenceBlk* query, Int4 query_index); 173 174 /** Search BlastContextInfo structures for the specified offset */ 175 NCBI_XBLAST_EXPORT 176 Int4 BSearchContextInfo(Int4 n, const BlastQueryInfo * A); 177 178 /** Get the number of bytes required for the concatenated sequence 179 * buffer, given a query info structure. The context data should 180 * already be assigned. 181 * @param qinfo Query info structure. [in/out] 182 * @return Number of bytes for all queries and inter-query marks. 183 */ 184 NCBI_XBLAST_EXPORT 185 Uint4 186 QueryInfo_GetSeqBufLen(const BlastQueryInfo* qinfo); 187 188 189 /** Copy the context query offsets to an allocated array of Int4. 190 * @param info Describes the concatenated query. 191 * @return Allocated array. 192 */ 193 NCBI_XBLAST_EXPORT 194 Int4 * ContextOffsetsToOffsetArray(const BlastQueryInfo* info); 195 196 197 /** Copy the context query offsets from an array of Int4, allocating 198 * the context array if needed. 199 * @param info Destination for the values. 200 * @param new_offsets Array of values to copy from. 201 * @param prog The blast program type. 202 */ 203 NCBI_XBLAST_EXPORT 204 void OffsetArrayToContextOffsets(BlastQueryInfo * info, 205 Int4 * new_offsets, 206 EBlastProgramType prog); 207 208 #ifdef __cplusplus 209 } 210 #endif 211 212 #endif /* !ALGO_BLAST_CORE__BLAST_QUERY_INFO__H */ 213