# Class CRAMFileReader

java.lang.Object
htsjdk.samtools.SamReader.ReaderImplementation
htsjdk.samtools.CRAMFileReader

All Implemented Interfaces:
  `SamReader.Indexing, SamReader.PrimitiveSamReader, AutoCloseable`

public class CRAMFileReader extends SamReader.ReaderImplementation implements SamReader.Indexing, AutoCloseable
`BAMFileReader` analogue for CRAM files. Supports random access using BAI index file formats.

## Constructor Summary

Constructors
Constructor
Description
`CRAMFileReader(File cramFile, CRAMReferenceSource referenceSource)`
Create a CRAMFileReader from a file using the supplied reference source.
`CRAMFileReader(File cramFile, File indexFile, CRAMReferenceSource referenceSource)`
Create a CRAMFileReader from a file and optional index file using the supplied reference source.
`CRAMFileReader(File cramFile, File indexFile, CRAMReferenceSource referenceSource, ValidationStringency validationStringency)`
Create a CRAMFileReader from a CRAM file and optional index file using the supplied reference source and validation stringency.
`CRAMFileReader(File cramFile, InputStream inputStream)`
Create a CRAMFileReader from either a file or input stream using the reference source returned by `getDefaultCRAMReferenceSource`.
`CRAMFileReader(File cramFile, InputStream inputStream, CRAMReferenceSource referenceSource)`
Create a CRAMFileReader from either a file or input stream using the supplied reference source.
`CRAMFileReader(InputStream inputStream, SeekableStream indexInputStream, CRAMReferenceSource referenceSource, ValidationStringency validationStringency)`
Create a CRAMFileReader from an input stream and optional index stream using the supplied reference source and validation stringency.
`CRAMFileReader(InputStream stream, File indexFile, CRAMReferenceSource referenceSource, ValidationStringency validationStringency)`
Create a CRAMFileReader from an input stream and optional index file using the supplied reference source and validation stringency.

## Method Summary

Modifier and Type
Method
Description
`void`
`close()`
`CloseableIterator<SAMRecord>`
`createIndexIterator(QueryInterval[] intervals, boolean contained, long[] filePointers)`
Prepare to iterate through SAMRecords that match the intersection of the given intervals and chunk boundaries.
`BrowseableBAMIndex`
`getBrowseableIndex()`
Gets an index tagged with the BrowseableBAMIndex interface.
`SAMFileHeader`
`getFileHeader()`
`SAMFileSpan`
`getFilePointerSpanningReads()`
Gets a pointer spanning all reads in the BAM file.
`BAMIndex`
`getIndex()`
Retrieves the index for the given file type.
`SAMRecordIterator`
`getIterator()`
`CloseableIterator<SAMRecord>`
`getIterator(SAMFileSpan fileSpan)`
Note: the resolution of this iterator is the Slice, so the records returned are all of the records in all the slices that overlap these spans.
`ValidationStringency`
`getValidationStringency()`
`boolean`
`hasBrowseableIndex()`
Returns true if the supported index is browseable, meaning the bins in it can be traversed and chunk data inspected and retrieved.
`boolean`
`hasIndex()`
`SAMRecordIterator`
`iterator(SAMFileSpan fileSpan)`
Iterate through the given chunks in the file.
`CloseableIterator<SAMRecord>`
`query(QueryInterval[] intervals, boolean contained)`
`CloseableIterator<SAMRecord>`
`queryAlignmentStart(String sequence, int start)`
`CloseableIterator<SAMRecord>`
`queryUnmapped()`
`SamReader.Type`
`type()`

### Methods inherited from class Object

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

### Methods inherited from interface SamReader.PrimitiveSamReader

`isQueryable`

## Constructor Details

### CRAMFileReader

public CRAMFileReader(File cramFile, InputStream inputStream)
Create a CRAMFileReader from either a file or input stream using the reference source returned by `getDefaultCRAMReferenceSource`.

Parameters:
  `cramFile` - CRAM file to open
  `inputStream` - CRAM stream to read
Throws:
  `IllegalArgumentException` - if the `cramFile` and the `inputStream` are both null
  `IllegalStateException` - if a `default` reference source cannot be acquired

### CRAMFileReader

public CRAMFileReader(File cramFile, InputStream inputStream, CRAMReferenceSource referenceSource)
Create a CRAMFileReader from either a file or input stream using the supplied reference source.

Parameters:
  `cramFile` - CRAM file to read
  `inputStream` - CRAM stream to read
  `referenceSource` - a `source` of reference sequences. May not be null.
Throws:
  `IllegalArgumentException` - if the `cramFile` and the `inputStream` are both null or if the `CRAMReferenceSource` is null

### CRAMFileReader

public CRAMFileReader(File cramFile, File indexFile, CRAMReferenceSource referenceSource)
Create a CRAMFileReader from a file and optional index file using the supplied reference source. If index file is supplied then random access will be available.

Parameters:
  `cramFile` - CRAM file to read. May not be null.
  `indexFile` - index file to be used for random access. May be null.
  `referenceSource` - a `source` of reference sequences. May not be null.
Throws:
  `IllegalArgumentException` - if the `cramFile` or the `CRAMReferenceSource` is null

### CRAMFileReader

public CRAMFileReader(File cramFile, CRAMReferenceSource referenceSource)
Create a CRAMFileReader from a file using the supplied reference source.

Parameters:
  `cramFile` - CRAM file to read. Can not be null.
  `referenceSource` - a `source` of reference sequences. May not be null.
Throws:
  `IllegalArgumentException` - if the `cramFile` or the `CRAMReferenceSource` is null

### CRAMFileReader

public CRAMFileReader(InputStream inputStream, SeekableStream indexInputStream, CRAMReferenceSource referenceSource, ValidationStringency validationStringency) throws IOException
Create a CRAMFileReader from an input stream and optional index stream using the supplied reference source and validation stringency.

Parameters:
  `inputStream` - CRAM stream to read. May not be null.
  `indexInputStream` - index stream to be used for random access. May be null.
  `referenceSource` - a `source` of reference sequences. May not be null.
  `validationStringency` - Validation stringency to be used when reading
Throws:
  `IllegalArgumentException` - if the `inputStream` or the `CRAMReferenceSource` is null
  `IOException`

### CRAMFileReader

public CRAMFileReader(InputStream stream, File indexFile, CRAMReferenceSource referenceSource, ValidationStringency validationStringency) throws IOException
Create a CRAMFileReader from an input stream and optional index file using the supplied reference source and validation stringency.

Parameters:
  `stream` - CRAM stream to read. May not be null.
  `indexFile` - index file to be used for random access. May be null.
  `referenceSource` - a `source` of reference sequences. May not be null.
  `validationStringency` - Validation stringency to be used when reading
Throws:
  `IllegalArgumentException` - if the `inputStream` or the `CRAMReferenceSource` is null
  `IOException`

### CRAMFileReader

public CRAMFileReader(File cramFile, File indexFile, CRAMReferenceSource referenceSource, ValidationStringency validationStringency) throws IOException
Create a CRAMFileReader from a CRAM file and optional index file using the supplied reference source and validation stringency.

Parameters:
  `cramFile` - CRAM stream to read. May not be null.
  `indexFile` - index file to be used for random access. May be null.
  `referenceSource` - a `source` of reference sequences. May not be null.
  `validationStringency` - Validation stringency to be used when reading
Throws:
  `IllegalArgumentException` - if the `cramFile` or the `CRAMReferenceSource` is null
  `IOException`

## Method Details

### hasIndex

public boolean hasIndex()

Specified by:
  `hasIndex` in interface `SamReader.PrimitiveSamReader`

### getIndex

public BAMIndex getIndex()
Description copied from interface: `SamReader.Indexing`
Retrieves the index for the given file type. Ensure that the index is of the specified type.

Specified by:
  `getIndex` in interface `SamReader.Indexing`
Specified by:
  `getIndex` in interface `SamReader.PrimitiveSamReader`
Returns:
  An index of the given type.

### hasBrowseableIndex

public boolean hasBrowseableIndex()
Description copied from interface: `SamReader.Indexing`
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()
Description copied from interface: `SamReader.Indexing`
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.

### iterator

public SAMRecordIterator iterator(SAMFileSpan fileSpan)
Description copied from interface: `SamReader.Indexing`
Iterate through the given chunks in the file.

Specified by:
  `iterator` in interface `SamReader.Indexing`
Parameters:
  `fileSpan` - List of chunks for which to retrieve data.
Returns:
  An iterator over the given chunks.

### getFileHeader

public SAMFileHeader getFileHeader()

Specified by:
  `getFileHeader` in interface `SamReader.PrimitiveSamReader`

### getIterator

public SAMRecordIterator getIterator()

Specified by:
  `getIterator` in interface `SamReader.PrimitiveSamReader`

### getIterator

public CloseableIterator<SAMRecord> getIterator(SAMFileSpan fileSpan)
Note: the resolution of this iterator is the Slice, so the records returned are all of the records in all the slices that overlap these spans.

Specified by:
  `getIterator` in interface `SamReader.PrimitiveSamReader`

### getFilePointerSpanningReads

public SAMFileSpan getFilePointerSpanningReads()
Description copied from interface: `SamReader.Indexing`
Gets a pointer spanning all reads in the BAM file.

Specified by:
  `getFilePointerSpanningReads` in interface `SamReader.Indexing`
Specified by:
  `getFilePointerSpanningReads` in interface `SamReader.PrimitiveSamReader`
Returns:
  Unbounded pointer to the first record, in chunk format.

### queryAlignmentStart

public CloseableIterator<SAMRecord> queryAlignmentStart(String sequence, int start)

Specified by:
  `queryAlignmentStart` in interface `SamReader.PrimitiveSamReader`

### queryUnmapped

public CloseableIterator<SAMRecord> queryUnmapped()

Specified by:
  `queryUnmapped` in interface `SamReader.PrimitiveSamReader`

### close

public void close()

Specified by:
  `close` in interface `AutoCloseable`
Specified by:
  `close` in interface `SamReader.PrimitiveSamReader`

### getValidationStringency

public ValidationStringency getValidationStringency()

Specified by:
  `getValidationStringency` in interface `SamReader.PrimitiveSamReader`

### query

public CloseableIterator<SAMRecord> query(QueryInterval[] intervals, boolean contained)

Specified by:
  `query` in interface `SamReader.PrimitiveSamReader`

### type

public SamReader.Type type()

Specified by:
  `type` in interface `SamReader.PrimitiveSamReader`

### createIndexIterator

public CloseableIterator<SAMRecord> createIndexIterator(QueryInterval[] intervals, boolean contained, long[] filePointers)
Prepare to iterate through SAMRecords that match the intersection of the given intervals and chunk boundaries.

Parameters:
  `intervals` - the intervals to restrict reads to
  `contained` - if `true`, return records that are strictly contained in the intervals, otherwise return records that overlap
  `filePointers` - file pointer pairs corresponding to chunk boundaries for the intervals