# Class VariantContextUtils

java.lang.Object
htsjdk.variant.variantcontext.VariantContextUtils

public class VariantContextUtils extends Object

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`static class`
`VariantContextUtils.JexlVCMatchExp`
A simple but common wrapper for matching `VariantContext` objects using JEXL expressions

## Field Summary

Fields
Modifier and Type
Field
Description
`static final Lazy<org.apache.commons.jexl2.JexlEngine>`
`engine`
Use a `Lazy` `JexlEngine` instance to avoid class-loading issues.

## Constructor Summary

Constructors
Constructor
Description
`VariantContextUtils()`

## Method Summary

Modifier and Type
Method
Description
`static double`
`calculateAltAlleleFrequency(VariantContext vc)`
Computes the alternate allele frequency at the provided `VariantContext` by dividing its "AN" by its "AC".
`static void`
`calculateChromosomeCounts(VariantContextBuilder builder, boolean removeStaleValues)`
Update the attributes of the attributes map in the VariantContextBuilder to reflect the proper chromosome-based VCF tags based on the current VC produced by builder.make()
`static void`
`calculateChromosomeCounts(VariantContextBuilder builder, boolean removeStaleValues, Set<String> founderIds)`
Update the attributes of the attributes map in the VariantContextBuilder to reflect the proper chromosome-based VCF tags based on the current VC produced by builder.make()
`static Map<String,Object>`
`calculateChromosomeCounts(VariantContext vc, Map<String,Object> attributes, boolean removeStaleValues)`
Update the attributes of the attributes map given the VariantContext to reflect the proper chromosome-based VCF tags
`static Map<String,Object>`
`calculateChromosomeCounts(VariantContext vc, Map<String,Object> attributes, boolean removeStaleValues, Set<String> founderIds)`
Update the attributes of the attributes map given the VariantContext to reflect the proper chromosome-based VCF tags
`static int`
`computeEndFromAlleles(List<Allele> alleles, int start, int endForSymbolicAlleles)`
Compute the end position for this VariantContext from the alleles themselves In the trivial case this is a single BP event and end = start (open intervals) In general the end is start + ref length - 1, handling the case where ref length == 0 However, if alleles contains a symbolic allele then we use endForSymbolicAllele in all cases
`static Set<String>`
`genotypeNames(Collection<Genotype> genotypes)`
`static final VCFCompoundHeaderLine`
`getMetaDataForField(VCFHeader header, String field)`
`static int`
`getSize(VariantContext vc)`
`static List<VariantContextUtils.JexlVCMatchExp>`
`initializeMatchExps(String[] names, String[] exps)`
Method for creating JexlVCMatchExp from input walker arguments names and exps.
`static List<VariantContextUtils.JexlVCMatchExp>`
`initializeMatchExps(List<String> names, List<String> exps)`
Method for creating JexlVCMatchExp from input walker arguments names and exps.
`static List<VariantContextUtils.JexlVCMatchExp>`
`initializeMatchExps(Map<String,String> names_and_exps)`
Method for creating JexlVCMatchExp from input walker arguments mapping from names to exps.
`static boolean`
`isTransition(VariantContext vc)`
Answers if the provided variant is transitional (otherwise, it's transversional).
`static boolean`
`match(VariantContext vc, Genotype g, VariantContextUtils.JexlVCMatchExp exp)`
Returns true if `exp` match `vc`, `g`.
`static boolean`
`match(VariantContext vc, Genotype g, VariantContextUtils.JexlVCMatchExp exp, JexlMissingValueTreatment howToTreatMissingValues)`
Returns true if `exp` match `vc`, `g`.
`static Map<VariantContextUtils.JexlVCMatchExp, Boolean>`
`match(VariantContext vc, Genotype g, Collection<VariantContextUtils.JexlVCMatchExp> exps)`
Matches each `VariantContextUtils.JexlVCMatchExp` exp against the data contained in `vc`, `g`, and returns a map from these expressions to `true` (if they matched) or `false` (if they didn't).
`static Map<VariantContextUtils.JexlVCMatchExp, Boolean>`
`match(VariantContext vc, Genotype g, Collection<VariantContextUtils.JexlVCMatchExp> exps, JexlMissingValueTreatment howToTreatMissingValues)`
Matches each `VariantContextUtils.JexlVCMatchExp` exp against the data contained in `vc`, `g`, and returns a map from these expressions to `true` (if they matched) or `false` (if they didn't).
`static boolean`
`match(VariantContext vc, VariantContextUtils.JexlVCMatchExp exp)`
Returns true if `exp` match `vc`.
`static Map<VariantContextUtils.JexlVCMatchExp, Boolean>`
`match(VariantContext vc, Collection<VariantContextUtils.JexlVCMatchExp> exps)`
Matches each `VariantContextUtils.JexlVCMatchExp` exp against the data contained in `vc`, and returns a map from these expressions to `true` (if they matched) or `false` (if they didn't).
`static VariantContext`
`sitesOnlyVariantContext(VariantContext vc)`
Returns a newly allocated VC that is the same as VC, but without genotypes
`static Collection<VariantContext>`
`sitesOnlyVariantContexts(Collection<VariantContext> vcs)`
Returns a newly allocated list of VC, where each VC is the same as the input VCs, but without genotypes

### Methods inherited from class Object

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

## Field Details

### engine

public static final Lazy<org.apache.commons.jexl2.JexlEngine> engine
Use a `Lazy` `JexlEngine` instance to avoid class-loading issues. (Applications that access this class are otherwise forced to build a `JexlEngine` instance, which depends on some apache logging libraries that mightn't be packaged.)

## Constructor Details

### VariantContextUtils

public VariantContextUtils()

## Method Details

### calculateAltAlleleFrequency

public static double calculateAltAlleleFrequency(VariantContext vc)
Computes the alternate allele frequency at the provided `VariantContext` by dividing its "AN" by its "AC".

Parameters:
  `vc` - The variant whose alternate allele frequency is computed
Returns:
  The alternate allele frequency in [0, 1]
Throws:
  `AssertionError` - When either annotation is missing, or when the compuated frequency is outside the expected range

### calculateChromosomeCounts

public static Map<String,Object> calculateChromosomeCounts(VariantContext vc, Map<String,Object> attributes, boolean removeStaleValues)
Update the attributes of the attributes map given the VariantContext to reflect the proper chromosome-based VCF tags

Parameters:
  `vc` - the VariantContext
  `attributes` - the attributes map to populate; must not be null; may contain old values
  `removeStaleValues` - should we remove stale values from the mapping?
Returns:
  the attributes map provided as input, returned for programming convenience

### calculateChromosomeCounts

public static Map<String,Object> calculateChromosomeCounts(VariantContext vc, Map<String,Object> attributes, boolean removeStaleValues, Set<String> founderIds)
Update the attributes of the attributes map given the VariantContext to reflect the proper chromosome-based VCF tags

Parameters:
  `vc` - the VariantContext
  `attributes` - the attributes map to populate; must not be null; may contain old values
  `removeStaleValues` - should we remove stale values from the mapping?
  `founderIds` - - Set of founders Ids to take into account. AF and FC will be calculated over the founders. If empty or null, counts are generated for all samples as unrelated individuals
Returns:
  the attributes map provided as input, returned for programming convenience

### calculateChromosomeCounts

public static void calculateChromosomeCounts(VariantContextBuilder builder, boolean removeStaleValues)
Update the attributes of the attributes map in the VariantContextBuilder to reflect the proper chromosome-based VCF tags based on the current VC produced by builder.make()

Parameters:
  `builder` - the VariantContextBuilder we are updating
  `removeStaleValues` - should we remove stale values from the mapping?

### calculateChromosomeCounts

public static void calculateChromosomeCounts(VariantContextBuilder builder, boolean removeStaleValues, Set<String> founderIds)
Update the attributes of the attributes map in the VariantContextBuilder to reflect the proper chromosome-based VCF tags based on the current VC produced by builder.make()

Parameters:
  `builder` - the VariantContextBuilder we are updating
  `removeStaleValues` - should we remove stale values from the mapping?
  `founderIds` - - Set of founders to take into account. AF and FC will be calculated over the founders only. If empty or null, counts are generated for all samples as unrelated individuals

### getMetaDataForField

public static final VCFCompoundHeaderLine getMetaDataForField(VCFHeader header, String field)

### initializeMatchExps

public static List<VariantContextUtils.JexlVCMatchExp> initializeMatchExps(String[] names, String[] exps)
Method for creating JexlVCMatchExp from input walker arguments names and exps. These two arrays contain the name associated with each JEXL expression. initializeMatchExps will parse each expression and return a list of JexlVCMatchExp, in order, that correspond to the names and exps. These are suitable input to match() below.

Parameters:
  `names` - names
  `exps` - expressions
Returns:
  list of matches

### initializeMatchExps

public static List<VariantContextUtils.JexlVCMatchExp> initializeMatchExps(List<String> names, List<String> exps)
Method for creating JexlVCMatchExp from input walker arguments names and exps. These two lists contain the name associated with each JEXL expression. initializeMatchExps will parse each expression and return a list of JexlVCMatchExp, in order, that correspond to the names and exps. These are suitable input to match() below.

Parameters:
  `names` - names
  `exps` - expressions
Returns:
  list of matches

### initializeMatchExps

public static List<VariantContextUtils.JexlVCMatchExp> initializeMatchExps(Map<String,String> names_and_exps)
Method for creating JexlVCMatchExp from input walker arguments mapping from names to exps. These two arrays contain the name associated with each JEXL expression. initializeMatchExps will parse each expression and return a list of JexlVCMatchExp, in order, that correspond to the names and exps. These are suitable input to match() below.

Parameters:
  `names_and_exps` - mapping of names to expressions
Returns:
  list of matches

### match

public static boolean match(VariantContext vc, VariantContextUtils.JexlVCMatchExp exp)
Returns true if `exp` match `vc`. See `match(VariantContext, Collection)` for full docs.

Parameters:
  `vc` - variant context
  `exp` - expression
Returns:
  true if there is a match

### match

public static Map<VariantContextUtils.JexlVCMatchExp, Boolean> match(VariantContext vc, Collection<VariantContextUtils.JexlVCMatchExp> exps)
Matches each `VariantContextUtils.JexlVCMatchExp` exp against the data contained in `vc`, and returns a map from these expressions to `true` (if they matched) or `false` (if they didn't). This the best way to apply JEXL expressions to `VariantContext` records. Use the various `initializeMatchExps()`'s to create the list of `VariantContextUtils.JexlVCMatchExp` expressions. Expressions that contain literals not available in the VariantContext or Genotype will be treated as not matching

Parameters:
  `vc` - variant context
  `exps` - expressions
Returns:
  true if there is a match

### match

public static boolean match(VariantContext vc, Genotype g, VariantContextUtils.JexlVCMatchExp exp)
Returns true if `exp` match `vc`, `g`. See `match(VariantContext, Genotype, Collection)` for full docs.

Parameters:
  `vc` - variant context
  `g` - genotype
  `exp` - expression
Returns:
  true if there is a match

### match

public static boolean match(VariantContext vc, Genotype g, VariantContextUtils.JexlVCMatchExp exp, JexlMissingValueTreatment howToTreatMissingValues)
Returns true if `exp` match `vc`, `g`. See `match(VariantContext, Genotype, Collection)` for full docs.

Parameters:
  `vc` - variant context
  `g` - genotype
  `exp` - expression
  `howToTreatMissingValues` - what to do if the jexl expression contains literals that aren't in the context
Returns:
  true if there is a match

### match

public static Map<VariantContextUtils.JexlVCMatchExp, Boolean> match(VariantContext vc, Genotype g, Collection<VariantContextUtils.JexlVCMatchExp> exps)
Matches each `VariantContextUtils.JexlVCMatchExp` exp against the data contained in `vc`, `g`, and returns a map from these expressions to `true` (if they matched) or `false` (if they didn't). This the best way to apply JEXL expressions to `VariantContext` records. Use the various `initializeMatchExps()`'s to create the list of `VariantContextUtils.JexlVCMatchExp` expressions. Expressions that contain literals not available in the VariantContext or Genotype will be treated as not matching

Parameters:
  `vc` - variant context
  `g` - genotype
  `exps` - expressions
Returns:
  true if there is a match

### match

public static Map<VariantContextUtils.JexlVCMatchExp, Boolean> match(VariantContext vc, Genotype g, Collection<VariantContextUtils.JexlVCMatchExp> exps, JexlMissingValueTreatment howToTreatMissingValues)
Matches each `VariantContextUtils.JexlVCMatchExp` exp against the data contained in `vc`, `g`, and returns a map from these expressions to `true` (if they matched) or `false` (if they didn't). This the best way to apply JEXL expressions to `VariantContext` records. Use the various `initializeMatchExps()`'s to create the list of `VariantContextUtils.JexlVCMatchExp` expressions.

Parameters:
  `vc` - variant context
  `g` - genotype
  `exps` - expressions
  `howToTreatMissingValues` - what to do if the jexl expression contains literals that aren't in the context
Returns:
  true if there is a match

### isTransition

public static boolean isTransition(VariantContext vc) throws IllegalArgumentException
Answers if the provided variant is transitional (otherwise, it's transversional). Transitions: A->G G->A C->T T->C

Transversions: A->C A->T C->A C->G G->C G->T T->A T->G

Parameters:
  `vc` - a biallelic polymorphic SNP
Returns:
  true if a transition and false if transversion
Throws:
  `IllegalArgumentException` - if vc is monomorphic, not a SNP or not bi-allelic.

### sitesOnlyVariantContext

public static VariantContext sitesOnlyVariantContext(VariantContext vc)
Returns a newly allocated VC that is the same as VC, but without genotypes

Parameters:
  `vc` - variant context
Returns:
  new VC without genotypes

### sitesOnlyVariantContexts

public static Collection<VariantContext> sitesOnlyVariantContexts(Collection<VariantContext> vcs)
Returns a newly allocated list of VC, where each VC is the same as the input VCs, but without genotypes

Parameters:
  `vcs` - collection of VCs
Returns:
  new VCs without genotypes

### getSize

public static int getSize(VariantContext vc)

### genotypeNames

public static Set<String> genotypeNames(Collection<Genotype> genotypes)

### computeEndFromAlleles

public static int computeEndFromAlleles(List<Allele> alleles, int start, int endForSymbolicAlleles)
Compute the end position for this VariantContext from the alleles themselves In the trivial case this is a single BP event and end = start (open intervals) In general the end is start + ref length - 1, handling the case where ref length == 0 However, if alleles contains a symbolic allele then we use endForSymbolicAllele in all cases

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