GenomicRegion - SeqAn API Documentation

# Class GenomicRegion
Store information about a genomic region.

Defined in | <seqan/seq_io.h>
Signature | `class GenomicRegion;`

## Member Function Overview

- `GenomicRegion::GenomicRegion();, GenomicRegion::GenomicRegion(str);`
  Constructor.
- `void GenomicRegion::toString(out);`
  Write string representation of interval to out.

## Interface Function Overview

- `void clear(genomicRegion);`
  Reset a GenomicRegion object to the same state after default construction.
- `bool parse(genomicRegion, regionString);`
  Parse genomic region string store results in GenomicRegion.

## Member Variable Overview

- `int32_t GenomicRegion::beginPos`
  Begin position of the range on the chromosome. Default is `-1`.
- `int32_t GenomicRegion::endPos`
  End position of the range on the chromosome. Default is `-1`.
- `int32_t GenomicRegion::INVALID_ID`
  Constant for marking a position as invalid (static-const member).
- `int32_t GenomicRegion::INVALID_POS`
  Constant for marking a position as invalid (static-const member).
- `int32_t GenomicRegion::rID`
  An optional field storing an integer. Default is `-1`.
- `CharString GenomicRegion::seqName`
  Name of the sequence the region lies on, default is the empty string.

## Detailed Description

A genomic region is a range on a chromosome. The chromosome is identified by its name (as text in seqName, optionally also as an `integer` in rID). The range is stored as a half-open interval [beginPos, endPos). If beginPos is set to `-1` then the range spans the whole chromosome. If beginPos is set to a value `>= 0` and endPos is set ot `-1`, then the chromosome is selected from beginPos to the end.

Examples for genomic regions are `chr1`, `chr1:1,000`, `chr1:1,000-2,000`.

The textual description of a genomic region has one of the formats `NAME`, `NAME:START`, `NAME:START-END`. The positions in the textual representation `START` and `END` are one-based. However, the representation in the members of GenomicRegion is zero-based.

### Examples

Construct a GenomicRegion object and fill it from different region strings.

    seqan2::GenomicRegion genomicRegion;

    parse(genomicRegion, "chr1");
    // genomicRegion.seqName == "chr1"
    // genomicRegion.rID == -1, genomicRegion.beginPos == -1, genomicRegion.beginPos == -1

    parse(genomicRegion, "chr1:1000");
    // genomicRegion.seqName == "chr1"
    // genomicRegion.beginPos == 999
    // genomicRegion.rID == -1, genomicRegion.beginPos == -1

    parse(genomicRegion, "chr1:1000-2000");
    // genomicRegion.seqName == "chr1"
    // genomicRegion.beginPos == 999
    // genomicRegion.beginPos == 2000
    // genomicRegion.rID == -1

## Member Functions Detail

### `GenomicRegion::GenomicRegion(); GenomicRegion::GenomicRegion(str);`

Constructor.

#### Parameters

`str` | The string to parse region from. Types: CharString

The default constructor sets all integer members to `INVALID_POS`, the `seqName` member is left empty.

#### Data Races

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

### `void GenomicRegion::toString(out);`

Write string representation of interval to out.

#### Parameters

`out` | Target to write textual interval description to.

#### Data Races

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

## Interface Functions Detail

### `void clear(genomicRegion);`

Reset a GenomicRegion object to the same state after default construction.

#### Parameters

`genomicRegion` | The GenomicRegion object to reset. Types: GenomicRegion

#### Data Races

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

### `bool parse(genomicRegion, regionString);`

Parse genomic region string store results in GenomicRegion.

#### Parameters

`regionString` | The region string to prse. Types: CharString.
`genomicRegion` | The GenomicRegion object to write the results to. Types: GenomicRegion

#### Returns

`bool` | true indicates successful parsing.

#### Data Races

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

## Member Variables Detail

### `int32_t GenomicRegion::beginPos`

Begin position of the range on the chromosome. Default is `-1`.

### `int32_t GenomicRegion::endPos`

End position of the range on the chromosome. Default is `-1`.

### `int32_t GenomicRegion::INVALID_ID`

Constant for marking a position as invalid (static-const member).

### `int32_t GenomicRegion::INVALID_POS`

Constant for marking a position as invalid (static-const member).

### `int32_t GenomicRegion::rID`

An optional field storing an integer. Default is `-1`.

### `CharString GenomicRegion::seqName`

Name of the sequence the region lies on, default is the empty string.

#### Dox Sources

    /*!
     * @class GenomicRegion
     *
     * @headerfile <seqan/seq_io.h>
     *
     * @brief Store information about a genomic region.
     *
     * @signature class GenomicRegion;
     *
     * A genomic region is a range on a chromosome. The chromosome is identified by
     * its name (as text in @link GenomicRegion::seqName @endlink, optionally also
     * as an <tt>integer</tt> in @link GenomicRegion::rID @endlink). The range is
     * stored as a half-open interval [@link GenomicRegion::beginPos @endlink, @link
     * GenomicRegion::endPos @endlink). If @link GenomicRegion::beginPos @endlink is
     * set to <tt>-1</tt> then the range spans the whole chromosome. If @link
     * GenomicRegion::beginPos @endlink is set to a value <tt>&gt;= 0</tt> and @link
     * GenomicRegion::endPos @endlink is set ot <tt>-1</tt>, then the chromosome is
     * selected from @link GenomicRegion::beginPos @endlink to the end.
     *
     * Examples for genomic regions are <tt>chr1</tt>, <tt>chr1:1,000</tt>,
     * <tt>chr1:1,000-2,000</tt>.
     *
     * The textual description of a genomic region has one of the formats
     * <tt>NAME</tt>, <tt>NAME:START</tt>, <tt>NAME:START-END</tt>. The positions in
     * the textual representation <tt>START</tt> and <tt>END</tt> are one-based.
     * However, the representation in the members of @link GenomicRegion @endlink is
     * zero-based.
     *
     * @section Examples
     *
     * Construct a @link GenomicRegion @endlink object and fill it from different
     * region strings.
     *
     * @code{.cpp}
     * seqan2::GenomicRegion genomicRegion;
     *
     * parse(genomicRegion, "chr1");
     * // genomicRegion.seqName == "chr1"
     * // genomicRegion.rID == -1, genomicRegion.beginPos == -1, genomicRegion.beginPos == -1
     *
     * parse(genomicRegion, "chr1:1000");
     * // genomicRegion.seqName == "chr1"
     * // genomicRegion.beginPos == 999
     * // genomicRegion.rID == -1, genomicRegion.beginPos == -1
     *
     * parse(genomicRegion, "chr1:1000-2000");
     * // genomicRegion.seqName == "chr1"
     * // genomicRegion.beginPos == 999
     * // genomicRegion.beginPos == 2000
     * // genomicRegion.rID == -1
     * @endcode
     *
     *
     *
     *
     * @fn GenomicRegion::GenomicRegion
     *
     * @brief Constructor.
     *
     * @signature GenomicRegion::GenomicRegion();
     * @signature GenomicRegion::GenomicRegion(str);
     *
     * @param[in] str The string to parse region from. Types: CharString
     *
     * The default constructor sets all integer members to <tt>INVALID_POS</tt>, the
     * <tt>seqName</tt> member is left empty.
     *
     * @fn GenomicRegion::toString
     *
     * @brief Write string representation of interval to out.
     *
     * @signature void GenomicRegion::toString(out);
     *
     * @param[in,out] out Target to write textual interval description to.
     *
     * @fn GenomicRegion#clear
     *
     * @brief Reset a GenomicRegion object to the same state after default
     *        construction.
     *
     * @signature void clear(genomicRegion);
     *
     * @param[in,out] genomicRegion The @link GenomicRegion @endlink object to
     *                              reset. Types: GenomicRegion
     *
     * @fn GenomicRegion#parse
     *
     * @brief Parse genomic region string store results in @link GenomicRegion
     *        @endlink.
     *
     * @signature bool parse(genomicRegion, regionString);
     *
     * @param[in] regionString The region string to prse. Types: @link CharString
     *                         @endlink.
     * @param[out] genomicRegion The @link GenomicRegion @endlink object to write
     *                           the results to. Types: GenomicRegion
     *
     * @return bool true indicates successful parsing.
     *
     * @var int32_t GenomicRegion::INVALID_POS;
     *
     * @brief Constant for marking a position as invalid (static-const member).
     *
     * @var int32_t GenomicRegion::INVALID_ID;
     *
     * @brief Constant for marking a position as invalid (static-const member).
     *
     * @var CharString GenomicRegion::seqName;
     *
     * @brief Name of the sequence the region lies on, default is the empty string.
     *
     * @var int32_t GenomicRegion::rID;
     *
     * @brief An optional field storing an integer. Default is <tt>-1</tt>.
     *
     * @var int32_t GenomicRegion::beginPos;
     *
     * @brief Begin position of the range on the chromosome. Default is <tt>-1</tt>.
     *
     * @var int32_t GenomicRegion::endPos;
     *
     * @brief End position of the range on the chromosome. Default is <tt>-1</tt>.
     */