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:
1 parent
b132f0847f
commit
b55123a376
7 files changed
+49
-7
No files matched your search
@@ -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
|
||||
|
||||
@@ -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))
|
||||
|
||||
Reference in new issue
Block a user