docs: clarify VCF pseudo-alignment format and update obikmer dependency
ci.yml / build (pull_request) Successful in 3m40s
Release / create-release (push) Successful in 1m7s
Release / build-macos-arm64 (push) Successful in 1m52s
Release / build-linux-x86_64 (push) Successful in 6m41s

Update the VCF export documentation to reflect that `-` represents an overlapping deletion (extra allele `*`) and introduce the `<ABS>` symbolic allele for absent families. Add a new dedicated documentation file for the VCF pseudo-alignment format, remove obsolete descriptions from phylo.md, and fix benchmark scripts to handle errors and directory creation correctly.

- Update `obikmer` dependency from 1.4.1 to 1.4.2 in Cargo.toml and Cargo.lock
- Add `UserDocMD/formats/vcf.md` describing VCF pseudo-alignment structure, alleles, and genotypes
- Remove obsolete VCF descriptions from `UserDocMD/usage/phylo.md` and update ploidy/free-loss notes
- Update `DevDocMD/theory/evolutionary_distances.md` to clarify `-` as overlapping deletion and `<ABS>` for others
- Fix `benchmark/index_one_count.sh` to create index directory and check read command errors
- Fix `benchmark/index_one_presence.sh` to create index directory and check simulation errors
- Update `src/obikphylo/src/siblings/algorithms/alignment_vcf.rs` to use `<ABS>` for absent families instead of `*`
This commit is contained in:
Eric Coissac committed 2026-11-09 20:59:28 +11:00
1 parent 5368c98875
commit 0134c69cf4
9 files changed
+156 -34

No files matched your search

+1 -1
View File
@@ -1537,7 +1537,7 @@ dependencies = [
[[package]]
name = "obikmer"
version = "1.4.1"
version = "1.4.2"
dependencies = [
"clap",
"csv",
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "obikmer"
version = "1.4.1"
version = "1.4.2"
edition = "2024"
[[bin]]
@@ -12,11 +12,13 @@
//! central base of the family member's *canonical* form, which is not
//! necessarily the strand of the `ID` k-mer. A `-` cell (family absent from
//! the genome — a real state, unlike `?`, which `--free-loss` produces and
//! which means missing) is the extra allele `*`, listed after the bases.
//! which means missing) is the symbolic allele `<ABS>`, declared by a `##ALT`
//! line and listed after the bases. (`*` is not used: in VCF it means an
//! allele missing because of an overlapping deletion.)
//!
//! Ploidy of the genotypes is a caller choice. Haploid: one allele per
//! genome; an ambiguous cell is missing. Diploid: a single base `X` is
//! `X/X`, a two-base code is the heterozygote, `*` is `*/*`; codes with
//! `X/X`, a two-base code is the heterozygote, `<ABS>` is `<ABS>/<ABS>`; codes with
//! three or four bases (and `?`) are missing (`./.`). In both modes a
//! genome gets the allele indices in ascending order.
@@ -29,18 +31,25 @@ use super::masking::iupac_state;
const BASES: [u8; 4] = *b"ACGT";
/// Internal marker of the absence allele (the alignment's own `-`), written
/// as [`ABSENT_ALT`].
const ABSENT: u8 = b'-';
/// How the absence allele appears in the `ALT` column.
const ABSENT_ALT: &[u8] = b"<ABS>";
fn base_index(cell: u8) -> Option<usize> {
BASES.iter().position(|&b| b == cell)
}
/// One cell as alleles: `None` = missing; else its (one or, diploid, two)
/// allele characters — a base, or `*` for absence. A cell with more forms
/// allele characters — a base, or [`ABSENT`] for absence. A cell with more forms
/// than the ploidy allows, or `?`, is missing.
fn cell_alleles(cell: u8, diploid: bool) -> Option<[u8; 2]> {
let state = iupac_state(cell)?;
let allele = |bit: u8| if bit == 0 { b'*' } else { BASES[bit.trailing_zeros() as usize] };
let allele = |bit: u8| if bit == 0 { ABSENT } else { BASES[bit.trailing_zeros() as usize] };
match state.count_ones() {
0 => Some([b'*', b'*']),
0 => Some([ABSENT, ABSENT]),
1 => Some([allele(state), allele(state)]),
2 if diploid => {
let low = state & state.wrapping_neg();
@@ -89,6 +98,7 @@ impl SnpAlignment {
last = Some((s.partition, s.layer));
}
}
writeln!(out, "##ALT=<ID=ABS,Description=\"Family absent from the genome\">")?;
writeln!(out, "##FORMAT=<ID=GT,Number=1,Type=String,Description=\"Genotype ({})\">", if diploid { "diploid" } else { "haploid" })?;
write!(out, "#CHROM\tPOS\tID\tREF\tALT\tQUAL\tFILTER\tINFO\tFORMAT")?;
for &g in &self.genome_indices {
@@ -119,7 +129,7 @@ impl SnpAlignment {
let mut alleles = vec![BASES[ref_base]];
alleles.extend((0..4).filter(|&b| b != ref_base && counts[b] > 0).map(|b| BASES[b]));
if absent {
alleles.push(b'*');
alleles.push(ABSENT);
}
let s = &self.sites[j];
@@ -135,7 +145,11 @@ impl SnpAlignment {
if i > 0 {
out.write_all(b",")?;
}
out.write_all(&[a])?;
if a == ABSENT {
out.write_all(ABSENT_ALT)?;
} else {
out.write_all(&[a])?;
}
}
}
out.write_all(b"\t.\t.\t.\tGT")?;
@@ -208,16 +222,16 @@ mod tests {
}
#[test]
fn absence_is_a_star_allele_after_the_bases() {
// A, T, - (family absent), ? (missing): REF=A, ALT=T,*.
fn absence_is_the_abs_allele_after_the_bases() {
// A, T, - (family absent), ? (missing): REF=A, ALT=T,<ABS>.
let a = alignment(&[b"A", b"T", b"-", b"?"], vec![site(0, 0, 0)]);
let f = first_record(&a);
assert_eq!(&f[3..5], ["A", "T,*"]);
assert_eq!(&f[3..5], ["A", "T,<ABS>"]);
assert_eq!(&f[9..], ["0", "1", "2", "."]);
// Only presence/absence differs: REF=A, ALT=*.
// Only presence/absence differs: REF=A, ALT=<ABS>.
let a = alignment(&[b"A", b"-"], vec![site(0, 0, 0)]);
let f = first_record(&a);
assert_eq!(&f[3..5], ["A", "*"]);
assert_eq!(&f[3..5], ["A", "<ABS>"]);
assert_eq!(&f[9..], ["0", "1"]);
}
@@ -234,8 +248,8 @@ mod tests {
// A, R (A/G), G, N (4 forms -> missing), - (absent), ? (missing).
let a = alignment(&[b"A", b"R", b"G", b"N", b"-", b"?"], vec![site(0, 0, 0)]);
let f = first_record_ploidy(&a, true);
// majority: A = 2 + 1 = 3, G = 1 + 2 = 3 -> tie -> A; ALT = G,*
assert_eq!(&f[3..5], ["A", "G,*"]);
// majority: A = 2 + 1 = 3, G = 1 + 2 = 3 -> tie -> A; ALT = G,<ABS>
assert_eq!(&f[3..5], ["A", "G,<ABS>"]);
assert_eq!(&f[9..], ["0/0", "0/1", "1/1", "./.", "2/2", "./."]);
// Same column, haploid: the ambiguous cells are missing.
let f = first_record_ploidy(&a, false);