BlastMatch - SeqAn API Documentation

# Class BlastMatch
An data structure to hold a blast match, also known as high-scoring segment pair (HSP)

Implements | AssignableConcept, CopyConstructibleConcept, DefaultConstructibleConcept, EqualityComparableConcept, LessThanComparableConcept
All Impl'd | AssignableConcept, CopyConstructibleConcept, DefaultConstructibleConcept, EqualityComparableConcept, LessThanComparableConcept
Defined in | <seqan/blast.h>
Signature | `struct BlastMatch<TAlign, TPos, TQId, TSId> { ... };`

## Template Parameters

`TAlignRow0` | Type of the first alignment row, usually Gaps
`TAlignRow1` | Type of the second alignment row, usually Gaps
`TPos` | Position type of the sequences, defaults to `uint32_t`
`TQId` | Type of qId, defaults to `std::string`
`TSId` | Type of sId, defaults to `std::string`
`TSAccs` | Type of sAccs, defaults to `std::vector` of `std::string`
`TSTaxIds` | Type of sTaxIds, defaults to String of `uint32_t`

## Member Function Overview

- `BlastMatch::BlastMatch() BlastMatch::BlastMatch(sId) BlastMatch::BlastMatch(qId, sId) [deprecated]`
  Constructor, can be called with arguments for qId and sId.
- `bool BlastMatch::operator< (BlastMatch const & bm2) const`
  The comparison operator (for sorting by bit-score).

### Member Functions Inherited From AssignableConcept

- `operator=`

### Member Functions Inherited From EqualityComparableConcept

- `operator!=`
- `operator==`

### Member Functions Inherited From LessThanComparableConcept

- `operator<`

## Interface Function Overview

- `void computeAlignmentStats(blastMatch, context);`
  Compute the alignStats member of a BlastMatch.
- `double computeBitScore(blastMatch, context);`
  Compute the bit-score for a BlastMatch.
- `double computeEValue(blastMatch, qLength, context); [[deprecated]] double computeEValue(blastMatch, context);`
  Compute the E-Value for a BlastMatch.

### Interface Functions Inherited From AssignableConcept

- `assign`
- `set`
- `move`

## Member Variable Overview

- `TAlign BlastMatch::alignRow0`
  First alignment row (Gaps object).
- `TAlign BlastMatch::alignRow1`
  Second alignment row (Gaps object).
- `AlignmentStats BlastMatch::alignStats`
  An AlignmentStats object holding further stats of the alignment.
- `double BlastMatch::bitScore`
  The bit-score of the alignment.
- `double BlastMatch::eValue`
  The e-value of the alignment.
- `TPos BlastMatch::qEnd`
  The end of the alignment on the (possibly translated) query sequence.
- `char BlastMatch::qFrameShift`
  An indicator for query frame and query strand.
- `TQId BlastMatch::qId`
  The verbose Id of the query.
- `TPos BlastMatch::qLength`
  The length of the original query sequence (possibly before translation).
- `TPos BlastMatch::qStart`
  The start of the alignment on the (possibly translated) query sequence.
- `TSId BlastMatch::sAccs`
  The Accession number(s) of the subject.
- `TPos BlastMatch::sEnd`
  The end of the alignment on the (possibly translated) subject sequence.
- `char BlastMatch::sFrameShift`
  An indicator for subject frame and subject strand.
- `TSId BlastMatch::sId`
  The verbose Id of the subject.
- `TPos BlastMatch::sLength`
  The length of the original subject sequence (possibly before translation).
- `TPos BlastMatch::sStart`
  The start of the alignment on the (possibly translated) subject sequence.
- `TSId BlastMatch::sTaxIds`
  The taxonomic ID(s) of the subject.

## Detailed Description

You should set the following members manually: qId, sId, qLength, sLength, qFrameShift and sFrameShift.

If you then also set valid alignRow-members (alignRow0, alignRow1), you can let the other members be computed by computeAlignmentStats and computeBitScore, computeEValue.

## Member Functions Detail

### `BlastMatch::BlastMatch() BlastMatch::BlastMatch(sId) BlastMatch::BlastMatch(qId, sId) [deprecated]`

Constructor, can be called with arguments for qId and sId.

#### Data Races

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

### `bool BlastMatch::operator< (BlastMatch const & bm2) const`

The comparison operator (for sorting by bit-score).

To facilitate fast sorting of matches in a BlastRecord, only the bit-score is compared. Also large bit-score are sorted to front (i.e. operator< on BlastMatch checks operator>= on the bitScores).

#### Data Races

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

## Interface Functions Detail

### `void computeAlignmentStats(blastMatch, context);`

Compute the alignStats member of a BlastMatch.

#### Parameters

`blastMatch` | A BlastMatch that has a valid align member.
`context` | A BlastIOContext with parameters and buffers.

The alignRow-members (alignRow0, alignRow1) are used as in-parameter to compute the alignStats member. This includes the raw score, amount of gaps, mismatches et cetera. This is a prerequisite for printing a match to file or computing it's e-value.

#### Data Races

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

### `double computeBitScore(blastMatch, context);`

Compute the bit-score for a BlastMatch.

#### Parameters

`blastMatch` | A BlastMatch that has a valid align member.
`context` | A BlastIOContext with parameters and buffers.

#### Returns

`double` | blastMatch.bitScore after computation

#### Remarks

This will compute the bit-score for a BlastMatch. At least the following members need to be set before calling this function:

- blastMatch.alignStats.alignmentScore (if you have valid alignRow-members (alignRow0, alignRow1), you can call computeAlignmentStats to compute the stats member).

#### Data Races

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

### `double computeEValue(blastMatch, qLength, context); [[deprecated]] double computeEValue(blastMatch, context);`

Compute the E-Value for a BlastMatch.

#### Parameters

`blastMatch` | A BlastMatch that has a valid align member.
`qLength` | The length of the query sequence (pass qLength).
`context` | A BlastIOContext with parameters and buffers.

#### Returns

`double` | blastMatch.eValue after computation

#### Remarks

This will compute the e-value for a BlastMatch. At least the following members need to be set before calling this function:

- blastMatch.alignStats.alignmentScore (if you have valid alignRow-members (alignRow0, alignRow1), you can call computeAlignmentStats to compute the stats member).
- blastMatch.qLength (only in the deprecated interface)
- context.dbTotalLength

Note, that in contrast to the general interface (computeEValue), this interface caches some computation steps in the context and is therefore faster.

#### Data Races

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

## Member Variables Detail

### `TAlign BlastMatch::alignRow0`

First alignment row (Gaps object).

### `TAlign BlastMatch::alignRow1`

Second alignment row (Gaps object).

### `AlignmentStats BlastMatch::alignStats`

An AlignmentStats object holding further stats of the alignment.

### `double BlastMatch::bitScore`

The bit-score of the alignment.

### `double BlastMatch::eValue`

The e-value of the alignment.

### `TPos BlastMatch::qEnd`

The end of the alignment on the (possibly translated) query sequence.

### `char BlastMatch::qFrameShift`

An indicator for query frame and query strand.

one out of { -3, -2, -1, +1, +2, +3 } where the `absolute value - 1` is the shift of the translation frame and a negative sign indicates the reverse complement strand [query sequence, only applies for BlastFormatProgram == BLASTX | TBLASTX]; -1 implies reverse complement for BLASTN.

### `TQId BlastMatch::qId`

The verbose Id of the query.

### `TPos BlastMatch::qLength`

The length of the original query sequence (possibly before translation).

### `TPos BlastMatch::qStart`

The start of the alignment on the (possibly translated) query sequence.

### `TSId BlastMatch::sAccs`

The Accession number(s) of the subject.

### `TPos BlastMatch::sEnd`

The end of the alignment on the (possibly translated) subject sequence.

### `char BlastMatch::sFrameShift`

An indicator for subject frame and subject strand.

one out of { -3, -2, -1, +1, +2, +3 } where the `absolute value - 1` is the shift of the translation frame and a negative sign indicates the reverse complement strand [subject sequence, only applies for BlastFormatProgram == TBLASTN | TBLASTX].

### `TSId BlastMatch::sId`

The verbose Id of the subject.

### `TPos BlastMatch::sLength`

The length of the original subject sequence (possibly before translation).

### `TPos BlastMatch::sStart`

The start of the alignment on the (possibly translated) subject sequence.

### `TSId BlastMatch::sTaxIds`

The taxonomic ID(s) of the subject.

#### Dox Sources

    /*!
     * @class BlastMatch
     *
     * @implements AssignableConcept
     * @implements CopyConstructibleConcept
     * @implements DefaultConstructibleConcept
     * @implements EqualityComparableConcept
     * @implements LessThanComparableConcept
     *
     * @headerfile <seqan/blast.h>
     *
     * @brief An data structure to hold a blast match, also known as high-scoring
     *        segment pair (HSP)
     *
     * @signature struct BlastMatch<TAlign, TPos, TQId, TSId> { ... };
     *
     * @tparam TAlignRow0 Type of the first alignment row, usually @link Gaps
     *                    @endlink
     * @tparam TAlignRow1 Type of the second alignment row, usually @link Gaps
     *                    @endlink
     * @tparam TPos Position type of the sequences, defaults to <tt>uint32_t</tt>
     * @tparam TQId Type of qId, defaults to <tt>std::string</tt>
     * @tparam TSId Type of sId, defaults to <tt>std::string</tt>
     * @tparam TSAccs Type of sAccs, defaults to <tt>std::vector</tt> of
     *                <tt>std::string</tt>
     * @tparam TSTaxIds Type of sTaxIds, defaults to @link String @endlink of
     *                  <tt>uint32_t</tt>
     *
     * You should set the following members manually: @link BlastMatch::qId
     * @endlink, @link BlastMatch::sId @endlink, @link BlastMatch::qLength @endlink,
     * @link BlastMatch::sLength @endlink, @link BlastMatch::qFrameShift @endlink
     * and @link BlastMatch::sFrameShift @endlink.
     *
     * If you then also set valid alignRow-members (@link BlastMatch::alignRow0
     * @endlink, @link BlastMatch::alignRow1 @endlink), you can let the other
     * members be computed by @link BlastMatch#computeAlignmentStats @endlink and
     * @link BlastMatch#computeBitScore @endlink, @link BlastMatch#computeEValue
     * @endlink.
     *
     * @fn BlastMatch::BlastMatch()
     *
     * @brief Constructor, can be called with arguments for qId and sId.
     *
     * @signature BlastMatch::BlastMatch() BlastMatch::BlastMatch(sId)
     *            BlastMatch::BlastMatch(qId, sId) [deprecated]
     *
     * @fn BlastMatch::operator<
     *
     * @brief The comparison operator (for sorting by bit-score).
     *
     * @signature bool BlastMatch::operator< (BlastMatch const & bm2) const
     *
     * To facilitate fast sorting of matches in a @link BlastRecord @endlink, only
     * the bit-score is compared. Also large bit-score are sorted to front (i.e.
     * operator< on BlastMatch checks operator>= on the bitScores).
     *
     * @var TQId BlastMatch::qId;
     *
     * @brief The verbose Id of the query.
     *
     * @deprecated Use @link BlastRecord::qId @endlink instead.
     *
     * @var TSId BlastMatch::sId;
     *
     * @brief The verbose Id of the subject.
     *
     * @var TSId BlastMatch::sAccs;
     *
     * @brief The Accession number(s) of the subject.
     *
     * @var TSId BlastMatch::sTaxIds;
     *
     * @brief The taxonomic ID(s) of the subject.
     *
     * @var TPos BlastMatch::qStart;
     *
     * @brief The start of the alignment on the (possibly translated) query
     *        sequence.
     *
     * @var TPos BlastMatch::qEnd;
     *
     * @brief The end of the alignment on the (possibly translated) query sequence.
     *
     * @var TPos BlastMatch::sStart;
     *
     * @brief The start of the alignment on the (possibly translated) subject
     *        sequence.
     *
     * @var TPos BlastMatch::sEnd;
     *
     * @brief The end of the alignment on the (possibly translated) subject
     *        sequence.
     *
     * @var TPos BlastMatch::qLength;
     *
     * @brief The length of the original query sequence (possibly before
     *        translation).
     *
     * @deprecated Use @link BlastRecord::qLength @endlink instead.
     *
     * @var TPos BlastMatch::sLength;
     *
     * @brief The length of the original subject sequence (possibly before
     *        translation).
     *
     * @var char BlastMatch::qFrameShift;
     *
     * @brief An indicator for query frame and query strand.
     *
     * one out of { -3, -2, -1, +1, +2, +3 } where the <tt>absolute value - 1</tt>
     * is the shift of the translation frame and a negative sign indicates the
     * reverse complement strand [query sequence, only applies for
     * BlastFormatProgram == BLASTX | TBLASTX]; -1 implies reverse complement for
     * BLASTN.
     *
     * @var char BlastMatch::sFrameShift;
     *
     * @brief An indicator for subject frame and subject strand.
     *
     * one out of { -3, -2, -1, +1, +2, +3 } where the <tt>absolute value - 1</tt>
     * is the shift of the translation frame and a negative sign indicates the
     * reverse complement strand [subject sequence, only applies for
     * BlastFormatProgram == TBLASTN | TBLASTX].
     *
     * @var double BlastMatch::eValue;
     *
     * @brief The e-value of the alignment.
     *
     * @var double BlastMatch::bitScore;
     *
     * @brief The bit-score of the alignment.
     *
     * @var AlignmentStats BlastMatch::alignStats;
     *
     * @brief An @link AlignmentStats @endlink object holding further stats of the
     *        alignment.
     *
     * @var TAlign BlastMatch::alignRow0;
     *
     * @brief First alignment row (@link Gaps @endlink object).
     *
     * @var TAlign BlastMatch::alignRow1;
     *
     * @brief Second alignment row (@link Gaps @endlink object).
     *
     * @fn BlastMatch#computeAlignmentStats
     *
     * @headerfile <seqan/blast.h>
     *
     * @brief Compute the @link BlastMatch::alignStats @endlink member of a @link
     *        BlastMatch @endlink.
     *
     * @signature void computeAlignmentStats(blastMatch, context);
     *
     * @param[in,out] blastMatch A @link BlastMatch @endlink that has a valid align
     *                           member.
     * @param[in] context A @link BlastIOContext @endlink with parameters and
     *                    buffers.
     *
     * The alignRow-members (@link BlastMatch::alignRow0 @endlink, @link
     * BlastMatch::alignRow1 @endlink) are used as in-parameter to compute the @link
     * BlastMatch::alignStats @endlink member. This includes the raw score, amount
     * of gaps, mismatches et cetera. This is a prerequisite for printing a match to
     * file or computing it's e-value.
     *
     * @fn BlastMatch#computeBitScore
     *
     * @headerfile <seqan/blast.h>
     *
     * @brief Compute the bit-score for a @link BlastMatch @endlink.
     *
     * @signature double computeBitScore(blastMatch, context);
     *
     * @param[in,out] blastMatch A @link BlastMatch @endlink that has a valid align
     *                           member.
     * @param[in] context A @link BlastIOContext @endlink with parameters and
     *                    buffers.
     *
     * @return double blastMatch.@link BlastMatch::bitScore @endlink after
     *                computation
     *
     * @section Remarks
     *
     * This will compute the bit-score for a @link BlastMatch @endlink. At least the
     * following members need to be set before calling this function: <li>
     * blastMatch.@link BlastMatch::alignStats @endlink.@link
     * AlignmentStats::alignmentScore @endlink (if you have valid alignRow-members
     * (@link BlastMatch::alignRow0 @endlink, @link BlastMatch::alignRow1 @endlink),
     * you can call @link BlastMatch#computeAlignmentStats @endlink to compute the
     * stats member). </li>
     *
     * @fn BlastMatch#computeEValue
     *
     * @headerfile <seqan/blast.h>
     *
     * @brief Compute the E-Value for a @link BlastMatch @endlink.
     *
     * @signature double computeEValue(blastMatch, qLength, context); [[deprecated]]
     *            double computeEValue(blastMatch, context);
     *
     * @param[in,out] blastMatch A @link BlastMatch @endlink that has a valid align
     *                           member.
     * @param[in] qLength The length of the query sequence (pass @link
     *                    BlastRecord::qLength @endlink).
     * @param[in,out] context A @link BlastIOContext @endlink with parameters and
     *                        buffers.
     *
     * @return double blastMatch.@link BlastMatch::eValue @endlink after computation
     *
     * @section Remarks
     *
     * This will compute the e-value for a @link BlastMatch @endlink. At least the
     * following members need to be set before calling this function: <li>
     * blastMatch.@link BlastMatch::alignStats @endlink.@link
     * AlignmentStats::alignmentScore @endlink (if you have valid alignRow-members
     * (@link BlastMatch::alignRow0 @endlink, @link BlastMatch::alignRow1 @endlink),
     * you can call @link BlastMatch#computeAlignmentStats @endlink to compute the
     * stats member). </li> <li> blastMatch.@link BlastMatch::qLength @endlink (only
     * in the deprecated interface)</li> <li> context.@link
     * BlastIOContext::dbTotalLength @endlink </li>
     *
     * Note, that in contrast to the general interface (@link
     * BlastScoringScheme#computeEValue @endlink), this interface caches some
     * computation steps in the context and is therefore faster.
     */