Journaled String Tree - SeqAn API Documentation

# Class Journaled String Tree
This data structure represents a virtual set of strings using a veritcal compression scheme.

Defined in | <seqan/journaled_string_tree.h>
Signature | `template <typename TSequence[, typename TConfig][, TSpec]> class JournaledStringTree<TDeltaStore, TConfig, TSpec>;`

## Template Parameters

`TSequence` | Type of underlying base sequence.
`TConfig` | A configuration object, whose traits can be used to specialize the underlying DeltaMap. Defaults to DefaultJstConfig.
`TSpec` | The specialization tag for the journaled string tree. Defaults to Default.

## Member Function Overview

- `JournaledStringTree();, JournaledStringTree(size);, JournaledStringTree(source, size);`
  Constructor.

## Interface Function Overview

- `void clear(jst);`
  Clears the journaled string tree.
- `bool erase(jst, pos, type);`
  Erases a delta event in the journaled string tree.
- `THost host(jst);`
  Returns the set base sequence.
- `bool insert(jst, pos, val, ids, type);`
  Adds a new delta ecent to the journaled string tree.
- `TSize length(jst);`
  Returns the number of sequences represented by the journaled string tree.
- `void resize(jst, size);`
  Resizes the number of sequences represented by the journaled string tree.
- `void setHost(jst, host);`
  Sets the base sequence of the journaled string tree.

## Interface Metafunction Overview

- `Host<TJst>::Type;`
  The host type.
- `Position<TJst>::Type;`
  The position type.
- `Size<TJst>::Type;`
  The size type.
- `Spec<TJst>::Type;`
  Returns the specialization type.

## Detailed Description

This data structure stores a virtual set of sequences in a compressed form. The sequences are described in form of a pointer to a common reference sequence and in addition delta events, which are stored in a DeltaMap. The interface is a hybrid between a container interface and a associative container interface. So it uses typical string set intrefaces to access the virtual strings. On the other hand it implements an associative container to store the delta events given their reference position as a key. This data structure can then be traversed efficiently, while exploring only those sequence contexts, that are unique to the set of sequences. This means, that redundant parts, that are shared by one or many sequences is traversed only once.

## Member Functions Detail

### `JournaledStringTree(); JournaledStringTree(size); JournaledStringTree(source, size);`

Constructor.

#### Parameters

`size` | The number of sequences represented by the JST.
`source` | The underlying base sequence to which the sequences are compressed.

#### Data Races

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

## Interface Functions Detail

### `void clear(jst);`

Clears the journaled string tree.

#### Parameters

`jst` | The journaled string tree to be cleared.

#### Data Races

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

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

Erases a delta event in the journaled string tree.

#### Parameters

`jst` | The journaled string tree to be modified.
`pos` | The host source position of the delta event.
`type` | A tag representing the type of the delta event. One of DeltaTypeTags. Note there can be multiple nodes at the same `pos<\tt> with different `type<\tt>.``

A delta event is described by it's host position and the type. If a left end of a deletion is deleted its accompanied right end is deleted as well.

@remark The deletion time is depends on the implementation of the underlying DeltaMap. See erase for detailed information.

#### Data Races

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

#### See Also

- insert

### `THost host(jst);`

Returns the set base sequence.

#### Parameters

`jst` | The journaled string tree.

#### Returns

`THost` | A reference to the host of type Host.

#### Data Races

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

### `bool insert(jst, pos, val, ids, type);`

Adds a new delta ecent to the journaled string tree.

#### Parameters

`jst` | The journaled string tree to be modified.
`pos` | The position of the host to place the new delta event at. This position must not exceed length of the host.
`val` | The value of the delta event.
`ids` | An object of ContainerConcept storing the ids of the sequences covering this delta event. The ids must be in the range [0, length).
`type` | A tag representing the type of the delta event. One of DeltaTypeTags.

Note the value given by `val<\tt> depends on the `type<\tt>, which can be a single character, a string, an integer or a pair of integer and string, representing a SNP, an insertion, a deletion or a structural variant respectively.``

When inserting a deletion of size > 1 (the same holds for the structural variant), the event is split into a left begin and a right begin and two events are inserted into the underlying DeltaMap. Hence the number of inserted events can differ from the actual number of calls to the insert function.

@remark The insertion time depends on the implementation of the underlying DeltaMap. See insert for more details.

#### Data Races

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

#### See Also

- erase

### `TSize length(jst);`

Returns the number of sequences represented by the journaled string tree.

#### Parameters

`jst` | The journaled string tree to query the length for.

#### Returns

`TSize` | The number of sequences represented by the `jst<\tt>. Of type Size.`

#### Data Races

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

### `void resize(jst, size);`

Resizes the number of sequences represented by the journaled string tree.

#### Parameters

`jst` | The journaled string tree to resize.
`size` | The new size of the `jst`.

Note, when invoking this method all stored delta events are parsed and their coverage is resized to the given `size`. If `size` is smaller than the previous size this reduces the actual size of the stored coverages. If `size` is bigger than the previous size, the coverages are filled up with 0s, i.e. they represent a copy of the underlying base sequence. Hence the performance is linear in the number of stored delta events times the linear time for resizing the coverages.

#### Data Races

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

#### See Also

- length

### `void setHost(jst, host);`

Sets the base sequence of the journaled string tree.

#### Parameters

`jst` | The journaled string tree.
`host` | The new host to set.

When setting a new host, the `jst` will be cleared all previous information are lost.

#### Data Races

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

## Interface Metafunctions Detail

### `Host<TJst>::Type;`

The host type.

#### Template Parameters

`TJst` | The JST type to get the host type for.

#### Returns

`THost` | The type of the underlying data structure.

### `Position<TJst>::Type;`

The position type.

#### Template Parameters

`TJst` | The JST type to get the position type for.

#### Returns

`TPosition` | The position type.

### `Size<TJst>::Type;`

The size type.

#### Template Parameters

`TJst` | The JST type to get the size type for.

#### Returns

`TSize` | The size type.

### `Spec<TJst>::Type;`

Returns the specialization type.

#### Template Parameters

`TJst` | The JST type to query the specialization type for.

#### Returns

`TSpec` | The specialization type.

#### Dox Sources

    /*!
     * @class JournaledStringTree Journaled String Tree
     *
     * @headerfile <seqan/journaled_string_tree.h>
     *
     * @brief This data structure represents a virtual set of strings using a
     *        veritcal compression scheme.
     *
     * @signature template <typename TSequence[, typename TConfig][, TSpec]> class
     *            JournaledStringTree<TDeltaStore, TConfig, TSpec>;
     *
     * @tparam TSequence Type of underlying base sequence.
     * @tparam TConfig A configuration object, whose traits can be used to
     *                 specialize the underlying @link DeltaMap @endlink. Defaults
     *                 to @link DefaultJstConfig @endlink.
     * @tparam TSpec The specialization tag for the journaled string tree. Defaults
     *               to @link Default @endlink.
     *
     * This data structure stores a virtual set of sequences in a compressed form.
     * The sequences are described in form of a pointer to a common reference
     * sequence and in addition delta events, which are stored in a @link DeltaMap
     * @endlink. The interface is a hybrid between a container interface and a
     * associative container interface. So it uses typical string set intrefaces to
     * access the virtual strings. On the other hand it implements an associative
     * container to store the delta events given their reference position as a key.
     * This data structure can then be traversed efficiently, while exploring only
     * those sequence contexts, that are unique to the set of sequences. This means,
     * that redundant parts, that are shared by one or many sequences is traversed
     * only once.
     *
     * @mfn JournaledStringTree#Spec
     *
     * @headerfile <seqan/journaled_string_tree.h>
     *
     * @brief Returns the specialization type.
     *
     * @signature Spec<TJst>::Type;
     *
     * @tparam TJst The JST type to query the specialization type for.
     *
     * @return TSpec The specialization type.
     *
     * @mfn JournaledStringTree#Size
     *
     * @headerfile <seqan/journaled_string_tree.h>
     *
     * @brief The size type.
     *
     * @signature Size<TJst>::Type;
     *
     * @tparam TJst The JST type to get the size type for.
     *
     * @return TSize The size type.
     *
     * @mfn JournaledStringTree#Position
     *
     * @headerfile <seqan/journaled_string_tree.h>
     *
     * @brief The position type.
     *
     * @signature Position<TJst>::Type;
     *
     * @tparam TJst The JST type to get the position type for.
     *
     * @return TPosition The position type.
     *
     * @mfn JournaledStringTree#Host
     *
     * @headerfile <seqan/journaled_string_tree.h>
     *
     * @brief The host type.
     *
     * @signature Host<TJst>::Type;
     *
     * @tparam TJst The JST type to get the host type for.
     *
     * @return THost The type of the underlying data structure.
     *
     * @fn JournaledStringTree::JournaledStringTree
     *
     * @headerfile <seqan/journaled_string_tree.h>
     *
     * @brief Constructor.
     *
     * @signature JournaledStringTree();
     * @signature JournaledStringTree(size);
     * @signature JournaledStringTree(source, size);
     *
     * @param size The number of sequences represented by the JST.
     * @param source The underlying base sequence to which the sequences are
     *               compressed.
     *
     * @fn JournaledStringTree#host
     *
     * @headerfile <seqan/journaled_string_tree.h>
     *
     * @brief Returns the set base sequence.
     *
     * @signature THost host(jst);
     *
     * @param[in] jst The journaled string tree.
     *
     * @return THost A reference to the host of type @link JournaledStringTree#Host
     *               @endlink.
     *
     * @fn JournaledStringTree#setHost
     *
     * @headerfile <seqan/journaled_string_tree.h>
     *
     * @brief Sets the base sequence of the journaled string tree.
     *
     * @signature void setHost(jst, host);
     *
     * @param[in,out] jst The journaled string tree.
     * @param[in] host The new host to set.
     *
     * When setting a new host, the <tt>jst</tt> will be cleared all previous
     * information are lost.
     *
     * @fn JournaledStringTree#length
     *
     * @headerfile <seqan/journaled_string_tree.h>
     *
     * @brief Returns the number of sequences represented by the journaled string
     *        tree.
     *
     * @signature TSize length(jst);
     *
     * @param[in] jst The journaled string tree to query the length for.
     *
     * @return TSize The number of sequences represented by the <tt>jst<\tt>. Of
     *               type @link JournaledStringTree#Size @endlink.
     *
     * @fn JournaledStringTree#resize
     *
     * @headerfile <seqan/journaled_string_tree.h>
     *
     * @brief Resizes the number of sequences represented by the journaled string
     *        tree.
     *
     * @signature void resize(jst, size);
     *
     * @param[in,out] jst The journaled string tree to resize.
     * @param[in] size The new size of the <tt>jst</tt>.
     *
     * Note, when invoking this method all stored delta events are parsed and their
     * coverage is resized to the given <tt>size</tt>. If <tt>size</tt> is smaller
     * than the previous size this reduces the actual size of the stored coverages.
     * If <tt>size</tt> is bigger than the previous size, the coverages are filled
     * up with 0s, i.e. they represent a copy of the underlying base sequence. Hence
     * the performance is linear in the number of stored delta events times the
     * linear time for resizing the coverages.
     *
     * @see JournaledStringTree#length
     *
     * @fn JournaledStringTree#clear
     *
     * @headerfile <seqan/journaled_string_tree.h>
     *
     * @brief Clears the journaled string tree.
     *
     * @signature void clear(jst);
     *
     * @param[in,out] jst The journaled string tree to be cleared.
     *
     * @fn JournaledStringTree#insert
     *
     * @headerfile <seqan/journaled_string_tree.h>
     *
     * @brief Adds a new delta ecent to the journaled string tree.
     *
     * @signature bool insert(jst, pos, val, ids, type);
     *
     * @param[in,out] jst The journaled string tree to be modified.
     * @param[in] pos The position of the host to place the new delta event at. This
     *                position must not exceed length of the @link
     *                JournaledStringTree#host @endlink.
     * @param[in] val The value of the delta event.
     * @param[in] ids An object of @link ContainerConcept @endlink storing the ids
     *                of the sequences covering this delta event. The ids must be in
     *                the range [0, @link JournaledStringTree#length @endlink).
     * @param[in] type A tag representing the type of the delta event. One of @link
     *                 DeltaTypeTags @endlink.
     *
     * Note the value given by <tt>val<\tt> depends on the <tt>type<\tt>, which can
     * be a single character, a string, an integer or a pair of integer and string,
     * representing a SNP, an insertion, a deletion or a structural variant
     * respectively.
     *
     * When inserting a deletion of size > 1 (the same holds for the structural
     * variant), the event is split into a left begin and a right begin and two
     * events are inserted into the underlying @link DeltaMap @endlink. Hence the
     * number of inserted events can differ from the actual number of calls to the
     * insert function.
     *
     * @remark The insertion time depends on the implementation of the underlying
     * @link DeltaMap @endlink. See @link DeltaMap#insert @endlink for more details.
     *
     * @see JournaledStringTree#erase
     *
     * @fn JournaledStringTree#erase
     *
     * @headerfile <seqan/journaled_string_tree.h>
     *
     * @brief Erases a delta event in the journaled string tree.
     *
     * @signature bool erase(jst, pos, type);
     *
     * @param[in,out] jst The journaled string tree to be modified.
     * @param[in] pos The host source position of the delta event.
     * @param[in] type A tag representing the type of the delta event. One of @link
     *                 DeltaTypeTags @endlink. Note there can be multiple nodes at
     *                 the same <tt>pos<\tt> with different <tt>type<\tt>.
     *
     * A delta event is described by it's host position and the type. If a left end
     * of a deletion is deleted its accompanied right end is deleted as well.
     *
     * @remark The deletion time is depends on the implementation of the underlying
     * @link DeltaMap @endlink. See @link DeltaMap#erase @endlink for detailed
     * information.
     *
     * @see JournaledStringTree#insert
     */