/* $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 <algo/blast/core/blast_options.h>
#include <algo/blast/core/blast_hits.h>
#include <algo/blast/core/blast_diagnostics.h>   
#include <algo/blast/api/blast_message_api.h>   
#include <blfmtutl.h>

/** @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__ */

