/* $Id: blast_returns.h,v 1.15 2007/07/10 15:28:07 papadopo Exp $ * =========================================================================== * * PUBLIC DOMAIN NOTICE * National Center for Biotechnology Information * * This software/database is a "United States Government Work" under the * terms of the United States Copyright Act. It was written as part of * the author's offical duties as a United States Government employee and * thus cannot be copyrighted. This software/database is freely available * to the public for use. The National Library of Medicine and the U.S. * Government have not placed any restriction on its use or reproduction. * * Although all reasonable efforts have been taken to ensure the accuracy * and reliability of the software and data, the NLM and the U.S. * Government do not and cannot warrant the performance or results that * may be obtained by using this software or data. The NLM and the U.S. * Government disclaim all warranties, express or implied, including * warranties of performance, merchantability or fitness for any particular * purpose. * * Please cite the author in any work or product based on this material. * * Author: Ilya Dondoshansky * ===========================================================================*/ /** @file blast_returns.h * Manipulation of data returned from BLAST other than Seq-aligns */ #ifndef __BLAST_RETURNS__ #define __BLAST_RETURNS__ #ifdef __cplusplus extern "C" { #endif #ifndef NCBI_C_TOOLKIT #define NCBI_C_TOOLKIT #endif #include #include #include #include #include /** @addtogroup CToolkitAlgoBlast * * @{ */ /** Small structure containing the just those Karlin-Altschul parameters needed * for the BLAST formatting */ typedef struct BLAST_KAParameters { double Lambda; /**< Karlin-Altschul scaling parameter. */ double K; /**< Karlin-Altschul K parameter. */ double H; /**< Karlin-Altschul entropy */ double C; /**< Constant factor for PHI BLAST e-values. */ } BLAST_KAParameters; /** Small structure containing some numbers about database length, adjustment, * etc. */ typedef struct BLAST_DatabaseStats { Int4 dbnum; /**< number of sequences in database search */ Int8 dblength; /**< Length of databases. */ Int8 eff_dblength; /**< Length of databases with edge corrections. */ Int4 qlen; /**< Length of query with edge corrections. */ Int4 eff_qlen; /**< Length of query with edge corrections. */ Int4 hsp_length; /**< Expect length of an HSP. */ Int8 eff_searchsp; /**< effective search-space */ Int8 eff_searchsp_used; /**< effective search-space actually used. */ } Blast_DatabaseStats; /** Small structure containing relevant search parameters. * Mostly for use in building XML or footer in BLAST report. */ typedef struct Blast_SearchParams { Boolean gapped_search; /**< true if a gapped search. */ Int4 gap_open; /**< Cost of gap existence. */ Int4 gap_extension; /**< Cost to extend gap by one letter. */ char* filter_string; /**< filtering command. */ char* matrix; /**< name of matrix (e.g., BLOSUM62) */ double expect; /**< expect value cutoff. */ Int4 match; /**< reward for a match (blastn only) */ Int4 mismatch; /**< penalty for a mismatch (blastn only) */ char* pattern; /**< phi-blast pattern used. */ char* entrez_query; /**< query to entrez */ double ethresh; /**< PSI-BLAST threshold to keep HSPs in profile. */ double threshold; /**< threshold to start extension of hits. */ Int4 window_size; /**< max allowed distance between hits to init extension in 2-hit mode. */ } Blast_SearchParams; Int2 Blast_SearchParamsFill(EBlastProgramType program_number, const BlastScoringOptions* score_options, const LookupTableOptions* lookup_options, const BlastHitSavingOptions* hit_options, const QuerySetUpOptions* query_setup, const BlastInitialWordOptions* word_options, const char* entrez_query, Blast_SearchParams** search_params); /** Structure holding all calculated data returned from a BLAST search other * than the alignment. */ typedef struct Blast_SummaryReturn { BLAST_KAParameters* ka_params; /**< Ungapped Karlin-Altschul parameters */ BLAST_KAParameters* ka_params_gap;/**< Gapped Karlin-Altschul parameters */ Blast_DatabaseStats* db_stats; /**< database numbers and adjustments */ Blast_SearchParams* search_params;/**< parameters used in search. */ BlastDiagnostics* diagnostics; /**< diagnositics from engine. */ SBlastMessage* error; /**< Error or warning message. */ SPHIQueryInfo* pattern_info; /**< In PHI BLAST only: information about pattern occurrences in query. */ } Blast_SummaryReturn; /** Retrieves necessary information from a sequence source and fills the * TxDfDbInfo structure. * @param rdfp pointer to BLAST db reader [in] * @return pointer to info about database. */ TxDfDbInfo* Blast_GetDbInfo(ReadDBFILE* rdfp); /** Formats the BLAST parameters for the BLAST report. * * @param program_number indicates blastn, blastp, etc. [in] * @param sum_return object constructed by Blast_SummaryReturnFill, used * to fill buffer [in] * @return char* with information, newlines indicated by tildes ('~'). */ char* Blast_GetParametersBuffer(EBlastProgramType program_number, const Blast_SummaryReturn* sum_return); /** Fills the summary returns from the provided information. * NOTE: either one of rdfp or subject_loc (below) can be NULL, * but not both. * @param program_number Type of BLAST program [in] * @param score_options pointer for scoring options [in] * @param sbp Karlin-Altschul/statistics information [in] * @param lookup_options pointer for lookup table options [in] * @param word_options pointer for word finding options [in] * @param ext_options pointer for extension options [in] * @param hit_options pointer for hit saving options [in] * @param eff_len_options pointer for effective length options [in] * @param query_setup pointer for query setup options [in] * @param query_info Information about query. Note: in PHI BLAST, the query * pattern information pointer is passed on to the sum_returns * structure and set to NULL in the query_info within this * function. [in] * @param seq_src Source of subject sequences [in] * @param diagnostics pointer to diagnostic information, SET to NULL * on return [in|out] * @param sum_returns Object to be filled in. Must be already allocated. [out] * @return zero returned on success */ Int2 Blast_SummaryReturnFill(EBlastProgramType program_number, const BlastScoringOptions* score_options, const BlastScoreBlk* sbp, const LookupTableOptions* lookup_options, const BlastInitialWordOptions* word_options, const BlastExtensionOptions* ext_options, const BlastHitSavingOptions* hit_options, const BlastEffectiveLengthsOptions* eff_len_options, const QuerySetUpOptions* query_setup, const BlastQueryInfo* query_info, const BlastSeqSrc* seq_src, BlastDiagnostics** diagnostics, Blast_SummaryReturn* sum_returns); /** Allocate the Blast_SummaryReturn structure */ Blast_SummaryReturn* Blast_SummaryReturnNew(void); /** Deallocates memory for the summary returns structure * @param sum_return object to be freed [in] * @return NULL pointer */ Blast_SummaryReturn* Blast_SummaryReturnFree(Blast_SummaryReturn* sum_return); /** Frees the contents of the summary returns structure, but not the structure * itself. * @param sum_returns Structure to clean. [in] [out] */ void Blast_SummaryReturnClean(Blast_SummaryReturn* sum_returns); /** Updates the summary returns structure in case of multiple iterations * over the database. The hit counts from all iterations are aggregated in the * diagnostics structure. The rest of the data is copied from the new summary * returns. * @param new_return Data returned from the new database scan [in] * @param full_return The aggregate return. [in] [out] */ int Blast_SummaryReturnUpdate(const Blast_SummaryReturn* new_return, Blast_SummaryReturn* *full_return); /* @} */ #ifdef __cplusplus } #endif #endif /* !__BLAST_FORMAT__ */