DeltaMap - SeqAn API Documentation

# Class DeltaMap
Stores delta information and maps them to a common coordinate system.

Defined in | <seqan/journaled_string_tree.h>
Signature | `template <typename TConfig> class DeltaMap`

## Template Parameters

`TConfig` | A config type to set the types for the different delta values.

## Interface Function Overview

- `TIterator begin(deltaMap, tag)`
  Returns an iterator pointing to the beginning of the map.
- `clear(deltaMap)`
  Clears the delta map.
- `TSize count(deltaMap, pos, type)`
  Counts the number of elements that compare equal to the specified key.
- `bool empty(deltaMap)`
  Checks if the delta map is empty.
- `TIterator end(deltaMap, tag)`
  Returns an iterator pointing to the end of the map.
- `Pair<TIterator> equalRange(deltaMap, pos, type)`
  Returns the range over all elements comparing equal to the specified key.
- `bool erase(deltaMap, pos, type);`
  Erases an existing delta entry.
- `TIterator find(deltaMap, pos, type)`
  Finds the element specified by the given delta position and delta type.
- `bool insert(deltaMap, pos, val, cov, type);`
  Inserts a new delta entry.
- `TIterator lowerBound(deltaMap, pos, type)`
  Finds the first element that compares not less than the specified key.
- `TSize size(deltaMap)`
  Returns the number of mapped delta events.
- `TSize size(deltaMap)`
  Returns the number of mapped delta events.
- `TIterator upperBound(deltaMap, pos, type)`
  Finds the first element that compares not less or equal to the specified key.

## Interface Metafunction Overview

- `DeltaCoverage<TDeltaMap>::Type`
  Returns coverage type for a delta map.
- `DeltaValue<TDeltaMap, TType>::Type`
  Returns value type for a specific delta.
- `Iterator<TDeltaMap, Standard>::Type`
  Returns iterator type for a delta map.
- `Size<TDeltaMap>::Type`
  Returns size type for a delta map.
- `Value<TDeltaMap>::Type`
  Returns value type for the delta map.

## Detailed Description

This map stores delta events, i.e. replacements, insertions and deletions, for multiple sequences based on a common reference sequence. A bitvector is used to store the coverage of a delta. The types of the corresponding delta values must be set with the `TConfig<\tt> object, which can be any object which defines the following types:`

`TDeltaPos<\tt>: The value type used to store the position of the delta within the reference. `TDeltaSnp<\tt>: The value type used to store SNPs. `TDeltaDel<\tt>: The value type used to store deletions. `TDeltaIns<\tt>: The value type used to store insertions. `TDeltaSV<\tt>: The value type used to store structural variants.`````

The delta values are stored in a multi-container. To access a delta value at any given iterator position of the delta map the delta type (see DeltaTypeTags) must be known. The function deltaType can be used to access the id of the corresponding delta event. Given the delta type the function deltaValue can be used to access the corresponding value.

The delta map implements the interfaces of the AssociativeContainerConcept<\b> and is a multi-map.

## Interface Functions Detail

### `TIterator begin(deltaMap, tag)`

Returns an iterator pointing to the beginning of the map.

#### Parameters

`deltaMap` | The map to get the iterator for.
`tag` | The iterator tag. Of type ContainerIteratorTags.

#### Returns

`TIterator` | An iterator of type Iterator pointing to the beginning of the map.

#### Data Races

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

### `clear(deltaMap)`

Clears the delta map.

#### Parameters

`deltaMap` | The map to be cleared.

#### Data Races

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

### `TSize count(deltaMap, pos, type)`

Counts the number of elements that compare equal to the specified key.

#### Parameters

`deltaMap` | The delta map that is searched for the element.
`pos` | The delta position to be searched for.
`type` | The type of the delta operation. Must be of type DeltaTypeTags.

#### Returns

`TSize` | the number of elements with the specified key. Of type Size.

@remark The runtime is logarithmic in the size of the map.

#### Data Races

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

### `bool empty(deltaMap)`

Checks if the delta map is empty.

#### Parameters

`deltaMap` | The map to be checked for.

#### Returns

`bool` | `true` if empty, otherwise `false`

#### Data Races

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

### `TIterator end(deltaMap, tag)`

Returns an iterator pointing to the end of the map.

#### Parameters

`deltaMap` | The map to get the iterator for.
`tag` | The iterator tag. Of type ContainerIteratorTags.

#### Returns

`TIterator` | An iterator of type Iterator pointing to the end of the map.

#### Data Races

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

### `Pair<TIterator> equalRange(deltaMap, pos, type)`

Returns the range over all elements comparing equal to the specified key.

#### Parameters

`deltaMap` | The delta map that is searched for the element.
`pos` | The delta position to be searched for.
`type` | The type of the delta operation. Must be of type DeltaTypeTags.

#### Returns

`Pair<TIterator>` | A Pair of iterator types Iterator. The first value points to the first element that compares not less than the specified key or to the end if such an elment could not be found. The second value points to the first element that does not compare less than or equal to the specified key or to the end if such an elment could not be found.

@remark The runtime is logarithmic in the size of the map.

#### Data Races

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

### `bool erase(deltaMap, pos, type);`

Erases an existing delta entry.

#### Parameters

`deltaMap` | The map to erase the delta from. Of type DeltaMap.
`pos` | The position of the targeted delta entry.
`type` | The type of the targeted delta entry. One of DeltaTypeTags.

#### Returns

`bool` | `false<\tt> if such an entry does not exist, `true<\tt> otherwise.``

@remark The map is implemented as a vector and the insertion time is linear in worst case.

#### Data Races

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

### `TIterator find(deltaMap, pos, type)`

Finds the element specified by the given delta position and delta type.

#### Parameters

`deltaMap` | The delta map that is searched for the element.
`pos` | The delta position to be searched for.
`type` | The type of the delta operation. Must be of type DeltaTypeTags.

#### Returns

`TIterator` | An Iterator pointing to the corresponding element. If the key is not contained end is returned.

@remark The runtime is logarithmic in the size of the map.

#### Data Races

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

### `bool insert(deltaMap, pos, val, cov, type);`

Inserts a new delta entry.

#### Parameters

`deltaMap` | The map to insert the new delta operation. Of type DeltaMap.
`pos` | The position of the inserted delta entry.
`deltaVal` | The value of the delta operation.
`cov` | The coverage of the delta operation.
`type` | A specifier to select the correct delta type. One of DeltaTypeTags.

@remark The map is implemented as a vector and the insertion time is linear in worst case.

#### Data Races

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

### `TIterator lowerBound(deltaMap, pos, type)`

Finds the first element that compares not less than the specified key.

#### Parameters

`deltaMap` | The delta map that is searched for the element.
`pos` | The delta position to be searched for.
`type` | The type of the delta operation. Must be of type DeltaTypeTags.

#### Returns

`TIterator` | An Iterator pointing to the corresponding element. If the key is not contained end is returned.

@remark The runtime is logarithmic in the size of the map.

#### Data Races

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

### `TSize size(deltaMap)`

Returns the number of mapped delta events.

#### Parameters

`deltaMap` | The map to get the size for.

#### Returns

`TSize` | The number of delta events stored in the map.

#### Data Races

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

### `TSize size(deltaMap)`

Returns the number of mapped delta events.

#### Parameters

`deltaMap` | The map to get the size for.

#### Returns

`TSize` | The number of delta events stored in the map.

#### Data Races

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

### `TIterator upperBound(deltaMap, pos, type)`

Finds the first element that compares not less or equal to the specified key.

#### Parameters

`deltaMap` | The delta map that is searched for the element.
`pos` | The delta position to be searched for.
`type` | The type of the delta operation. Must be of type DeltaTypeTags.

#### Returns

`TIterator` | An Iterator pointing to the corresponding element. If the key is not contained end is returned.

@remark The runtime is logarithmic in the size of the map.

#### Data Races

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

## Interface Metafunctions Detail

### `DeltaCoverage<TDeltaMap>::Type`

Returns coverage type for a delta map.

#### Template Parameters

`TDeltaMap` | The type of the delta map.

### `DeltaValue<TDeltaMap, TType>::Type`

Returns value type for a specific delta.

#### Template Parameters

`TDeltaMap` | The type of the delta map.
`TType` | The type of the delta value. One of DeltaTypeTags.

The delta map stores four different delta events: SNPs, insertions, deletions and variable replacements. This metafunction returns the correct type for the specified event given the delta type tag.

### `Iterator<TDeltaMap, Standard>::Type`

Returns iterator type for a delta map.

#### Template Parameters

`TDeltaMap` | The type to query the iterator type for.

#### Returns

`TIterator` | The iterator type to use for `TDeltaMap`. DeltaMapIterator.

### `Size<TDeltaMap>::Type`

Returns size type for a delta map.

#### Template Parameters

`TDeltaMap` | The type to query the size type for.

#### Returns

`TSize` | The size type to use for `TDeltaMap`.

### `Value<TDeltaMap>::Type`

Returns value type for the delta map.

#### Template Parameters

`TDeltaMap` | The type to query the value type for.

#### Returns

`TValue` | The value type to use for `TDeltaMap`.

#### Dox Sources

    /*!
     * @class DeltaMap
     *
     * @headerfile <seqan/journaled_string_tree.h>
     *
     * @brief Stores delta information and maps them to a common coordinate system.
     *
     * @signature template <typename TConfig> class DeltaMap
     *
     * @tparam TConfig A config type to set the types for the different delta
     *                 values.
     *
     * This map stores delta events, i.e. replacements, insertions and deletions,
     * for multiple sequences based on a common reference sequence. A bitvector is
     * used to store the coverage of a delta. The types of the corresponding delta
     * values must be set with the <tt>TConfig<\tt> object, which can be any object
     * which defines the following types:
     *
     * <tt>TDeltaPos<\tt>: The value type used to store the position of the delta
     * within the reference. <tt>TDeltaSnp<\tt>: The value type used to store SNPs.
     * <tt>TDeltaDel<\tt>: The value type used to store deletions.
     * <tt>TDeltaIns<\tt>: The value type used to store insertions.
     * <tt>TDeltaSV<\tt>: The value type used to store structural variants.
     *
     * The delta values are stored in a multi-container. To access a delta value at
     * any given iterator position of the delta map the delta type (see @link
     * DeltaTypeTags @endlink) must be known. The function @link
     * DeltaMapIterator#deltaType @endlink can be used to access the id of the
     * corresponding delta event. Given the delta type the function @link
     * DeltaMapIterator#deltaValue @endlink can be used to access the corresponding
     * value.
     *
     * The delta map implements the interfaces of the
     * <b>AssociativeContainerConcept<\b> and is a multi-map.
     *
     * @mfn DeltaMap#Value
     *
     * @headerfile <seqan/journaled_string_tree.h>
     *
     * @brief Returns value type for the delta map.
     *
     * @signature Value<TDeltaMap>::Type
     *
     * @tparam TDeltaMap The type to query the value type for.
     *
     * @return TValue The value type to use for <tt>TDeltaMap</tt>.
     *
     * @mfn DeltaMap#Size
     *
     * @headerfile <seqan/journaled_string_tree.h>
     *
     * @brief Returns size type for a delta map.
     *
     * @signature Size<TDeltaMap>::Type
     *
     * @tparam TDeltaMap The type to query the size type for.
     *
     * @return TSize The size type to use for <tt>TDeltaMap</tt>.
     *
     * @mfn DeltaMap#Iterator
     *
     * @headerfile <seqan/journaled_string_tree.h>
     *
     * @brief Returns iterator type for a delta map.
     *
     * @signature Iterator<TDeltaMap, Standard>::Type
     *
     * @tparam TDeltaMap The type to query the iterator type for.
     *
     * @return TIterator The iterator type to use for <tt>TDeltaMap</tt>. @link
     *                   DeltaMapIterator @endlink.
     *
     * @mfn DeltaMap#DeltaValue
     *
     * @headerfile <seqan/journaled_string_tree.h>
     *
     * @brief Returns value type for a specific delta.
     *
     * @signature DeltaValue<TDeltaMap, TType>::Type
     *
     * @tparam TDeltaMap The type of the delta map.
     * @tparam TType The type of the delta value. One of @link DeltaTypeTags
     *               @endlink.
     *
     * The delta map stores four different delta events: SNPs, insertions, deletions
     * and variable replacements. This metafunction returns the correct type for the
     * specified event given the delta type tag.
     *
     * @mfn DeltaMap#DeltaCoverage
     *
     * @headerfile <seqan/journaled_string_tree.h>
     *
     * @brief Returns coverage type for a delta map.
     *
     * @signature DeltaCoverage<TDeltaMap>::Type
     *
     * @tparam TDeltaMap The type of the delta map.
     *
     * @fn DeltaMap#lowerBound
     *
     * @headerfile <seqan/journaled_string_tree.h>
     *
     * @brief Finds the first element that compares not less than the specified key.
     *
     * @signature TIterator lowerBound(deltaMap, pos, type)
     *
     * @param[in] deltaMap The delta map that is searched for the element.
     * @param[in] pos The delta position to be searched for.
     * @param[in] type The type of the delta operation. Must be of type @link
     *                 DeltaTypeTags @endlink.
     *
     * @return TIterator An @link DeltaMap#Iterator @endlink pointing to the
     *                   corresponding element. If the key is not contained @link
     *                   DeltaMap#end @endlink is returned.
     *
     * @remark The runtime is logarithmic in the size of the map.
     *
     * @fn DeltaMap#upperBound
     *
     * @headerfile <seqan/journaled_string_tree.h>
     *
     * @brief Finds the first element that compares not less or equal to the
     *        specified key.
     *
     * @signature TIterator upperBound(deltaMap, pos, type)
     *
     * @param[in] deltaMap The delta map that is searched for the element.
     * @param[in] pos The delta position to be searched for.
     * @param[in] type The type of the delta operation. Must be of type @link
     *                 DeltaTypeTags @endlink.
     *
     * @return TIterator An @link DeltaMap#Iterator @endlink pointing to the
     *                   corresponding element. If the key is not contained @link
     *                   DeltaMap#end @endlink is returned.
     *
     * @remark The runtime is logarithmic in the size of the map.
     *
     * @fn DeltaMap#find
     *
     * @headerfile <seqan/journaled_string_tree.h>
     *
     * @brief Finds the element specified by the given delta position and delta
     *        type.
     *
     * @signature TIterator find(deltaMap, pos, type)
     *
     * @param[in] deltaMap The delta map that is searched for the element.
     * @param[in] pos The delta position to be searched for.
     * @param[in] type The type of the delta operation. Must be of type @link
     *                 DeltaTypeTags @endlink.
     *
     * @return TIterator An @link DeltaMap#Iterator @endlink pointing to the
     *                   corresponding element. If the key is not contained @link
     *                   DeltaMap#end @endlink is returned.
     *
     * @remark The runtime is logarithmic in the size of the map.
     *
     * @fn DeltaMap#count
     *
     * @headerfile <seqan/journaled_string_tree.h>
     *
     * @brief Counts the number of elements that compare equal to the specified key.
     *
     * @signature TSize count(deltaMap, pos, type)
     *
     * @param[in] deltaMap The delta map that is searched for the element.
     * @param[in] pos The delta position to be searched for.
     * @param[in] type The type of the delta operation. Must be of type @link
     *                 DeltaTypeTags @endlink.
     *
     * @return TSize the number of elements with the specified key. Of type @link
     *               DeltaMap#Size @endlink.
     *
     * @remark The runtime is logarithmic in the size of the map.
     *
     * @fn DeltaMap#equalRange
     *
     * @headerfile <seqan/journaled_string_tree.h>
     *
     * @brief Returns the range over all elements comparing equal to the specified
     *        key.
     *
     * @signature Pair<TIterator> equalRange(deltaMap, pos, type)
     *
     * @param[in] deltaMap The delta map that is searched for the element.
     * @param[in] pos The delta position to be searched for.
     * @param[in] type The type of the delta operation. Must be of type @link
     *                 DeltaTypeTags @endlink.
     *
     * @return Pair<TIterator> A @link Pair @endlink of iterator types @link
     *                         DeltaMap#Iterator @endlink. The first value points to
     *                         the first element that compares not less than the
     *                         specified key or to the @link DeltaMap#end @endlink
     *                         if such an elment could not be found. The second
     *                         value points to the first element that does not
     *                         compare less than or equal to the specified key or to
     *                         the @link DeltaMap#end @endlink if such an elment
     *                         could not be found.
     *
     * @remark The runtime is logarithmic in the size of the map.
     *
     * @fn DeltaMap#insert
     *
     * @headerfile <seqan/journaled_string_tree.h>
     *
     * @brief Inserts a new delta entry.
     *
     * @signature bool insert(deltaMap, pos, val, cov, type);
     *
     * @param[in,out] deltaMap The map to insert the new delta operation. Of type
     *                         @link DeltaMap @endlink.
     * @param[in] pos The position of the inserted delta entry.
     * @param[in] deltaVal The value of the delta operation.
     * @param[in] cov The coverage of the delta operation.
     * @param[in] type A specifier to select the correct delta type. One of @link
     *                 DeltaTypeTags @endlink.
     *
     * @remark The map is implemented as a vector and the insertion time is linear
     * in worst case.
     *
     * @fn DeltaMap#erase
     *
     * @headerfile <seqan/journaled_string_tree.h>
     *
     * @brief Erases an existing delta entry.
     *
     * @signature bool erase(deltaMap, pos, type);
     *
     * @param[in,out] deltaMap The map to erase the delta from. Of type @link
     *                         DeltaMap @endlink.
     * @param[in] pos The position of the targeted delta entry.
     * @param[in] type The type of the targeted delta entry. One of @link
     *                 DeltaTypeTags @endlink.
     *
     * @return bool <tt>false<\tt> if such an entry does not exist, <tt>true<\tt>
     *              otherwise.
     *
     * @remark The map is implemented as a vector and the insertion time is linear
     * in worst case.
     *
     * @fn DeltaMap#begin
     *
     * @headerfile <seqan/journaled_string_tree.h>
     *
     * @brief Returns an iterator pointing to the beginning of the map.
     *
     * @signature TIterator begin(deltaMap, tag)
     *
     * @param[in] deltaMap The map to get the iterator for.
     * @param[in] tag The iterator tag. Of type @link ContainerIteratorTags
     *                @endlink.
     *
     * @return TIterator An iterator of type @link DeltaMap#Iterator @endlink
     *                   pointing to the beginning of the map.
     *
     * @fn DeltaMap#end
     *
     * @headerfile <seqan/journaled_string_tree.h>
     *
     * @brief Returns an iterator pointing to the end of the map.
     *
     * @signature TIterator end(deltaMap, tag)
     *
     * @param[in] deltaMap The map to get the iterator for.
     * @param[in] tag The iterator tag. Of type @link ContainerIteratorTags
     *                @endlink.
     *
     * @return TIterator An iterator of type @link DeltaMap#Iterator @endlink
     *                   pointing to the end of the map.
     *
     * @fn DeltaMap#clear
     *
     * @headerfile <seqan/journaled_string_tree.h>
     *
     * @brief Clears the delta map.
     *
     * @signature clear(deltaMap)
     *
     * @param[in,out] deltaMap The map to be cleared.
     *
     * @fn DeltaMap#empty
     *
     * @headerfile <seqan/journaled_string_tree.h>
     *
     * @brief Checks if the delta map is empty.
     *
     * @signature bool empty(deltaMap)
     *
     * @param[in] deltaMap The map to be checked for.
     *
     * @return bool <tt>true</tt> if empty, otherwise <tt>false</tt>
     *
     * @fn DeltaMap#size
     *
     * @headerfile <seqan/journaled_string_tree.h>
     *
     * @brief Returns the number of mapped delta events.
     *
     * @signature TSize size(deltaMap)
     *
     * @param[in] deltaMap The map to get the size for.
     *
     * @return TSize The number of delta events stored in the map.
     *
     * @fn DeltaMap#maxSize
     *
     * @headerfile <seqan/journaled_string_tree.h>
     *
     * @brief Returns the number of mapped delta events.
     *
     * @signature TSize size(deltaMap)
     *
     * @param[in] deltaMap The map to get the size for.
     *
     * @return TSize The number of delta events stored in the map.
     */