src/api/BamIndex.h

   1 // ***************************************************************************
   2 // BamIndex.h (c) 2009 Derek Barnett
   3 // Marth Lab, Department of Biology, Boston College
   4 // All rights reserved.
   5 // ---------------------------------------------------------------------------
   6 // Last modified: 24 February 2011 (DB)
   7 // ---------------------------------------------------------------------------
   8 // Provides basic BAM index interface
   9 // ***************************************************************************
  10
  11 #ifndef BAM_INDEX_H
  12 #define BAM_INDEX_H
  13
  14 #include <api/api_global.h>
  15 #include <api/BamAux.h>
  16 #include <iostream>
  17 #include <string>
  18 #include <vector>
  19
  20 namespace BamTools {
  21
  22 class BamReader;
  23
  24 namespace Internal {
  25     class BamReaderPrivate;
  26 } // namespace Internal
  27
  28 // --------------------------------------------------
  29 // BamIndex base class
  30 class API_EXPORT BamIndex {
  31
  32     // enums
  33     public:
  34         // specify index-caching behavior
  35         enum IndexCacheMode { FullIndexCaching = 0 // store entire index file contents in memory
  36                             , LimitedIndexCaching  // store only index data for current reference
  37                             , NoIndexCaching       // do not store any index data between jumps
  38                             };
  39
  40         // list of supported BamIndex types
  41         enum IndexType { BAMTOOLS = 0
  42                        , STANDARD
  43                        };
  44
  45     // ctor & dtor
  46     public:
  47         BamIndex(void);
  48         virtual ~BamIndex(void);
  49
  50     // index interface
  51     public:
  52         // creates index data (in-memory) from @reader data
  53         virtual bool Build(Internal::BamReaderPrivate* reader) =0;
  54         // returns supported file extension
  55         virtual const std::string Extension(void) =0;
  56         // returns whether reference has alignments or no
  57         virtual bool HasAlignments(const int& referenceID) const =0;
  58         // attempts to use index data to jump to @region in @reader; returns success/fail
  59         // a "successful" jump indicates no error, but not whether this region has data
  60         //   * thus, the method sets a flag to indicate whether there are alignments
  61         //     available after the jump position
  62         virtual bool Jump(Internal::BamReaderPrivate* reader,
  63                           const BamTools::BamRegion& region,
  64                           bool* hasAlignmentsInRegion) =0;
  65         // loads existing data from file into memory
  66         virtual bool Load(const std::string& filename);
  67         // change the index caching behavior
  68         virtual void SetCacheMode(const BamIndex::IndexCacheMode& mode);
  69         // writes in-memory index data out to file
  70         // N.B. - (this is the original BAM filename, method will modify it to use applicable extension)
  71         virtual bool Write(const std::string& bamFilename);
  72
  73     // derived-classes MUST provide implementation
  74     protected:
  75         // clear all current index offset data in memory
  76         virtual void ClearAllData(void) =0;
  77         // return file position after header metadata
  78         virtual off_t DataBeginOffset(void) const =0;
  79         // return true if all index data is cached
  80         virtual bool HasFullDataCache(void) const =0;
  81         // clears index data from all references except the first
  82         virtual void KeepOnlyFirstReferenceOffsets(void) =0;
  83         // load index data for all references, return true if loaded OK
  84         // @saveData - save data in memory if true, just read & discard if false
  85         virtual bool LoadAllReferences(bool saveData = true) =0;
  86         // load first reference from file, return true if loaded OK
  87         // @saveData - save data in memory if true, just read & discard if false
  88         virtual bool LoadFirstReference(bool saveData = true) =0;
  89         // load header data from index file, return true if loaded OK
  90         virtual bool LoadHeader(void) =0;
  91         // position file pointer to first reference begin, return true if skipped OK
  92         virtual bool SkipToFirstReference(void) =0;
  93         // write index reference data
  94         virtual bool WriteAllReferences(void) =0;
  95         // write index header data
  96         virtual bool WriteHeader(void) =0;
  97
  98     // internal methods (but available to derived classes)
  99     protected:
 100         // rewind index file to beginning of index data, return true if rewound OK
 101         bool Rewind(void);
 102
 103     private:
 104         // return true if FILE* is open
 105         bool IsOpen(void) const;
 106         // opens index file according to requested mode, return true if opened OK
 107         bool OpenIndexFile(const std::string& filename, const std::string& mode);
 108         // updates in-memory cache of index data, depending on current cache mode
 109         void UpdateCache(void);
 110
 111     // data members
 112     protected:
 113         FILE* m_indexStream;
 114         std::string m_indexFilename;
 115         BamIndex::IndexCacheMode  m_cacheMode;
 116 };
 117
 118 } // namespace BamTools
 119
 120 #endif // BAM_INDEX_H