BlastIOContext - SeqAn API Documentation

# Class BlastIOContext
An object that holds file global information and buffers for BlastIO

Defined in | <seqan/blast.h>
Signature | `template <typename TScore_ = Blosum62, BlastProgram p = BlastProgram::UNKNOWN, BlastTabularSpec h = BlastTabularSpec::UNKNOWN> struct BlastIOContext { ... };`

## Template Parameters

`TScore` | Type of the Score object used.
`p` | BlastProgram as compile-time parameter.
`h` | BlastTabularSpec as compile-time parameter.

## Member Variable Overview

- `BlastProgramSelector BlastIOContext::blastProgram`
  The BlastProgram.
- `StringSet<TString> BlastIOContext::conformancyErrors`
  Holds non fatal error messages when reading from BlastTabularFileIn.
- `TString BlastIOContext::dbName`
  Name of the dabase or path to the file.
- `uint64_t BlastIOContext::dbNumberOfSeqs`
  Number of sequences in the database.
- `uint64_t BlastIOContext::dbTotalLength`
  Summed up sequence length of the database.
- `std::vector<BlastMatchField::Enum> BlastIOContext::fields`
  The fields (types of columns) in BlastTabular-formats.
- `StringSet<TString> BlastIOContext::fieldsAsStrings`
  The fields (types of columns) in BlastTabular-formats, but as uninterpreted strings.
- `bool BlastIOContext::ignoreFieldsInComments`
  Use fields as in-parameter for readRecord as well (only BlastTabularFileIn).
- `bool BlastIOContext::legacyFormat`
  Whether to use the legacy format (only BlastTabular).
- `StringSet<TString> BlastIOContext::otherLines`
  A StringSet that will contain all comment lines that could not be interpreted in another way (only BlastTabularFileIn).
- `BlastScoringScheme<TScore> BlastIOContext::scoringScheme`
  The BlastScoringScheme.
- `BlastTabularSpecSelector BlastIOContext::tabularSpec`
  The BlastTabularSpec.
- `TString BlastIOContext::versionString`
  The blast version string.

## Detailed Description

This is a part of the Blast formatted files. Before writing, some of the context's members should be set; after reading it will contain all information from the file that did not belong to a BlastRecord, e.g. the name of the database. It also contains buffers for internal use.

You should re-use this object (i.e. only create it once for every file that you read/write). And you don't need to and should not clear() this, except when restarting IO on a different file.

To speed-up file writing slightly you can set the value template parameters `p` and/or `h` to something other than ::DYNAMIC at compile-time (e.g. if you know that you will be printing only BLASTX), but then you won't be able to modify these values at run-time. For file reading this is also possible, but usually the added flexibility of automatically detecting these values is prefferable.

If not explicitly stated otherwise, the member variables are out-parameters of `readHeader()`, `readRecord()` and `readFooter()`, i.e. they are set by these functions; and they are in-parameters to `writeHeader()`, `writeRecord()` and `writeFooter()`, i.e. they influence these functions' output.

See BlastTabularFileOut and BlastReportFileOut for more complete examples of usage.

## Member Variables Detail

### `BlastProgramSelector BlastIOContext::blastProgram`

The BlastProgram.

#### Remarks

Behaves exactly like an enum of type BlastProgram, unless the second template parameter was specified to make this a compile-time constant. See BlastProgramSelector for more information.

### `StringSet<TString> BlastIOContext::conformancyErrors`

Holds non fatal error messages when reading from BlastTabularFileIn.

#### Remarks

After doing a readRecord this will indicate whether the comment lines contained non-fatal parse errors, usually the result of a file written by a sloppy blast implementation or possibly a bug in SeqAn. An empty StringSet indicates that all is good.

### `TString BlastIOContext::dbName`

Name of the dabase or path to the file.

### `uint64_t BlastIOContext::dbNumberOfSeqs`

Number of sequences in the database.

### `uint64_t BlastIOContext::dbTotalLength`

Summed up sequence length of the database.

### `std::vector<BlastMatchField::Enum> BlastIOContext::fields`

The fields (types of columns) in BlastTabular-formats.

#### Remarks

This is an out-parameter for:

- readRecord iff tabularSpec == COMMENTS (otherwise it can't be deduced)

This is an in-parameter for:

- readRecord if tabularSpec != COMMENTS (specified fields will be expected)
- writeRecord (specified fields will written)

Setting ignoreFieldsInComments will make this variable be an in-parameter for the first case, as well. This variable is ignored in the legacy formats and for non-tabular formats.

### `StringSet<TString> BlastIOContext::fieldsAsStrings`

The fields (types of columns) in BlastTabular-formats, but as uninterpreted strings.

#### Remarks

Useful when the comment lines do not conform to standards and you want to extract the verbatim column labels or if you wish to print non-standard column labels (which you shouldn't!).

### `bool BlastIOContext::ignoreFieldsInComments`

Use fields as in-parameter for readRecord as well (only BlastTabularFileIn).

#### Remarks

See readRecord. Use this when the comment lines do not conform to standards (and the fields can't be read), but you know that the matches are in the given, e.g. default format.

### `bool BlastIOContext::legacyFormat`

Whether to use the legacy format (only BlastTabular).

#### Remarks

Setting this flag when writing to a BlastTabularFileOut (that has BlastTabularSpec::COMMENTS set) will result in the legacy version of the comments being written. In the legacy format the mismatches column also includes all gaps in addition to mismatches. Note that many other features like custom fields are not supported in this format.

When reading BlastTabularFileOut this flag will automatically be set based on the comments (if a they exist).

### `StringSet<TString> BlastIOContext::otherLines`

A StringSet that will contain all comment lines that could not be interpreted in another way (only BlastTabularFileIn).

### `BlastScoringScheme<TScore> BlastIOContext::scoringScheme`

The BlastScoringScheme.

### `BlastTabularSpecSelector BlastIOContext::tabularSpec`

The BlastTabularSpec.

#### Remarks

Behaves exactly like an enum of type BlastTabularSpec, unless the third template parameter was specified to make this a compile-time constant. See BlastTabularSpecSelector for more information.

### `TString BlastIOContext::versionString`

The blast version string.

#### Remarks

Used when writing BlastReportFileOut and BlastTabularFileOut if the context's tabularSpec is set to BlastTabularSpec::COMMENTS. Defaults to a version string based on the emulated blast version and the current SeqAn version. When reading from BlastTabularFileOut the corresponding line is extracted from the comment lines (if present).

#### Dox Sources

    /*!
     * @class BlastIOContext
     *
     * @headerfile <seqan/blast.h>
     *
     * @brief An object that holds file global information and buffers for BlastIO
     *
     * @signature template <typename TScore_ = Blosum62, BlastProgram p =
     *            BlastProgram::UNKNOWN, BlastTabularSpec h =
     *            BlastTabularSpec::UNKNOWN> struct BlastIOContext { ... };
     *
     * @tparam TScore Type of the @link Score @endlink object used.
     * @tparam p @link BlastProgram @endlink as compile-time parameter.
     * @tparam h @link BlastTabularSpec @endlink as compile-time parameter.
     *
     * This is a part of the Blast formatted files. Before writing, some of the
     * context's members should be set; after reading it will contain all
     * information from the file that did not belong to a @link BlastRecord
     * @endlink, e.g. the name of the database. It also contains buffers for
     * internal use.
     *
     * You should re-use this object (i.e. only create it once for every file that
     * you read/write). And you don't need to and should not clear() this, except
     * when restarting IO on a different file.
     *
     * To speed-up file writing slightly you can set the value template parameters
     * <tt>p</tt> and/or <tt>h</tt> to something other than ::DYNAMIC at compile-
     * time (e.g. if you know that you will be printing only BLASTX), but then you
     * won't be able to modify these values at run-time. For file reading this is
     * also possible, but usually the added flexibility of automatically detecting
     * these values is prefferable.
     *
     * If not explicitly stated otherwise, the member variables are <i>out-
     * parameters</i> of <tt>readHeader()</tt>, <tt>readRecord()</tt> and
     * <tt>readFooter()</tt>, i.e. they are set by these functions; and they are
     * <i>in-parameters</i> to <tt>writeHeader()</tt>, <tt>writeRecord()</tt> and
     * <tt>writeFooter()</tt>, i.e. they influence these functions' output.
     *
     * See @link BlastTabularFileOut @endlink and @link BlastReportFileOut @endlink
     * for more complete examples of usage.
     *
     * @var BlastProgramSelector BlastIOContext::blastProgram;
     *
     * @brief The @link BlastProgram @endlink.
     *
     * @section Remarks
     *
     * Behaves exactly like an enum of type @link BlastProgram @endlink, unless the
     * second template parameter was specified to make this a compile-time constant.
     * See @link BlastProgramSelector @endlink for more information.
     *
     * @var BlastTabularSpecSelector BlastIOContext::tabularSpec;
     *
     * @brief The @link BlastTabularSpec @endlink.
     *
     * @section Remarks
     *
     * Behaves exactly like an enum of type @link BlastTabularSpec @endlink, unless
     * the third template parameter was specified to make this a compile-time
     * constant. See @link BlastTabularSpecSelector @endlink for more information.
     *
     * @var BlastScoringScheme<TScore> BlastIOContext::scoringScheme;
     *
     * @brief The @link BlastScoringScheme @endlink.
     *
     * @var TString BlastIOContext::versionString;
     *
     * @brief The blast version string.
     *
     * @section Remarks
     *
     * Used when writing @link BlastReportFileOut @endlink and @link
     * BlastTabularFileOut @endlink if the context's tabularSpec is set to
     * BlastTabularSpec::COMMENTS. Defaults to a version string based on the
     * emulated blast version and the current SeqAn version. When reading from @link
     * BlastTabularFileOut @endlink the corresponding line is extracted from the
     * comment lines (if present).
     *
     * @var bool BlastIOContext::legacyFormat;
     *
     * @brief Whether to use the legacy format (only @link BlastTabular @endlink).
     *
     * @section Remarks
     *
     * Setting this flag when writing to a @link BlastTabularFileOut @endlink (that
     * has BlastTabularSpec::COMMENTS set) will result in the legacy version of the
     * comments being written. In the legacy format the mismatches column also
     * includes all gaps in addition to mismatches. Note that many other features
     * like custom fields are not supported in this format.
     *
     * When reading @link BlastTabularFileOut @endlink this flag will automatically
     * be set based on the comments (if a they exist).
     *
     * @var TString BlastIOContext::dbName;
     *
     * @brief Name of the dabase or path to the file.
     *
     * @var uint64_t BlastIOContext::dbTotalLength;
     *
     * @brief Summed up sequence length of the database.
     *
     * @var uint64_t BlastIOContext::dbNumberOfSeqs;
     *
     * @brief Number of sequences in the database.
     *
     * @var StringSet<TString> BlastIOContext::otherLines;
     *
     * @brief A StringSet that will contain all comment lines that could not be
     *        interpreted in another way (only @link BlastTabularFileIn @endlink).
     *
     * @var std::vector<BlastMatchField::Enum> BlastIOContext::fields;
     *
     * @brief The fields (types of columns) in @link BlastTabular @endlink-formats.
     *
     * @section Remarks
     *
     * This is an <i>out-parameter</i> for: <li> @link BlastTabularFileIn#readRecord
     * @endlink iff tabularSpec == COMMENTS (otherwise it can't be deduced)</li>
     *
     * This is an <i>in-parameter</i> for: <li> @link BlastTabularFileIn#readRecord
     * @endlink if tabularSpec != COMMENTS (specified fields will be expected)</li>
     * <li> @link BlastTabularFileOut#writeRecord @endlink (specified fields will
     * written)
     *
     * Setting @link BlastIOContext::ignoreFieldsInComments @endlink will make this
     * variable be an <i>in-parameter</i> for the first case, as well. This variable
     * is ignored in the legacy formats and for non-tabular formats.
     *
     * @var StringSet<TString> BlastIOContext::fieldsAsStrings;
     *
     * @brief The fields (types of columns) in @link BlastTabular @endlink-formats,
     *        but as uninterpreted strings.
     *
     * @section Remarks
     *
     * Useful when the comment lines do not conform to standards and you want to
     * extract the verbatim column labels or if you wish to print non-standard
     * column labels (which you shouldn't!).
     *
     * @var bool BlastIOContext::ignoreFieldsInComments;
     *
     * @brief Use fields as in-parameter for readRecord as well (only @link
     *        BlastTabularFileIn @endlink).
     *
     * @section Remarks
     *
     * See @link BlastTabularFileIn#readRecord @endlink. Use this when the comment
     * lines do not conform to standards (and the fields can't be read), but you
     * know that the matches are in the given, e.g. default format.
     *
     * @var StringSet<TString> BlastIOContext::conformancyErrors;
     *
     * @brief Holds non fatal error messages when reading from @link
     *        BlastTabularFileIn @endlink.
     *
     * @section Remarks
     *
     * After doing a @link BlastTabularFileIn#readRecord @endlink this will indicate
     * whether the comment lines contained non-fatal parse errors, usually the
     * result of a file written by a sloppy blast implementation or possibly a bug
     * in SeqAn. An empty StringSet indicates that all is good.
     */