Package htsjdk.samtools.util

Class GZIIndex

java.lang.Object
htsjdk.samtools.util.GZIIndex
public final class GZIIndex extends Object
Represents a .gzi index of a block-compressed file.

The .gzi index is a mapping between the offset of each block in the gzipped file and the uncompressed offset that that block starts with. This mapping is represented by GZIIndex.IndexEntry.

An example of usage for this index for random access a bgzip file using an index generated from raw data. For example, for indexing a compressed FASTA file the .gzi index can be used in conjunction with the FastaSequenceIndex to seek concrete sequences.

See Also:

  • Field Details

  • Method Details

    • getNumberOfBlocks

      public int getNumberOfBlocks()
      Gets the number of blocks on the file.
      Returns:
      the number of blocks.

    • getIndexEntries

      public List<GZIIndex.IndexEntry> getIndexEntries()
      Gets an unmodifiable list with the index entries.

      Note: because the first block corresponds to a dummy index entry (0, 0), the returned list does not include it. Thus, the size of the list is getNumberOfBlocks() - 1.

      Returns:
      index entries.

    • getVirtualOffsetForSeek

      public long getVirtualOffsetForSeek(long uncompressedOffset)
      Gets the virtual offset for seek with BlockCompressedInputStream.seek(long).

      BlockCompressedInputStream.seek(long) parameter is not a byte-offset, but a special virtual file pointer that specifies the block-offset within the file (BlockCompressedFilePointerUtil.getBlockAddress(long)), and the offset within the block (BlockCompressedFilePointerUtil.getBlockOffset(long)).

      This methods converts the provided byte-offset on the file to the special file pointer used to seek a block-compressed file, using this index to find the block where the byte-offset is located.

      Parameters:
      uncompressedOffset - the file-offset.
      Returns:
      virtual offset for BlockCompressedInputStream.
      See Also:

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • writeIndex

      public void writeIndex(Path output) throws IOException
      Writes this index into the requested path.
      Parameters:
      output - the output path.
      Throws:
      IOException - if an I/O error occurs.

    • writeIndex

      public void writeIndex(OutputStream output) throws IOException
      Writes this index into the requested path. NOTE: This method will close out the provided output stream when it finishes writing the index
      Parameters:
      output - the output file.
      Throws:
      IOException - if an I/O error occurs.

    • loadIndex

      public static GZIIndex loadIndex(Path indexPath) throws IOException
      Loads the index from the provided file.
      Parameters:
      indexPath - the path for the index to load.
      Returns:
      loaded index.
      Throws:
      IOException - if an I/O error occurs.

    • loadIndex

      public static final GZIIndex loadIndex(String source, InputStream indexIn) throws IOException
      Loads the index from the provided input stream.
      Parameters:
      source - The named source of the reference file (used in error messages). May be null if unknown.
      indexIn - the input stream for the index to load.
      Returns:
      loaded index.
      Throws:
      IOException - if an I/O error occurs.

    • loadIndex

      public static final GZIIndex loadIndex(String source, ReadableByteChannel channel) throws IOException
      Loads the index from the provided channel.
      Parameters:
      source - The named source of the reference file (used in error messages). May be null if unknown.
      channel - the channel to read the index from.
      Returns:
      loaded index.
      Throws:
      IOException - if an I/O error occurs.

    • buildIndex

      public static final GZIIndex buildIndex(Path bgzipFile) throws IOException
      Builds a GZIIndex on the fly from a BGZIP file.

      Note that this method does not write the index on disk. Use writeIndex(OutputStream) on the returned object to save the index.

      Parameters:
      bgzipFile - the bgzip file.
      Returns:
      in-memory .gzi index.
      Throws:
      IOException - if an I/O error occurs.

    • createIndex

      public static GZIIndex createIndex(Path bgzipFile, boolean overwrite) throws IOException
      Creates a GZIIndex from a BGZIP file and store it in memory and disk.
      Parameters:
      bgzipFile - the bgzip file.
      overwrite - if the .fai index already exists override it if true; otherwise, throws a IOException.
      Returns:
      the in-memory representation for the created index.
      Throws:
      IOException - if an IO error occurs.

    • resolveIndexNameForBgzipFile

      public static Path resolveIndexNameForBgzipFile(Path bgzipFile)
      Gets the default index path for the bgzip file.