org.broadinstitute.hellbender.utils.bwa

Class BwaMemIndex

java.lang.Object

org.broadinstitute.hellbender.utils.bwa.BwaMemIndex

All Implemented Interfaces:

java.lang.AutoCloseable

public final class BwaMemIndex
extends java.lang.Object
implements java.lang.AutoCloseable

BwaMemIndex manages the mapping of a bwa index image file into (non-Java) memory. It's typically a huge chunk of memory, so you need to manage it as a precious resource. Usage pattern is: Create a BwaMemIndex for some reference. Create Aligners as needed to do some aligning -- they're pretty lightweight and thread safe. (But you may need to manage memory by controlling the number of reads that you align in one chunk.) Close the BwaMemIndex when you're done aligning. This class doesn't know anything about Spark. You can use it in a distributed setting if you distribute the index file to each node using the Yarn --files mechanism. You might find it convenient to manage a singleton instance of a BwaMemIndex on each Java VM when you're running distributed: check out BwaMemIndexSingleton in GATK. Alternatively, you could use this class directly to run bwa multi-threaded on a single machine, if that's what you want to do.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	BwaMemIndex.Algorithm Indexing algorithms supported by Bwa.

Field Summary

Fields

Modifier and Type	Field and Description
static java.util.List<java.lang.String>	FASTA_FILE_EXTENSIONS
static java.lang.String	IMAGE_FILE_EXTENSION
static java.util.List<java.lang.String>	INDEX_FILE_EXTENSIONS

Constructor Summary

Constructors

Constructor and Description
BwaMemIndex(java.lang.String indexImageFile) Loads an index from an image file.

Method Summary

Modifier and Type	Method and Description
void	close() Close the index and release the (non-Java) memory that's been allocated
static java.lang.String	createIndexImageFromFastaFile(java.lang.String fasta) Create the index image file for a fasta file.
static void	createIndexImageFromFastaFile(java.lang.String fasta, java.lang.String imageFile) Creates the index image file for a reference fasta file.
static void	createIndexImageFromFastaFile(java.lang.String fasta, java.lang.String imageFile, BwaMemIndex.Algorithm algo) Creates the index image file for a reference fasta file.
static void	createIndexImageFromIndexFiles(java.lang.String indexPrefix, java.lang.String imageFile) Create the index image file for a complete set of BWA index files
void	deRefIndex() done using the index -- if ref count has fallen to 0, a call to close can be expected to succeed
static java.lang.String	getBWAVersion() returns github GUID for the version of bwa that has been compiled
static java.lang.String	getDefaultIndexImageNameFromFastaFile(java.lang.String fasta) Gets the default index image name for the provided FASTA.
java.util.List<java.lang.String>	getReferenceContigNames() retrieve list of contig names in the reference dictionary
boolean	isOpen() true if index has not been closed
long	refIndex() there's someone using the index -- don't allow it to be closed

Methods inherited from class java.lang.Object

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

Field Detail

INDEX_FILE_EXTENSIONS

public static final java.util.List<java.lang.String> INDEX_FILE_EXTENSIONS

IMAGE_FILE_EXTENSION

public static final java.lang.String IMAGE_FILE_EXTENSION

See Also:

Constant Field Values

FASTA_FILE_EXTENSIONS

public static final java.util.List<java.lang.String> FASTA_FILE_EXTENSIONS

Constructor Detail

BwaMemIndex

public BwaMemIndex(java.lang.String indexImageFile)

Loads an index from an image file.

You can use other methods to create such indexes from fasta reference (createIndexImageFromFastaFile(java.lang.String) or their index files (createIndexImageFromIndexFiles(java.lang.String, java.lang.String)).

WARNING!: Notice that currently this method is making JNI call that might result in an abrupt process interruption (e.g. exit or abort system call) and so the control may never be returned.

Throws:

java.lang.IllegalArgumentException - if indexImageFile is null.

CouldNotReadImageException - if some problem occurred when loading the image file.

Method Detail

createIndexImageFromIndexFiles

public static void createIndexImageFromIndexFiles(java.lang.String indexPrefix,
                                                  java.lang.String imageFile)

Create the index image file for a complete set of BWA index files

Parameters:

indexPrefix - the location of the index files.

imageFile - the location of the new index image file.

WARNING!: Notice that currently this method is making JNI call that might result in an abrupt process interruption (e.g. exit or abort system call) and so the control may never be returned.

Throws:

java.lang.IllegalArgumentException - if indexPrefix is null or it does not look like it points to a complete set of index files.

java.lang.IllegalArgumentException - if imageFile is null.

createIndexImageFromFastaFile

public static java.lang.String createIndexImageFromFastaFile(java.lang.String fasta)

Create the index image file for a fasta file.

The name of the output index file will be determined by the name of the fasta file using getDefaultIndexImageNameFromFastaFile(String).

This is equivalent to calling {@link #createIndexImageFromFastaFile(String,String) createIndexImageFromFastaFile(X, getDefaultIndexImageNameFromFastaFile(X)))}

WARNING!: Notice that currently this method is making JNI call that might result in an abrupt process interruption (e.g. exit or abort system call) and so the control may never be returned.

Parameters:

fasta - the location of the fasta reference file.

Returns:

location of the generated index image file (equivaled to getDefaultIndexImageNameFromFastaFile(String)).

Throws:

java.lang.IllegalArgumentException - if fasta is null or does not finish with out of the standard fasta extension names (listed in FASTA_FILE_EXTENSIONS).

InvalidFileFormatException - if fasta does not seem to be a fasta formatted regular readable file.

CouldNotCreateIndexImageException - if for some reason we could not create the index file.

See Also:

getDefaultIndexImageNameFromFastaFile(String)

getDefaultIndexImageNameFromFastaFile

public static java.lang.String getDefaultIndexImageNameFromFastaFile(java.lang.String fasta)

Gets the default index image name for the provided FASTA.

The default name is substitutes its extension (typically .fasta or .fa) by IMAGE_FILE_EXTENSION (.img).

Parameters:

fasta - the location of the fasta reference file.

Throws:

java.lang.IllegalArgumentException - if fasta is null or does not finish with out of the standard fasta extension names (listed in FASTA_FILE_EXTENSIONS).

createIndexImageFromFastaFile

public static void createIndexImageFromFastaFile(java.lang.String fasta,
                                                 java.lang.String imageFile)

Creates the index image file for a reference fasta file.

The index will be created using the default algorithm BwaMemIndex.Algorithm.AUTO.

Calling this method is equivalent to calling createIndexImageFromFastaFile(a, b, Algorithm.AUTO)

WARNING!: Notice that currently this method is making JNI call that might result in an abrupt process interruption (e.g. exit or abort system call) and so the control may never be returned.

Parameters:

fasta - the location of the targeted reference.

imageFile - the location of the new index image file.

Throws:

java.lang.IllegalArgumentException - if fasta is null or it does not look like it points to a fasta formatted readable file.

java.lang.IllegalArgumentException - if imageFile is null.

InvalidFileFormatException - if fasta does not seem to be a fasta formatted regular and readable file.

CouldNotCreateIndexImageException - if there was a problem creating the output image.

CouldNotCreateIndexException - if there was some problem while creating the intermediary index file set.

createIndexImageFromFastaFile

public static void createIndexImageFromFastaFile(java.lang.String fasta,
                                                 java.lang.String imageFile,
                                                 BwaMemIndex.Algorithm algo)

Creates the index image file for a reference fasta file.

WARNING!: Notice that currently this method is making JNI call that might result in an abrupt process interruption (e.g. exit or abort system call) and so the control may never be returned.

Parameters:

fasta - the location of the targeted reference.

imageFile - the location of the new index image file.

algo - the algorithm to use to construct the index (see BwaMemIndex.Algorithm to see what there is available.).

Throws:

java.lang.IllegalArgumentException - if fasta is null or it does not look like it points to a fasta formatted readable file.

java.lang.IllegalArgumentException - if imageFile is null.

InvalidFileFormatException - if fasta does not seem to be a fasta formatted regular and readable file.

CouldNotCreateIndexImageException - if there was a problem creating the output image.

CouldNotCreateIndexException - if there was some problem while creating the intermediary index file set.

isOpen

public boolean isOpen()

true if index has not been closed

refIndex

public long refIndex()

there's someone using the index -- don't allow it to be closed

deRefIndex

public void deRefIndex()

done using the index -- if ref count has fallen to 0, a call to close can be expected to succeed

close

public void close()

Close the index and release the (non-Java) memory that's been allocated

WARNING!: Notice that currently this method is making JNI call that might result in an abrupt process interruption (e.g. exit or abort system call) and so the control may never be returned.

Specified by:

close in interface java.lang.AutoCloseable

getReferenceContigNames

public java.util.List<java.lang.String> getReferenceContigNames()

retrieve list of contig names in the reference dictionary

getBWAVersion

public static java.lang.String getBWAVersion()

returns github GUID for the version of bwa that has been compiled