= vg-giraffe(1)
vgteam contributors
v1.20.0
:doctype: manpage
:manmanual: vg
:mansource: vg
:man-linkstyle: pass:[blue R < >]

== Name

vg-giraffe - map unpaired short reads using minimizers and gapless extension

== Synopsis

*vg giraffe* [_OPTION_]... [_FASTA_ [_VCF_]] > output.gam

== Arguments

_FASTA_::
    Specify a FASTA file to build the graph from. Must have an extension *.fa*, *.fna*, or *.fasta*, with optional *.gz*. The name without extension is used as the _basename_ under which to look for index files with their own extensions, if *-x*/*--xg-name* is not specified. If omitted, *-x*/*--xg-name* is required.
    
_VCF_::
    Variant Call Format file containing phased haplotypes, used to build the graph and haplotype database (GBWT) if those are not themselves provided. Must have a *.vcf.gz* extension, and an associated *.vcf.gz.tbi* index file. If omitted, a graph and GBWT must already exist and must be provided, either explicitly with *-x*/*--xg-name* and *-H*/*--gbwt-name*, or via the _FASTA_ or *-x*/*--xg-name* derived _basename_.
    
_TAG_::
    Specify a collection of tests to run, via []-enclosed tag. Tag may need to be quoted to avoid being interpreted as a shell wildcard character class.

== Options

*-x*::
*--xg-name*=_FILE_::
  Use this xg index or graph. The file name without extension is also used as the _basename_ for finding indexes, overriding any FASTA-derived _basename_. If omitted, _FASTA_ is required. If not specified, will load _basename.vg_ and create that file if not present.
 
*-g*::
*--graph-name*=_FILE_:: 
  Load this GBWTGraph. If not specified, will load _basename.gg_ and create that file if not present.

*-H*::
*--gbwt-name*=_FILE_:: 
  Use this GBWT index. If not specified, will load _basename.gbwt_ and create that file if not present.

*-m*::
*--minimizer-name*=_FILE_:: 
  Use this minimizer index. If not specified, will load _basename.min_ and create that file if not present.

*-d*::
*--dist-name*=_FILE_:: 
  Cluster using this distance index. If not specified, will load _basename.dist_ and create that file if not present.

*-p*::
*--progress*:: 
  Show progress

*-G*::
*--gam-in*=_FILE_:: 
  Read and realign GAM-format reads from FILE (may repeat)

*-f*::
*--fastq-in*=_FILE_:: 
  Read and align FASTQ-format reads from FILE (may repeat)

*-i*::
*--interleaved*:: 
  GAM/FASTQ input is interleaved pairs, for paired-end alignment

*-M*::
*--max-multimap*=_INT_:: 
  Produce up to INT alignments for each read [1]

*-N*::
*--sample*=_NAME_:: 
  Add this sample name

*-R*::
*--read-group*=_NAME_:: 
  Add this read group

*-n*::
*--discard*:: 
  Discard all output alignments (for profiling)

*--output-basename*=_NAME_:: 
  Write output to a GAM file beginning with the given prefix for each setting combination

*--report-name*=_NAME_:: 
  Write a TSV of output file and mapping speed to the given file

*-c*::
*--hit-cap*=_INT_:: 
  Use all minimizers with at most INT hits [10]

*-C*::
*--hard-hit-cap*=_INT_:: 
  Use all minimizers with at most INT hits [10]

*-F*::
*--score-fraction*=_FLOAT_:: 
  Select minimizers between hit caps until score is FLOAT of total [0.6]

*-D*::
*--distance-limit*=_INT_:: 
  Cluster using this distance limit [200]

*-e*::
*--max-extensions*=_INT_:: 
  Extend up to INT clusters [48]

*-a*::
*--max-alignments*=_INT_:: 
  Align up to INT clusters [8]

*-s*::
*--cluster-score*=_INT_:: 
  Only extend clusters if they are within INT of the best score [50]

*-u*::
*--cluster-coverage*=_FLOAT_:: 
  Only extend clusters if they are within INT of the best read coverage [0.4]

*-v*::
*--extension-score*=_INT_:: 
  Only align extensions if their score is within INT of the best score [1]

*-w*::
*--extension-set*=_INT_:: 
  Only align extension sets if their score is within extension-set of the best score [20]

*-O*::
*--no-dp*:: 
  Disable all gapped alignment

*--track-provenance*:: 
  Track how internal intermediate alignment candidates were arrived at

*--track-correctness*:: 
  Track if internal intermediate alignment candidates are correct (implies --track-provenance)

*-t*::
*--threads*=_INT_:: 
  Number of compute threads to use


== Description

*vg gaffe* is a fast (experimental) algorithm to map reads to a graph. 
It is specialized for low-error-rate short reads.
Giraffe uses minimizers of the graph's haplotypes and gapless extension to map the reads.
Because the graph is expected to contain a relatively complete inventory of a certain type of variation, gapless alignment is sufficient to align most reads and a more expensive gapped alignment step is required for only a minority of cases.

*vg gaffe* requires four input files to define the reference: A graph or GBWTGraph, a GBWT index, a minimizer index, and a distance index. 
Each can also be automatically produced by *vg gaffe*, given the requisite input files.
The graph and indexes can be produced automatically if _FASTA_ and _VCF_ are specified.
The _basename_ is a file path derived from the graph file (specified by *-x*/*--xg-name*), or from the _FASTA_ argument if no graph file is specified. It is combined with an extension for each index type to produce the filename from which that index will be loaded, or to which it will be saved if it is constructed.

Because indexing is resource-intensive, the graph and indexes can be manually constructed in advance.
The graph can be built wiht *vg construct*.
Indexes can be manually built with *vg index* and *vg minimizer*, as well as *vg snarls* to provide the snarls file needed for the distance index.
If desired, the GBWTgraph can also be pre-generated with *vg gbwt*.

When building the graph with *vg construct* for use with *vg gaffe*, it is important to provide the *-a* option in order to embed the variant information necessary to later build the GBWT.

When building snarls with *vg snarls*, it is important to provide the *-T*/*--include-trivial* option to include trivial snarls, which are required when building the distance index.

== Examples

To map reads to an indexed graph and write the alignment to a gam file:

----
$ vg gaffe -x reference.xg -H reference.gbwt -m reference.min -d reference.dist -G reads.gam > mapped.gam
----

Same as above, but implicitly finding other indexes using the graph's filename:

----
$ vg gaffe -x reference.xg -G reads.gam > mapped.gam
----

To map reads building all indexes dynamically, if not found, from a FASTA and indexed VCF:

----
$ vg gaffe reference.fa phased_haplotypes.vcf.gz -G reads.gam > mapped.gam
----

Same as above, but manually pre-building the graph and all indexes, and providing the graph to define _basename_:

----
$ vg construct -a -r reference.fa -v phased_haplotypes.vcf.gz >reference.vg
$ vg index -G reference.gbwt -v phased_haplotypes.vcf.gz reference.vg
$ vg snarls --include-trivial reference.vg > reference.snarls
$ vg index -s reference.snarls -j reference.dist reference.vg
$ vg minimizer -k 29 -w 11 -g reference.gbwt -i reference.min reference.vg
$ vg gbwt -g reference.gg -x reference.vg reference.gbwt
$ vg gaffe -x reference.vg -G reads.gam > mapped.gam
----

== See Also
*vg*(1)

== Copyright

Copyright (C) 2020 {author}.

Free use of this documentation is granted under the terms of the MIT License.
