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

+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))