htsjdk.samtools

Class SAMFileReader

java.lang.Object

htsjdk.samtools.SAMFileReader

All Implemented Interfaces:

SamReader, SamReader.Indexing, java.io.Closeable, java.lang.AutoCloseable, java.lang.Iterable<SAMRecord>

Direct Known Subclasses:

SAMFileTruncatedReader

Deprecated.

@Deprecated
public class SAMFileReader
extends java.lang.Object
implements SamReader, SamReader.Indexing

Class for reading and querying SAM/BAM files. Delegates to appropriate concrete implementation.

See Also:

SamReaderFactory

Nested Class Summary

Nested classes/interfaces inherited from interface htsjdk.samtools.SamReader

SamReader.AssertingIterator, SamReader.Indexing, SamReader.PrimitiveSamReader, SamReader.PrimitiveSamReaderToSamReaderAdapter, SamReader.ReaderImplementation, SamReader.Type

Constructor Summary

Constructors

Constructor and Description
SAMFileReader(java.io.File file) Deprecated. Prepare to read a SAM or BAM file.
SAMFileReader(java.io.File file, boolean eagerDecode) Deprecated. Read a SAM or BAM file, possibly with an index file if present.
SAMFileReader(java.io.File file, java.io.File indexFile) Deprecated. Prepare to read a SAM or BAM file.
SAMFileReader(java.io.File file, java.io.File indexFile, boolean eagerDecode) Deprecated. Read a SAM or BAM file, possibly with an index file.
SAMFileReader(java.io.InputStream stream) Deprecated. Prepare to read a SAM or BAM file.
SAMFileReader(java.io.InputStream stream, boolean eagerDecode) Deprecated. Read a SAM or BAM file.
SAMFileReader(SeekableStream strm, java.io.File indexFile, boolean eagerDecode) Deprecated. Read a BAM file via caller-supplied mechanism.
SAMFileReader(SeekableStream strm, SeekableStream indexStream, boolean eagerDecode) Deprecated.
SAMFileReader(java.net.URL url, java.io.File indexFile, boolean eagerDecode) Deprecated. Read a BAM file by http indexed query will be allowed.

Method Summary

Modifier and Type	Method and Description
void	close() Deprecated.
void	enableCrcChecking(boolean enabled) Deprecated. Only meaningful for BAM file readers - enables or disables checking of checksums on uncompressed data during decompression.
void	enableFileSource(boolean enabled) Deprecated. If true, writes the source of every read into the source SAMRecords.
void	enableIndexCaching(boolean enabled) Deprecated. If true, uses the caching version of the index reader.
void	enableIndexMemoryMapping(boolean enabled) Deprecated. If false, disable the use of memory mapping for accessing index files (default behavior is to use memory mapping).
BrowseableBAMIndex	getBrowseableIndex() Deprecated. Gets an index tagged with the BrowseableBAMIndex interface.
static ValidationStringency	getDefaultValidationStringency() Deprecated.
SAMFileHeader	getFileHeader() Deprecated.
SAMFileSpan	getFilePointerSpanningReads() Deprecated. Gets a pointer spanning all reads in the BAM file.
BAMIndex	getIndex() Deprecated. Retrieves the index for the given file type.
java.lang.String	getResourceDescription() Deprecated.
static SAMSequenceDictionary	getSequenceDictionary(java.io.File dictionaryFile) Deprecated. Returns the SAMSequenceDictionary from the provided FASTA.
boolean	hasBrowseableIndex() Deprecated. Returns true if the supported index is browseable, meaning the bins in it can be traversed and chunk data inspected and retrieved.
boolean	hasIndex() Deprecated.
SamReader.Indexing	indexing() Deprecated. Exposes the SamReader.Indexing facet of this SamReader.
boolean	isBinary() Deprecated.
SAMRecordIterator	iterator() Deprecated. Iterate through file in order.
SAMRecordIterator	iterator(SAMFileSpan chunks) Deprecated. Iterate through the given chunks in the file.
QueryInterval	makeQueryInterval(java.lang.String sequence, int start) Deprecated. Convenience method to create a QueryInterval that goes from start to end of given sequence.
QueryInterval	makeQueryInterval(java.lang.String sequence, int start, int end) Deprecated. Convenience method to create a QueryInterval
SAMRecordIterator	query(QueryInterval[] intervals, boolean contained) Deprecated. Iterate over records that match one of the given intervals.
SAMRecordIterator	query(java.lang.String sequence, int start, int end, boolean contained) Deprecated. Iterate over records that match the given interval.
SAMRecordIterator	queryAlignmentStart(java.lang.String sequence, int start) Deprecated. Iterate over records that map to the given sequence and start at the given position.
SAMRecordIterator	queryContained(QueryInterval[] intervals) Deprecated. Iterate over records that are contained in the given interval.
SAMRecordIterator	queryContained(java.lang.String sequence, int start, int end) Deprecated. Iterate over records that are contained in the given interval.
SAMRecord	queryMate(SAMRecord rec) Deprecated. Fetch the mate for the given read.
SAMRecordIterator	queryOverlapping(QueryInterval[] intervals) Deprecated. Iterate over records that overlap any of the given intervals.
SAMRecordIterator	queryOverlapping(java.lang.String sequence, int start, int end) Deprecated. Iterate over records that overlap the given interval.
SAMRecordIterator	queryUnmapped() Deprecated.
static void	setDefaultValidationStringency(ValidationStringency defaultValidationStringency) Deprecated. Set validation stringency for all subsequently-created SAMFileReaders.
void	setSAMRecordFactory(SAMRecordFactory factory) Deprecated. Override the default SAMRecordFactory class used to instantiate instances of SAMRecord and BAMRecord.
void	setValidationStringency(ValidationStringency validationStringency) Deprecated. Control validation of SAMRecords as they are read from file.
java.lang.String	toString() Deprecated.
SamReader.Type	type() Deprecated.

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Constructor Detail

SAMFileReader

public SAMFileReader(java.io.InputStream stream)

Deprecated.

Prepare to read a SAM or BAM file. Indexed lookup not allowed because reading from InputStream.

SAMFileReader

public SAMFileReader(java.io.File file)

Deprecated.

Prepare to read a SAM or BAM file. If the given file is a BAM, and has a companion BAI index file that is named according to the convention, it will be found and opened, and indexed query will be allowed.

SAMFileReader

public SAMFileReader(java.io.File file,
                     java.io.File indexFile)

Deprecated.

Prepare to read a SAM or BAM file. If the given file is a BAM, and an index is present, indexed query will be allowed.

Parameters:

file - SAM or BAM to read.

indexFile - Index file that is companion to BAM, or null if no index file, or if index file should be found automatically.

SAMFileReader

public SAMFileReader(java.io.InputStream stream,
                     boolean eagerDecode)

Deprecated.

Read a SAM or BAM file. Indexed lookup not allowed because reading from InputStream.

Parameters:

stream - input SAM or BAM. This is buffered internally so caller need not buffer.

eagerDecode - if true, decode SAM record entirely when reading it.

SAMFileReader

public SAMFileReader(java.io.File file,
                     boolean eagerDecode)

Deprecated.

Read a SAM or BAM file, possibly with an index file if present. If the given file is a BAM, and an index is present, indexed query will be allowed.

Parameters:

file - SAM or BAM.

eagerDecode - if true, decode SAM record entirely when reading it.

SAMFileReader

public SAMFileReader(java.io.File file,
                     java.io.File indexFile,
                     boolean eagerDecode)

Deprecated.

Read a SAM or BAM file, possibly with an index file. If the given file is a BAM, and an index is present, indexed query will be allowed.

Parameters:

file - SAM or BAM.

indexFile - Location of index file, or null in order to use the default index file (if present).

eagerDecode - eagerDecode if true, decode SAM record entirely when reading it.

SAMFileReader

public SAMFileReader(java.net.URL url,
                     java.io.File indexFile,
                     boolean eagerDecode)

Deprecated.

Read a BAM file by http indexed query will be allowed.

Parameters:

url - BAM.

indexFile - Location of index file, or null if indexed access not required.

eagerDecode - eagerDecode if true, decode SAM record entirely when reading it.

SAMFileReader

public SAMFileReader(SeekableStream strm,
                     java.io.File indexFile,
                     boolean eagerDecode)

Deprecated.

Read a BAM file via caller-supplied mechanism. Indexed query will be allowed, but index file must be provided in that case.

Parameters:

strm - BAM -- If the stream is not buffered, caller should wrap in SeekableBufferedStream for better performance.

indexFile - Location of index file, or null indexed access not required.

eagerDecode - if true, decode SAM record entirely when reading it.

SAMFileReader

public SAMFileReader(SeekableStream strm,
                     SeekableStream indexStream,
                     boolean eagerDecode)

Deprecated.

Parameters:

strm - BAM -- If the stream is not buffered, caller should wrap in SeekableBufferedStream for better performance.

Method Detail

getDefaultValidationStringency

public static ValidationStringency getDefaultValidationStringency()

Deprecated.

setDefaultValidationStringency

public static void setDefaultValidationStringency(ValidationStringency defaultValidationStringency)

Deprecated.

Set validation stringency for all subsequently-created SAMFileReaders. This is the only way to change the validation stringency for SAM header. NOTE: Programs that change this should make sure to have a try/finally clause wrapping the work that they do, so that the original stringency can be restored after the program's work is done. This facilitates calling a program that is usually run stand-alone from another program, without messing up the original validation stringency.

getSequenceDictionary

public static SAMSequenceDictionary getSequenceDictionary(java.io.File dictionaryFile)

Deprecated.

Returns the SAMSequenceDictionary from the provided FASTA.

close

public void close()

Deprecated.

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

enableFileSource

public void enableFileSource(boolean enabled)

Deprecated.

If true, writes the source of every read into the source SAMRecords.

Parameters:

enabled - true to write source information into each SAMRecord.

enableIndexCaching

public void enableIndexCaching(boolean enabled)

Deprecated.

If true, uses the caching version of the index reader.

Parameters:

enabled - true to write source information into each SAMRecord.

enableIndexMemoryMapping

public void enableIndexMemoryMapping(boolean enabled)

Deprecated.

If false, disable the use of memory mapping for accessing index files (default behavior is to use memory mapping). This is slower but more scalable when accessing large numbers of BAM files sequentially.

Parameters:

enabled - True to use memory mapping, false to use regular I/O.

enableCrcChecking

public void enableCrcChecking(boolean enabled)

Deprecated.

Only meaningful for BAM file readers - enables or disables checking of checksums on uncompressed data during decompression. Enabling this will increase decompression time by 15-30%.

setSAMRecordFactory

public void setSAMRecordFactory(SAMRecordFactory factory)

Deprecated.

Override the default SAMRecordFactory class used to instantiate instances of SAMRecord and BAMRecord.

isBinary

public boolean isBinary()

Deprecated.

Returns:

True if this is a BAM reader.

hasIndex

public boolean hasIndex()

Deprecated.

Specified by:

hasIndex in interface SamReader

Returns:

true if ths is a BAM file, and has an index

indexing

public SamReader.Indexing indexing()

Deprecated.

Description copied from interface: SamReader

Exposes the SamReader.Indexing facet of this SamReader.

Specified by:

indexing in interface SamReader

getIndex

public BAMIndex getIndex()

Deprecated.

Retrieves the index for the given file type. Ensure that the index is of the specified type.

Specified by:

getIndex in interface SamReader.Indexing

Returns:

An index of the given type.

hasBrowseableIndex

public boolean hasBrowseableIndex()

Deprecated.

Returns true if the supported index is browseable, meaning the bins in it can be traversed and chunk data inspected and retrieved.

Specified by:

hasBrowseableIndex in interface SamReader.Indexing

Returns:

True if the index supports the BrowseableBAMIndex interface. False otherwise.

getBrowseableIndex

public BrowseableBAMIndex getBrowseableIndex()

Deprecated.

Gets an index tagged with the BrowseableBAMIndex interface. Throws an exception if no such index is available.

Specified by:

getBrowseableIndex in interface SamReader.Indexing

Returns:

An index with a browseable interface, if possible.

Throws:

SAMException - if no such index is available.

getFileHeader

public SAMFileHeader getFileHeader()

Deprecated.

Specified by:

getFileHeader in interface SamReader

type

public SamReader.Type type()

Deprecated.

Specified by:

type in interface SamReader

Returns:

the SamReader.Type of this SamReader

getResourceDescription

public java.lang.String getResourceDescription()

Deprecated.

Specified by:

getResourceDescription in interface SamReader

Returns:

a human readable description of the resource backing this sam reader

setValidationStringency

public void setValidationStringency(ValidationStringency validationStringency)

Deprecated.

Control validation of SAMRecords as they are read from file. In order to control validation stringency for SAM Header, call SAMFileReader.setDefaultValidationStringency before constructing a SAMFileReader.

iterator

public SAMRecordIterator iterator()

Deprecated.

Iterate through file in order. For a SAMFileReader constructed from an InputStream, and for any SAM file, a 2nd iteration starts where the 1st one left off. For a BAM constructed from a File, each new iteration starts at the first record.

Only a single open iterator on a SAM or BAM file may be extant at any one time. If you want to start a second iteration, the first one must be closed first.

Specified by:

iterator in interface SamReader

Specified by:

iterator in interface java.lang.Iterable<SAMRecord>

iterator

public SAMRecordIterator iterator(SAMFileSpan chunks)

Deprecated.

Iterate through the given chunks in the file.

Specified by:

iterator in interface SamReader.Indexing

Parameters:

chunks - List of chunks for which to retrieve data.

Returns:

An iterator over the given chunks.

getFilePointerSpanningReads

public SAMFileSpan getFilePointerSpanningReads()

Deprecated.

Gets a pointer spanning all reads in the BAM file.

Specified by:

getFilePointerSpanningReads in interface SamReader.Indexing

Returns:

Unbounded pointer to the first record, in chunk format.

query

public SAMRecordIterator query(java.lang.String sequence,
                               int start,
                               int end,
                               boolean contained)

Deprecated.

Iterate over records that match the given interval. Only valid to call this if hasIndex() == true.

Only a single open iterator on a given SAMFileReader may be extant at any one time. If you want to start a second iteration, the first one must be closed first. You can use a second SAMFileReader to iterate in parallel over the same underlying file.

Note that indexed lookup is not perfectly efficient in terms of disk I/O. I.e. some SAMRecords may be read and then discarded because they do not match the interval of interest.

Note that an unmapped read will be returned by this call if it has a coordinate for the purpose of sorting that is in the query region.

Specified by:

query in interface SamReader

Parameters:

sequence - Reference sequence of interest.

start - 1-based, inclusive start of interval of interest. Zero implies start of the reference sequence.

end - 1-based, inclusive end of interval of interest. Zero implies end of the reference sequence.

contained - If true, each SAMRecord returned is will have its alignment completely contained in the interval of interest. If false, the alignment of the returned SAMRecords need only overlap the interval of interest.

Returns:

Iterator over the SAMRecords matching the interval.

queryOverlapping

public SAMRecordIterator queryOverlapping(java.lang.String sequence,
                                          int start,
                                          int end)

Deprecated.

Iterate over records that overlap the given interval. Only valid to call this if hasIndex() == true.

Only a single open iterator on a given SAMFileReader may be extant at any one time. If you want to start a second iteration, the first one must be closed first.

Note that indexed lookup is not perfectly efficient in terms of disk I/O. I.e. some SAMRecords may be read and then discarded because they do not match the interval of interest.

Note that an unmapped read will be returned by this call if it has a coordinate for the purpose of sorting that is in the query region.

Specified by:

queryOverlapping in interface SamReader

Parameters:

sequence - Reference sequence of interest.

start - 1-based, inclusive start of interval of interest. Zero implies start of the reference sequence.

end - 1-based, inclusive end of interval of interest. Zero implies end of the reference sequence.

Returns:

Iterator over the SAMRecords overlapping the interval.

queryContained

public SAMRecordIterator queryContained(java.lang.String sequence,
                                        int start,
                                        int end)

Deprecated.

Iterate over records that are contained in the given interval. Only valid to call this if hasIndex() == true.

Only a single open iterator on a given SAMFileReader may be extant at any one time. If you want to start a second iteration, the first one must be closed first.

Note that indexed lookup is not perfectly efficient in terms of disk I/O. I.e. some SAMRecords may be read and then discarded because they do not match the interval of interest.

Note that an unmapped read will be returned by this call if it has a coordinate for the purpose of sorting that is in the query region.

Specified by:

queryContained in interface SamReader

Parameters:

sequence - Reference sequence of interest.

start - 1-based, inclusive start of interval of interest. Zero implies start of the reference sequence.

end - 1-based, inclusive end of interval of interest. Zero implies end of the reference sequence.

Returns:

Iterator over the SAMRecords contained in the interval.

query

public SAMRecordIterator query(QueryInterval[] intervals,
                               boolean contained)

Deprecated.

Iterate over records that match one of the given intervals. This may be more efficient than querying each interval separately, because multiple reads of the same SAMRecords is avoided.

Only valid to call this if hasIndex() == true.

Only a single open iterator on a given SAMFileReader may be extant at any one time. If you want to start a second iteration, the first one must be closed first. You can use a second SAMFileReader to iterate in parallel over the same underlying file.

Note that indexed lookup is not perfectly efficient in terms of disk I/O. I.e. some SAMRecords may be read and then discarded because they do not match an interval of interest.

Note that an unmapped read will be returned by this call if it has a coordinate for the purpose of sorting that is in the query region.

Specified by:

query in interface SamReader

Parameters:

intervals - Intervals to be queried. The intervals must be optimized, i.e. in order, with overlapping and abutting intervals merged. This can be done with QueryInterval.optimizeIntervals(htsjdk.samtools.QueryInterval[])

contained - If true, each SAMRecord returned is will have its alignment completely contained in one of the intervals of interest. If false, the alignment of the returned SAMRecords need only overlap one of the intervals of interest.

Returns:

Iterator over the SAMRecords matching the interval.

queryOverlapping

public SAMRecordIterator queryOverlapping(QueryInterval[] intervals)

Deprecated.

Iterate over records that overlap any of the given intervals. This may be more efficient than querying each interval separately, because multiple reads of the same SAMRecords is avoided.

Only valid to call this if hasIndex() == true.

Only a single open iterator on a given SAMFileReader may be extant at any one time. If you want to start a second iteration, the first one must be closed first.

Note that indexed lookup is not perfectly efficient in terms of disk I/O. I.e. some SAMRecords may be read and then discarded because they do not match the interval of interest.

Note that an unmapped read will be returned by this call if it has a coordinate for the purpose of sorting that is in the query region.

Specified by:

queryOverlapping in interface SamReader

Parameters:

intervals - Intervals to be queried. The intervals must be optimized, i.e. in order, with overlapping and abutting intervals merged. This can be done with QueryInterval.optimizeIntervals(htsjdk.samtools.QueryInterval[])

Returns:

Iterator over the SAMRecords overlapping any of the intervals.

queryContained

public SAMRecordIterator queryContained(QueryInterval[] intervals)

Deprecated.

Iterate over records that are contained in the given interval. This may be more efficient than querying each interval separately, because multiple reads of the same SAMRecords is avoided.

Only valid to call this if hasIndex() == true.

Only a single open iterator on a given SAMFileReader may be extant at any one time. If you want to start a second iteration, the first one must be closed first.

Note that indexed lookup is not perfectly efficient in terms of disk I/O. I.e. some SAMRecords may be read and then discarded because they do not match the interval of interest.

Note that an unmapped read will be returned by this call if it has a coordinate for the purpose of sorting that is in the query region.

Specified by:

queryContained in interface SamReader

Parameters:

intervals - Intervals to be queried. The intervals must be optimized, i.e. in order, with overlapping and abutting intervals merged. This can be done with QueryInterval.optimizeIntervals(htsjdk.samtools.QueryInterval[])

Returns:

Iterator over the SAMRecords contained in any of the intervals.

queryUnmapped

public SAMRecordIterator queryUnmapped()

Deprecated.

Specified by:

queryUnmapped in interface SamReader

queryAlignmentStart

public SAMRecordIterator queryAlignmentStart(java.lang.String sequence,
                                             int start)

Deprecated.

Iterate over records that map to the given sequence and start at the given position. Only valid to call this if hasIndex() == true.

Only a single open iterator on a given SAMFileReader may be extant at any one time. If you want to start a second iteration, the first one must be closed first.

Note that indexed lookup is not perfectly efficient in terms of disk I/O. I.e. some SAMRecords may be read and then discarded because they do not match the interval of interest.

Note that an unmapped read will be returned by this call if it has a coordinate for the purpose of sorting that matches the arguments.

Specified by:

queryAlignmentStart in interface SamReader

Parameters:

sequence - Reference sequence of interest.

start - Alignment start of interest.

Returns:

Iterator over the SAMRecords with the given alignment start.

queryMate

public SAMRecord queryMate(SAMRecord rec)

Deprecated.

Fetch the mate for the given read. Only valid to call this if hasIndex() == true. This will work whether the mate has a coordinate or not, so long as the given read has correct mate information. This method iterates over the SAM file, so there may not be an unclosed iterator on the SAM file when this method is called.

Note that it is not possible to call queryMate when iterating over the SAMFileReader, because queryMate requires its own iteration, and there cannot be two simultaneous iterations on the same SAMFileReader. The work-around is to open a second SAMFileReader on the same input file, and call queryMate on the second reader.

Specified by:

queryMate in interface SamReader

Parameters:

rec - Record for which mate is sought. Must be a paired read.

Returns:

rec's mate, or null if it cannot be found.

toString

public java.lang.String toString()

Deprecated.

Overrides:

toString in class java.lang.Object

makeQueryInterval

public QueryInterval makeQueryInterval(java.lang.String sequence,
                                       int start,
                                       int end)

Deprecated.

Convenience method to create a QueryInterval

Parameters:

sequence - sequence of interest, must exist in sequence dictionary

start - 1-based start position, must be >= 1

end - 1-based end position.

Throws:

java.lang.IllegalArgumentException - if sequence not found in sequence dictionary, or start position < 1

makeQueryInterval

public QueryInterval makeQueryInterval(java.lang.String sequence,
                                       int start)

Deprecated.

Convenience method to create a QueryInterval that goes from start to end of given sequence.

Parameters:

sequence - sequence of interest, must exist in sequence dictionary

start - 1-based start position, must be >= 1

Throws:

java.lang.IllegalArgumentException - if sequence not found in sequence dictionary, or start position < 1