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.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class 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 Description static String
DEFAULT_EXTENSION
Deprecated.since June 2019 UseFileExtensions.GZI
instead.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description static GZIIndex
buildIndex(Path bgzipFile)
Builds aGZIIndex
on the fly from a BGZIP file.static GZIIndex
createIndex(Path bgzipFile, boolean overwrite)
Creates aGZIIndex
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 withBlockCompressedInputStream.seek(long)
.int
hashCode()
static GZIIndex
loadIndex(String source, InputStream indexIn)
Loads the index from the provided input stream.static 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.
-
-
-
Field Detail
-
DEFAULT_EXTENSION
@Deprecated public static final String DEFAULT_EXTENSION
Deprecated.since June 2019 UseFileExtensions.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 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 withBlockCompressedInputStream.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
-
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 final 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 aGZIIndex
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 aGZIIndex
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 iftrue
; otherwise, throws aIOException
.- Returns:
- the in-memory representation for the created index.
- Throws:
IOException
- if an IO error occurs.
-
-