htsjdk.variant.variantcontext.writer

Class VariantContextWriterBuilder

java.lang.Object

htsjdk.variant.variantcontext.writer.VariantContextWriterBuilder

public class VariantContextWriterBuilder
extends java.lang.Object

Author:

thibault

Provides methods for creating VariantContextWriters using the Builder pattern. Replaces VariantContextWriterFactory.

The caller must choose an output file or an output stream for the VariantContextWriter to write to. When a file is chosen, the output stream is created implicitly based on Defaults and options passed to the builder. When a stream is chosen, it is passed unchanged to the VariantContextWriter.

Example: Create a series of files with buffering and indexing on the fly. Determine the appropriate file type based on filename.

   VariantContextWriterBuilder builder = new VariantContextWriterBuilder()
       .setReferenceDictionary(refDict)
       .setOption(Options.INDEX_ON_THE_FLY)
       .setBuffer(8192);
 
   VariantContextWriter sample1_writer = builder
       .setOutputFile("sample1.vcf")
       .build();
   VariantContextWriter sample2_writer = builder
       .setOutputFile("sample2.bcf")
       .build();
   VariantContextWriter sample3_writer = builder
       .setOutputFile("sample3.vcf.bgzf")
       .build();
   

Example: Explicitly turn off buffering and explicitly set the file type

   VariantContextWriterBuilder builder = new VariantContextWriterBuilder()
       .setReferenceDictionary(refDict)
       .setOption(Options.INDEX_ON_THE_FLY)
       .unsetBuffering();
 
   VariantContextWriter sample1_writer = builder
       .setOutputFile("sample1.custom_extension")
       .setOutputFileType(OutputType.VCF)
       .build();
   VariantContextWriter sample2_writer = builder
       .setOutputFile("sample2.custom_extension")
       .setOutputFileType(OutputType.BLOCK_COMPRESSED_VCF)
       .build();
   

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	VariantContextWriterBuilder.OutputType

Field Summary

Fields

Modifier and Type	Field and Description
static java.util.EnumSet<Options>	DEFAULT_OPTIONS
static java.util.EnumSet<VariantContextWriterBuilder.OutputType>	FILE_TYPES
static java.util.EnumSet<Options>	NO_OPTIONS
protected java.util.EnumSet<Options>	options
static java.util.EnumSet<VariantContextWriterBuilder.OutputType>	STREAM_TYPES

Constructor Summary

Constructors

Constructor and Description
VariantContextWriterBuilder() Default constructor.

Method Summary

Modifier and Type	Method and Description
VariantContextWriter	build() Validate and build the VariantContextWriter.
VariantContextWriterBuilder	clearIndexCreator() Do not pass an IndexCreator to the next VariantContextWriter created by this builder.
VariantContextWriterBuilder	clearOptions() Remove all options from the set of Options for the VariantContextWriterBuilder.
VariantContextWriterBuilder	setBuffer(int bufferSize) Set a buffer size for the file output stream passed to the next VariantContextWriter created by this builder.
VariantContextWriterBuilder	setCreateMD5() Create an MD5 digest file for the next VariantContextWriter created by this builder.
VariantContextWriterBuilder	setCreateMD5(boolean createMD5) Choose whether to also create an MD5 digest file for the next VariantContextWriter created by this builder.
static void	setDefaultOption(Options option) Add one option to the set of default Options that will be used as the initial set of options for all VariantContextWriterBuilders created after this call.
VariantContextWriterBuilder	setIndexCreator(IndexCreator idxCreator) Set an IndexCreator for the next VariantContextWriter created by this builder.
VariantContextWriterBuilder	setOption(Options option) Add one option to the set of Options for the VariantContextWriterBuilder, if it's not already present.
VariantContextWriterBuilder	setOptions(java.util.EnumSet<Options> options) Replace the set of Options for the VariantContextWriterBuilder with a new set.
VariantContextWriterBuilder	setOutputBCFStream(java.io.OutputStream outStream) Set the output BCF stream for the next VariantContextWriter created by this builder.
VariantContextWriterBuilder	setOutputFile(java.io.File outFile) Set the output file for the next VariantContextWriter created by this builder.
VariantContextWriterBuilder	setOutputFile(java.lang.String outFile) Set the output file for the next VariantContextWriter created by this builder.
VariantContextWriterBuilder	setOutputFileType(VariantContextWriterBuilder.OutputType outType) Set the output file type for the next VariantContextWriter created by this builder.
VariantContextWriterBuilder	setOutputStream(java.io.OutputStream outStream) Set the output stream (VCF, by default) for the next VariantContextWriter created by this builder.
VariantContextWriterBuilder	setOutputVCFStream(java.io.OutputStream outStream) Set the output VCF stream for the next VariantContextWriter created by this builder.
VariantContextWriterBuilder	setReferenceDictionary(SAMSequenceDictionary refDict) Set the reference dictionary to be used by VariantContextWriters created by this builder.
VariantContextWriterBuilder	unsetBuffering() Do not use buffering in the next VariantContextWriter created by this builder.
VariantContextWriterBuilder	unsetCreateMD5() Don't create an MD5 digest file for the next VariantContextWriter created by this builder.
static void	unsetDefaultOption(Options option) Remove an option from the set of default Options that will be used as the initial set of options for all VariantContextWriterBuilders created after this call.
VariantContextWriterBuilder	unsetOption(Options option) Remove one option from the set of Options for the VariantContextWriterBuilder, if it's present.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_OPTIONS

public static final java.util.EnumSet<Options> DEFAULT_OPTIONS

NO_OPTIONS

public static final java.util.EnumSet<Options> NO_OPTIONS

FILE_TYPES

public static final java.util.EnumSet<VariantContextWriterBuilder.OutputType> FILE_TYPES

STREAM_TYPES

public static final java.util.EnumSet<VariantContextWriterBuilder.OutputType> STREAM_TYPES

options

protected java.util.EnumSet<Options> options

Constructor Detail

VariantContextWriterBuilder

public VariantContextWriterBuilder()

Default constructor. Adds USE_ASYNC_IO to the Options if it is present in Defaults.

Method Detail

setReferenceDictionary

public VariantContextWriterBuilder setReferenceDictionary(SAMSequenceDictionary refDict)

Set the reference dictionary to be used by VariantContextWriters created by this builder.

Parameters:

refDict - the reference dictionary

Returns:

this VariantContextWriterBuilder

setOutputFile

public VariantContextWriterBuilder setOutputFile(java.io.File outFile)

Set the output file for the next VariantContextWriter created by this builder. Determines file type implicitly from the filename.

Parameters:

outFile - the file the VariantContextWriter will write to

Returns:

this VariantContextWriterBuilder

setOutputFile

public VariantContextWriterBuilder setOutputFile(java.lang.String outFile)

Set the output file for the next VariantContextWriter created by this builder. Determines file type implicitly from the filename.

Parameters:

outFile - the file the VariantContextWriter will write to

Returns:

this VariantContextWriterBuilder

setOutputFileType

public VariantContextWriterBuilder setOutputFileType(VariantContextWriterBuilder.OutputType outType)

Set the output file type for the next VariantContextWriter created by this builder.

Parameters:

outType - the type of file the VariantContextWriter will write to

Returns:

this VariantContextWriterBuilder

setOutputVCFStream

public VariantContextWriterBuilder setOutputVCFStream(java.io.OutputStream outStream)

Set the output VCF stream for the next VariantContextWriter created by this builder. If buffered writing is desired, caller must provide some kind of buffered OutputStream.

Parameters:

outStream - the output stream to write to

Returns:

this VariantContextWriterBuilder

setOutputBCFStream

public VariantContextWriterBuilder setOutputBCFStream(java.io.OutputStream outStream)

Set the output BCF stream for the next VariantContextWriter created by this builder. If buffered writing is desired, caller must provide some kind of buffered OutputStream.

Parameters:

outStream - the output stream to write to

Returns:

this VariantContextWriterBuilder

setOutputStream

public VariantContextWriterBuilder setOutputStream(java.io.OutputStream outStream)

Set the output stream (VCF, by default) for the next VariantContextWriter created by this builder. If buffered writing is desired, caller must provide some kind of buffered OutputStream.

Parameters:

outStream - the output stream to write to

Returns:

this VariantContextWriterBuilder

setIndexCreator

public VariantContextWriterBuilder setIndexCreator(IndexCreator idxCreator)

Set an IndexCreator for the next VariantContextWriter created by this builder.

Parameters:

idxCreator - the IndexCreator to use

Returns:

this VariantContextWriterBuilder

clearIndexCreator

public VariantContextWriterBuilder clearIndexCreator()

Do not pass an IndexCreator to the next VariantContextWriter created by this builder.

Returns:

this VariantContextWriterBuilder

setBuffer

public VariantContextWriterBuilder setBuffer(int bufferSize)

Set a buffer size for the file output stream passed to the next VariantContextWriter created by this builder. Set to 0 for no buffering. Does not affect OutputStreams passed directly to VariantContextWriterBuilder.

Parameters:

bufferSize - the buffer size to use

Returns:

this VariantContextWriterBuilder

unsetBuffering

public VariantContextWriterBuilder unsetBuffering()

Do not use buffering in the next VariantContextWriter created by this builder. Does not affect OutputStreams passed directly to VariantContextWriterBuilder.

Returns:

this VariantContextWriterBuilder

setCreateMD5

public VariantContextWriterBuilder setCreateMD5(boolean createMD5)

Choose whether to also create an MD5 digest file for the next VariantContextWriter created by this builder.

Parameters:

createMD5 - boolean, true to create an MD5 digest

Returns:

this VariantContextWriterBuilder

setCreateMD5

public VariantContextWriterBuilder setCreateMD5()

Create an MD5 digest file for the next VariantContextWriter created by this builder.

Returns:

this VariantContextWriterBuilder

unsetCreateMD5

public VariantContextWriterBuilder unsetCreateMD5()

Don't create an MD5 digest file for the next VariantContextWriter created by this builder.

Returns:

this VariantContextWriterBuilder

setOptions

public VariantContextWriterBuilder setOptions(java.util.EnumSet<Options> options)

Replace the set of Options for the VariantContextWriterBuilder with a new set.

Parameters:

options - the complete set of options to use

Returns:

this VariantContextWriterBuilder

setOption

public VariantContextWriterBuilder setOption(Options option)

Add one option to the set of Options for the VariantContextWriterBuilder, if it's not already present.

Parameters:

option - the option to set

Returns:

this VariantContextWriterBuilder

unsetOption

public VariantContextWriterBuilder unsetOption(Options option)

Remove one option from the set of Options for the VariantContextWriterBuilder, if it's present.

Parameters:

option - the option to unset

Returns:

this VariantContextWriterBuilder

setDefaultOption

public static void setDefaultOption(Options option)

Add one option to the set of default Options that will be used as the initial set of options for all VariantContextWriterBuilders created after this call.

Parameters:

option - the option to set

unsetDefaultOption

public static void unsetDefaultOption(Options option)

Remove an option from the set of default Options that will be used as the initial set of options for all VariantContextWriterBuilders created after this call.

Parameters:

option - the option to unset

clearOptions

public VariantContextWriterBuilder clearOptions()

Remove all options from the set of Options for the VariantContextWriterBuilder.

Returns:

this VariantContextWriterBuilder

build

public VariantContextWriter build()

Validate and build the VariantContextWriter.

Returns:

the VariantContextWriter as specified by previous method calls

Throws:

RuntimeIOException - if the writer is configured to write to a file, and the corresponding path does not exist.

java.lang.IllegalArgumentException - if no output file or stream is specified.

java.lang.IllegalArgumentException - if Options.INDEX_ON_THE_FLY is specified and no reference dictionary is provided.

java.lang.IllegalArgumentException - if Options.INDEX_ON_THE_FLY is specified and a stream output is specified.