updated documentation. Added more FermiAssembler options

Author: travis-ci

Doxyfile

@@ -463,7 +463,7 @@ WARN_LOGFILE           =
 # directories like "/usr/src/myproject". Separate the files or directories 
 # with spaces.
 
-INPUT                  = 
+INPUT                  = /xchip/gistic/Jeremiah/GIT/SeqLib
 
 # If the value of the INPUT tag contains directories, you can use the 
 # FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp 
@@ -484,26 +484,19 @@ RECURSIVE              = YES
 # excluded from the INPUT source files. This way you can easily exclude a 
 # subdirectory from a directory tree whose root is specified with the INPUT tag.
 
-EXCLUDE                = bwa \
-		         figs \ 
-		         htslib \
-		         multifast-v1.4.2 \
-		         blat \
-			 src/non_api \
-			 fermi-lite \
-			 src/BLATWrapper.cpp \
-			 json \
-			 src/old \
-			 src/ssw.c \
-			 src/ssw_cpp.cpp \
-			 SeqLib/ssw.h \
-			 SeqLib/ssw_cpp.h \
-			 src/gzstream.C \
-		         SGA \
-		         seq_test \ 
-		         .git \
-			 .travis.scripts \
-		         README.md
+EXCLUDE                = /xchip/gistic/Jeremiah/GIT/SeqLib/bwa \
+		         /xchip/gistic/Jeremiah/GIT/SeqLib/figs \ 
+		         /xchip/gistic/Jeremiah/GIT/SeqLib/htslib \
+		         /xchip/gistic/Jeremiah/GIT/SeqLib/blat \
+			 /xchip/gistic/Jeremiah/GIT/SeqLib/src/non_api \
+			 /xchip/gistic/Jeremiah/GIT/SeqLib/fermi-lite \
+			 /xchip/gistic/Jeremiah/GIT/SeqLib/json \
+			 /xchip/gistic/Jeremiah/GIT/SeqLib/SeqLib/ssw.h \
+			 /xchip/gistic/Jeremiah/GIT/SeqLib/SeqLib/ssw_cpp.h \
+		         /xchip/gistic/Jeremiah/GIT/SeqLib/SeqLib/seq_test \ 
+		         /xchip/gistic/Jeremiah/GIT/SeqLib/SeqLib/.git \
+			 /xchip/gistic/Jeremiah/GIT/SeqLib/SeqLib/.travis.scripts \
+		         /xchip/gistic/Jeremiah/GIT/SeqLib/SeqLib/README.md
 
 # The EXCLUDE_SYMLINKS tag can be used select whether or not files or 
 # directories that are symbolic links (a Unix filesystem feature) are excluded 

SeqLib/BFC.h

@@ -48,8 +48,10 @@ namespace SeqLib {
      */
     bool AllocateMemory(size_t n);
 
+    /** Peform BFC error correction on the sequences stored in this object */
     bool ErrorCorrect();
 
+    /** Train the error corrector using the reads stored in this object */
     bool Train();
 
     /** Add a sequence for either training or correction */

SeqLib/BWAWrapper.h

@@ -105,7 +105,7 @@ class BWAWrapper {
   void SetGapOpen(int gap_open);
 
   /** Set the gap open penalty
-   * @param gap_open Gap extension penalty. Default 1
+   * @param gap_ext Gap extension penalty. Default 1
    * @exception Throws invalid_argument if gap_ext < 0
    */
   void SetGapExtension(int gap_ext);

SeqLib/BamHeader.h

@@ -13,13 +13,13 @@
 namespace SeqLib {
 
   /** Store a reference chromosome and its length
-   * @note This parallels the data found in @SQ tag of BAM header
+   * @note This parallels the data found in SQ tag of BAM header
    */
   struct HeaderSequence {
 
     /** Make a new header sequence 
-     * @param Name of the chromosome
-     * @param Length of the chromosome
+     * @param n Name of the chromosome
+     * @param l Length of the chromosome
      */
   HeaderSequence(const std::string& n, uint32_t l) : Name(n), Length(l) {}
 
@@ -50,8 +50,8 @@ namespace SeqLib {
     BamHeader(const HeaderSequenceVector& hsv);
 
     /** Initialize a BamHeader from a string containing
-     * a BAM header in human-readable form (e.g. @PG ... )
-     * @param Text of a BAM header, with newlines separating lines
+     * a BAM header in human-readable form (e.g. PG ... )
+     * @param hdr Text of a BAM header, with newlines separating lines
      */
     BamHeader(const std::string& hdr);
 

SeqLib/BamReader.h

@@ -122,9 +122,9 @@ class BamReader {
 
   /** Explicitly set a reference genome to be used to decode CRAM file.
    * If no reference is specified, will automatically load from
-   * file pointed to in CRAM header using the @SQ tags. 
+   * file pointed to in CRAM header using the SQ tags. 
    * @note This function is useful if the reference path pointed
-   * to by the UR field of @SQ is not on your system, and you would
+   * to by the UR field of SQ is not on your system, and you would
    * like to explicitly provide one.
    * @param ref Path to an index reference genome
    */
@@ -262,8 +262,9 @@ class BamReader {
 
  protected:
 
-  // regions to walk
-  GRC m_region;
+  GRC m_region; ///< Regions to access
+
+ private:
 
   // store the file pointers etc to BAM files
   _BamMap m_bams;

SeqLib/BamRecord.h

@@ -222,7 +222,7 @@ class BamRecord {
   void init();
 
   /** Check if a read is empty (not initialized)
-   * @value true if read was not initialized with any values
+   * @return true if read was not initialized with any values
    */
   bool isEmpty() const { return !b; }
 
@@ -427,13 +427,24 @@ class BamRecord {
   /** Set the query name */
   void SetQname(const std::string& n);
 
-  //Set the quality scores 
+  /** Set the quality scores 
+   * @param n String of quality scores or empty string
+   * @param offset Offset parameter for encoding (eg 33)
+   * @exception Throws an invalid_argument if n is non-empty
+   * and different length than sequence
+   */
   void SetQualities(const std::string& n, int offset);
 
-  /** Set the sequence name */
+  /** Set the sequence name 
+   * @param seq Sequence in upper-case (ACTGN) letters. 
+   */
   void SetSequence(const std::string& seq);
 
-  /** Set the cigar field explicitly */
+  /** Set the cigar field explicitly 
+   * @param c Cigar operation to set
+   * @note Will not check if the cigar ops are consistent with 
+   * the length of the sequence.
+   */
   void SetCigar(const Cigar& c);
 
   /** Print a SAM-lite record for this alignment */
@@ -515,10 +526,7 @@ class BamRecord {
     uint32_t* c = bam_get_cigar(b);
     Cigar cig;
     for (int k = b->core.n_cigar - 1; k >= 0; --k) 
-      //cig.add(CigarField(c[k]));
       cig.add(CigarField(c[k]));
-      //cig.push_back(CigarField(c[k]));
-    //cig.add(CigarField("MIDSSHP=XB"[c[k]&BAM_CIGAR_MASK], bam_cigar_oplen(c[k])));
     return cig;
   }
 
@@ -527,14 +535,19 @@ class BamRecord {
    */
   void ClearSeqQualAndTags();
 
-  /** Get the sequence of this read as a string */
-  /*inline */std::string Sequence() const;
+  /** Retrieve the sequence of this read as a string (ACTGN) */
+  std::string Sequence() const;
 
-  /** Return the mean phred score 
+  /** Return the mean quality score 
    */
   double MeanPhred() const;
 
-  /** Do a smith waterman alignment
+  /** Performa a Smith-Waterman alignment between two strings
+   * @param name Name of the query sequence to align
+   * @param seq Sequence (ACTGN) of the query string
+   * @param ref Sequence (ACTGN) of the reference string
+   * @param gr Location of the reference string. The alignment record after Smith-Waterman alignment
+   * will be relative to this location.
    */
   BamRecord(const std::string& name, const std::string& seq, const std::string& ref, const GenomicRegion * gr);
 
@@ -651,20 +664,26 @@ class BamRecord {
   std::string GetZTag(const std::string& tag) const;
 
   /** Get a vector of type int from a Z tag delimited by "^"
+   * Smart-tags allow one to store vectors of strings, ints or doubles in the alignment tags, and
+   * do not require an additional data structure on top of bseq1_t. 
    * @param tag Name of the tag eg "AL"
    * @return A vector of ints, retrieved from the x delimited Z tag
    * @exception Throws an invalid_argument if cannot convert delimited field val to int
    */
   std::vector<int> GetSmartIntTag(const std::string& tag) const;
 
   /** Get a vector of type double from a Z tag delimited by "x"
+   * Smart-tags allow one to store vectors of string, ints or doubles in the alignment tags, and
+   * do not require an additional data structure on top of bseq1_t. 
    * @param tag Name of the tag eg "AL"
    * @return A vector of double elems, retrieved from the "^" delimited Z tag
    * @exception Throws an invalid_argument if cannot convert delimited field val to double
    */
   std::vector<double> GetSmartDoubleTag(const std::string& tag) const;
 
   /** Get a vector of strings from a Z tag delimited by "^"
+   * Smart-tags allow one to store vectors of strings, ints or doubles in the alignment tags, and
+   * do not require an additional data structure on top of bseq1_t. 
    * @param tag Name of the tag eg "CN"
    * @return A vector of strngs, retrieved from the x delimited Z tag
    */
@@ -681,7 +700,6 @@ class BamRecord {
     return bam_aux2i(p);
   }
 
-
   /** Add a string (Z) tag
    * @param tag Name of the tag. eg "XP"
    * @param val Value for the tag
@@ -722,6 +740,9 @@ class BamRecord {
 
   /** Return a human readable chromosome name assuming chr is indexed
    * from 0 (eg id 0 return "1")
+   * @note This is a quick convienence function, and is not robust to non-numbered
+   * chromosomes (eg chrX becomes 23). For accurate string representation of 
+   * any chromosomes, use the full ChrName with BamHeader input.
    */
   inline std::string ChrName() const {
     std::stringstream ss;
@@ -732,9 +753,7 @@ class BamRecord {
   }
 
   /** Retrieve the human readable chromosome name. 
-   * 
-   * Note that this requires that the header not be empty. If
-   * it is empty, assumes this ia chr1 based reference
+   * @param h Dictionary for chr name lookup. If it is empty, assumes this is chr1 based reference.
    * @exception Throws an out_of_range exception if chr id is not in dictionary
    * @return Empty string if chr id < 0, otherwise chromosome name from dictionary.
    */
@@ -812,11 +831,11 @@ class BamRecord {
 
 };
 
- typedef std::vector<BamRecord> BamRecordVector; 
+ typedef std::vector<BamRecord> BamRecordVector; ///< Store a vector of alignment records
 
- typedef std::vector<BamRecordVector> BamRecordClusterVector;
+ typedef std::vector<BamRecordVector> BamRecordClusterVector; ///< Store a vector of alignment vectors
 
- /** @brief Sort methods for reads
+ /** @brief Sort methods for alignment records
   */
  namespace BamRecordSort {
 
@@ -829,7 +848,7 @@ class BamRecord {
      }
    };
 
-   /** @brief Sort by read-mate position 
+   /** @brief Sort by mate position 
     */
    struct ByMatePosition
    {

SeqLib/BamWalker.h

@@ -6,7 +6,7 @@
 #include <stdint.h> 
 #include "SeqLib/BamRecord.h"
 
-// dont understand this
+// not sure what going on here...
 #ifndef INT32_MAX
 #define INT32_MAX 0x7fffffffL
 #endif
@@ -58,13 +58,13 @@ inline char *samfaipath(const char *fn_ref)
 
 namespace SeqLib {
 
-  /** Small class to store a counter to measure BamWalker progress.
-   *
+  /** Small class to store a counter to measure BamReader progress.
    * Currently only stores number of reads seen / kept. 
    */
 struct ReadCount {
 
-  uint32_t keep, total;
+  uint32_t keep; ///< Store total number of reads kept
+  uint32_t total; ///< Store total number of reads seen
 
   ReadCount() : keep(0), total(0) {}
 

SeqLib/BamWriter.h

@@ -76,9 +76,9 @@ class BamWriter  {
 
   /** Explicitly set a reference genome to be used to decode CRAM file.
    * If no reference is specified, will automatically load from
-   * file pointed to in CRAM header using the @SQ tags. 
+   * file pointed to in CRAM header using the SQ tags. 
    * @note This function is useful if the reference path pointed
-   * to by the UR field of @SQ is not on your system, and you would
+   * to by the UR field of SQ is not on your system, and you would
    * like to explicitly provide one.
    * @param ref Path to an index reference genome
    * @return Returns true if reference loaded.
@@ -88,7 +88,7 @@ class BamWriter  {
   /** Return the BAM header */
   BamHeader Header() const { return hdr; };
 
- protected:
+ private:
 
   // path to output file
   std::string m_out; 

SeqLib/FermiAssembler.h

@@ -29,7 +29,7 @@ namespace SeqLib {
     ~FermiAssembler();
 
     /** Provide a set of reads to be assembled 
-     * @param Reads with or without quality scores
+     * @param brv Reads with or without quality scores
      * @note This will copy the reads and quality scores
      * into this object. Deallocation is automatic with object
      * destruction, or with ClearReads.
@@ -66,7 +66,8 @@ namespace SeqLib {
      */
     void PerformAssembly();
 
-    /** Return the assembled contigs. 
+    /** Return the assembled contigs
+     * @return Assembled contigs in upper case strings (ACTGN)
      */
     std::vector<std::string> GetContigs() const;
 
@@ -76,6 +77,28 @@ namespace SeqLib {
     /** Set the minimum overlap between reads during string graph construction */
     void SetMinOverlap(uint32_t m) { opt.min_asm_ovlp = m; }
 
+    /** Aggressively trim graph to discard heterozygotes. 
+     * Suggested by lh3 for bacterial assembly
+     * @note See: https://github.com/lh3/fermi-lite/blob/master/example.c
+     */
+    void SetAggressiveTrim() { opt.mag_opt.flag |= MAG_F_AGGRESSIVE; }
+
+    /** From lh3: Drop an overlap if its length is below max_overlap * ratio
+     * @param ratio Overlaps below ratio * max_overlap will be removed
+     */
+    void SetDropOverlapRatio(double ratio) { opt.mag_opt.min_dratio1 = ratio; }
+
+    /** From lh3: Min k-mer & read count thresholds for ec and graph cleaning
+     */
+    void SetKmerMinThreshold(int min) { opt.min_cnt = min; }
+
+    /** From lh3: Max k-mer & read count thresholds for ec and graph cleaning
+     */
+    void SetKmerMaxThreshold(int max) { opt.max_cnt = max; }
+
+    // From lh3: retain a bubble if one side is longer than the other side by >INT-bp
+    //void SetBubbleDifference(int bdiff) { opt.mag_opt.max_bdiff; }
+
     /** Return the minimum overlap parameter for this assembler */
     uint32_t GetMinOverlap() const { return opt.min_asm_ovlp; }
 

SeqLib/GenomicRegion.h

@@ -30,7 +30,7 @@ class GenomicRegion {
    * @param t_chr Chromosome id  (chr1 = 0, etc)
    * @param t_pos1 Start position
    * @param t_pos2 End position. Must be >= start position.
-   * @param strand. +, -, or * (default is *)
+   * @param t_strand +, -, or * (default is *)
    * @exception throws an invalid_argument exception if pos2 < pos1
    * @exception throws an invalid_argument exception if char not one of +, - , *
   */
@@ -54,7 +54,7 @@ class GenomicRegion {
    * Note that this requires that a BamHeader be provided as well 
    * to convert the text representation of the chr to the id number.
    * @param reg Samtools-style string (e.g. "1:1,000,000-2,000,000") or single chr
-   * @param h Pointer to BAM header that will be used to convert chr string to ref id
+   * @param hdr Pointer to BAM header that will be used to convert chr string to ref id
    * @exception throws an invalid_argument exception if cannot parse correctly
    */
   GenomicRegion(const std::string& reg, const BamHeader& hdr);

SeqLib/GenomicRegionCollection.cpp

@@ -729,10 +729,11 @@ GenomicRegionCollection<T>::GenomicRegionCollection(const T& gr)
 }
 
 template<class T>
-GRC GenomicRegionCollection<T>::Intersection(GRC& subject, bool ignore_strand) const
+template<class K>
+GRC GenomicRegionCollection<T>::Intersection(GenomicRegionCollection<K>& subject, bool ignore_strand) const
 {
   std::vector<int32_t> sub, que;
-  GRC out = this->FindOverlaps(subject, que, sub, ignore_strand);
+  GRC out = this->FindOverlaps<K>(subject, que, sub, ignore_strand);
   return out;
 }