BlastTabularFileIn - SeqAn API Documentation

# Spec BlastTabularFileIn
FormattedFileIn abstraction for BlastTabular

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

## Member Function Overview

### Member Functions Inherited From FormattedFile

- `getFileExtensions`
- `operatorTDependentContext`

## Interface Function Overview

- `bool onRecord(blastTabularIn);`
  Returns whether the currently buffered line looks like the start of a record.
- `void readFooter(blastTabularIn);`
  Read the footer (bottom-most section) of a BlastTabular file.
- `void readHeader(blastTabularIn);`
  Read the header (top-most section) of a BlastTabular file.
- `void readRecord(blastRecord, blastTabularIn);`
  Read a record from a file in BlastTabular format.

### Interface Functions Inherited From FormattedFile

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

### Interface Functions Inherited From FormattedFileIn

- `readHeader`
- `readRecord`

## Interface Metafunction Overview

### Interface Metafunctions Inherited From FormattedFile

- `FileFormat`
- `FormattedFileContext`

## Detailed Description

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

### Overview

- open BlastTabularFileIn
- readHeader
- while onRecord

- readRecord

- readFooter

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

## See Also

- BlastRecord

## Interface Functions Detail

### `bool onRecord(blastTabularIn);`

Returns whether the currently buffered line looks like the start of a record.

#### Parameters

`blastTabularIn` | A BlastTabularFileIn formattedFile.

#### Returns

`bool` | true or false

#### Thrown Exceptions

`IOError` | On low-level I/O errors.
`ParseError` | On high-level file format errors.

#### Data Races

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

### `void readFooter(blastTabularIn);`

Read the footer (bottom-most section) of a BlastTabular file.

#### Parameters

`blastTabularIn` | A BlastTabularFileIn formattedFile.

#### Thrown Exceptions

`IOError` | On low-level I/O errors.
`ParseError` | On high-level file format errors.

#### Data Races

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

### `void readHeader(blastTabularIn);`

Read the header (top-most section) of a BlastTabular file.

#### Parameters

`blastTabularIn` | A BlastTabularFileIn formattedFile.

#### Thrown Exceptions

`IOError` | On low-level I/O errors.
`ParseError` | On high-level file format errors.

#### Data Races

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

### `void readRecord(blastRecord, blastTabularIn);`

Read a record from a file in BlastTabular format.

#### Parameters

`blastRecord` | A BlastRecord to hold all information related to one query sequence.
`blastTabularIn` | A BlastTabularFileIn formattedFile.

#### Remarks

This function will read an entire record from a blast tabular file, i.e. it will read the comment lines (if the format is COMMENTS) and 0-n BlastMatches belonging to one query.

Please note that if there are no comment lines in the file the boundary between records is inferred from the indentity of the first field, i.e. non-standard field configurations must also have Q_SEQ_ID as their first BlastMatchField.

##### Comment lines

The qId member of the record is read from the comment lines and the matches are resized to the expected number of matches succeeding the comments.

This function also sets many properties of blastTabularIn's BlastIOContext, including these members:

- versionString: version string of the program.
- dbName: name of the database.
- fields: descriptors for the columns.
- fieldsAsStrings: labels of the columns as they appear in the file.
- conformancyErrors: if this StringSet is not empty, then there are issues in the comments.
- otherLines: any lines that cannot be interpreted; these always also imply conformancyErrors.
- legacyFormat: whether the record (and likely the entire file) is in legacyFormat.

It also sets the blast program run-time parameter of the context depending on the information found in the comments. If the compile time parameter was set on the context and they are different this will result in a critical error.

Please note that for legacyFormat the fields member is always ignored, however fieldsAsStrings is still read from the comments, in case you want to process it.

In case you do not wish the fields to be read from the comments, you can set context.ignoreFieldsInComments to true. This will be prevent it from being read and will allow you to specify it manually which might be relevant for reading the match lines.

If the format is NO_COMMENTS none of the above happens and qId is derived from the first match.

##### Matches

A match line contains 1 - n columns or fields, 12 by default. The fields member of the context is considered when reading these fields. It is usually extracted from the comment lines but can also be set by yourself if there are no comments or if you want to overwrite the comments' information (see above). You may specify less fields than are actually present, in this case the additional fields will be discarded. The parameter is ignored if legacyFormat is set.

To differentiate between members of a BlastMatch that were read from the file and those that have not been set (e.g. both could be 0), the latter are initialized to their respective max-values.

Please note that the only transformations made to the data are the following:

- computation of the number of identities (from the percentage) [default]
- computation of the number of positives (from the percentage) [if given]
- number of gaps computed from other values [default]

In contrast to writeRecord no other transformations are made, e.g. the positions are still one-indexed and flipped for reverse strand matches. This is due to the required fields for retransformation (sequence lengths, frames) not being available in the default columns.

#### Thrown Exceptions

`IOError` | On low-level I/O errors.
`ParseError` | On high-level file format errors.

#### Data Races

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

#### Dox Sources

    /*!
     * @class BlastTabularFileIn
     *
     * @extends FormattedFileIn
     *
     * @headerfile <seqan/blast.h>
     *
     * @brief FormattedFileIn abstraction for @link BlastTabular @endlink
     *
     * @signature template <typename TBlastIOContext> using BlastTabularFileIn =
     *            FormattedFile<BlastTabular, Input, TBlastIOContext>;
     *
     * This is a @link FormattedFile @endlink specialization for reading @link
     * BlastTabular @endlink formats. For details on how to influence the reading of
     * files and how to differentiate between the tabular format without comment
     * lines and the one with comment lines, see @link BlastIOContext @endlink.
     * Please note that you have specify the type of the context as a template
     * parameter to BlastTabularFileIn.
     *
     * @section Overview
     *
     * <ul> <li> open @link BlastTabularFileIn @endlink</li> <li> @link
     * BlastTabularFileIn#readHeader @endlink </li> <li> while @link
     * BlastTabularFileIn#onRecord @endlink </li> <ul><li> @link
     * BlastTabularFileIn#readRecord @endlink</li></ul> <li> @link
     * BlastTabularFileIn#readFooter @endlink </li> </ul>
     *
     * For a detailed example have a look at the <a href="https://seqan.readthedocs.
     * io/en/main/Tutorial/InputOutput/BlastIO.html">Blast IO tutorial</a>.
     *
     * @see BlastRecord
     *
     * @fn BlastTabularFileIn#onRecord
     *
     * @headerfile seqan/blast.h
     *
     * @brief Returns whether the currently buffered line looks like the start of a
     *        record.
     *
     * @signature bool onRecord(blastTabularIn);
     *
     * @param[in,out] blastTabularIn A @link BlastTabularFileIn @endlink
     *                               formattedFile.
     *
     * @return bool true or false
     *
     * @throw IOError On low-level I/O errors.
     * @throw ParseError On high-level file format errors.
     *
     * @fn BlastTabularFileIn#readRecord
     *
     * @headerfile seqan/blast.h
     *
     * @brief Read a record from a file in BlastTabular format.
     *
     * @signature void readRecord(blastRecord, blastTabularIn);
     *
     * @param[out] blastRecord A @link BlastRecord @endlink to hold all information
     *                         related to one query sequence.
     * @param[in,out] blastTabularIn A @link BlastTabularFileIn @endlink
     *                               formattedFile.
     *
     * @throw IOError On low-level I/O errors.
     * @throw ParseError On high-level file format errors.
     *
     * @section Remarks
     *
     * This function will read an entire record from a blast tabular file, i.e. it
     * will read the comment lines (if the format is @link
     * BlastTabularSpec::COMMENTS @endlink) and 0-n @link BlastMatch @endlinkes
     * belonging to one query.
     *
     * Please note that if there are no comment lines in the file the boundary
     * between records is inferred from the indentity of the first field, i.e. non-
     * standard field configurations must also have Q_SEQ_ID as their first @link
     * BlastMatchField @endlink.
     *
     * @subsection Comment lines
     *
     * The @link BlastRecord::qId @endlink member of the record is read from the
     * comment lines and the @link BlastRecord::matches @endlink are resized to the
     * expected number of matches succeeding the comments.
     *
     * This function also sets many properties of blastTabularIn's @link
     * BlastIOContext @endlink, including these members: <li> @link
     * BlastIOContext::versionString @endlink: version string of the program.</li>
     * <li> @link BlastIOContext::dbName @endlink: name of the database.</li> <li>
     * @link BlastIOContext::fields @endlink: descriptors for the columns.</li> <li>
     * @link BlastIOContext::fieldsAsStrings @endlink: labels of the columns as they
     * appear in the file.</li> <li> @link BlastIOContext::conformancyErrors
     * @endlink: if this StringSet is not empty, then there are issues in the
     * comments.</li> <li> @link BlastIOContext::otherLines @endlink: any lines that
     * cannot be interpreted; these always also imply conformancyErrors.</li>
     * <li>@link BlastIOContext::legacyFormat @endlink: whether the record (and
     * likely the entire file) is in legacyFormat.</li>
     *
     * It also sets the blast program run-time parameter of the context depending on
     * the information found in the comments. If the compile time parameter was set
     * on the context and they are different this will result in a critical error.
     *
     * Please note that for @link BlastIOContext::legacyFormat @endlink the @link
     * BlastIOContext::fields @endlink member is always ignored, however @link
     * BlastIOContext::fieldsAsStrings @endlink is still read from the comments, in
     * case you want to process it.
     *
     * In case you do not wish the @link BlastIOContext::fields @endlink to be read
     * from the comments, you can set context.@link
     * BlastIOContext::ignoreFieldsInComments @endlink to true. This will be prevent
     * it from being read and will allow you to specify it manually which might be
     * relevant for reading the match lines.
     *
     * If the format is @link BlastTabularSpec::NO_COMMENTS @endlink none of the
     * above happens and @link BlastRecord::qId @endlink is derived from the first
     * match.
     *
     * @subsection Matches
     *
     * A match line contains 1 - n columns or fields, 12 by default. The @link
     * BlastIOContext::fields @endlink member of the context is considered when
     * reading these fields. It is usually extracted from the comment lines but can
     * also be set by yourself if there are no comments or if you want to overwrite
     * the comments' information (see above). You may specify less fields than are
     * actually present, in this case the additional fields will be discarded. The
     * parameter is ignored if @link BlastIOContext::legacyFormat @endlink is set.
     *
     * To differentiate between members of a @link BlastMatch @endlink that were
     * read from the file and those that have not been set (e.g. both could be 0),
     * the latter are initialized to their respective max-values.
     *
     * Please note that the only transformations made to the data are the following:
     *
     * <li> computation of the number of identities (from the percentage)
     * [default]</li> <li> computation of the number of positives (from the
     * percentage) [if given]</li> <li> number of gaps computed from other values
     * [default]</li>
     *
     * In contrast to @link BlastTabularFileOut#writeRecord @endlink no other
     * transformations are made, e.g. the positions are still one-indexed and
     * flipped for reverse strand matches. This is due to the required fields for
     * retransformation (sequence lengths, frames) not being available in the
     * default columns.
     *
     * @fn BlastTabularFileIn#readHeader
     *
     * @headerfile seqan/blast.h
     *
     * @brief Read the header (top-most section) of a BlastTabular file.
     *
     * @signature void readHeader(blastTabularIn);
     *
     * @param[in,out] blastTabularIn A @link BlastTabularFileIn @endlink
     *                               formattedFile.
     *
     * @throw IOError On low-level I/O errors.
     * @throw ParseError On high-level file format errors.
     *
     * @fn BlastTabularFileIn#readFooter
     *
     * @headerfile seqan/blast.h
     *
     * @brief Read the footer (bottom-most section) of a BlastTabular file.
     *
     * @signature void readFooter(blastTabularIn);
     *
     * @param[in,out] blastTabularIn A @link BlastTabularFileIn @endlink
     *                               formattedFile.
     *
     * @throw IOError On low-level I/O errors.
     * @throw ParseError On high-level file format errors.
     */