Skip to content
Open
Show file tree
Hide file tree
Changes from 9 commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
db7fbd1
vg call: refuse --top-down and -Y with --read-likelihood
benedictpaten Oct 29, 2026
48e81d5
vg call: add --group-candidates, which lets groups of a site's walks …
benedictpaten Oct 29, 2026
80a25b0
vg call: turn --group-candidates on by default, and add --no-group-ca…
benedictpaten Oct 29, 2026
2ad02fa
vg call: keep two TAP tests of grouped walks, on reads where grouping…
benedictpaten Oct 29, 2026
ce5c000
vg call: test a child chain that one strand of a grouped parent crosses
benedictpaten Oct 29, 2026
ec9cb73
vg call: re-genotype each read-linked run in its own frame
benedictpaten Nov 5, 2026
c06c52e
vg call: weigh the panel's phase by its fitted error rates
benedictpaten Nov 8, 2026
0d3f87c
vg call: count each read once in a hung site's vote
benedictpaten Nov 8, 2026
f924614
Merge vgteam/vg master into group-candidates
benedictpaten Nov 8, 2026
60adde5
vg call: document mapping without the reference, for the mosaic and a…
benedictpaten Nov 16, 2026
298ecfe
vg call: read the grouped-walk test records with cut, and fix its MAP…
benedictpaten Nov 16, 2026
5cdc448
vg call: anchor file version 10, with a kind column and ranked pin so…
benedictpaten Nov 17, 2026
93cef84
vg call: fill anchors at evenly spaced points inside unbranched node …
benedictpaten Nov 17, 2026
d64ceeb
vg call: document fill anchors, and test them on the command line
benedictpaten Nov 17, 2026
808cf76
vg call: fill anchors take their slot from the innermost genotyped site
benedictpaten Nov 17, 2026
3b36c7f
vg call: tally the fill anchors' fetches apart, and test fill anchors…
benedictpaten Nov 17, 2026
bccdd1e
vg call: say why fill anchors in repeats hold more misplaced reads th…
benedictpaten Nov 17, 2026
1d9ac91
vg call: build each site's anchors over the alleles its line wrote
benedictpaten Nov 17, 2026
8d3cc33
vg call: place the fill anchors' reads from the windows the direct pa…
benedictpaten Nov 17, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 45 additions & 14 deletions artifacts/allele_likelihood.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -149,6 +149,12 @@ vector<double> AlleleReadLikelihoods::mixture_weights(const vector<int>& genotyp
}

double AlleleReadLikelihoods::genotype_likelihood(const vector<int>& genotype) const {
return genotype_likelihood(genotype, matrix);
}

double AlleleReadLikelihoods::genotype_likelihood(const vector<int>& genotype,
const vector<double>& rows,
bool with_depth) const {
if (genotype.empty()) {
return 0.0;
}
Expand All @@ -165,7 +171,7 @@ double AlleleReadLikelihoods::genotype_likelihood(const vector<int>& genotype) c
if (allele < 0 || (size_t)allele >= n_alleles) {
continue;
}
mixture += weights[i] * rel(r, (size_t)allele);
mixture += weights[i] * rows.at(r * n_alleles + (size_t)allele);
}

// Mix in the chance that the read is mismapped, in which case its likelihood is the row
Expand All @@ -174,16 +180,19 @@ double AlleleReadLikelihoods::genotype_likelihood(const vector<int>& genotype) c
total += log((1.0 - e_r) * mixture + e_r);
}

if (uses_depth_term()) {
// Add ln of the tempered density f^beta / Z_beta at the observed count, with beta the
// depth weight. Z_beta grows with lambda when beta < 1, so without it we would favour
// the genotypes that expect more reads.
double lambda = expected_reads(genotype);
total += depth_weight * ln_poisson_pmf(observed_reads(), lambda)
- ln_tempered_poisson_normaliser(lambda, depth_weight);
}
return with_depth ? total + depth_term(genotype) : total;
}

return total;
double AlleleReadLikelihoods::depth_term(const vector<int>& genotype) const {
if (!uses_depth_term()) {
return 0.0;
}
// Take ln of the tempered density f^beta / Z_beta at the observed count, with beta the depth
// weight. Z_beta grows with lambda when beta < 1, so without it we would favour the genotypes
// that expect more reads.
double lambda = expected_reads(genotype);
return depth_weight * ln_poisson_pmf(observed_reads(), lambda)
- ln_tempered_poisson_normaliser(lambda, depth_weight);
}

double AlleleReadLikelihoods::achievable_gap(const vector<int>& called,
Expand Down Expand Up @@ -278,9 +287,32 @@ vector<vector<int>> AlleleReadLikelihoods::enumerate_genotypes(size_t num_allele
}

vector<pair<vector<int>, double>> AlleleReadLikelihoods::score_genotypes(int ploidy) const {
return score_genotypes(enumerate_genotypes(n_alleles, ploidy));
}

vector<pair<vector<int>, double>> AlleleReadLikelihoods::score_genotypes(
const vector<vector<int>>& genotypes, const vector<int>* group_of, bool with_depth) const {
assert(group_of == nullptr || group_of->size() == n_alleles);
// With groups, give each read's entry for an allele the read's best entry in the allele's
// group.
vector<double> shared;
if (group_of != nullptr && n_alleles > 0) {
shared.resize(matrix.size());
vector<double> best(*std::ranges::max_element(*group_of) + 1);
for (size_t r = 0; r < n_reads; ++r) {
std::ranges::fill(best, 0.0);
for (size_t a = 0; a < n_alleles; ++a) {
best[(*group_of)[a]] = max(best[(*group_of)[a]], rel(r, a));
}
for (size_t a = 0; a < n_alleles; ++a) {
shared[r * n_alleles + a] = best[(*group_of)[a]];
}
}
}
const vector<double>& rows = group_of != nullptr ? shared : matrix;
vector<pair<vector<int>, double>> scored;
for (auto& genotype : enumerate_genotypes(n_alleles, ploidy)) {
double ll = genotype_likelihood(genotype);
for (auto& genotype : genotypes) {
double ll = genotype_likelihood(genotype, rows, with_depth);
scored.emplace_back(genotype, ll);
}
return scored;
Expand Down Expand Up @@ -2068,8 +2100,7 @@ void GraphAlignedAlleleLikelihoodCalculator::score_row(
for (size_t a = 0; a < alleles.steps.size(); ++a) {
const vector<AlleleStep>& steps = alleles.steps[a];
if (steps.empty()) {
// An allele with no visits, such as the empty traversal of a star allele, cannot place
// the read.
// An allele with no visits cannot place the read.
row[a] = -numeric_limits<double>::infinity();
continue;
}
Expand Down
18 changes: 16 additions & 2 deletions artifacts/allele_likelihood.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -91,8 +91,7 @@ class AlleleReadLikelihoods {
* Get the likelihood of read r under allele a, relative to the best allele of read r.
*
* It is 0 where allele a fits the read so much worse than the best that the ratio
* underflows. It is also 0 where allele a has no node visits, as the empty traversal of a
* star allele has, and cannot place the read.
* underflows. It is also 0 where allele a has no node visits, and so cannot place the read.
*/
double rel(size_t r, size_t a) const;

Expand Down Expand Up @@ -182,6 +181,9 @@ class AlleleReadLikelihoods {
return depth.expected_reads(genotype);
}

/// Return the depth term of `genotype` in `genotype_likelihood`, or 0 when the term is off.
double depth_term(const vector<int>& genotype) const;

/// Return whether `set_depth_context` has supplied traversal lengths.
bool has_depth_context() const { return !depth.lengths.empty(); }

Expand Down Expand Up @@ -274,6 +276,13 @@ class AlleleReadLikelihoods {
/// Return `genotype_likelihood` for every genotype of this ploidy, in VCF GL order.
vector<pair<vector<int>, double>> score_genotypes(int ploidy) const;

/// Return `genotype_likelihood` for each of `genotypes`, in their order. With `group_of`, the
/// relative likelihood of each read for an allele is its best over the allele's group. With
/// `with_depth` false, each score leaves out the depth term.
vector<pair<vector<int>, double>> score_genotypes(const vector<vector<int>>& genotypes,
const vector<int>* group_of = nullptr,
bool with_depth = true) const;

/// Write the matrix as TSV for debugging, with one line per read.
void dump(ostream& out, const string& site_name) const;

Expand Down Expand Up @@ -325,6 +334,11 @@ class AlleleReadLikelihoods {
/// Set N in `depth` from the reads and from whether they count as 1 - e_r.
void count_observed();

/// Return `genotype_likelihood` with `rows` in place of the relative likelihoods. `rows` is
/// row major, n_reads * n_alleles. Leave out the depth term when `with_depth` is false.
double genotype_likelihood(const vector<int>& genotype, const vector<double>& rows,
bool with_depth = true) const;

/// The anchor evidence of the site, or null.
unique_ptr<AnchorSiteEvidence> anchor_evidence;
/// The read-phasing evidence of the site, or null.
Expand Down
3 changes: 1 addition & 2 deletions artifacts/doc/read-likelihood-architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -85,8 +85,7 @@ but phasing is not written (`--no-phased`), the `PhaseTable` stays empty, so rea
re-genotyping do nothing, and nested calling is off. Without nested calling, `DescentPolicy` lists
no children. By default, `SiteWalker` walks the children of a top-level site that cannot be
genotyped as top-level sites; `--all-snarls` makes it walk the children of every site, and turns
nested calling off. `--top-down` makes `TreeGenotyper` genotype each child against the traversals
its parent's called alleles allow, and `SiteWalker` walk no children.
nested calling off.

The linkage pass drops a child that no allele of its parent's chosen genotype crosses, and can
bring back a child that an earlier linkage pass dropped. A child whose parent has too many
Expand Down
82 changes: 81 additions & 1 deletion artifacts/doc/read-likelihood-direct-genotyping.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,9 @@ own, from the site's reads. For each genotype $G$ that the site could have, it c
genotype's **site likelihood** $\mathcal{L}(G)$, a number that measures how well $G$ explains the
reads. The genotype with the highest site likelihood is the site's **direct call**. No prior over
genotypes is applied, so the direct call is the maximum-likelihood genotype (ties are broken as
[Direct genotype](read-likelihood-genotyping.md#direct-genotype) says).
[Direct genotype](read-likelihood-genotyping.md#direct-genotype) says). Where the site's candidate
alleles have groups, the grouped likelihood takes the place of the site likelihood (see
[Groups of alleles](#groups-of-alleles)).

Direct genotyping hands the rest of the caller the site likelihood of every genotype, the direct
call, and two kinds of value for each of the site's reads: its mismapping probability, and one
Expand Down Expand Up @@ -118,6 +120,15 @@ error that follows.
| $U_i(G)$ | at ploidy 2, the length in bases of the nodes that $g_i$ visits and the other allele of $G$ does not, each node counted once |
| $\bar L$ | the mean length of the reads that begin in the site's rate window (see [Depth term inputs](#depth-term-inputs)) |
| $\kappa$ | the read-start rate: the expected number of correctly mapped reads that begin at each base of one haplotype near the site |
| $\gamma, \gamma'$ | groups of candidate alleles (see [Groups of alleles](#groups-of-alleles)) |
| $\gamma(a)$ | the group of allele $a$ |
| $X, X'$ | multisets of groups |
| $\mathrm{own}(G)$, $\mathrm{shared}(G)$ | the own and shared scores of $G$; of a multiset $X$, the best of its genotypes' scores |
| $\mathrm{own}_R$, $\mathrm{shared}_R$ | the own and shared scores without the depth term |
| $\Delta(X)$ | the gain of $X$: $\mathrm{shared}_R(X) - \mathrm{own}_R(X)$ |
| $X \oplus \gamma$ | $X$ with one more copy of the group $\gamma$ |
| $c(X)$ | the charge of $X$ |
| $\tilde{\mathcal{L}}(G)$ | the grouped likelihood of $G$ |

## Likelihood formula

Expand Down Expand Up @@ -366,6 +377,75 @@ the haplotype and still include some of the interior of $g_i$. When $g_i$ has no
($T_{g_i} = 0$), it is the number of positions from which a read reaches across the junction
between the two boundary nodes.

## Groups of alleles

The candidate alleles of a site can have **groups**: sets of alleles that take one route through
the site and differ only inside child chains (see
[Choosing among alleles that differ inside child chains](read-likelihood-genotyping.md#choosing-among-alleles-that-differ-inside-child-chains)).
Where they do, the groups choose the site's genotype, and the alleles choose within the chosen
groups. vg does this by giving each genotype a **grouped likelihood** $\tilde{\mathcal{L}}(G)$,
which takes the place of $\mathcal{L}(G)$. This section builds it from two scores of each multiset
of groups, and a charge on each multiset.

### Shared and own scores

$\gamma(a)$ is the group of allele $a$. A genotype's **multiset of groups** holds the group of each
of its alleles. Each genotype $G$ has two scores:

- its **own score**, $\mathrm{own}(G) = \ln \mathcal{L}(G)$;
- its **shared score**, $\mathrm{shared}(G)$, which is $\ln \mathcal{L}(G)$ with each relative
likelihood $p_{r g_i}$ replaced by $\max_{b \in \gamma(g_i)} p_{rb}$, the read's best relative
likelihood over the allele's group.

The shared score lets each read choose its allele within each copy of a group. A multiset $X$ of
groups takes the best of each score over the genotypes whose multiset of groups is $X$:
$\mathrm{own}(X)$ is the best own score among them, and $\mathrm{shared}(X)$ the best shared score.
$\mathrm{own}_R$ and $\mathrm{shared}_R$ are the same scores without the [depth term](#depth-term).

### Charge

The **gain** $\Delta(X) = \mathrm{shared}_R(X) - \mathrm{own}_R(X)$ is how much better the reads fit
when each read chooses its allele within each copy of a group. The gain measures how the reads fit
the alleles, so it leaves out the depth term, which scores only the number of reads. The choice is
right where a haplotype is a mosaic of the alleles of a group, and wrong where one copy of a group
carries the reads of two haplotypes. To tell the two apart, vg scores $X \oplus \gamma$, which is
$X$ with one more copy of one of its groups $\gamma$ of two or more alleles, at ploidy $P + 1$. A
copy that carried the reads of a second haplotype hands them to the new copy, so the gain drops.
One more allele of the group does not spell a mosaic either, so a mosaic should lose less of its
gain, though how much it keeps depends on the reads. The **charge** of $X$ is the largest drop,

$$
c(X) = \max\left(0,\ \max_{\gamma} \left[\Delta(X) - \Delta(X \oplus \gamma)\right]\right)
$$

with $\gamma$ over the groups of $X$ that have two or more alleles. A multiset with no such group
has a charge of 0.

### Scores at one more copy

The number of genotypes at ploidy $P + 1$ grows with the cube of the number of alleles at a diploid
site, so vg scores $X \oplus \gamma$ from fewer genotypes. For each group $\gamma'$ of two or more
alleles that $X \oplus \gamma$ holds at least twice, removing one copy of $\gamma'$ from
$X \oplus \gamma$ gives a multiset $X'$ at ploidy $P$. $X'$ has a best genotype by
$\mathrm{shared}_R$ and a best by $\mathrm{own}_R$, the first in VCF `GL` order over the candidate
alleles where genotypes tie. Adding any one allele of $\gamma'$ to either of them gives a genotype of $X \oplus \gamma$.
$\mathrm{shared}_R(X \oplus \gamma)$ and $\mathrm{own}_R(X \oplus \gamma)$ are the best scores over
all the genotypes made this way.

### Grouped likelihood

A genotype $G$ whose multiset of groups is $X$ has the grouped likelihood

$$
\ln \tilde{\mathcal{L}}(G) = \mathrm{shared}(X) - c(X) - \left(\mathrm{own}(X) - \ln \mathcal{L}(G)\right)
$$

The highest grouped likelihood goes to the genotype with the highest $\mathcal{L}(G)$ in the
multiset with the highest $\mathrm{shared}(X) - c(X)$. The runner-up, whose gap to the best sets
`GQ`, is either the next genotype of that multiset or the best genotype of the next multiset.
A genotype with $\mathcal{L}(G) = 0$ has $\tilde{\mathcal{L}}(G) = 0$. Where the alleles form one
group, $\tilde{\mathcal{L}}(G) = \mathcal{L}(G)$.

## Computing the terms

The read term needs, for each read of the site, its relative likelihoods and its mismapping
Expand Down
Loading
Loading