Package htsjdk.variant.variantcontext

# Class VariantContextBuilder

java.lang.Object
htsjdk.variant.variantcontext.VariantContextBuilder

public class VariantContextBuilder extends Object

Builder class for `VariantContext`.

Some basic assumptions here:

1. data isn't protectively copied. If you provide an attribute map to the build, and modify it later, the builder will see this and so will any resulting variant contexts. It's best not to modify collections provided to a builder.
2. the system uses the standard builder model, allowing the simple construction idiom:

   > `builder.source("a").genotypes(gc).id("x").make()` => `VariantContext`

3. The best way to copy a VariantContext is:

   > `new VariantContextBuilder(vc).make()` => a copy of VC

4. validation of arguments is done at the during the final `make()` call, so a `VariantContextBuilder` can exist in an inconsistent state as long as those issues are resolved before the call to `make()` is issued.

## Constructor Summary

Constructors
Constructor
Description
`VariantContextBuilder()`
Create an empty VariantContextBuilder where all values adopt their default values.
`VariantContextBuilder(VariantContext parent)`
Returns a new builder based on parent -- the new VC will have all fields initialized to their corresponding values in parent.
`VariantContextBuilder(VariantContextBuilder parent)`
`VariantContextBuilder(String source, String contig, long start, long stop, Collection<Allele> alleles)`
Create an empty VariantContextBuilder where all values adopt their default values, but the bare min.

## Method Summary

Modifier and Type
Method
Description
`VariantContextBuilder`
`alleles(String... alleleStrings)`
`VariantContextBuilder`
`alleles(Collection<Allele> alleles)`
Tells this builder to use this collection of alleles for the resulting VariantContext
`VariantContextBuilder`
`alleles(List<String> alleleStrings)`
`VariantContextBuilder`
`attribute(String key, Object value)`
Puts the key -> value mapping into this builder's attributes
`VariantContextBuilder`
`attributes(Map<String,?> attributes)`
Tells this builder to use this map of attributes for the resulting `VariantContext`.
`VariantContextBuilder`
`chr(String contig)`
Tells us that the resulting VariantContext should have the specified contig chr
`VariantContextBuilder`
`computeEndFromAlleles(List<Allele> alleles, int start)`
`VariantContextBuilder`
`computeEndFromAlleles(List<Allele> alleles, int start, int endForSymbolicAlleles)`
Compute the end position for this VariantContext from the alleles themselves assigns this builder the stop position computed.
`VariantContextBuilder`
`copy()`
`VariantContextBuilder`
`filter(String filter)`
Adds the given filter to the list of filters
`VariantContextBuilder`
`filters(String... filters)`
`filters`
`VariantContextBuilder`
`filters(Set<String> filters)`
This builder's filters are set to this value filters can be `null` -> meaning there are no filters
`VariantContextBuilder`
`fullyDecoded(boolean isFullyDecoded)`
Sets this builder's fully decoded state to true.
`VariantContextBuilder`
`genotypes(Genotype... genotypes)`
Tells this builder that the resulting `VariantContext` should use a `GenotypeContext` containing genotypes
`VariantContextBuilder`
`genotypes(GenotypesContext genotypes)`
Tells this builder that the resulting `VariantContext` should use this genotype's `GenotypeContext`.
`VariantContextBuilder`
`genotypes(Collection<Genotype> genotypes)`
Tells this builder that the resulting `VariantContext` should use a `GenotypeContext` containing genotypes Note that genotypes can be `null`, meaning there are no genotypes
`VariantContextBuilder`
`genotypesNoValidation(GenotypesContext genotypes)`
`List<Allele>`
`getAlleles()`
`Map<String,Object>`
`getAttributes()`
Getter for attributes (DANGEROUS!!! DOES NOT MAKE A COPY!!!)
`String`
`getContig()`
Getter for contig
`Set<String>`
`getFilters()`
Getter for filters (DANGEROUS!!! DOES NOT MAKE A COPY!!!)
`GenotypesContext`
`getGenotypes()`
Getter for genotypes (DANGEROUS!!! DOES NOT MAKE A COPY!!!)
`String`
`getID()`
Getter for id of variant
`long`
`getStart()`
Getter for start position
`long`
`getStop()`
Getter for stop position
`VariantContextBuilder`
`id(String ID)`
Tells us that the resulting VariantContext should have ID
`boolean`
`isFullyDecoded()`
`VariantContextBuilder`
`loc(String contig, long start, long stop)`
Tells us that the resulting VariantContext should have the specified location
`VariantContextBuilder`
`log10PError(double log10PError)`
Tells us that the resulting VariantContext should have log10PError
`VariantContext`
`make()`
Takes all of the builder data provided up to this point, and instantiates a freshly allocated VariantContext with all of the builder data.
`VariantContext`
`make(boolean leaveModifyableAsIs)`
`VariantContextBuilder`
`noGenotypes()`
Tells this builder that the resulting VariantContext should not contain any GenotypeContext
`VariantContextBuilder`
`noID()`
Tells us that the resulting VariantContext should not have an ID
`VariantContextBuilder`
`passFilters()`
Tells this builder that the resulting VariantContext should have PASS filters
`VariantContextBuilder`
`putAttributes(Map<String,?> attributes)`
Tells this builder to put this map of attributes into the resulting `VariantContext`.
`VariantContextBuilder`
`rmAttribute(String key)`
Removes key if present in the attributes
`VariantContextBuilder`
`rmAttributes(List<String> keys)`
Removes list of keys if present in the attributes
`VariantContextBuilder`
`source(String source)`
Tells us that the resulting VariantContext should have source field set to source
`VariantContextBuilder`
`start(long start)`
Tells us that the resulting VariantContext should have the specified contig start
`VariantContextBuilder`
`stop(long stop)`
Tells us that the resulting VariantContext should have the specified contig stop
`VariantContextBuilder`
`unfiltered()`
Tells this builder that the resulting VariantContext be unfiltered

### Methods inherited from class java.lang.Object

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

## Constructor Details

### VariantContextBuilder

public VariantContextBuilder()
Create an empty VariantContextBuilder where all values adopt their default values. Note that source, chr, start, stop, and alleles must eventually be filled in, or the resulting VariantContext will throw an error.

### VariantContextBuilder

public VariantContextBuilder(String source, String contig, long start, long stop, Collection<Allele> alleles)
Create an empty VariantContextBuilder where all values adopt their default values, but the bare min. of info (source, chr, start, stop, and alleles) have been provided to start.

### VariantContextBuilder

public VariantContextBuilder(VariantContext parent)
Returns a new builder based on parent -- the new VC will have all fields initialized to their corresponding values in parent. This is the best way to create a derived VariantContext

Parameters:
  `parent` - Cannot be null

### VariantContextBuilder

public VariantContextBuilder(VariantContextBuilder parent)

## Method Details

### getContig

public String getContig()
Getter for contig

Returns:
  the current contig

### getStart

public long getStart()
Getter for start position

Returns:
  the current start position

### getStop

public long getStop()
Getter for stop position

Returns:
  the current stop position

### getID

public String getID()
Getter for id of variant

Returns:
  the current variant id

### getGenotypes

public GenotypesContext getGenotypes()
Getter for genotypes (DANGEROUS!!! DOES NOT MAKE A COPY!!!)

Returns:
  the current GenotypeContext

### getFilters

public Set<String> getFilters()
Getter for filters (DANGEROUS!!! DOES NOT MAKE A COPY!!!)

Returns:
  the current set of filters

### getAttributes

public Map<String,Object> getAttributes()
Getter for attributes (DANGEROUS!!! DOES NOT MAKE A COPY!!!)

Returns:
  the current map of attributes

### copy

public VariantContextBuilder copy()

### alleles

public VariantContextBuilder alleles(Collection<Allele> alleles)
Tells this builder to use this collection of alleles for the resulting VariantContext

Parameters:
  `alleles` - a Collection of alleles to set as the alleles of this builder
Returns:
  this builder

### alleles

public VariantContextBuilder alleles(List<String> alleleStrings)

### alleles

public VariantContextBuilder alleles(String... alleleStrings)

### getAlleles

public List<Allele> getAlleles()

### attributes

public VariantContextBuilder attributes(Map<String,?> attributes)
Tells this builder to use this map of attributes for the resulting `VariantContext`. The contents of the Map are copied to a new Map to ensure that modifications to the provided Map post-invocation don't affect the VariantContext and also to ensure additional attributes can be added in case the provided map doesn't support changes (e.g. UnmodifiableMap). Attributes can be `null` -> meaning there are no attributes. After calling this routine the builder assumes it can modify the attributes object here, if subsequent calls are made to set attribute values Value for each attribute must be of a type that implements `Serializable` or else serialization will fail.

Parameters:
  `attributes` - a Map of attributes to replace existing attributes with

### putAttributes

public VariantContextBuilder putAttributes(Map<String,?> attributes)
Tells this builder to put this map of attributes into the resulting `VariantContext`. The contents of the Map are copied to the current Map (or a new one is created if null) After calling this routine the builder assumes it can modify the attributes object here, if subsequent calls are made to set attribute values Value for each attribute must be of a type that implements `Serializable` or else serialization will fail.

Parameters:
  `attributes` - a Map of attributes to complement any existing attributes with, overwriting any that share the same key.

### attribute

public VariantContextBuilder attribute(String key, Object value)
Puts the key -> value mapping into this builder's attributes

Parameters:
  `key` - key for the attribute
  `value` - value for the attribute (must be of a type that implements `Serializable` or else serialization will fail)

### rmAttribute

public VariantContextBuilder rmAttribute(String key)
Removes key if present in the attributes

Parameters:
  `key` - key to remove
Returns:
  this builder

### rmAttributes

public VariantContextBuilder rmAttributes(List<String> keys)
Removes list of keys if present in the attributes

Parameters:
  `keys` - list of keys to remove
Returns:
  this builder

### filters

public VariantContextBuilder filters(Set<String> filters)
This builder's filters are set to this value filters can be `null` -> meaning there are no filters

Parameters:
  `filters` - Set of strings to set as the filters for this builder This set will be copied so that external set can be safely changed.
Returns:
  this builder

### filters

public VariantContextBuilder filters(String... filters)
`filters`

Parameters:
  `filters` - Strings to set as the filters for this builder
Returns:
  this builder

### filter

public VariantContextBuilder filter(String filter)
Adds the given filter to the list of filters

Parameters:
  `filter` -
Returns:

### passFilters

public VariantContextBuilder passFilters()
Tells this builder that the resulting VariantContext should have PASS filters

Returns:
  this builder

### unfiltered

public VariantContextBuilder unfiltered()
Tells this builder that the resulting VariantContext be unfiltered

Returns:
  this builder

### genotypes

public VariantContextBuilder genotypes(GenotypesContext genotypes)
Tells this builder that the resulting `VariantContext` should use this genotype's `GenotypeContext`. Note that this method will call the immutable method on the provided genotypes object to ensure that the user will not modify it further. Note that genotypes can be `null` -> meaning there are no genotypes

Parameters:
  `genotypes` - GenotypeContext to use in this builder
Returns:
  this builder

### genotypesNoValidation

public VariantContextBuilder genotypesNoValidation(GenotypesContext genotypes)

### genotypes

public VariantContextBuilder genotypes(Collection<Genotype> genotypes)
Tells this builder that the resulting `VariantContext` should use a `GenotypeContext` containing genotypes Note that genotypes can be `null`, meaning there are no genotypes

Parameters:
  `genotypes` - Collection of genotypes to set as genotypes for this builder

### genotypes

public VariantContextBuilder genotypes(Genotype... genotypes)
Tells this builder that the resulting `VariantContext` should use a `GenotypeContext` containing genotypes

Parameters:
  `genotypes` - genotypes to set as genotypes for this builder

### noGenotypes

public VariantContextBuilder noGenotypes()
Tells this builder that the resulting VariantContext should not contain any GenotypeContext

### id

public VariantContextBuilder id(String ID)
Tells us that the resulting VariantContext should have ID

Parameters:
  `ID` - id of variant
Returns:
  this builder

### noID

public VariantContextBuilder noID()
Tells us that the resulting VariantContext should not have an ID

Returns:
  this builder

### log10PError

public VariantContextBuilder log10PError(double log10PError)
Tells us that the resulting VariantContext should have log10PError

Parameters:
  `log10PError` - value of QUAL field for this builder
Returns:
  this builder

### source

public VariantContextBuilder source(String source)
Tells us that the resulting VariantContext should have source field set to source

Parameters:
  `source` - string describing the source of the variant
Returns:
  this builder

### loc

public VariantContextBuilder loc(String contig, long start, long stop)
Tells us that the resulting VariantContext should have the specified location

Parameters:
  `contig` - the contig the variant is on (must be in the dictionary)
  `start` - the start position of the variant
  `stop` - the end position of the variant
Returns:
  this builder

### chr

public VariantContextBuilder chr(String contig)
Tells us that the resulting VariantContext should have the specified contig chr

Parameters:
  `contig` - the contig of the variant
Returns:
  this builder

### start

public VariantContextBuilder start(long start)
Tells us that the resulting VariantContext should have the specified contig start

Parameters:
  `start` - the start position of the variant
Returns:
  this builder

### stop

public VariantContextBuilder stop(long stop)
Tells us that the resulting VariantContext should have the specified contig stop

Parameters:
  `stop` - the stop position of the variant
Returns:
  this builder

### computeEndFromAlleles

public VariantContextBuilder computeEndFromAlleles(List<Allele> alleles, int start)

See Also:
  - `with endForSymbolicAlleles == -1`

### computeEndFromAlleles

public VariantContextBuilder computeEndFromAlleles(List<Allele> alleles, int start, int endForSymbolicAlleles)
Compute the end position for this VariantContext from the alleles themselves assigns this builder the stop position computed.

Parameters:
  `alleles` - the list of alleles to consider. The reference allele must be the first one
  `start` - the known start position of this event
  `endForSymbolicAlleles` - the end position to use if any of the alleles is symbolic. Can be -1 if no is expected but will throw an error if one is found
Returns:
  this builder

### isFullyDecoded

public boolean isFullyDecoded()

Returns:
  true if this builder contains fully decoded data See VariantContext for more information

### fullyDecoded

public VariantContextBuilder fullyDecoded(boolean isFullyDecoded)
Sets this builder's fully decoded state to true. A fully decoded builder indicates that all fields are represented by their proper java objects (e.g., Integer(10) not "10"). See VariantContext for more information

Parameters:
  `isFullyDecoded` -

### make

public VariantContext make()
Takes all of the builder data provided up to this point, and instantiates a freshly allocated VariantContext with all of the builder data. This VariantContext is validated as appropriate and if not failing QC (and throwing an exception) is returned. Note that this function can be called multiple times to create multiple VariantContexts from the same builder.

### make

public VariantContext make(boolean leaveModifyableAsIs)