Linear references and vg

While vg is built around pangenome variation graphs, in some cases you may need linear references as part of your analysis. This page covers a few such useful operations.

• Extract a FASTA from a graph
• Convert a FASTA file into a single-haplotype "stick" graph
• Extract a single-haplotype "stick" graph from a larger graph

Extract a FASTA from a graph

Graph references often contain linear references within them, which you might want copies of for, for example, calling variants with a linear-reference-based caller like Google's DeepVariant. If you don't already have a FASTA file for an assembly that is included in a graph, you can use vg to extract the assembly FASTA directly from the graph, like this:

vg paths --extract-fasta -x ./graphs/rgfa_with_reference.rgfa --paths-by GRCh38

Here, the argument to -x should be the graph file, in rGFA, GFA, .vg, .gbz, or any other graph file format that vg can read (see File Types). The argument to --paths-by should be the prefix of the set of paths you would like to extract; generally you can use a sample or assembly name here. You can use vg paths --list -x <the graph> to get a list of all paths available.

This will produce a FASTA file on standard output. To save it to a file, you can redirect the output with >.

>GRCh38#0#chr1
GGGGTACA

In most cases, the sequence names in the FASTA will be in PanSN format (see Path Metadata Model); these will match the names used by vg surject, and so a FASTA extracted like this is easy to use with a BAM file produced by vg surject.

If you are interested in extracting haplotype paths from a .gbwt file, you can pass the .gbwt file with the -g option to vg paths, and the corresponding .gg file or any matching graph with -x.

Convert a FASTA file into a single-haplotype "stick" graph

You can go the other direction as well. For some comparisons, it's useful to have vg's mappers align to a "pangenome" graph consisting of a single haplotype with no variants. This means using a simplified version of the normal graph construction process. By default vg construct will try to make the entire haplotype into a single node as there are no variants to break it up. Note the -m 1024: chopping long nodes makes it possible to index the graph.

# Run within vg's "test" directory
# Create VG format graph
vg construct -r ./small/x.fa -m 1024 > x.vg
# Create GBWT index
vg gbwt -o x.gbwt --index-paths -x x.vg
# Create GBZ for vg autoindex/giraffe
vg gbwt -g x.gbz -x x.vg x.gbwt

This GBZ can then be input into vg autoindex and used for any downstream applications within vg's ecosystem.

Extract a single-haplotype "stick" graph from a larger graph

If you already have a bigger graph and just want to cut it down to a single haplotype (essentially doing manual Haplotype Sampling) then it's easy to extract that sub-graph.

vg paths --retain-paths -x ./graphs/rgfa_with_reference.rgfa --paths-by GRCh38

Standard output:

H       VN:Z:1.1        RS:Z:GRCh38
S       1       G
S       2       A
S       4       GGG
S       5       T
S       6       A
S       7       C
S       8       A
S       9       A
L       1       +       4       +       0M
L       1       +       2       +       0M
L       2       +       4       +       0M
L       4       +       5       +       0M
L       5       +       6       +       0M
L       6       +       8       +       0M
L       6       +       7       +       0M
L       7       +       9       +       0M
L       8       +       9       +       0M
W       GRCh38  0       chr1    0       8       >1>4>5>6>7>9

You can get a similar result by extracting a FASTA (first section) and then converting that into a graph (second section), but this method 1) requires less steps and 2) preserves original node IDs.