docs: clarify VCF pseudo-alignment format and update obikmer dependency
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:
1 parent
5368c98875
commit
0134c69cf4
9 files changed
+156
-34
No files matched your search
Generated
+1
-1
@@ -1537,7 +1537,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "obikmer"
|
||||
version = "1.4.1"
|
||||
version = "1.4.2"
|
||||
dependencies = [
|
||||
"clap",
|
||||
"csv",
|
||||
|
||||
@@ -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);
|
||||
|
||||
Reference in new issue
Block a user