Input graphs and indexes

Graphs

Stoat accepts graphs that implement the handlegraph interface from libhandlegraph. Specifically, it can use .hg and .pg formats from libbdsg, and .gbz format from gbwtgraph. GBZ format is generally more efficient when there are many haplotype paths in the graph. Stoat does not accept graphs in .gfa format, but conversion between formats is possible using the vg format.

Note that converting to GBZ format may change the node id space.

GFA to PG

vg convert -p -g {graph-base}.gfa > {graph-base}.pg

GFA to HG

vg convert -a -g {graph-base}.gfa > {graph-base}.hg

GFA to GBZ

vg gbwt --gbz-format -g {GRAPH_BASE}.gbz -G ${GRAPH_BASE}.gfa

HG/PG to GBZ

vg gbwt -x {graph-base}.[hg|pg] -E --gbz-format -g {graph-base}.gbz

GBZ to HG

vg convert -a {graph-base}.gbz > {graph-base}.hg

Graph path manipulation

It is sometimes necessary to specify a reference sample for a graph. Output coordinates will be given on the reference sample.

To find out which samples are present in the graph and the senses of their paths, first list all paths in the graph:

vg paths -M -x {graph-base}.[hg|pg|gbz]

Each path will have a sense of either REFERENCE, HAPLOTYPE, or GENERIC. Note that reference coordinates are only given relative to REFERENCE- or GENERIC-sense paths. A locus/sample can be promoted form GENERIC to HAPLOTYPE sense, and from HAPLOTYPE to REFERENCE sense.

For a pg or hg, a path can be promoted from GENERIC to HAPLOTYPE sense with:

vg convert --hap-locus [locus] --new-sample [locus] {graph-base}.[hg|ph] > {graph-base}.hap.vg

This will take the generic paths with the given locus and make them haplotype paths, with the locus name as the sample name. Then promote a path from HAPLOTYPE to REFERENCE sense with:

vg convert --ref-sample [sample] {graph-base}.[hg|pg|hap.vg] > {graph-base}.ref.vg

Then convert back to hash- or packed-graph format and replace the original graph.

For a gbz, convert a HAPLOTYPE sense path to REFERENCE sense with:

vg gbwt --set-tag "reference_samples={sample}" --gbz-format -g {graph-base}.ref.gbz -Z ${GRAPH_BASE}.gbz

See the wiki for more details

Snarl decomposition / distance index

Stoat depends on the snarl decomposition of the graph, which is stored as part of the distance index. Distances are not required in the index, but including them can speed up stoat graph because it allows snarls to be filtered based on size.

Get the snarls without distances

vg index -j {graph-base}.nodist.dist --snarl-limit 0 {graph-base}.[pg|hg|gbz]

Get the snarls and distances

vg index -j {graph-base}.dist {graph-base}.[pg|hg|gbz]

The snarl decomposition can sometimes be confounded by complex graphs, resulting in non-intuitive snarls that don't resemble real variants. To force the the snarls to be more regular, we can provide hints to the indexer about where the snarl tree should be rooted.

vg index -j {graph-base}.dist $(python3 indexing_scripts/get_snarl_backbone_nodes.py {graph-base}.[pg|hg]) {graph-base}.[pg|hg|gbz]