htsjdk.samtools.util

Class GZIIndex

java.lang.Object

htsjdk.samtools.util.GZIIndex

public final class GZIIndex
extends java.lang.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 and Description
static class	GZIIndex.GZIIndexer Helper class for constructing the GZIindex.
static 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 and Description
static java.lang.String	DEFAULT_EXTENSION Deprecated. since June 2019 Use FileExtensions.GZI instead.

Method Summary

Modifier and Type	Method and Description
static GZIIndex	buildIndex(java.nio.file.Path bgzipFile) Builds a GZIIndex on the fly from a BGZIP file.
static GZIIndex	createIndex(java.nio.file.Path bgzipFile, boolean overwrite) Creates a GZIIndex from a BGZIP file and store it in memory and disk.
boolean	equals(java.lang.Object obj)
java.util.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 GZIIndex	loadIndex(java.nio.file.Path indexPath) Loads the index from the provided file.
static GZIIndex	loadIndex(java.lang.String source, java.io.InputStream indexIn) Loads the index from the provided input stream.
static GZIIndex	loadIndex(java.lang.String source, java.nio.channels.ReadableByteChannel channel) Loads the index from the provided channel.
static java.nio.file.Path	resolveIndexNameForBgzipFile(java.nio.file.Path bgzipFile) Gets the default index path for the bgzip file.
java.lang.String	toString()
void	writeIndex(java.io.OutputStream output) Writes this index into the requested path.
void	writeIndex(java.nio.file.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 Detail

DEFAULT_EXTENSION

@Deprecated
public static final java.lang.String DEFAULT_EXTENSION

Deprecated. since June 2019 Use FileExtensions.GZI instead.

See Also:

Constant Field Values

Method Detail

getNumberOfBlocks

public int getNumberOfBlocks()

Gets the number of blocks on the file.

Returns:

the number of blocks.

getIndexEntries

public java.util.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(java.lang.Object obj)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

writeIndex

public void writeIndex(java.nio.file.Path output)
                throws java.io.IOException

Writes this index into the requested path.

Parameters:

output - the output path.

Throws:

java.io.IOException - if an I/O error occurs.

writeIndex

public void writeIndex(java.io.OutputStream output)
                throws java.io.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:

java.io.IOException - if an I/O error occurs.

loadIndex

public static final GZIIndex loadIndex(java.nio.file.Path indexPath)
                                throws java.io.IOException

Loads the index from the provided file.

Parameters:

indexPath - the path for the index to load.

Returns:

loaded index.

Throws:

java.io.IOException - if an I/O error occurs.

loadIndex

public static final GZIIndex loadIndex(java.lang.String source,
                                       java.io.InputStream indexIn)
                                throws java.io.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:

java.io.IOException - if an I/O error occurs.

loadIndex

public static final GZIIndex loadIndex(java.lang.String source,
                                       java.nio.channels.ReadableByteChannel channel)
                                throws java.io.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:

java.io.IOException - if an I/O error occurs.

buildIndex

public static final GZIIndex buildIndex(java.nio.file.Path bgzipFile)
                                 throws java.io.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:

java.io.IOException - if an I/O error occurs.

createIndex

public static GZIIndex createIndex(java.nio.file.Path bgzipFile,
                                   boolean overwrite)
                            throws java.io.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:

java.io.IOException - if an IO error occurs.

resolveIndexNameForBgzipFile

public static java.nio.file.Path resolveIndexNameForBgzipFile(java.nio.file.Path bgzipFile)

Gets the default index path for the bgzip file.