LiftoverVcf (picard 2.18.2 API)

java.lang.Object
- picard.cmdline.CommandLineProgram
- - picard.vcf.LiftoverVcf

```
@DocumentedFeature
public class LiftoverVcf
extends CommandLineProgram
```
Summary
Tool for "lifting over" a VCF from one genome build to another, producing a properly headered, sorted and indexed VCF in one go.
Details
This tool adjusts the coordinates of variants within a VCF file to match a new reference. The output file will be sorted and indexed using the target reference build. To be clear, CommandLineProgram.REFERENCE_SEQUENCE should be the target reference build (that is, the "new" one). The tool is based on the UCSC LiftOver tool and uses a UCSC chain file to guide its operation.
For each variant, the tool will look for the target coordinate, reverse-complement and left-align the variant if needed, and, in the case that the reference and alternate alleles of a SNP have been swapped in the new genome build, it will adjust the SNP, and correct AF-like INFO fields and the relevant genotypes.

Example
```
 java -jar picard.jar LiftoverVcf \\
     I=input.vcf \\
     O=lifted_over.vcf \\
     CHAIN=b37tohg38.chain \\
     REJECT=rejected_variants.vcf \\
     R=reference_sequence.fasta
 
```
Caveats

Rejected Records
Records may be rejected because they cannot be lifted over or because of sequence incompatibilities between the source and target reference genomes. Rejected records will be emitted to the REJECT file using the source genome build coordinates. The reason for the rejection will be stated in the FILTER field, and more detail may be placed in the INFO field.
Memory Use
LiftOverVcf sorts the output using a SortingCollection which relies on CommandLineProgram.MAX_RECORDS_IN_RAM to specify how many (vcf) records to hold in memory before "spilling" to disk. The default value is reasonable when sorting SAM files, but not for VCFs as there is no good default due to the dependence on the number of samples and amount of information in the INFO and FORMAT fields. Consider lowering to 100,000 or even less if you have many genotypes.

Field Summary

Fields
Modifier and Type	Field	Description
`boolean`	`ALLOW_MISSING_FIELDS_IN_HEADER`
`static String`	`ATTEMPTED_LOCUS`	Attribute used to store the position of the failed variant on the target contig prior to finding out that alleles do not match.
`File`	`CHAIN`
`static int`	`EXIT_CODE_WHEN_CONTIG_NOT_IN_REFERENCE`
`static String`	`FILTER_CANNOT_LIFTOVER_INDEL`	Filter name to use when a target cannot be lifted over.
`static String`	`FILTER_INDEL_STRADDLES_TWO_INTERVALS`	Filter name to use when an indel cannot be lifted over since it straddles two intervals in a chain which means that it is unclear what are the right alleles to be used.
`static String`	`FILTER_MISMATCHING_REF_ALLELE`	Filter name to use when a target is lifted over, but the reference allele doesn't match the new reference.
`static String`	`FILTER_NO_TARGET`	Filter name to use when a target cannot be lifted over.
`File`	`INPUT`
`double`	`LIFTOVER_MIN_MATCH`
`boolean`	`LOG_FAILED_INTERVALS`
`static String`	`ORIGINAL_CONTIG`	Attribute used to store the name of the source contig/chromosome prior to liftover.
`static String`	`ORIGINAL_START`	Attribute used to store the position of the variant on the source contig prior to liftover.
`File`	`OUTPUT`
`File`	`REJECT`
`Collection<String>`	`TAGS_TO_DROP`
`Collection<String>`	`TAGS_TO_REVERSE`
`boolean`	`WARN_ON_MISSING_CONTIG`
`boolean`	`WRITE_ORIGINAL_POSITION`

Fields inherited from class picard.cmdline.CommandLineProgram
COMPRESSION_LEVEL, CREATE_INDEX, CREATE_MD5_FILE, GA4GH_CLIENT_SECRETS, MAX_RECORDS_IN_RAM, QUIET, REFERENCE_SEQUENCE, referenceSequence, specialArgumentsCollection, TMP_DIR, USE_JDK_DEFLATER, USE_JDK_INFLATER, VALIDATION_STRINGENCY, VERBOSITY

Constructor Summary

Constructors
Constructor Description

LiftoverVcf()

Constructors
Constructor	Description
`LiftoverVcf()`

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`protected int`	`doWork()`	Do the work after command line has been parsed.
`protected ReferenceArgumentCollection`	`makeReferenceArgumentCollection()`

Methods inherited from class picard.cmdline.CommandLineProgram
customCommandLineValidation, getCommandLine, getCommandLineParser, getDefaultHeaders, getFaqLink, getMetricsFile, getStandardUsagePreamble, getStandardUsagePreamble, getVersion, hasWebDocumentation, instanceMain, instanceMainWithExit, parseArgs, requiresReference, setDefaultHeaders, useLegacyParser

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

INPUT

@Argument(shortName="I",
          doc="The input VCF/BCF file to be lifted over.")
public File INPUT

OUTPUT

@Argument(shortName="O",
          doc="The output location for the lifted over VCF/BCF.")
public File OUTPUT

CHAIN

@Argument(shortName="C",
          doc="The liftover chain file. See https://genome.ucsc.edu/goldenPath/help/chain.html for a description of chain files.  See http://hgdownload.soe.ucsc.edu/downloads.html#terms for where to download chain files.")
public File CHAIN

REJECT

@Argument(doc="File to which to write rejected records.")
public File REJECT

WARN_ON_MISSING_CONTIG

@Argument(shortName="WMC",
          doc="Warn on missing contig.",
          optional=true)
public boolean WARN_ON_MISSING_CONTIG

LOG_FAILED_INTERVALS

@Argument(shortName="LFI",
          doc="If true, intervals failing due to match below LIFTOVER_MIN_MATCH will be logged as a warning to the console.",
          optional=true)
public boolean LOG_FAILED_INTERVALS

WRITE_ORIGINAL_POSITION

@Argument(doc="Write the original contig/position for lifted variants to the INFO field.",
          optional=true)
public boolean WRITE_ORIGINAL_POSITION

LIFTOVER_MIN_MATCH

@Argument(doc="The minimum percent match required for a variant to be lifted.",
          optional=true)
public double LIFTOVER_MIN_MATCH

ALLOW_MISSING_FIELDS_IN_HEADER

@Argument(doc="Allow INFO and FORMAT in the records that are not found in the header",
          optional=true)
public boolean ALLOW_MISSING_FIELDS_IN_HEADER

TAGS_TO_REVERSE

@Argument(doc="INFO field annotations that behave like an Allele Frequency and should be transformed with x->1-x when swapping reference with variant alleles.",
          optional=true)
public Collection<String> TAGS_TO_REVERSE

TAGS_TO_DROP

@Argument(doc="INFO field annotations that should be deleted when swapping reference with variant alleles.",
          optional=true)
public Collection<String> TAGS_TO_DROP

EXIT_CODE_WHEN_CONTIG_NOT_IN_REFERENCE

public static int EXIT_CODE_WHEN_CONTIG_NOT_IN_REFERENCE

FILTER_CANNOT_LIFTOVER_INDEL
```
public static final String FILTER_CANNOT_LIFTOVER_INDEL
```
Filter name to use when a target cannot be lifted over.

See Also:

Constant Field Values

FILTER_NO_TARGET
```
public static final String FILTER_NO_TARGET
```
Filter name to use when a target cannot be lifted over.

See Also:

Constant Field Values

FILTER_MISMATCHING_REF_ALLELE
```
public static final String FILTER_MISMATCHING_REF_ALLELE
```
Filter name to use when a target is lifted over, but the reference allele doesn't match the new reference.

See Also:

Constant Field Values

FILTER_INDEL_STRADDLES_TWO_INTERVALS
```
public static final String FILTER_INDEL_STRADDLES_TWO_INTERVALS
```
Filter name to use when an indel cannot be lifted over since it straddles two intervals in a chain which means that it is unclear what are the right alleles to be used.

See Also:

Constant Field Values

ORIGINAL_CONTIG
```
public static final String ORIGINAL_CONTIG
```
Attribute used to store the name of the source contig/chromosome prior to liftover.

See Also:

Constant Field Values

ORIGINAL_START
```
public static final String ORIGINAL_START
```
Attribute used to store the position of the variant on the source contig prior to liftover.

See Also:

Constant Field Values

ATTEMPTED_LOCUS
```
public static final String ATTEMPTED_LOCUS
```
Attribute used to store the position of the failed variant on the target contig prior to finding out that alleles do not match.

See Also:

Constant Field Values

Constructor Detail
- LiftoverVcf
```
public LiftoverVcf()
```

Method Detail
- makeReferenceArgumentCollection
```
protected ReferenceArgumentCollection makeReferenceArgumentCollection()
```
  Overrides:
  
  makeReferenceArgumentCollection in class CommandLineProgram
- doWork
```
protected int doWork()
```
  Description copied from class: CommandLineProgram
  
  Do the work after command line has been parsed. RuntimeException may be thrown by this method, and are reported appropriately.
  
  Specified by:
  
  doWork in class CommandLineProgram
  
  Returns:
  
  program exit status.

Class LiftoverVcf

Summary

Details

Example

Caveats

Rejected Records

Memory Use

Field Summary

Fields inherited from class picard.cmdline.CommandLineProgram

Constructor Summary

Method Summary

Methods inherited from class picard.cmdline.CommandLineProgram

Methods inherited from class java.lang.Object

Field Detail

INPUT

OUTPUT

CHAIN

REJECT

WARN_ON_MISSING_CONTIG

LOG_FAILED_INTERVALS

WRITE_ORIGINAL_POSITION

LIFTOVER_MIN_MATCH

ALLOW_MISSING_FIELDS_IN_HEADER

TAGS_TO_REVERSE

TAGS_TO_DROP

EXIT_CODE_WHEN_CONTIG_NOT_IN_REFERENCE

FILTER_CANNOT_LIFTOVER_INDEL

FILTER_NO_TARGET

FILTER_MISMATCHING_REF_ALLELE

FILTER_INDEL_STRADDLES_TWO_INTERVALS

ORIGINAL_CONTIG

ORIGINAL_START

ATTEMPTED_LOCUS

Constructor Detail

LiftoverVcf

Method Detail

makeReferenceArgumentCollection

doWork