/* $Id: blast_format.h,v 1.46 2006/10/06 12:22:00 madden 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_format.h * Functions needed for formatting of BLAST results */ #ifndef __BLAST_FORMAT__ #define __BLAST_FORMAT__ #ifdef __cplusplus extern "C" { #endif #ifndef NCBI_C_TOOLKIT #define NCBI_C_TOOLKIT #endif #include #include #include #include #include #include #include #include #include #include /** @addtogroup CToolkitAlgoBlast * * @{ */ /** Enums for selecting view type (query-anchored, pairwise, etc.) */ typedef enum EAlignView { /** Pairwise. */ eAlignViewPairwise = 0, /** Query anchored with identities. */ eAlignViewQueryAnchoredIdent = 1, /** Query anchored without identities. */ eAlignViewQueryAnchoredNoIdent = 2, /** Flat query anchored with identities. */ eAlignViewFlatQueryAnchoredIdent = 3, /** Flat query anchored without identities. */ eAlignViewFlatQueryAnchoredNoIdent = 4, /** Query anchored with blunt ends. */ eAlignViewQueryAnchoredBluntEnds = 5, /** Flat query anchored with blunt ends. */ eAlignViewFlatQueryAnchoredBluntEnds = 6, /** XML. */ eAlignViewXml = 7, /** Tabular without comments. */ eAlignViewTabular = 8, /** Tabular with per-query comments. */ eAlignViewTabularWithComments = 9, /** ASN.1 in text form. */ eAlignViewAsnText = 10, /** ASN.1 in binary form. */ eAlignViewAsnBinary = 11, /** Sentinel value, binding the allowed range. */ eAlignViewMax } EAlignView; /** Options for formatting BLAST results */ typedef struct BlastFormattingOptions { EAlignView align_view; /**< How to show alignments? */ Uint4 align_options; /**< Options for showing alignments. */ Uint4 print_options; /**< Printing options. */ Boolean believe_query; /**< Should query defline be trusted? */ Boolean html; /**< Create an HTML output? */ Int4 number_of_descriptions; /**< Number of descriptions to show. */ Int4 number_of_alignments; /**< Number of alignments to show. */ Boolean is_megablast; /**< Is this a megablast search? Needed for determination of which reference to use. */ } BlastFormattingOptions; /** Structure containing all information necessary for producing the * formatted BLAST output. */ typedef struct BlastFormattingInfo { const SBlastOptions* search_options; /**< Search options. */ char* program_name; /**< Program name as a sting. */ char* db_name; /**< Database name. Null for a 2 sequences search. */ int num_formatted; /**< Number of queries formatted so far. */ BlastFormattingOptions* format_options; /**< Formatting options. */ FILE* outfp; /**< Output stream for text output. */ AsnIo* aip; /**< Output stream for ASN.1 output */ MBXml* xmlp; /**< Output stream for XML output */ Boolean is_seqalign_null; /**< flag indicating absence of seqalign */ Boolean head_on_every_query; /**< Flag indicating that reference, db, etc. should appear on every entry. */ } BlastFormattingInfo; /** Allocates and initializes the formatting information structure. * @param align_view Alignment view option [in] * @param search_options BLAST search options [in] * @param program_name BLAST program name [in] * @param db_name BLAST database name (NULL for non-database search) [in] * @param outfile_name Name of the output file. [in] * @param info_ptr Initialized structure. [out] */ Int2 BlastFormattingInfoNew(EAlignView align_view, const SBlastOptions* search_options, const char* program_name, const char* db_name, const char* outfile_name, BlastFormattingInfo* *info_ptr); /** Allocate and initialize the formatting information structure, given the * basic two sequences search options. * @param align_view What kind of formatted output to show? [in] * @param basic_options Basic two sequences search options [in] * @param query_seqloc Query Seq-loc [in] * @param outfile_name Name of the output file [in] * @param advanced_options Advanced BLAST search options structure. Must be * returned to avoid memory leak. [out] * @param info_ptr The initialized formatting info structure [out] */ Int2 BlastFormattingInfoNewBasic(EAlignView align_view, const BLAST_SummaryOptions* basic_options, SeqLoc* query_seqloc, const char* outfile_name, SBlastOptions* *advanced_options, BlastFormattingInfo* *info_ptr); /** Fill the formatting options in the formatting info structure. * @param info The structure to work with [in] * @param num_descriptions Number of descriptions to show in the formatted * output. [in] * @param num_alignments Number of alignments to show in the formatted * output. [in] * @param html Format with HTML tags or in plain text? [in] * @param is_megablast Is this a megablast search, needed for correct * reference? [in] * @param show_gi Should gis be shown in database sequence descriptions? [in] * @param believe_defline Should query def-lines be parsed? [in] */ void BlastFormattingInfoSetUpOptions(BlastFormattingInfo* info, Int4 num_descriptions, Int4 num_alignments, Boolean html, Boolean is_megablast, Boolean show_gi, Boolean believe_defline); /** Deallocates the formatting information structure. In particular, closes the * output stream(s). * @param info The structure to free. [in] */ BlastFormattingInfo* BlastFormattingInfoFree(BlastFormattingInfo* info); /** Print formatted output. * @param seqalign_arr object with arrays of seqaligns [in] * @param num_queries Number of query sequences [in] * @param query_slp Linked list of query SeqLocs [in] * @param mask_loc Masking locations for all queries [in] * @param format_info Formatting options and other information [in] * @param sum_returns Summary data returned from the search. [in] */ Int2 BLAST_FormatResults(SBlastSeqalignArray* seqalign_arr, Int4 num_queries, SeqLocPtr query_slp, SeqLoc* mask_loc, BlastFormattingInfo* format_info, Blast_SummaryReturn* sum_returns); /** Print the summary at the end of the BLAST report. * @param format_info Formatting options and other information. [in] * @param sum_returns infor from inside blast engine [in] */ Int2 Blast_PrintOutputFooter(const BlastFormattingInfo* format_info, const Blast_SummaryReturn* sum_returns); /** Prints the top part of the traditional BLAST output, including version, * reference(s) and database information. * @param format_info Formatting options and other information [in] */ Int2 BLAST_PrintOutputHeader(const BlastFormattingInfo* format_info); /** Prints the "log info" at the bottom of the megablast output, looks something * like: * "Mega BLAST run finished, processed 2 queries" * * @param outfp output file pointer [in] * @param num_processed number of records proceessed [in] * stream pointer. [in] * @return 0 on success */ Int2 BlastPrintLogReport(FILE* outfp, Int4 num_processed); /** Given a Seq-id structure, returns a buffer in requested form. * @param sip Seq-id to get information from. [in] * @param buffer_ptr Buffer to fill. [out] * @param ncbi_gi Should the NCBI gi be included in the id buffer? [in] * @param accession_only Should only accession be returned (only gi if ncbi_gi * is TRUE)? [in] * @param search_for_id If TRUE, attempt to find a sequence identifier. * If FALSE, the first token in the defline is treated * as an identifier, even if it is not an actual ID [in] */ void Blast_SeqIdGetDefLine(SeqIdPtr sip, char** buffer_ptr, Boolean ncbi_gi, Boolean accession_only, Boolean search_for_id); /** Posts an error message from the summary returns, if any, to a provided * output stream. If no stream provided, nothing is written. * @param sum_return Summary returns structure. [in] */ Int2 Blast_SummaryReturnsPostError(Blast_SummaryReturn* sum_return); /** Format the PHI BLAST report. * @param phivnps List of ValNode's, containing PHI BLAST Seq-aligns * corresponding to different pattern occurrences in query. [in] * @param query_slp Query Seq-loc [in] * @param format_info Formatting information structure [in] * @param sum_returns Search summary returns [in] */ Int2 PHIBlastFormatResults(ValNode* phivnps, SeqLocPtr query_slp, const BlastFormattingInfo* format_info, Blast_SummaryReturn* sum_returns); /** Frees a chain of ValNode's containing PHI BLAST results. * @param phivnps Head of chain to be freed. [in] * @return NULL. */ ValNode* PHIBlastResultsFree(ValNode* phivnps); /** Returns the integer alignment type value used in the C toolkit * formatting code, given the EBlastProgramType enumeration value. * @param prog The BLAST program enumeration value [in] * @param db_is_na Is database nucleotide or protein for this program? [out] * @return Integer alignment type for use in old formatting code. */ Uint1 GetOldAlignType(EBlastProgramType prog, Boolean* db_is_na); /* @} */ #ifdef __cplusplus } #endif #endif /* !__BLAST_FORMAT__ */