/*!
* @class FragmentStore
*
* @headerfile <seqan/store.h>
*
* @brief Multi-container to store contigs, reads, multiple read alignments and
* genome annotations.
*
* @signature template <[typename TSpec[, typename TConfig]]> class
* FragmentStore;
*
* @tparam TSpec The specialializing type. Default: <tt>void</tt>.
* @tparam TConfig The configuration struct. Default:
* <tt>FragmentStoreConfig<TSpec></tt>.
*
* The FragmentStore is a data structure specifically designed for read mapping,
* genome assembly or gene annotation. These tasks typically require lots of
* data structures that are related to each other like: reads, mate-pairs,
* reference genome; pairwise alignments; genome annotation.
*
* The FragmentStore subsumes all these data structures in an easy to use
* interface. It represents a multiple alignment of millions of reads or mate-
* pairs against a reference genome consisting of multiple contigs.
* Additionally, regions of the reference genome can be annotated with features
* like 'gene', 'mRNA', 'exon', 'intro' or custom features. The FragmentStore
* supports I/O functions to read/write a read alignment in Sam or Amos format
* and to read/write annotations in Gff/Gtf format.
*
* The FragmentStore can be compared with a database where each table (called
* "store") is implemented as a String member of the FragmentStore class. The
* rows of each table (implemented as structs) are referred by their ids which
* are their positions in the string and not stored explicitly. The only
* exception is the alignedReadStore whose elements of type
* AlignedReadStoreElement contain an id-member as they may be rearranged in
* arbitrary order, e.g. by increasing genomic positions or by readId. Many
* stores have an associated name store to store element names. Each name store
* is a StringSet that stores the element name at the position of its id. All
* stores are present in the FragmentStore and empty if unused. The concrete
* types, e.g. the position types or read/contig alphabet, can be easily changed
* by defining a custom config struct which is a template parameter of the
* FragmentStore class.
*
* @section Examples
*
* Load read alignments and a reference genome and display the multiple
* alignment in a genomic range:
*
* @include demos/dox/store/store_example.cpp
*
* @code{.console}
* ATTTAAGAAATTACAAAATATAGTTGAAAGCTCTAACAATAGACTAAACCAAGCAGAAGAAAGAGGTTCAGAACTTGAAGACAAGTCTCTTATGAATTAA
* ATTTAA AATTACAAAATATAGTTGAAAGCTCTAACAATAGA AACCAAGCAGAAGAAAGAGGTTCAGAACTTGAAGA AGTCTCTTATGAATTAA
* ATTTA GAAATTACAAAATATAGTTGAAAGCTCTAACAATA ACTAAACCAAGCAGAAGAAAGAGGTTCAGAACTTG AGACAAGTCTCTTATGAATTAA
* attta GAAATTACAAAATATAGTTGAAAGCTCTAACAATAG AACCAAGCAGAAGAAAGAGGCTCAGAACTTGAAGA AGTCTCTTATGAATTAA
* ATTTAA ATTACAAAATATAGTTGAAAGATCTAACAATAGAC CCAAGCAGAAGAAAGAGGTTCAGAACTTGAAGACAA TTATGAATTAA
* ATTTAAGAA TTACAAAATATAGTTGAAAGCTCTAACAATAGACT AAGCAGAAGAAAGAGGTTCAGAACTTGAAGACAAG TATGAATTAA
* ATTTAAGAAA ACAAAATATAGTTGAAAGCTCTAACAATAGACTAA GCAGAAGAAAGAGGTTCAGAACTTGAAGACAAGTC ATGAATTAA
* ATTTAAGAAA ACAAAATATAGTTGAAAGCTCTAACAATAGACTAA CAGAAGAAAGAGGTTCAGAACTTGAAGACAAGTCT TGAATTAA
* ATTTAAGAAA ACAAAATATAGTTGAAAGCTCTAACAATAGACTAA CAGAAGAAAGAGGTTCANANNNTGANGACAAGTCT TGAATTAA
* ATTTAAGAAATT CAAAATATAGTTGAAAGCTCTAACAATAGACTAAA GAAGAAAGAGGTTCAGAACTTGAAGACAAGTCTCT GAATTAA
* ATTTAAGAAAT AAAATATAGTTGAAAGCTCTAACAATAGACTAAAC AAGAAAGAGGTTCAGAACTTGAAGACAAGTCTCGT GAATTAA
* ATTTAAGAAAT AAAATATAGTTGAAAGCTCTAACAATAGACTAAAC AAGAAAGAGGTTCAGAACTTGAAGACAAGTCTCTT AATTAA
* ATTTAAGAAAT AAATATAGTTGAAAGCTCTAACAATAGACTAAACC GAAAGAGGTTCAGAACTTGAAGACAAGTCTCTTATG
* ATTTAAGAAATT AAATATAGTTGAAAGCTCTAACAATAGACTAAACC AAGAGGTTCAGAACTTGAAGACAAGTCTCTTATGA
* ATTTAAGAAATT AATATAGTTGAAAGCTCTAACAATAGACTAAACCAA AAGAGGTTCAGAACTTGAAGACAAGTCTCTTATGA
* ATTTAAGAAATTACA ATATAGTTGAAAGCTCTAACAATAGACTAAACCAA GAGGTTCAGAACTTGAAGACAAGTCTCTTATGAAT
* ATTTAAGAAATTACAA ATAGTTGAAAGCTCTAACAATAGACTAAACCAAGC GAGGTTCAGAACTTGAAGACAAGTCTCTTATGAAT
* ATTTAAGAAATTACAAAATA AGTTGAAAGCTCTAACAATAGACTAAACCAAGCAG AGGTTCAGAACTTGAAGACAAGTCTCTTATGAATT
* ATTTAAGAAATTACAAAATAT TTGAAAGCTCTAACAATAGACTAAACCAAGCAGAA GGTTCAGAACTTGAAGACAAGTCTCTTATGAATTA
* ATTTAAGAAATTACAAAATATA GAAAGCTCTAACAATAGACTAAACCAAGCAGAAGAAAGAG TTCAGAACTTGAAGACAAGTCTCTTATGAATTAA
* ATTTAAGAAATTACAAAATATAGTTGAA CTAACAATAGACTAAACCAAGCAGAAGAAAGAGTT CTTGAAGACAAGTCTCTTATGAATTAA
* ATTTAAGAAATTACAAAATATAGTTGAAA CTAACAATAGACTAAACCAAGCAGAAGAAAGAGGTT TTGAAGACAAGTCTCTTATGAATTAA
* ATTTAAGAAATTACAAAATATAGTTGAAAG TAACAATAGACTAAACCAAGCAGAAGAAAGAGGTT TGAAGACAAGTCTCTTATGAATTAA
* ATTTAAGAAATTACAAAATATAGTTGAAAGCTCT ACAATAGACTAAACCAAGCAGAAGAAAGAGGTTCA TGAAGACAAGTCTCTTATGAATTAA
* TTAAGAAATTACAAAATATAGTTGAAAGCTCTAAC GACTAAACCAAGCAGAAGAAAGAGGTTCAGAACTT AAGACAAGTCTCTTATGAATTAA
* TAAGAAATTACAAAATATAGTTGAAAGCTCTAACAATAGA GGTTCAGAACTTGAAGACAAGTCTCTTATGAATTA
* TTACAAAATATAGTTGAAAGCTCTAACAATAGACT GGTTCAGAACTTGAAGACAAGTCTCTTATGAATTA
* ATAGTTGAAAGCTCTAACAATAGACTAAACCAAGC GTTCAGAACTTGAAGACAAGTCTCTTATGAATTAA
* AAAGCTCTAACAATAGACTAAACCAAGCAGAAGAA TCAGAACTTGAAGACAAGTCTCTTATGAATTAA
* AAAGCTCTAACAATAGACTAAACCAAGCAGAAGAA NAAGACAAGTCTCTTATGAATTAA
* AAGCTCTAACAATAGACTAAACCAAGCAGAAGAAA GAAGACAAGTCTCTTATGAATTAA
* TAACAATAGACTAAACCAAGCAGAAGAAAGAGGTT AGTCTCTTATGAATTAA
* TAACAATAGACTAAACCAAGCAGAAGAAAGAGGTT GTCTCTTATGAATTAA
* AACAATAGACTAAACCAAGCAGAAGAAAGAGGTTC
* AACAATAGACTAAACCAAGCAGAAGAAAGAGGTTC
* AATAGACTAAACCAAGCAGAAGAAAGAGGTTCAGA
* AATAGACTAAACCAAGCAGAAGAAAGAGGTTCAGA
* @endcode
*
*
* @section Remarks
*
* The following figures visualize the relations between the different stores:
*
* <img width="597" height="363" src="FragmentStore.png" title="Stores that are
* involved in the representation of a multiple read alignment." />
*
* <img width="597" height="363" src="AnnotationStore.png" title="Stores that
* are involved in the representation of a genome alignment." />
*
* @fn FragmentStore::clearReads
*
* @brief Removes all reds from a FragmentStore.
*
* @signature void clearReads(store);
*
* @param[in,out] store The FragmentStore to remove all reads from.
*
* Clears the @link FragmentStore::readStore @endlink, @link
* FragmentStore::readSeqStore @endlink, and @link FragmentStore::readNameStore
* @endlink.
*
* @typedef FragmentStore::TReadStore
*
* @brief Type of the @link FragmentStore::readStore @endlink member.
*
* @signature typedef (..) TFragmentStore::TReadStore;
*
* @typedef FragmentStore::TReadSeqStore
*
* @brief Type of the @link FragmentStore::readSeqStore @endlink member.
*
* @signature typedef (..) TFragmentStore::TReadSeqStore;
*
* @typedef FragmentStore::TMatePairStore
*
* @brief Type of the @link FragmentStore::matePairStore @endlink member.
*
* @signature typedef (..) TFragmentStore::TMatePairStore;
*
* @typedef FragmentStore::TContigFileStore
*
* @brief Type of the @link FragmentStore::contigFileStore @endlink member.
*
* @signature typedef (..) TFragmentStore::TContigFileStore;
*
* @typedef FragmentStore::TContigStore
*
* @brief Type of the @link FragmentStore::contigStore @endlink member.
*
* @signature typedef (..) TFragmentStore::TContigStore;
*
* @typedef FragmentStore::TAlignedReadStore
*
* @brief Type of the @link FragmentStore::alignedReadStore @endlink member.
*
* @signature typedef (..) TFragmentStore::TAlignedReadStore;
*
* @typedef FragmentStore::TAnnotationStore
*
* @brief Type of the @link FragmentStore::annotationStore @endlink member.
*
* @signature typedef (..) TFragmentStore::TAnnotationStore;
*
* @typedef FragmentStore::TAlignQualityStore
*
* @brief Type of the @link FragmentStore::alignQualityStore @endlink member.
*
* @signature typedef (..) TFragmentStore::TAlignQualityStore;
*
* @typedef FragmentStore::TAlignedReadTagStore
*
* @brief Type of the @link FragmentStore::alignedReadTagStore @endlink member.
*
* @signature typedef (..) TFragmentStore::TAlignedReadTagStore;
*
* @typedef FragmentStore::TReadNameStore
*
* @brief Type of the @link FragmentStore::readNameStore @endlink member.
*
* @signature typedef (..) TFragmentStore::TReadNameStore;
*
* @typedef FragmentStore::TMatePairNameStore
*
* @brief Type of the @link FragmentStore::matePairNameStore @endlink member.
*
* @signature typedef (..) TFragmentStore::TMatePairNameStore;
*
* @typedef FragmentStore::TLibraryNameStore
*
* @brief Type of the @link FragmentStore::libraryNameStore @endlink member.
*
* @signature typedef (..) TFragmentStore::TLibraryNameStore;
*
* @typedef FragmentStore::TContigNameStore
*
* @brief Type of the @link FragmentStore::contigNameStore @endlink member.
*
* @signature typedef (..) TFragmentStore::TContigNameStore;
*
* @typedef FragmentStore::TAnnotationNameStore
*
* @brief Type of the @link FragmentStore::annotationNameStore @endlink member.
*
* @signature typedef (..) TFragmentStore::TAnnotationNameStore;
*
* @typedef FragmentStore::TAnnotationTypeStore
*
* @brief Type of the @link FragmentStore::annotationTypeStore @endlink member.
*
* @signature typedef (..) TFragmentStore::TAnnotationTypeStore;
*
* @typedef FragmentStore::TAnnotationKeyStore
*
* @brief Type of the @link FragmentStore::annotationKeyStore @endlink member.
*
* @signature typedef (..) TFragmentStore::TAnnotationKeyStore;
*
* @var FragmentStore::TReadStore FragmentStore::readStore;
*
* @brief A @link String @endlink that maps from readId to matePairId.
*
* The value type is @link ReadStoreElement @endlink.
*
* @var FragmentStore::TReadSeqStore FragmentStore::readSeqStore;
*
* @brief @link StringSet @endlink that maps from readId to readSeq.
*
* @var FragmentStore::TMatePairStore FragmentStore::matePairStore;
*
* @brief @link String @endlink that maps from matePairId to (readId[2], libId).
*
* The value type is @link MatePairStoreElement @endlink.
*
* @var FragmentStore::TLibraryStore FragmentStore::libraryStore;
*
* @brief @link String @endlink that maps from libId to (mean, std).
*
* Value type is @link LibraryStoreElement @endlink.
*
* @var FragmentStore::TContigFileStore FragmentStore::contigFileStore;
*
* @brief @link String @endlink that maps from contigId to (contigSeq,
* contigGaps, contigFileId).
*
* Value type is @link ContigFile @endlink.
*
* @var FragmentStore::TContigStore FragmentStore::contigStore;
*
* @brief @link String @endlink that maps from contigId to (contigSeq,
* contigGaps, contigFileId).
*
* Value type is @link ContigStoreElement @endlink.
*
* @var FragmentStore::TAlignedReadStore FragmentStore::alignedReadStore;
*
* @brief @link String @endlink that stores (alignId, readId, contigId,
* pairMatchId, beginPos, endPos, gapAnchors).
*
* The value type is @link AlignedReadStoreElement @endlink.
*
* @section Remarks
*
* You can sort <tt>alignedReadStore</tt> using @link sortAlignedReads @endlink.
* After sorting, you can use the functions @link lowerBoundAlignedReads
* @endlink and @link upperBoundAlignedReads @endlink to perform a binary
* search, e.g. for accessing only a subrange.
*
* @see lowerBoundAlignedReads
* @see upperBoundAlignedReads
* @see sortAlignedReads
*
* @var FragmentStore::TAnnotationStore FragmentStore::annotationStore;
*
* @brief String that maps from annoId to (contigId, typeId, beginPos, endPos,
* parentId, lastChildId, nextSiblingId, values).
*
* The value type is @link AnnotationStoreElement @endlink.
*
* Instead of accessing this store directly, consider to use the high-level
* interface provided by @link AnnotationTreeIterator @endlink.
*
* @var FragmentStore::TAlignQualityStore FragmentStore::alignQualityStore;
*
* @brief @link String @endlink that maps from alignId to (pairScore, score,
* errors).
*
* The value type is @link AlignQualityStoreElement @endlink.
*
* @var FragmentStore::TAlignedReadTagStore FragmentStore::alignedReadTagStore;
*
* @brief @link StringSet @endlink that maps from alignId to alignTag.
*
* @var FragmentStore::TReadNameStore FragmentStore::readNameStore;
*
* @brief @link StringSet @endlink that maps from readId to readName.
*
* @var FragmentStore::TContigNameStore FragmentStore::matePairNameStore;
*
* @brief @link StringSet @endlink that maps from contigId to matePairName.
*
* @var FragmentStore::TLibraryNameStore FragmentStore::libraryNameStore;
*
* @brief A @link StringSet @endlink that maps from libId to libName.
*
* @var FragmentStore::TContigNameStore FragmentStore::contigNameStore;
*
* @brief @link StringSet @endlink that maps from contigId to contigName.
*
* @var FragmentStore::TAnnotationNameStore FragmentStore::annotationNameStore;
*
* @brief @link StringSet @endlink that maps from annoId to annoName;
*
* @var FragmentStore::TAnnotationTypeStore FragmentStore::annotationTypeStore;
*
* @brief @link StringSet @endlink that maps from typeId to the type name of an
* annotation, e.g. "gene" or "exon". typeId is a member of the @link
* AnnotationStoreElement @endlink.
*
* @section Remarks
*
* There are @link FragmentStore::PredefinedAnnotationTypes predefined type ids
* @endlink for commonly used types e.g. <tt>ANNO_GENE</tt> or
* <tt>ANNO_EXON</tt> which can be used to set the @link
* AnnotationStoreElement::typeId @endlink directly as a fast alternative to
* @link AnnotationTreeIterator#getType @endlink and @link
* AnnotationTreeIterator#setType @endlink.
*
* @var FragmentStore::TAnnotationKeyStore FragmentStore::annotationKeyStore;
*
* @brief @link StringSet @endlink that maps from keyId to the name of a key.
* The keyId is used to address @link AnnotationStoreElement::values
* @endlink of an annotation.
*
* @fn FragmentStore#getClrRange
*
* @brief Get the "clear" range of a read alignment.
*
* @signature void getClrRange(store, alignEl, begClr, endClr);
*
* @param[in] store The FragmentStore to work on.
* @param[in] alignEl The @link AlignedReadStoreElement @endlink to work on.
* @param[out] begClr Begin of the clear range.
* @param[out] endClr End of the clear range.
*
* The clear range of a read alignment is the range of the part of the alignmetn
* that is not clipped.
*
* @fn FragmentStore#read
*
* @brief Read the contents of a FragmentStore from a file.
*
* @signature int read(file, store, tag);
*
* @param[in,out] file The @link StreamConcept @endlink to read from.
* @param[in,out] store The FragmentStore to append to.
* @param[in] tag The format to read from. Can be Amos or Sam.
*
* @return int 0 in the case of success, non-0 value in case of errors.
*
* @fn FragmentStore#write
*
* @brief Write the contents of a FragmentStore to a file.
*
* @signature int write(file, store, tag);
*
* @param[in,out] file The @link StreamConcept @endlink to write to.
* @param[in] store The FragmentStore to write to the file.
* @param[in] tag The format to write out. Types: Sam or Amos.
*
* @return int 0 in case of success, 1 in case of errors.
*
* @fn FragmentStore#writeRecords
*
* @brief Write all records to a file.
*
* @signature void writeRecords(bamFileOut, store);
* @signature void writeRecords(gffFileOut, store);
* @signature void writeRecords(ucscFileIn, store);
*
* @param[in,out] bamFileOut The @link BamFileOut @endlink object to write into.
* @param[in,out] gffFileOut The @link GffFileOut @endlink object to write into.
* @param[in,out] ucscFileOut The @link UcscFileOut @endlink object to write
* into.
* @param[in] store The @link FragmentStore @endlink object.
*
* @throw IOError On low-level I/O errors.
*
* @fn FragmentStore#writeContigs
*
* @brief Write contigs from FragmentStore into a @link StreamConcept @endlink.
*
* @signature bool writeContigs(file, store, tag);
*
* @param[in,out] file The @link StreamConcept @endlink to write to.
* @param[in] store The FragmentStore to write contigs of.
* @param[in] tag A tag for the sequence format.
*
* @return bool true on success, false on errors.
*
* @fn FragmentStore#readRecords
*
* @brief Read all records from a file.
*
* @signature void readRecords(store, bamFileIn[, importFlags]);
* @signature void readRecords(store, gffFileIn);
* @signature void readRecords(store, ucscFileIn);
*
* @param[in,out] store The @link FragmentStore @endlink object to store the
* records into.
* @param[in,out] bamFileIn The @link BamFileIn @endlink object to read from.
* @param[in,out] gffFileIn The @link GffFileIn @endlink object to read from.
* @param[in,out] ucscFileIn The @link UcscFileIn @endlink object to read from.
* @param[in] importFlags The import flags.
*
* @throw IOError On low-level I/O errors.
* @throw ParseError On high-level file format errors.
*
* @fn FragmentStore#loadContigs
*
* @brief Load contigs into a FragmentStore.
*
* @signature bool loadContigs(store, fileName[, loadSeqs]);
* @signature bool loadContigs(store, fileNameList[, loadSeqs]);
*
* @param[in,out] store The FragmentStore to append the contigs to.
* @param[in] fileName A @link CharString @endlink with the name of the file to
* load.
* @param[in] fileNameList A @link StringSet @endlink of @link CharString
* @endlink with a list of file names to load.
* @param[in] loadSeqs A <tt>bool</tt> indicating whether to load lazily. If
* <tt>true</tt> then sequences are loaded immediately. If
* <tt>false</tt>, an emptycontig with a reference to the
* file is created. Its sequence can be loaded on demand by
* @link FragmentStore#lockContig @endlink and @link
* FragmentStore#loadContig @endlink.
*
* @return bool true in case of success and false in case of error.
*
* @fn FragmentStore#loadContig
*
* @brief Manually load a contig sequence.
*
* @signature bool loadContig(store, contigId);
*
* @param[in,out] store The FragmentStore to load the contig for.
* @param[in] contigId The id of the contig that was created earlier by @link
* FragmentStore#loadContigs @endlink.
*
* @return bool true on success, false on failure.
*
* @fn FragmentStore#lockContig
*
* @brief Locks a contig sequence from being removed.
*
* @signature bool lockContig(store, contigId);
*
* @param[in,out] store The FragmentStore to lock the contig for.
* @param[in] contigId The id of the contig that was created earlier by @link
* FragmentStore#loadContigs @endlink.
*
* @return bool true on success, false on failure.
*
* This function increases the contig usage counter by 1 and ensures that the
* contig sequence is loaded.
*
* @fn FragmentStore#unlockContig
*
* @brief Removes a previous contig lock.
*
* @signature bool unlockContig(store, contigId);
*
* @param[in,out] store The FragmentStore to unlock the contig for.
* @param[in] contigId The id of the contig that was created earlier by @link
* FragmentStore#loadContigs @endlink.
*
* @return bool true on success, false on failure.
*
* This function decreases the contig usage counter by 1.
*
* @fn FragmentStore#unlockAndFreeContig
*
* @brief Removes a previous contig lock and clears the sequence if no further
* lock exists.
*
* @signature bool unlockContig(store, contigId);
*
* @param[in,out] store The FragmentStore to unlock the contig for.
* @param[in] contigId The id of the contig that was created earlier by @link
* FragmentStore#loadContigs @endlink.
*
* @return bool true on success, false on failure.
*
* This function decreases the contig usage counter by 1 and frees the
* sequences' memory if the counter equals 0.
*
* @fn FragmentStore#lockContigs
*
* @brief Locks all contig sequences from being remove.
*
* @signature bool lockContigs(store);
*
* @param[in,out] store The FragmentStore to lock the contigs for.
*
* @return bool true in case of success, false in case of errors.
*
* @fn FragmentStore#unlockContigs
*
* @brief Unlocks all contig sequences.
*
* @signature bool unlockContigs(store);
*
* @param[in,out] store The FragmentStore to unlock the contigs for.
*
* @return bool true in case of success, false in case of errors.
*
* @fn FragmentStore#unlockAndFreeContigs
*
* @brief Unlocks all contig sequences and clears sequences without lock.
*
* @signature bool unlockAndFreeContigs(store);
*
* @param[in,out] store The FragmentStore to unlock the contigs for.
*
* @return bool true in case of success, false in case of errors.
*
* @fn FragmentStore#loadReads
*
* @brief Loads reads into FragmentStore
*
* @signature bool loadReads(store, fileName);
* @signature bool loadReads(store, fileNameL, fileNameR);
*
* @param[in,out] store The FragmentStore to append the reads to.
* @param[in] fileName Path to single-end read file.
* @param[in] fileNameL Path to left read file in case of paired reads.
* @param[in] fileNameR Path to right read file in case of paired reads.
*
* @return bool true in case of success, false in case of errors.
*
* When two file names are given thent he files are expected to containt he same
* number of reads and reads with the same index are assumed to be mate pairs.
* Mate pairs are stored internally in an "interleaved mode": a read is read
* from each file before reading the next one.
*
* @fn FragmentStore#clearContigs
*
* @brief REvmoes all contigs from a FragmentStore.
*
* @signature void clearContigs(store);
*
* @param[in,out] store The FragmentStore to remove all contigs from.
*
* This function clears the @link FragmentStore::contigStore @endlink and @link
* FragmentStore::contigNameStore @endlink.
*
* @fn FragmentStore#appendRead
*
* @brief Append a read to a FragmentStore.
*
* @signature TSize appendRead(store, read[, matePairId]);
* @signature TSize appendRead(store, read, name[, matePairId]);
*
* @param[in,out] store The FragmentStore to append the read to.
* @param[in] read The read sequence. Type: @link ContainerConcept @endlink.
* @param[in] name The name of the read. Type: @link CharString @endlink.
* @param[in] matePairId ID of the mate-pair that this read is part of. Default:
* <tt>FragmentStore::INVALID_ID</tt> which corresponds to
* an unmated read.
*
* @return TSize The readId of the newly appended read. TSize is the size type
* of the @link FragmentStore::readStore @endlink.
*
* This funciton appends a single read to the @link FragmentStore::readStore
* @endlink and @link FragmentStore::readSeqStore @endlink.
*
* @see FragmentStore#getRead
*
* @fn FragmentStore#getRead
*
* @brief Returns the read with the given readId.
*
* @signature TRead getRead(store, id);
*
* @param[in] store The FragmentStore to query for the read.
* @param[in] id The id of the read.
*
* @return TRead The entry from the @link FragmentStore::readStore @endlink.
* TRead is the value type of the @link FragmentStore::readStore
* @endlink.
*
* @fn FragmentStore#appendAlignedRead
*
* @brief Appends an aligned read entyr to a fragment store.
*
* @signature TSize appendAlignedRead(store, readId, contigId, beginPos,
* endPos[, pairMatchId]);
*
* @param[in,out] store The FragmentStore to append to.
* @param[in] readId The id of the read to append an alignment for.
* @param[in] contigId The id of the contig of the alignment.
* @param[in] beginPos The begin position of the alignment.
* @param[in] endPos The end position of the alignment.
* @param[in] pairMatchId The id of the alignedRead pair. Default:
* <tt>FragmentStore::INVALID_ID</tt> which corresponds
* to an unmated read.
*
* @return TSize The alignedReadId of the alignment.
*
* @section Remarks
*
* This function appends a single read alignment to the @link
* FragmentStore::alignedReadStore @endlink. Note that this really only adds a
* match. To generate a global alignment out of all these matches, use @link
* FragmentStore#convertMatchesToGlobalAlignment @endlink.
*
* @see FragmentStore#appendRead
*
* @fn FragmentStore#appendMatePair
*
* @brief Appends the two reads of a mate pair to a FragmentStore.
*
* @signature TSize appendMatePair(store, readSeq1, readSeq2[, name1, name2]);
*
* @param[in,out] store The FragmentStore to append the mate pair to.
* @param[in] readSeq1 The read sequence of the first read.
* @param[in] readSeq2 The read sequence of the second read.
* @param[in] name1 The read name of the first read.
* @param[in] name2 The read name of the first read.
*
* @return TSize The matePairId of the newly appended mate pair. TSize is the
* size type of the @link FragmentStore::matePairStore @endlink.
*
* @section Remarks
*
* This function appends two reads to the @link FragmentStore::readStore
* @endlink and @link FragmentStore::readSeqStore @endlink and a mate pair entry
* for both them to the @link FragmentStore::matePairStore @endlink. If names
* are given, they are appended to @link FragmentStore::readNameStore @endlink.
*
* @fn FragmentStore#compactAlignedReads
*
* @brief Remove invalid aligned reads and rename the alignId's sequentially
* beginning with 0.
*
* @signature TSize compactAlignedReads(store);
*
* @param[in,out] store The FragmentStore to compact the aligned reads of.
*
* @return s TSize The new size of the @link FragmentStore::alignedReadStore
* @endlink. TSize is the size type of the @link
* FragmentStore::alignedReadStore @endlink.
*
* @section Remarks
*
* This function removes all entries from the @link
* FragmentStore::alignedReadStore @endlink whose alignId is equal to
* <tt>INVALID_ID</tt> as well as orphan entries in @link
* FragmentStore::alignQualityStore @endlink. Afterwards, the alignIds are
* renamed sequentially beginning with 0. This function can be used to remove
* alignments which are flagged by previously setting their id to INVALID_ID.
*
* @fn FragmentStore#compactPairMatchIds
*
* @brief Renames pairMatchId sequentially beginning with 0.
*
* @signature TSize compactPairMatchIds(store);
*
* @param[in,out] store The FragmentStore to compact pair match ids of.
*
* @return TSize The number of pair matches. TSize is the size type of @link
* FragmentStore::alignedReadStore @endlink.
*
* @section Remarks
*
* This function renames the pairMatchId in the @link
* FragmentStore::alignedReadStore @endlink sequentially beginning with 0. Two
* read alignments can be identified to be pair match if they have the same
* pairMatchId. Please note that paired reads not necessarily have to map as a
* pair match, e.g. if they are on different ocntigs or have the same
* orientation or a wrong insert size.
*
* @fn FragmentStore#calculateInsertSizes
*
* @brief Calcualtes a string wtih insert sizes for each pair match.
*
* @signature void calculateInsertSizes(insertSizes, store);
*
* @param[out] insertSizes A @link String @endlink of insert sizes. This string
* is accordingly resized and can be addressed by the
* pairMatchId.
* @param[in] store The @link FragmentStore @endlink to compute the insert sizes
* for.
*
* @section Remarks
*
* This function calls @link FragmentStore#compactPairMatchIds @endlink first
* and calcualte the insert size for every pair match. The insert size of a pair
* match is the outer distance between the two matches.
*
* @fn FragmentStore#getMateNo
*
* @brief Returns the mate number for a read given a readId.
*
* @signature int getMateNo(store, readId);
*
* @param[in] store The FragmentStore with the read.
* @param[in] readId The readId.
*
* @return int The mate number (0 for the first mate, 1 for the second mate) of
* the read in its mate pair or -1 if the read is not paired.
*
* @fn FragmentStore#calculateMateIndices
*
* @brief Calculates a string that maps the readId of a read to the index of its
* mate in the alignedReadStore.
*
* @signature void calculateMateIndices(mateIndices, store);
*
* @param[out] mateIndices A @link String @endlink with the resulting mate
* indices. This string is accordingly resized and can
* be addressed by the readId.
* @param[in] store The @link FragmentStore @endlink.
*
* Entries of reads without a mate contain <tt>INVALID_ID</tt>.
*
* @fn FragmentStore#convertMatchesToGlobalAlignment
*
* @brief Converts all matches to a multiple global alignment in gap-space.
*
* @signature void convertMatchesToGlobalAlignment(store, score, shrinkMatches);
*
* @param[in,out] store The fragment store. Types: FragmentStore
* @param[in] score A score object used by @link globalAlignment @endlink in
* this function.
* @param[in] shrinkMatches States whether the matches should be shrinked.
* Types: True, False
*
* @section Remarks
*
* Before calling this function all <tt>gaps</tt> structures in @link
* FragmentStore::alignedReadStore @endlink and @link FragmentStore::contigStore
* @endlink must be empty, i.e. there are no gaps in the alignments. This
* function iterates over entries in the @link FragmentStore::alignedReadStore
* @endlink and semi-global aligns each read to its contig segments given by
* begin and end position. Gaps introduced by these pair-wise alignments are
* then inserted to the affected contig and reads correspondingly.
*
* The invariant that positions in the @link FragmentStore::alignedReadStore
* @endlink are in gap-space holds before (there were no gaps in alignments) and
* after calling this functions.
*
* If the @link FragmentStore::alignQualityStore @endlink of the @link
* FragmentStore @endlink is empty when
* <tt>convertMatchesToGlobalAlignment()</tt> is called then the @link
* FragmentStore::alignQualityStore @endlink is filled with the edit distance
* scores.
*
* @fn FragmentStore#convertPairWiseToGlobalAlignment
*
* @brief Converts pairwise alignments to a multiple global alignment.
*
* @signature void convertPairWiseToGlobalAlignment(store, pairwiseContigGaps);
*
* @param[in,out] store The fragment store. Types: FragmentStore
* @param[in,out] pairwiseContigGaps A @link String @endlink of anchored contig
* gaps for every pairwise alignment.
*
* @section Remarks
*
* Before calling this function the <tt>gaps</tt> structures in the @link
* FragmentStore::contigStore @endlink must be empty, i.e. there are no gaps in
* the contig. The pairwise alignment gaps of the reads are stored in the
* <tt>gaps</tt> structure in the @link FragmentStore::alignedReadStore
* @endlink, whereas the pairwise alignment gaps of the contig are stored in the
* <tt>pairwiseContigGaps</tt> string.
*
* After calling this functions all positions in the @link
* FragmentStore::alignedReadStore @endlink are in gap-space.
*/