feat: add --only-diploid flag to filter for diploid genotypes only

Introduce a new `--only-diploid` option that restricts analysis to genomes with one or two family members (base or two-base IUPAC codes), treating others as missing data. This complements the existing `--no-ambiguity` behavior by providing a stricter filter for diploid-compatible sites, while ensuring conflict detection between the two flags.

- Add `only_diploid` boolean argument to `PhyloArgs` in `src/obikmer/src/cmd/phylo/args.rs`, documenting its effect on pseudo-alignment and its conflict with `--no-ambiguity`.
- Propagate `only_diploid` through `SamplingSpec` in `src/obikmer/src/cmd/phylo/mod.rs` and update the `run` function signature to accept the new argument.
- Implement masking logic in `src/obikphylo/src/siblings/algorithms/masking.rs`: modify `masked_state` to accept `only_diploid`, add `only_diploid_keeps_up_to_two_members` helper, and update `genome_mask` documentation.
- Update `sample_layer` in `src/obikphylo/src/siblings/algorithms/subsample.rs` to use `spec.only_diploid` for masking decisions and update `SamplingSpec` documentation.
- Adjust `tally_2genomes` in `src/obikphylo/src/siblings/algorithms/snp_distance.rs` to pass the new `only_diploid` parameter to `masked_state`.
- Update `DevDocMD/theory/evolutionary_distances.md` to describe the new `--only-diploid` option, the `masked_state` rule (`count_ones() > 2`), and clarify toy index behavior.
- Update `UserDocMD/usage/phylo.md` to document `--only-diploid`, `--quartet`, and `--pair-balance` behaviors, clarifying that diploid choice is a convention and explaining how three/four-allele genomes are treated as missing.
This commit is contained in:
Eric Coissac committed 2026-11-09 20:58:21 +11:00
1 parent b132f0847f
commit b55123a376
7 files changed
+49 -7

No files matched your search

+11 -1
View File
@@ -2920,7 +2920,17 @@ diploid, single base `X` -> `X/X`, two-base code -> `X/Y`, `-` -> `*/*`, and
three/four-base codes or `?` -> `./.`. `REF` is the majority allele counting
each copy once (so a het contributes 1+1, a homozygote 2). Counting copies
for a real dosage (polyploids) would need k-mer counts (`--with-counts`),
not used by the pseudo-alignment scan today. Toy index: default mode 187
not used by the pseudo-alignment scan today. `--only-diploid` (selection option, `conflicts_with --no-ambiguity`) adds a
third `masked_state` rule: `count_ones() > 2` -> missing. It lives in
`SamplingSpec`/`masked_state`, i.e. the post-hoc masking and
`survives_masking`, so FASTA, Sankoff and `snp-*` see it too. The persisted
entropy/quartet/pair-weight/overlap annexes are keyed by the `no_ambiguity`
bool (two variants on disk); a third variant was not added: they are read
under `no_ambiguity = false`, which for the quartet pre-filter is a superset
of what survives the stricter masking (reasoned, not tested) and for the
entropy/pair-weight draw weights only changes the weighting. Unit-tested
(`masked_state`); the toy index has no 3/4-member cells, so the end-to-end
run is identical to the default mode. Toy index: default mode 187
lines, no `ALT = .`; `--no-ambiguity` 93 lines (the sites whose polymorphism
was only ambiguity codes disappear, since those cells became `?`).
+2 -1
View File
@@ -85,7 +85,7 @@ The `ID` column is a label that does not depend on the index at all: the family'
`REF` is the most frequent allele among the genomes at that site, each allele copy counted once (alphabetical order on ties); `ALT` lists the other observed bases in the order A, C, G, T. The bases are those of the family member's canonical form, exactly as in the FASTA, so they are not necessarily on the same strand as the `ID` k-mer.
The ploidy of the genotypes follows `--no-ambiguity`. Without it, a genome can carry several forms of the same family, which the FASTA shows as an IUPAC ambiguity code, and genotypes are diploid: a single base `X` is written `X/X` (for example `0/0`), a code standing for two bases is the heterozygote (`0/1`), with the allele indices always in ascending order. A code standing for three or four bases (or `N`) cannot be expressed as a diploid genotype and is written `./.`. With `--no-ambiguity`, such genomes are already treated as missing, so genotypes are haploid: a single index (`0`, `1`...), and `.` for a missing genome. The diploid choice is a convention, not a measurement: the file records which forms the genome carries, not how many copies of each, and a genome with two forms may equally well come from a heterozygous individual or from two similar regions of the same genome.
The ploidy of the genotypes follows `--no-ambiguity`; `--only-diploid` keeps the diploid genotypes and simply removes, before the sites are selected, the genomes whose cell would have needed three or four alleles (so no `./.` comes from them). Without it, a genome can carry several forms of the same family, which the FASTA shows as an IUPAC ambiguity code, and genotypes are diploid: a single base `X` is written `X/X` (for example `0/0`), a code standing for two bases is the heterozygote (`0/1`), with the allele indices always in ascending order. A code standing for three or four bases (or `N`) cannot be expressed as a diploid genotype and is written `./.`. With `--no-ambiguity`, such genomes are already treated as missing, so genotypes are haploid: a single index (`0`, `1`...), and `.` for a missing genome. The diploid choice is a convention, not a measurement: the file records which forms the genome carries, not how many copies of each, and a genome with two forms may equally well come from a heterozygous individual or from two similar regions of the same genome.
Without `--free-loss`, the absence of a family in a genome is a real state (a loss), written `-` in the FASTA. In the VCF it is the extra allele `*`, listed after the bases, so a genome lacking the family gets the genotype of `*` (`1/1` if `*` is the only alternative, `3/3` if `ALT` is `G,T,*`) and a site that differs only by presence/absence has `ALT` equal to `*`. With `--free-loss`, absence is treated as missing data instead and such genomes get a missing genotype. A site where no genome has a single base or a two-base code has no `REF` and is left out; the log line gives the number of sites written out of the number drawn.
@@ -94,6 +94,7 @@ Without `--free-loss`, the absence of a family in a genome is a real state (a lo
| `--n-sites N\|all` | none (mandatory here) | Number of families to draw, or `all` to use every variable family that passes the other filters, with no sampling. A number is a target, not a guarantee. |
| `--free-loss` | off | Treat a genome carrying none of a family's observed members as missing data (`?`) instead of `-` |
| `--no-ambiguity` | off | Treat a genome carrying more than one member of a family as missing data (`?`) instead of an IUPAC ambiguity code |
| `--only-diploid` | off | Milder than `--no-ambiguity` (the two cannot be combined): keep the genomes carrying one or two members of a family (a base, or a two-base IUPAC code such as `R`) and treat those carrying three or four as missing data (`?`) |
| `--quartet` | off | Keep only the families that can separate two pairs of genomes from each other: at least two distinct called states, each carried by at least two genomes. Which genomes count as carriers follows `--no-ambiguity` |
| `--pair-balance` | off | Favour the families covering the pairs of genomes that share the fewest families across the index, so that every pair is better represented in the sample. Which genomes count as carriers follows `--no-ambiguity` |
| `--sample-stats` | off | Write three CSV files describing what the draw contains (see "Describing a draw" below) |
+7
View File
@@ -309,6 +309,13 @@ pub struct PhyloArgs {
#[arg(long)]
pub no_ambiguity: bool,
/// In `--pseudo-alignment`, keep only the genomes carrying one or two
/// members of a family (a base, or a two-base IUPAC code) and treat the
/// others (three or four members) as missing data (`?`). Milder than
/// `--no-ambiguity`, which it excludes.
#[arg(long, conflicts_with = "no_ambiguity")]
pub only_diploid: bool,
/// In `--pseudo-alignment`/`--sankoff`/`snp-*` `--distance`, keep only
/// the families that can separate two pairs of genomes from each other
/// (a bipartition): at least two distinct called states, each carried
+1
View File
@@ -254,6 +254,7 @@ pub fn run(args: PhyloArgs) {
let sampling = SamplingSpec {
free_loss: args.free_loss,
no_ambiguity: args.no_ambiguity,
only_diploid: args.only_diploid,
quartet: args.quartet,
pair_balance: args.pair_balance,
entropy_bias,
@@ -23,15 +23,20 @@ use crate::siblings::helpers::is_carrier;
/// is one `genome_mask` entry (bit `b` set iff this genome carries the
/// family member whose own canonical central base is `b`; `0` = no member
/// present in this genome, `∅` — a real state on its own unless
/// `free_loss` says otherwise).
/// `free_loss` says otherwise). `only_diploid` is the milder sibling of
/// `no_ambiguity`: it keeps the genomes carrying one or two members (a base
/// or a two-base IUPAC code) and drops those carrying three or four.
#[inline]
pub(crate) fn masked_state(m: u8, free_loss: bool, no_ambiguity: bool) -> Option<u8> {
pub(crate) fn masked_state(m: u8, free_loss: bool, no_ambiguity: bool, only_diploid: bool) -> Option<u8> {
if free_loss && m == 0 {
return None; // absence -> missing, not a real state
}
if no_ambiguity && m.count_ones() > 1 {
return None; // ambiguous (>1 member in this genome) -> missing
}
if only_diploid && m.count_ones() > 2 {
return None; // more than a heterozygote's two members -> missing
}
Some(m)
}
@@ -222,7 +227,19 @@ mod tests {
/// `subsample::sample_layer` does once, up front, before calling
/// [`survives_masking`].
fn masked(raw: &[u8], free_loss: bool, no_ambiguity: bool) -> Vec<Option<u8>> {
raw.iter().map(|&m| masked_state(m, free_loss, no_ambiguity)).collect()
raw.iter().map(|&m| masked_state(m, free_loss, no_ambiguity, false)).collect()
}
#[test]
fn only_diploid_keeps_up_to_two_members() {
let m = |raw: u8| masked_state(raw, false, false, true);
assert_eq!(m(0b0000), Some(0)); // absence stays a state (no --free-loss)
assert_eq!(m(0b0100), Some(0b0100));
assert_eq!(m(0b0101), Some(0b0101)); // R
assert_eq!(m(0b0111), None); // V
assert_eq!(m(0b1111), None); // N
// the stricter flag wins when both are set
assert_eq!(masked_state(0b0101, false, true, true), None);
}
#[test]
@@ -279,7 +279,7 @@ mod tests {
/// something these tests need to exercise).
fn tally_2genomes(pairs: &[(u8, u8)], n_shared: usize) -> PairwiseTally {
// No masking requested (`free_loss = no_ambiguity = false`) —
// `masked_state(m, false, false)` is always `Some(m)`, so the raw
// `masked_state(m, false, false, false)` is always `Some(m)`, so the raw
// mask is exactly what `subsample::sample_layer` would have
// computed here.
let mut families = Vec::new();
@@ -110,6 +110,12 @@ pub struct EntropyBias {
pub struct SamplingSpec {
pub free_loss: bool,
pub no_ambiguity: bool,
/// `--only-diploid`: like `no_ambiguity` but only genomes carrying three
/// or four members of a family become missing. Applied by the post-hoc
/// masking only — the persisted entropy/quartet/pair-weight annexes are
/// read under the `no_ambiguity` convention (`false` here), which is a
/// superset for the quartet pre-filter and only a weight otherwise.
pub only_diploid: bool,
pub quartet: bool,
/// `--pair-balance`: weight each family by the mean, over the pairs of
/// genomes carrying it, of 1 / (number of families the pair shares), so
@@ -488,7 +494,7 @@ fn sample_layer(
);
let masked: Vec<Option<u8>> = genome_mask
.iter()
.map(|&m| masked_state(m, spec.free_loss, spec.no_ambiguity))
.map(|&m| masked_state(m, spec.free_loss, spec.no_ambiguity, spec.only_diploid))
.collect();
if survives_masking(&masked, excluded)
&& (!spec.quartet || survives_quartet(&masked, excluded))