org.broadinstitute.hellbender.utils.fasta

Class CachingIndexedFastaSequenceFile

java.lang.Object

org.broadinstitute.hellbender.utils.fasta.CachingIndexedFastaSequenceFile

All Implemented Interfaces:

htsjdk.samtools.reference.ReferenceSequenceFile, java.io.Closeable, java.lang.AutoCloseable

public final class CachingIndexedFastaSequenceFile
extends java.lang.Object
implements htsjdk.samtools.reference.ReferenceSequenceFile

A caching version of the IndexedFastaSequenceFile that avoids going to disk as often as the raw indexer. Automatically upper-cases the bases coming in, unless the flag preserveCase is explicitly set. Automatically converts IUPAC bases to Ns, unless the flag preserveIUPAC is explicitly set. Instances of this class should be closed when they are no longer needed.

Field Summary

Fields

Modifier and Type	Field and Description
static long	DEFAULT_CACHE_SIZE The default cache size in bp
protected static org.apache.logging.log4j.Logger	logger

Constructor Summary

Constructors

Constructor and Description
CachingIndexedFastaSequenceFile(java.nio.file.Path fasta) Open the given indexed fasta sequence file.
CachingIndexedFastaSequenceFile(java.nio.file.Path fasta, boolean preserveAmbiguityCodesAndCapitalization) Open the given indexed fasta sequence file.
CachingIndexedFastaSequenceFile(java.nio.file.Path fasta, long cacheSize, boolean preserveCase, boolean preserveIUPAC) Open the given indexed fasta sequence file.

Method Summary

Modifier and Type	Method and Description
double	calcEfficiency() Returns the efficiency (% of hits of all queries) of this object
void	close() Close the backing ReferenceSequenceFile
long	getCacheHits()
long	getCacheMisses()
long	getCacheSize()
htsjdk.samtools.reference.ReferenceSequence	getSequence(java.lang.String contig) Retrieves the complete sequence described by this contig.
htsjdk.samtools.SAMSequenceDictionary	getSequenceDictionary() Returns the sequence dictionary associated with this reference file
htsjdk.samtools.reference.ReferenceSequence	getSubsequenceAt(java.lang.String contig, long start, long stop) Gets the subsequence of the contig in the range [start,stop] Uses the sequence cache if possible, or updates the cache to handle the request.
boolean	isIndexed() A CachingIndexedFastaSequenceFile is always indexed.
boolean	isPreservingCase() Is this CachingIndexedFastaReader keeping the original case of bases in the fasta, or is everything being made upper case?
htsjdk.samtools.reference.ReferenceSequence	nextSequence() Retrieves the next whole sequence from the file.
void	printEfficiency(org.apache.logging.log4j.Level priority) Print the efficiency (hits / queries) to logger with priority
void	reset() Resets the ReferenceSequenceFile so that the next call to nextSequence() will return the first sequence in the file.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface htsjdk.samtools.reference.ReferenceSequenceFile

toString

Field Detail

logger

protected static final org.apache.logging.log4j.Logger logger

DEFAULT_CACHE_SIZE

public static final long DEFAULT_CACHE_SIZE

The default cache size in bp

See Also:

Constant Field Values

Constructor Detail

CachingIndexedFastaSequenceFile

public CachingIndexedFastaSequenceFile(java.nio.file.Path fasta)

Open the given indexed fasta sequence file. Throw an exception if the file cannot be opened. Looks for index files for the fasta on disk. This CachingIndexedFastaReader will convert all FASTA bases to upper cases under the hood and all IUPAC bases to `N`.

Parameters:

fasta - The file to open.

CachingIndexedFastaSequenceFile

public CachingIndexedFastaSequenceFile(java.nio.file.Path fasta,
                                       boolean preserveAmbiguityCodesAndCapitalization)

Open the given indexed fasta sequence file. Throw an exception if the file cannot be opened. If preserveAmbiguityCodesAndCapitalization is true, will NOT convert IUPAC bases in the file to `N` and will NOT capitalize lower-case bases. NOTE: Most GATK tools do not support data created by setting preserveAmbiguityCodesAndCapitalization to true. Looks for index files for the fasta on disk.

Parameters:

fasta - Fasta file to be used as reference

preserveAmbiguityCodesAndCapitalization - Whether to preserve the original bases in the given reference file path or normalize them.

CachingIndexedFastaSequenceFile

public CachingIndexedFastaSequenceFile(java.nio.file.Path fasta,
                                       long cacheSize,
                                       boolean preserveCase,
                                       boolean preserveIUPAC)

Open the given indexed fasta sequence file. Throw an exception if the file cannot be opened. Looks for index files for the fasta on disk Uses provided cacheSize instead of the default NOTE: Most GATK tools do not support data created by setting preserveCase or preserveIUPAC to true.

Parameters:

fasta - The file to open.

cacheSize - the size of the cache to use in this CachingIndexedFastaReader, must be > 0

preserveCase - If true, we will keep the case of the underlying bases in the FASTA, otherwise everything is converted to upper case

preserveIUPAC - If true, we will keep the IUPAC bases in the FASTA, otherwise they are converted to Ns

Method Detail

printEfficiency

public void printEfficiency(org.apache.logging.log4j.Level priority)

Print the efficiency (hits / queries) to logger with priority

calcEfficiency

public double calcEfficiency()

Returns the efficiency (% of hits of all queries) of this object

Returns:

getCacheHits

public long getCacheHits()

Returns:

the number of cache hits that have occurred

getCacheMisses

public long getCacheMisses()

Returns:

the number of cache misses that have occurred

getCacheSize

public long getCacheSize()

Returns:

the size of the cache we are using

isPreservingCase

public boolean isPreservingCase()

Is this CachingIndexedFastaReader keeping the original case of bases in the fasta, or is everything being made upper case?

Returns:

true if the bases coming from this reader are in the original case in the fasta, false if they are all upper cased

getSequenceDictionary

public htsjdk.samtools.SAMSequenceDictionary getSequenceDictionary()

Returns the sequence dictionary associated with this reference file

Specified by:

getSequenceDictionary in interface htsjdk.samtools.reference.ReferenceSequenceFile

Returns:

a list of sequence records representing the sequences in this reference file

nextSequence

public htsjdk.samtools.reference.ReferenceSequence nextSequence()

Retrieves the next whole sequence from the file. *Note: This method does not use or interact with the cache at all.

Specified by:

nextSequence in interface htsjdk.samtools.reference.ReferenceSequenceFile

Returns:

a ReferenceSequence or null if at the end of the file

reset

public void reset()

Resets the ReferenceSequenceFile so that the next call to nextSequence() will return the first sequence in the file.

Specified by:

reset in interface htsjdk.samtools.reference.ReferenceSequenceFile

isIndexed

public boolean isIndexed()

A CachingIndexedFastaSequenceFile is always indexed.

Specified by:

isIndexed in interface htsjdk.samtools.reference.ReferenceSequenceFile

Returns:

true

getSequence

public htsjdk.samtools.reference.ReferenceSequence getSequence(java.lang.String contig)

Retrieves the complete sequence described by this contig. If the contig is longer than the cache size the cache will not be used or updated.

Specified by:

getSequence in interface htsjdk.samtools.reference.ReferenceSequenceFile

Parameters:

contig - contig whose data should be returned.

Returns:

The full sequence associated with this contig.

getSubsequenceAt

public htsjdk.samtools.reference.ReferenceSequence getSubsequenceAt(java.lang.String contig,
                                                                    long start,
                                                                    long stop)

Gets the subsequence of the contig in the range [start,stop] Uses the sequence cache if possible, or updates the cache to handle the request. If the range is larger than the cache itself, just loads the sequence directly, not changing the cache at all

Specified by:

getSubsequenceAt in interface htsjdk.samtools.reference.ReferenceSequenceFile

Parameters:

contig - Contig whose subsequence to retrieve.

start - inclusive, 1-based start of region.

stop - inclusive, 1-based stop of region.

Returns:

The partial reference sequence associated with this range. If preserveCase is false, then all of the bases in the ReferenceSequence returned by this method will be upper cased.

close

public void close()

Close the backing ReferenceSequenceFile

Specified by:

close in interface htsjdk.samtools.reference.ReferenceSequenceFile

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable