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:
  - https://github.com/samtools/htslib/issues/473

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`static final class`
`GZIIndex.GZIIndexer`
Helper class for constructing the GZIindex.
`static final class`
`GZIIndex.IndexEntry`
Index entry mapping the block-offset (compressed offset) to the uncompressed offset where the block starts.

## Field Summary

Fields
Modifier and Type
Field
Description
`static final String`
`DEFAULT_EXTENSION`
Deprecated.
since June 2019 Use `FileExtensions.GZI` instead.

## Method Summary

Modifier and Type
Method
Description
`static final GZIIndex`
`buildIndex(Path bgzipFile)`
Builds a `GZIIndex` on the fly from a BGZIP file.
`static GZIIndex`
`createIndex(Path bgzipFile, boolean overwrite)`
Creates a `GZIIndex` from a BGZIP file and store it in memory and disk.
`boolean`
`equals(Object obj)`
`List<GZIIndex.IndexEntry>`
`getIndexEntries()`
Gets an unmodifiable list with the index entries.
`int`
`getNumberOfBlocks()`
Gets the number of blocks on the file.
`long`
`getVirtualOffsetForSeek(long uncompressedOffset)`
Gets the virtual offset for seek with `BlockCompressedInputStream.seek(long)`.
`int`
`hashCode()`
`static final GZIIndex`
`loadIndex(String source, InputStream indexIn)`
Loads the index from the provided input stream.
`static final GZIIndex`
`loadIndex(String source, ReadableByteChannel channel)`
Loads the index from the provided channel.
`static GZIIndex`
`loadIndex(Path indexPath)`
Loads the index from the provided file.
`static Path`
`resolveIndexNameForBgzipFile(Path bgzipFile)`
Gets the default index path for the bgzip file.
`String`
`toString()`
`void`
`writeIndex(OutputStream output)`
Writes this index into the requested path.
`void`
`writeIndex(Path output)`
Writes this index into the requested path.

### Methods inherited from class java.lang.Object

`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

## Field Details

### DEFAULT_EXTENSION

@Deprecated public static final String DEFAULT_EXTENSION
Deprecated.
since June 2019 Use `FileExtensions.GZI` instead.

See Also:
  - Constant Field Values

## 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:
  - `BlockCompressedFilePointerUtil`

### 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.