Repository navigation
Add vg unitigs: cover the haplotype k-mers of a graph with walks - #5109
Open
glennhickey wants to merge 1 commit into
Open
glennhickey wants to merge 1 commit into
glennhickey wants to merge 1 commit into
Conversation
A linear k-mer tool cannot read a graph, and running it on every haplotype reads the shared sequence once per haplotype. vg unitigs writes a set of graph walks whose sequences spell every k-mer the haplotypes spell, each exactly once, so a scan of the output sees what a scan of all the haplotypes would. A k-mer here is a haplotype-consistent walk spelling k bases, so the same sequence in two places is two k-mers. A unitig is a maximal chain of k-mers in which each has one successor, that successor has one predecessor, and no haplotype begins or ends in between. Every k-mer lies in exactly one unitig, and a unitig is a substring of every haplotype holding any of its k-mers, so its support is one number. With --gref the k-mers that lie along a single gref path are left out, since the gref sequence already spells them, and what remains are the junction tigs. The gref paths and the tigs together are a cover: FASTA a linear tool can scan in place of the haplotypes, with --gaf giving each tig's walk for mapping the results back. Two supporting pieces come with it. WalkInterval (walk_interval.hpp) is a walk with offsets into its first and last node, which is what a tig is, and it can spell its sequence, extend, and cut. GrefIndex (gref.hpp) indexes a gref's paths so a walk can be placed on them: it answers which gref contig a visit lies on, at what coordinate and orientation, and whether that contig is the reference or an alt. A tig carries that placement, which is how the cover reports where it came from. GrefIndex::find_path() keyed its bracketed names, NAME[START] and NAME[START-END], off a start above 0, so it could not find a path whose subrange began at 0. A GBWT keeps a subrange's start in the count field of the path name and reads it back only when it is nonzero, so such a path arrives indistinguishable from one covering a whole contig, while a tool that read it still writes NAME[0-END] for what it found. The bracketed names now go in for every path. Some of the API this adds is used by vg lift in the PR that follows, not here: GrefCover::read_top_level_snarls(), GrefIndex::interval(), find_path() and GrefPlacement::along_one_path, the before/after arguments of GrefIndex::place(), and parse_gaf_columns()/parse_walk() in walk_interval.hpp. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A linear k-mer tool cannot read a graph, and running it on every haplotype reads the shared sequence once per haplotype.
vg unitigswrites graph walks whose sequences spell every k-mer the haplotypes spell, each once, so scanning the output sees what scanning all the haplotypes would.A k-mer here is a haplotype-consistent walk spelling k bases, so the same sequence in two places is two k-mers. A unitig is a maximal chain of k-mers in which each has one successor, that successor has one predecessor, and no haplotype begins or ends in between. Every k-mer lies in exactly one unitig, and a unitig is a substring of every haplotype holding any of its k-mers, so its support is one number.
With
--grefthe k-mers along a single gref path are left out, since the gref sequence already spells them, and what remains are the junction tigs. The gref paths and the tigs together are a cover: FASTA a linear tool can scan in place of the haplotypes, with--gafgiving each tig's walk for mapping results back.Two supporting pieces come with it:
WalkInterval(walk_interval.hpp) is a walk with offsets into its first and last node, which is what a tig is. It spells its sequence, extends and cuts.GrefIndex(gref.hpp) indexes a gref's paths so a walk can be placed on them: which gref contig a visit lies on, at what coordinate and orientation, and whether that contig is the reference or an alt.GrefIndex::find_path()keyed its bracketed names,NAME[START]andNAME[START-END], off a start above 0, so it could not find a path whose subrange began at 0. A GBWT keeps a subrange's start in thecountfield of the path name and reads it back only when it is nonzero, so such a path arrives indistinguishable from one covering a whole contig, while a tool that read it still writesNAME[0-END]for what it found. The bracketed names now go in for every path.Some of the API lands here but is called by
vg liftin the PR stacked on this one, not by anything here:GrefCover::read_top_level_snarls(),GrefIndex::interval(),find_path(),GrefPlacement::along_one_path, thebefore/afterarguments ofGrefIndex::place(), andparse_gaf_columns()/parse_walk().Tested on macOS:
make -j8clean,scripts/lint.pyclean, andprove t/58_vg_unitigs.t t/11_vg_paths.tgreen (155 assertions).58_vg_unitigs.tpins unitig counts and lengths for a triallelic SNP, k-mer set equality and disjointness against the paths with and without a gref, support values, placement strings for an insertion, a SNP, a deletion and an inversion, thread-count invariance, and the unsupported-gref warning.🤖 Generated with Claude Code