BlastTabularFileOut - SeqAn API Documentation

# Spec BlastTabularFileOut
FormattedFileOut abstraction for BlastTabular

Extends | FormattedFileOut
All Extended | FormattedFile, FormattedFileOut
Defined in | <seqan/blast.h>
Signature | `template <typename TBlastIOContext> using BlastTabularFileOut = FormattedFile<BlastTabular, Output, TBlastIOContext>;`

## Member Function Overview

### Member Functions Inherited From FormattedFile

- `getFileExtensions`
- `operatorTDependentContext`

## Interface Function Overview

- `void writeFooter(blastTabularOut);`
  Write the footer of a BlastTabular file.
- `void writeHeader(blastTabularOut);`
  Write the header (top-most section) of a BlastTabular file (this is a NOOP).
- `void writeRecord(blastTabularOut, blastRecord);`
  Write a BlastRecord including it's BlastMatches and possible comment lines to a file.

### Interface Functions Inherited From FormattedFile

- `atEnd`
- `close`
- `context`
- `format`
- `FormattedFile`
- `getFileExtensions`
- `guessFormat`
- `isOpen`
- `open`
- `setFormat`

### Interface Functions Inherited From FormattedFileOut

- `writeHeader`
- `writeRecord`

## Interface Metafunction Overview

### Interface Metafunctions Inherited From FormattedFile

- `FileFormat`
- `FormattedFileContext`

## Detailed Description

This is a FormattedFile specialization for writing BlastTabular formats. For details on how to influence the writing of files and how to differentiate between the tabular format with and without comment lines, see BlastIOContext. Please note that you have to specify the type of the context as a template parameter to BlastTabularFileOut, see the example below.

### Overview

- open BlastTabularFileOut,
- configure the BlastIOContext
- writeHeader
- writeRecord repeated up to n times
- writeFooter

The following members of the context have to be defined before writing:

- blastProgram (unless fixed at compile-time)
- scoringScheme
- dbName
- dbTotalLength
- dbNumberOfSeqs

For a detailed example have a look at the Blast IO tutorial.

Strictly speaking the `writeHeader()` call is not required for BlastTabular, but for consistency with other (blast) formats and the read interface it is recommended.

## See Also

- BlastRecord

## Interface Functions Detail

### `void writeFooter(blastTabularOut);`

Write the footer of a BlastTabular file.

#### Parameters

`blastTabularOut` | A BlastTabularFileOut formattedFile.

#### Thrown Exceptions

`IOError` | On low-level I/O errors.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

#### See Also

- BlastIOContext
- BlastRecord

### `void writeHeader(blastTabularOut);`

Write the header (top-most section) of a BlastTabular file (this is a NOOP).

#### Parameters

`blastTabularOut` | A BlastTabularFileOut formattedFile.

#### Thrown Exceptions

`IOError` | On low-level I/O errors.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

#### See Also

- BlastIOContext
- BlastRecord

### `void writeRecord(blastTabularOut, blastRecord);`

Write a BlastRecord including it's BlastMatches and possible comment lines to a file.

#### Parameters

`blastTabularOut` | A BlastTabularFileOut formattedFile.
`blastRecord` | The BlastRecord you wish to print.

#### Remarks

This function first writes the comment lines of the record and then writes match lines for every match in it. If the context's tabularSpec is set to BlastTabularSpec::NO_COMMENTS, no comment lines will be written and this function immediately prints the match lines.

##### Comment lines

The contents of the comment lines is largely defined by the members of the context.

If the context's versionString is set, this will be written, otherwise a stanadard version string is generated.

The context's dbName is printed as the database name / path.

If either the context's fields or fieldsAsStrings member are specified these will be printed as column labels. If both are specified than fieldsAsStrings is given preference. Please note that it is recommended to use fields and not fieldsAsStrings to stay "standards"-compliant. Also only fields has an influence on the values printed in the match lines.

##### Matches

Please note that BLAST is 1-indexed and considers the last position to be the back, not the end, i.e. last one included in a match/sequence/..., not the one behind it (as SeqAn does); this functions corrects for both of these bahaviours, so you don't have to. Additionally, based on the context's blastProgram, positions are transformed back to DNA space, if translation has taken place. Please note also that query and subject IDs are truncated at the first space character in NCBI BLAST, this is also done by default here.

By setting the context's fields meber you can specify which columns you wish to print (if you don't want defaults); the same conversions mentioned above will me made. See BlastMatchField::Enum for a list of fields available. If the context's legacy-flag is set (legacyFormat) the fields variable is ignored.

Many guides recommend always printing the default 12 columns and using only additional columns with additional (custom) data.

#### Thrown Exceptions

`IOError` | On low-level I/O errors.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

#### See Also

- BlastIOContext
- BlastRecord

#### Dox Sources

    /*!
     * @class BlastTabularFileOut
     *
     * @extends FormattedFileOut
     *
     * @headerfile <seqan/blast.h>
     *
     * @brief FormattedFileOut abstraction for @link BlastTabular @endlink
     *
     * @signature template <typename TBlastIOContext> using BlastTabularFileOut =
     *            FormattedFile<BlastTabular, Output, TBlastIOContext>;
     *
     * This is a @link FormattedFile @endlink specialization for writing @link
     * BlastTabular @endlink formats. For details on how to influence the writing of
     * files and how to differentiate between the tabular format with and without
     * comment lines, see @link BlastIOContext @endlink. Please note that you have
     * to specify the type of the context as a template parameter to
     * BlastTabularFileOut, see the example below.
     *
     * @section Overview
     *
     * <ul> <li> open @link BlastTabularFileOut @endlink,</li> <li> configure the
     * @link BlastIOContext @endlink </li> <li> @link
     * BlastTabularFileOut#writeHeader @endlink </li> <li> @link
     * BlastTabularFileOut#writeRecord @endlink repeated up to n times</li> <li>
     * @link BlastTabularFileOut#writeFooter @endlink </li> </ul>
     *
     * The following members of the context have to be defined before writing: <ul>
     * <li> @link BlastIOContext::blastProgram @endlink (unless fixed at compile-
     * time)</li> <li> @link BlastIOContext::scoringScheme @endlink</li> <li> @link
     * BlastIOContext::dbName @endlink</li> <li> @link BlastIOContext::dbTotalLength
     * @endlink</li> <li> @link BlastIOContext::dbNumberOfSeqs @endlink</li> </ul>
     *
     * For a detailed example have a look at the <a href="http://seqan.readthedocs.i
     * o/en/develop/Tutorial/InputOutput/BlastIO.html">Blast IO tutorial</a>.
     *
     * Strictly speaking the <tt>writeHeader()</tt> call is not required for
     * BlastTabular, but for consistency with other (blast) formats and the read
     * interface it is recommended.
     *
     * @see BlastRecord
     *
     * @fn BlastTabularFileOut#writeRecord
     *
     * @headerfile seqan/blast.h
     *
     * @brief Write a @link BlastRecord @endlink including it's @link BlastMatch
     *        @endlinkes and possible comment lines to a file.
     *
     * @signature void writeRecord(blastTabularOut, blastRecord);
     *
     * @param[in,out] blastTabularOut A @link BlastTabularFileOut @endlink
     *                                formattedFile.
     * @param[in] blastRecord The @link BlastRecord @endlink you wish to print.
     *
     * @throw IOError On low-level I/O errors.
     *
     * @section Remarks
     *
     * This function first writes the comment lines of the record and then writes
     * match lines for every match in it. If the context's @link
     * BlastIOContext::tabularSpec @endlink is set to BlastTabularSpec::NO_COMMENTS,
     * no comment lines will be written and this function immediately prints the
     * match lines.
     *
     * @subsection Comment lines
     *
     * The contents of the comment lines is largely defined by the members of the
     * context.
     *
     * If the context's @link BlastIOContext::versionString @endlink is set, this
     * will be written, otherwise a stanadard version string is generated.
     *
     * The context's @link BlastIOContext::dbName @endlink is printed as the
     * database name / path.
     *
     * If either the context's @link BlastIOContext::fields @endlink or @link
     * BlastIOContext::fieldsAsStrings @endlink member are specified these will be
     * printed as column labels. If both are specified than @link
     * BlastIOContext::fieldsAsStrings @endlink is given preference. Please note
     * that it is recommended to use @link BlastIOContext::fields @endlink and not
     * @link BlastIOContext::fieldsAsStrings @endlink to stay "standards"-compliant.
     * Also only @link BlastIOContext::fields @endlink has an influence on the
     * values printed in the match lines.
     *
     * @subsection Matches
     *
     * Please note that BLAST is 1-indexed and considers the last position to be the
     * back, not the end, i.e. last one included in a match/sequence/..., not the
     * one behind it (as SeqAn does); this functions corrects for both of these
     * bahaviours, so you don't have to. Additionally, based on the context's @link
     * BlastIOContext::blastProgram @endlink, positions are transformed back to DNA
     * space, if translation has taken place. Please note also that query and
     * subject IDs are truncated at the first space character in NCBI BLAST, this is
     * also done by default here.
     *
     * By setting the context's @link BlastIOContext::fields @endlink meber you can
     * specify which columns you wish to print (if you don't want defaults); the
     * same conversions mentioned above will me made. See @link
     * BlastMatchField::Enum @endlink for a list of fields available. If the
     * context's legacy-flag is set (@link BlastIOContext::legacyFormat @endlink)
     * the @link BlastIOContext::fields @endlink variable is ignored.
     *
     * Many guides recommend always printing the default 12 columns and using only
     * additional columns with additional (custom) data.
     *
     * @see BlastRecord
     * @see BlastIOContext
     *
     * @fn BlastTabularFileOut#writeHeader
     *
     * @headerfile seqan/blast.h
     *
     * @brief Write the header (top-most section) of a BlastTabular file (this is a
     *        NOOP).
     *
     * @signature void writeHeader(blastTabularOut);
     *
     * @param[in,out] blastTabularOut A @link BlastTabularFileOut @endlink
     *                                formattedFile.
     *
     * @throw IOError On low-level I/O errors.
     *
     * @see BlastRecord
     * @see BlastIOContext
     *
     * @fn BlastTabularFileOut#writeFooter
     *
     * @headerfile seqan/blast.h
     *
     * @brief Write the footer of a BlastTabular file.
     *
     * @signature void writeFooter(blastTabularOut);
     *
     * @param[in,out] blastTabularOut A @link BlastTabularFileOut @endlink
     *                                formattedFile.
     *
     * @throw IOError On low-level I/O errors.
     *
     * @see BlastRecord
     * @see BlastIOContext
     */