refactor: restructure phylo CLI arguments into submodules

Refactor the `phylo` command's argument handling by splitting the monolithic
`args.rs` file into specialized submodules (`distance`, `outputs`, `sampling`,
`select`) and a central `mod.rs`. This improves modularity and separates
concerns for distance metrics, sampling options, and output configurations.

- Move `alignment_output`, `ambiguity`, and `annex_selection` from `args.rs` to
  `args/mod.rs` in the `PhyloArgs` struct.
- Relocate distance parsing logic (`parse_gamma_shape`, `parse_n_sites`, `target`)
  and helper functions (`distance_to_compute`, `as_classic`, `as_snp`, etc.) from
  `args.rs` to `values.rs`.
- Add new submodule files: `args/distance.rs` for `DistanceArgs`, `args/outputs.rs`
  for `AlignArgs` and `CostsArgs`, `args/sampling.rs` for `SamplingArgs`, and
  `args/select.rs` for `SelectArgs` and `AnnexArgs`.
- Update `main.rs` to register the new `Phylo` command using `cmd::phylo::PhyloArgs`.
- Refactor `mod.rs` (`run`) to use nested argument structures (e.g., `args.dist`,
  `args.sample`) instead of flat fields.
- Update `alignment_out.rs` to reference the new nested paths (`args.align.fasta`,
  `args.sample.no_ambiguity`).
This commit is contained in:
Eric Coissac committed 2026-11-19 07:11:26 +01:00
1 parent 7f829ea557
commit 14433e80a5
10 files changed
+870 -613

No files matched your search

+3 -3
View File
@@ -29,7 +29,7 @@ pub(super) fn write_alignment_outputs(
let n_sites = alignment.sequences.first().map_or(0, Vec::len);
let n_genomes = alignment.genome_indices.len();
if args.fasta || !args.vcf {
if args.align.fasta || !args.align.vcf {
let path = path_for("fasta");
let mut f = create(&path);
for (&g, seq) in alignment.genome_indices.iter().zip(alignment.sequences.iter()) {
@@ -38,10 +38,10 @@ pub(super) fn write_alignment_outputs(
info!("pseudo-alignment ({n_sites} site(s), {n_genomes} genome(s)) → {path}");
}
if args.vcf {
if args.align.vcf {
let path = path_for("vcf");
let mut f = create(&path);
let written = alignment.write_vcf(labels, !args.no_ambiguity, &mut f).unwrap_or_else(|e| {
let written = alignment.write_vcf(labels, !args.sample.no_ambiguity, &mut f).unwrap_or_else(|e| {
eprintln!("error writing {path}: {e}");
std::process::exit(1);
});
-558
View File
@@ -1,558 +0,0 @@
use std::path::PathBuf;
use clap::Args;
use obikphylo::siblings::{AmbiguityPolicy, AnnexSelection};
use obikphylo::{DistanceMetric, GammaShape, SnpDistanceKind};
/// `--gamma-shape` CLI value: a fixed `alpha`, or `auto`/`estimate` to fit
/// it from the data (see [`GammaShape::Auto`]). Kept as its own tiny type
/// (rather than parsing straight to `GammaShape`) so the CLI layer stays
/// free of `GammaShape::Disabled`, which the `Option<GammaShapeArg>` around
/// this already expresses on its own (`None` = flag not given at all).
#[derive(Debug, Clone, Copy)]
pub enum GammaShapeArg {
Fixed(f64),
Auto,
}
impl From<GammaShapeArg> for GammaShape {
fn from(arg: GammaShapeArg) -> Self {
match arg {
GammaShapeArg::Fixed(a) => GammaShape::Fixed(a),
GammaShapeArg::Auto => GammaShape::Auto,
}
}
}
fn parse_gamma_shape(s: &str) -> Result<GammaShapeArg, String> {
if s.eq_ignore_ascii_case("auto") || s.eq_ignore_ascii_case("estimate") {
return Ok(GammaShapeArg::Auto);
}
s.parse::<f64>()
.map(GammaShapeArg::Fixed)
.map_err(|_| format!("invalid --gamma-shape value {s:?}: expected a positive number or \"auto\"/\"estimate\""))
}
/// `--n-sites` CLI value: a number of sites to draw, or `all` for every site
/// — the draw then keeps every variable family that passes the other filters,
/// with no sampling involved. Its own tiny type (like [`GammaShapeArg`]) so
/// the two cases stay distinct up to the call that needs the target, instead
/// of an in-band sentinel (a negative number, `0`, ...) that a typo could hit.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum NSitesArg {
All,
N(usize),
}
impl NSitesArg {
/// The target to hand to the sampler: `None` = exhaustive.
pub fn target(self) -> Option<usize> {
match self {
NSitesArg::All => None,
NSitesArg::N(n) => Some(n),
}
}
}
fn parse_n_sites(s: &str) -> Result<NSitesArg, String> {
if s.eq_ignore_ascii_case("all") {
return Ok(NSitesArg::All);
}
s.parse::<usize>()
.map(NSitesArg::N)
.map_err(|_| format!("invalid --n-sites value {s:?}: expected a non-negative integer or \"all\""))
}
/// `--distance` value — either one of `obikphylo::DistanceMetric`'s
/// whole-index metrics (routed to `IndexCache::distance`) or one of
/// `obikphylo::SnpDistanceKind`'s `snp-*` corrections (routed to
/// `obikphylo::siblings::distance_matrix`, over a tally built by
/// `sampled_scan`/`PairwiseReducer`, the sibling-annex pipeline) — two
/// genuinely different code paths behind one CLI vocabulary, see
/// `DevDocMD/theory/evolutionary_distances.md`, "`--distance` unification".
#[derive(clap::ValueEnum, Clone, Copy, Debug)]
pub enum DistanceArg {
Jaccard,
Mash,
Hamming,
BrayCurtis,
#[value(name = "relfreq-bray-curtis")]
RelfreqBrayCurtis,
Euclidean,
#[value(name = "relfreq-euclidean")]
RelfreqEuclidean,
Hellinger,
#[value(name = "hellinger-euclidean")]
HellingerEuclidean,
#[value(name = "snp-raw")]
SnpRaw,
#[value(name = "snp-jc")]
SnpJc,
#[value(name = "snp-k2p")]
SnpK2p,
#[value(name = "snp-k81")]
SnpK81,
#[value(name = "snp-f81")]
SnpF81,
#[value(name = "snp-t92")]
SnpT92,
#[value(name = "snp-tn93")]
SnpTn93,
#[value(name = "snp-tv")]
SnpTv,
}
/// The distance matrix this invocation must compute, if any: the one asked for
/// with `--distance`, else `jaccard` when `--nj`, `--upgma` or
/// `--shared-kmers` needs a matrix to work from, else none — a matrix is never
/// computed (nor written) just because nothing said otherwise.
pub fn distance_to_compute(
distance: Option<DistanceArg>,
nj: bool,
upgma: bool,
shared_kmers: bool,
) -> Option<DistanceArg> {
distance.or_else(|| (nj || upgma || shared_kmers).then_some(DistanceArg::Jaccard))
}
#[cfg(test)]
mod distance_tests {
use super::*;
#[test]
fn nothing_asked_nothing_computed() {
assert!(distance_to_compute(None, false, false, false).is_none());
}
#[test]
fn tree_and_shared_kmer_outputs_imply_jaccard() {
for (nj, upgma, shared) in [(true, false, false), (false, true, false), (false, false, true)] {
assert!(matches!(
distance_to_compute(None, nj, upgma, shared),
Some(DistanceArg::Jaccard)
));
}
}
#[test]
fn an_explicit_distance_wins() {
assert!(matches!(
distance_to_compute(Some(DistanceArg::Mash), true, true, true),
Some(DistanceArg::Mash)
));
assert!(matches!(
distance_to_compute(Some(DistanceArg::SnpJc), false, false, false),
Some(DistanceArg::SnpJc)
));
}
}
impl DistanceArg {
/// `Some` for the whole-index metrics, `None` for `snp-*` values.
pub fn as_classic(self) -> Option<DistanceMetric> {
Some(match self {
DistanceArg::Jaccard => DistanceMetric::Jaccard,
DistanceArg::Mash => DistanceMetric::Mash,
DistanceArg::Hamming => DistanceMetric::Hamming,
DistanceArg::BrayCurtis => DistanceMetric::BrayCurtis,
DistanceArg::RelfreqBrayCurtis => DistanceMetric::RelfreqBrayCurtis,
DistanceArg::Euclidean => DistanceMetric::Euclidean,
DistanceArg::RelfreqEuclidean => DistanceMetric::RelfreqEuclidean,
DistanceArg::Hellinger => DistanceMetric::Hellinger,
DistanceArg::HellingerEuclidean => DistanceMetric::HellingerEuclidean,
_ => return None,
})
}
/// `Some` for the `snp-*` values, `None` for the whole-index metrics.
pub fn as_snp(self) -> Option<SnpDistanceKind> {
Some(match self {
DistanceArg::SnpRaw => SnpDistanceKind::Raw,
DistanceArg::SnpJc => SnpDistanceKind::Jc,
DistanceArg::SnpK2p => SnpDistanceKind::K2p,
DistanceArg::SnpK81 => SnpDistanceKind::K81,
DistanceArg::SnpF81 => SnpDistanceKind::F81,
DistanceArg::SnpT92 => SnpDistanceKind::T92,
DistanceArg::SnpTn93 => SnpDistanceKind::Tn93,
DistanceArg::SnpTv => SnpDistanceKind::Tv,
_ => return None,
})
}
}
/// Genome-vs-genome distance computation: the whole-index `--distance` path
/// (classic metrics + `snp-*` corrections/NJ/UPGMA), annex construction
/// (`--sibling-annex`), annex diagnostics (`--sibling-stats`,
/// `--sibling-hist`), entropy reporting (`--shannon`), SNP pseudo-alignment
/// sampling (`--pseudo-alignment`, `--n-sites`, `--free-loss`,
/// `--no-ambiguity`, `--entropy`/`--entropy-sd`), Sankoff cost-matrix
/// calibration (`--sankoff`, `--sankoff-ratio-ceiling`) and its TNT/PhyG/
/// IQ-TREE exports (`--tnt`, `--phyg`, `--iqtree`/`--iqtree-min-freq`,
/// `--sankoff-cost-scale`), and Family Overlap (`--family-overlap`,
/// `--min-shared-family`).
#[derive(Args)]
pub struct PhyloArgs {
/// Index directory
pub index: PathBuf,
/// Exclude a genome (by its exact label) — from `--pseudo-alignment`'s
/// sampling (a family whose only polymorphism lived in an excluded
/// genome is discarded during sampling, not filtered afterward — see
/// `obikphylo::siblings::sampled_scan`'s own docs) and from the
/// distance matrix / shared-kmer matrix CSV output (row and column
/// both dropped; the underlying computation itself is unaffected).
/// Repeatable.
#[arg(long = "exclude-genome", value_name = "LABEL")]
pub exclude_genome: Vec<String>,
/// Auto-exclude any genome whose mean shared-variable-family count
/// against every other genome (`FamilyOverlap::mean_row` — the same
/// per-row statistic `--family-overlap`'s own matrix shows) falls below
/// this threshold — same exclusion machinery as `--exclude-genome`,
/// applied on top of it rather than instead of it. Applies to the
/// `snp-*` `--distance`/`--pseudo-alignment`/`--sankoff` computations
/// below (all sibling-annex-based); does *not* affect the whole-index
/// `--distance` metrics (jaccard, hamming, bray-curtis, ...) or their
/// matrix/NJ/UPGMA output — a genome with too little SNP-family
/// coverage to trust is a different concern from one whose plain k-mer
/// profile is simply divergent. Requires the Family Overlap annex
/// (built on demand if missing, same as every other annex here — see
/// `obikphylo::siblings::extensions::SiblingExt::family_overlap`'s own
/// docs).
#[arg(long, value_name = "N")]
pub min_shared_family: Option<f64>,
/// Build (or rebuild) the sibling-count/minorant annex — independent of
/// the distance metric below, meant to be run routinely, ahead of any
/// SNP-family distance computation that will later consume it. Rebuilding
/// it invalidates the annexes derived from it; those are rebuilt here
/// only for the options given alongside (`--entropy` the entropy annex,
/// `--quartet` the quartet one, `--pair-balance` the pair-weight and
/// family-overlap ones, `--family-overlap`/`--min-shared-family` the
/// family-overlap one), each under the `--no-ambiguity`/`--only-diploid`
/// convention given — anything not asked for is built later, on demand.
#[arg(long)]
pub sibling_annex: bool,
/// Tally the sibling-count distribution (CSV) of an already-built annex
/// (run with `--sibling-annex` first, in this invocation or an earlier
/// one). A separate, occasional diagnostic pass — not run every time the
/// annex itself is (re)built.
#[arg(long)]
pub sibling_stats: bool,
/// Print just the global family-size histogram (1-4 members) of an
/// already-built annex — the `global` row `--sibling-stats` also
/// writes, but without the per-genome breakdown, so it skips
/// `--sibling-stats`'s cross-partition resolution entirely (annex bits
/// only).
#[arg(long)]
pub sibling_hist: bool,
/// Write the Family Overlap matrix (CSV) — number of shared *variable*
/// families per genome pair, index-wide (`obikphylo::siblings::FamilyOverlap`).
/// Built on demand if missing (same as every other annex here); no
/// `--sibling-annex` prerequisite beyond that. Every genome is written,
/// unfiltered by `--exclude-genome`/`--min-shared-family` — a raw
/// coverage diagnostic, not a computation those exclusions are meant to
/// protect.
#[arg(long)]
pub family_overlap: bool,
/// Write a per-family Shannon entropy report (CSV) — requires an
/// already-built sibling annex (`--sibling-annex` first, in this
/// invocation or an earlier one). Always a full, unsampled scan of
/// every family (`--n-sites`/`--entropy`/`--entropy-sd` below only
/// apply to `--pseudo-alignment`, not this).
#[arg(long)]
pub shannon: bool,
/// Write the same entropy scan as `--shannon` as a distribution
/// (`<prefix>_shannon_summary.csv`): the number of families per entropy
/// kind, number of genomes carrying the family, number of those without
/// ambiguity and 0.05-bit entropy bin — a few hundred thousand lines at
/// most, whatever the size of the index, instead of one line per family.
/// Requires an already-built sibling annex, like `--shannon`.
#[arg(long)]
pub shannon_summary: bool,
/// Write a SNP-only pseudo-alignment (FASTA) — requires
/// `--n-sites <N|all>` and an already-built sibling annex
/// (`--sibling-annex` first, in this invocation or an earlier one).
#[arg(long)]
pub pseudo_alignment: bool,
/// Write the pseudo-alignment as FASTA (`<prefix>_alignment.fasta`) —
/// the default format when neither `--fasta` nor `--vcf` is given. Implies
/// `--pseudo-alignment`; combinable with `--vcf`.
#[arg(long)]
pub fasta: bool,
/// Write the pseudo-alignment as VCF (`<prefix>_alignment.vcf`): one
/// contig `obikmer_<partition>_<layer>` per scanned layer, `POS` the
/// family's index within it, `ID` the family's masked canonical k-mer.
/// Implies `--pseudo-alignment`; combinable with `--fasta`.
#[arg(long)]
pub vcf: bool,
/// Number of variable sites to draw index-wide, or `all` for every site
/// that passes the other filters (no sampling then). Mandatory for
/// `--pseudo-alignment`/`--sankoff`; optional for a `snp-*`
/// `--distance` value, where omitting it also means every site. A
/// number is a target, not a guarantee (proportional per-layer
/// sampling; see `obikphylo::siblings::sampled_scan`'s own docs).
#[arg(long = "n-sites", value_name = "N|all", value_parser = parse_n_sites)]
pub n_sites: Option<NSitesArg>,
/// In `--pseudo-alignment`, treat a genome carrying none of a family's
/// observed members (`∅`) as missing data (`?`) rather than a real
/// character state.
#[arg(long)]
pub free_loss: bool,
/// In `--pseudo-alignment`, treat a genome carrying more than one
/// member of a family (ambiguous) as missing data (`?`) rather than an
/// IUPAC ambiguity code.
#[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
/// by at least two genomes. A singleton variant, or a family carried by
/// fewer than four genomes, fits every topology and tells a tree
/// nothing. Which genomes count as carriers follows `--no-ambiguity`.
#[arg(long)]
pub quartet: bool,
/// In `--pseudo-alignment`/`--sankoff`/`snp-*` `--distance`, favour the
/// families that cover the pairs of genomes sharing the fewest families
/// across the index: each family is weighted by the mean, over the pairs
/// of genomes carrying it, of 1 / (number of families the pair shares).
/// Evens out how well each pair of genomes is represented in the sample.
/// Which genomes count as carriers follows `--no-ambiguity`.
#[arg(long)]
pub pair_balance: bool,
/// Write what the draw contains, from the very sites it kept
/// (requires `--pseudo-alignment`, `--sankoff` or a `snp-*`
/// `--distance`): `<prefix>_sample_genomes.csv` (per genome, the sites it
/// has a call in and the informative sites it takes part in),
/// `<prefix>_sample_carriers.csv` (sites and informative sites per number
/// of carriers) and `<prefix>_sample_overlap.csv` (the sample's own
/// genome × genome overlap matrix, to compare with `--family-overlap`).
#[arg(long)]
pub sample_stats: bool,
/// Write how the draw was spread over the layers of the index
/// (requires `--pseudo-alignment`, `--sankoff` or a `snp-*`
/// `--distance`): `<prefix>_sample_plan.csv`, one line per layer with the
/// families eligible, their total weight, the layer's quota, the families
/// drawn and the ones kept after masking.
#[arg(long)]
pub sample_plan: bool,
/// Entropy-biased sampling target (Gaussian kernel mean) for
/// `--pseudo-alignment` — activates biasing as soon as this or
/// `--entropy-sd` is given; the other defaults to 1.0/0.5.
#[arg(long)]
pub entropy: Option<f64>,
/// Entropy-biased sampling kernel width (Gaussian standard deviation)
/// for `--pseudo-alignment` — see `--entropy`.
#[arg(long)]
pub entropy_sd: Option<f64>,
/// Persist the `snp-*` `--distance` sample (the pairwise substitution
/// tally) in `DIR` across separate `obikmer phylo` invocations: a later
/// run against the same index with the exact same
/// `--n-sites`/`--free-loss`/`--no-ambiguity`/`--quartet`/`--exclude-genome`/
/// `--min-shared-family`/`--entropy`/`--entropy-sd` restores it instead
/// of resampling. `DIR` is created if it doesn't exist. If it already
/// holds a sample built under *different* selection parameters, this
/// run is rejected with an error listing what changed, unless
/// `--session-force` is also given (which discards the old sample and
/// starts fresh under this run's parameters). Only covers a `snp-*`
/// `--distance` today — `--sankoff`/`--tnt`/`--phyg`/`--iqtree` don't
/// read or write a `--session` yet.
#[arg(long, value_name = "DIR")]
pub session: Option<PathBuf>,
/// With `--session DIR`: overwrite its saved selection parameters (and
/// discard its cached sample) instead of erroring out when this run's
/// parameters don't match. No effect without `--session`.
#[arg(long, requires = "session")]
pub session_force: bool,
/// Calibrate a 16-state Sankoff cost matrix (and its matching
/// pseudo-alignment) from an already-built sibling annex — requires
/// `--n-sites <N|all>`, and shares `--free-loss`/`--no-ambiguity`/`--quartet`/
/// `--entropy`/`--entropy-sd` with `--pseudo-alignment` (one draw, same
/// selection feeds both the alignment and every calibration tally).
#[arg(long)]
pub sankoff: bool,
/// Exclude genome pairs whose raw SNP ratio exceeds this value from the
/// base-pair (composition) calibration `--sankoff` pools — a pair this
/// close to substitution saturation carries no information about the
/// true substitution spectrum. Does *not* gate the cardinality
/// calibration (see `obikphylo::siblings::CardinalityTally`'s own
/// docs for why).
#[arg(long, default_value = "0.5")]
pub sankoff_ratio_ceiling: f64,
/// Also write <prefix>_sankoff.tnt, a ready-to-run TNT script (`proc
/// <file>;`) for the same matrix/alignment `--sankoff` computes —
/// recoded to TNT's default xread alphabet (0-9A-F only; TNT rejects
/// the wider IUPAC set `--sankoff`'s own output uses unless `nstates
/// dna` is set, which imposes TNT's own incompatible DNA encoding
/// instead) with integer-scaled costs (TNT's smatrix/cost commands
/// reject decimals). Implies `--sankoff`.
#[arg(long)]
pub tnt: bool,
/// Also write <prefix>_sankoff.tcm and <prefix>_sankoff.pg, a
/// custom-alphabet cost matrix and a ready-to-run PhyG script (`read`/
/// `search`/`report`) for the same matrix/alignment `--sankoff`
/// computes. Reuses `--sankoff`'s own `_sankoff.fasta` directly — PhyG's
/// `tcm:` alphabet is read from the matrix file itself, so the IUPAC+`0`
/// alphabet needs no recoding here, unlike `--tnt`. Implies `--sankoff`.
#[arg(long)]
pub phyg: bool,
/// Also write <prefix>_iqtree.model and <prefix>_iqtree.fasta, a
/// custom-model file and a matching recoded alignment for genuine
/// maximum-likelihood inference with IQ-TREE (`iqtree3 -s ...
/// --seqtype MORPH -m ...+ASC`) — real branch lengths, unlike
/// `--tnt`/`--phyg`'s parsimony step counts. The model is the
/// reversible `Q(i,j) = R(i,j)·π_j` construction: `R` (exchangeability,
/// symmetric) recovered from the same calibrated cost matrix
/// `--sankoff` computes, `π` the real empirical state frequencies
/// counted from the alignment. Only the states that actually occur in
/// this alignment are kept, compactly renumbered (IQ-TREE infers its
/// state count from the alignment itself, and a gap in the numbering
/// would silently misalign the model file). Implies `--sankoff`.
#[arg(long)]
pub iqtree: bool,
/// Under `--iqtree --free-loss`, also recode to `?` (the same
/// missing-data treatment as `-`) any state whose empirical frequency
/// in the alignment falls below this threshold — not just genuinely
/// absent calls. States encoding 3 or 4 simultaneously-observed central
/// bases (IUPAC `V`/`H`/`K`.../`N` for 3, `N` for 4) are rare by
/// construction and often land in exactly this low-frequency range —
/// more likely assembly/detection noise than a genuine, widely-preserved
/// multi-way polymorphism, the same "sampling failure, not true signal"
/// reasoning `--free-loss` already applies to absence. No effect
/// without `--free-loss` (there is no missing-data symbol to recode to
/// otherwise). `<prefix>_iqtree_states.csv` reports the frequency
/// actually used to decide.
#[arg(long, default_value = "0.001")]
pub iqtree_min_freq: f64,
/// Scale factor applied before rounding real-valued costs to the
/// integers both `--tnt`'s smatrix/cost commands and `--phyg`'s `tcm:`
/// matrix require. Keep this small: the total tree score is this scale
/// times the sum of per-character costs across every character, and
/// there are hints in TNT's own manual that at least some of its
/// internal accumulators are 32-bit — a large scale risks a silent
/// integer overflow (undetectable, not just a crash) far more costly
/// than the resolution a bigger factor would buy. Shared between `--tnt`
/// and `--phyg` rather than split into two flags: both scale the same
/// calibrated matrix for the same reason (integer-only cost commands).
#[arg(long, default_value = "100")]
pub sankoff_cost_scale: f64,
/// Distance matrix to compute and write — none is computed unless this
/// is given, or `--nj`/`--upgma`/`--shared-kmers` is (they need a matrix
/// and use `jaccard` then, see [`distance_to_compute`]). Either a
/// whole-index metric (`jaccard`,
/// `mash`, `hamming`, `bray-curtis`, ...) or a `snp-*` correction over
/// the central-position SNP substitution spectrum (`snp-raw`, `snp-jc`,
/// `snp-k2p`, `snp-k81`, `snp-f81`, `snp-t92`, `snp-tn93`, `snp-tv`) —
/// the latter route to a different computation entirely
/// (`obikphylo::siblings::sampled_scan` + `distance_matrix`, requires
/// `--sibling-annex` first; see
/// `DevDocMD/theory/evolutionary_distances.md`, "`--distance`
/// unification" for the full catalog and why LogDet/Tajima-Nei/F84/
/// HKY85 aren't offered yet).
#[arg(long, value_enum)]
pub distance: Option<DistanceArg>,
/// Rate-heterogeneity correction (Jin-Nei gamma shape parameter `α`)
/// for `snp-*` `--distance` values that support it
/// (`obikphylo::SnpDistanceKind::supports_gamma`: every one except
/// `snp-raw`/`snp-tv`, which have nothing to correct/are deliberately
/// uncorrected). Has no effect on the whole-index metrics. Rejected at
/// runtime if given alongside an unsupported `--distance` value.
/// Either a positive number (fixed `alpha`) or `auto`/`estimate` to fit
/// `alpha` from the data itself — method-of-moments over the
/// over-dispersion of substitution rate across partitions.
#[arg(long, value_name = "ALPHA|auto", value_parser = parse_gamma_shape)]
pub gamma_shape: Option<GammaShapeArg>,
/// Minimum count to consider a kmer present when computing Jaccard on count indexes
#[arg(long, default_value = "1")]
pub presence_threshold: u32,
/// Write the primary distance matrix as plain CSV instead of the
/// default relaxed-PHYLIP format (`n` on the first line, then one
/// `label<TAB>value...` row per genome — no 10-character label
/// truncation, unlike strict PHYLIP, not yet offered here). PHYLIP is
/// the default because it's what external NJ tools (PHYLIP `neighbor`,
/// FastME, T-REX, SplitsTree) actually read; CSV stays available for
/// scripting/inspection. Only affects the primary distance matrix —
/// `--shared-kmers` keeps its own CSV-only format regardless of this
/// flag.
#[arg(long)]
pub csv: bool,
/// Also output the shared-kmer count matrix (CSV)
#[arg(long)]
pub shared_kmers: bool,
/// Compute and write a Neighbor-Joining tree (Newick)
#[arg(long)]
pub nj: bool,
/// Compute and write a UPGMA tree (Newick)
#[arg(long)]
pub upgma: bool,
/// Output prefix: <prefix>_dist.csv, <prefix>_shared.csv, <prefix>_nj.nwk,
/// <prefix>_upgma.nwk. If omitted, the distance matrix is written to stdout.
#[arg(short, long)]
pub output: Option<PathBuf>,
}
impl PhyloArgs {
/// How genomes carrying several members of a family are treated.
pub fn ambiguity(&self) -> AmbiguityPolicy {
AmbiguityPolicy::from_flags(self.no_ambiguity, self.only_diploid)
}
/// The derived annexes the options of this invocation read, all under
/// [`ambiguity`](Self::ambiguity).
pub fn annex_selection(&self) -> AnnexSelection {
AnnexSelection {
policy: self.ambiguity(),
entropy: self.entropy.is_some(),
quartet: self.quartet,
overlap: self.family_overlap || self.min_shared_family.is_some() || self.pair_balance,
pair_weight: self.pair_balance,
}
}
/// Whether a pseudo-alignment must be drawn and written (`--pseudo-alignment`,
/// or any of its output-format flags).
pub fn alignment_output(&self) -> bool {
self.pseudo_alignment || self.fasta || self.vcf
}
}
+137
View File
@@ -0,0 +1,137 @@
use std::path::PathBuf;
use clap::Args;
use super::super::values::{DistanceArg, GammaShapeArg, parse_gamma_shape};
/// Distance estimation and tree reconstruction.
#[derive(Args)]
#[command(next_help_heading = "Distance estimation and tree reconstruction")]
pub struct DistanceArgs {
/// Distance used to compare genomes
///
/// Computes a genome-by-genome distance matrix. Two families of
/// distances are available.
///
/// Whole-genome distances, based on the k-mer content of each genome.
/// The first three compare which k-mers are present or absent (on an
/// index that stores counts, a k-mer is present when its count reaches
/// --presence-threshold):
/// jaccard Jaccard distance
/// mash Mash distance, a divergence estimate derived
/// from the Jaccard index
/// hamming number of k-mers present in one genome and
/// absent from the other (only for indexes
/// without counts)
/// The others compare k-mer counts, and need an index that stores them:
/// bray-curtis Bray-Curtis dissimilarity on k-mer counts
/// relfreq-bray-curtis Bray-Curtis dissimilarity on counts divided
/// by each genome's total count
/// euclidean Euclidean distance on k-mer counts
/// relfreq-euclidean Euclidean distance on relative frequencies
/// hellinger Hellinger distance on k-mer counts
/// hellinger-euclidean Euclidean distance on square roots of
/// relative frequencies (unnormalised Hellinger)
///
/// SNP-based distances, calculated from the nucleotide differences at
/// the central position of related k-mers:
/// snp-raw proportion of differing sites, no correction
/// snp-jc Jukes-Cantor correction
/// snp-k2p Kimura two-parameter correction
/// snp-k81 Kimura three-parameter correction
/// snp-f81 Felsenstein 1981 correction
/// snp-t92 Tamura 1992 correction
/// snp-tn93 Tamura-Nei 1993 correction
/// snp-tv proportion of transversions only, no correction
/// They use every eligible variable site, or a sample drawn with
/// --n-sites.
#[arg(
long,
value_enum,
verbatim_doc_comment,
hide_possible_values = true,
value_name = "DISTANCE"
)]
pub distance: Option<DistanceArg>,
/// Minimum k-mer count to count as present
///
/// Converts counts into presence/absence for the Jaccard and Mash
/// distances and for the shared k-mer counts, when the index stores
/// counts: a k-mer is present in a genome only when its count reaches
/// this threshold. It has no effect on indexes without counts, nor on
/// the distances that use the counts themselves.
#[arg(long, default_value = "1")]
pub presence_threshold: u32,
/// Account for different evolution rates among sites
///
/// Applies a gamma rate-heterogeneity correction to SNP-based
/// distances. A positive number is the gamma shape parameter α. `auto`
/// (or `estimate`) estimates α from the data, using the variation of
/// the substitution rate across the partitions of the index.
///
/// Available for every snp-* distance except snp-raw and snp-tv, which
/// have no evolutionary correction to refine. It has no effect on
/// whole-genome distances, and combining it with a distance that does
/// not support it is an error.
#[arg(long, value_name = "ALPHA|auto", value_parser = parse_gamma_shape)]
pub gamma_shape: Option<GammaShapeArg>,
/// Save and reuse the sample of a SNP-based distance
///
/// Saves, in this directory, the sample's tally of pairwise differences
/// between genomes, so that a later run on the same index can reuse it
/// instead of drawing again. The directory is created if needed.
///
/// The saved sample is reused only if these options are identical:
/// --n-sites, --free-loss, --no-ambiguity, --quartet, --exclude-genome,
/// --min-shared-family, --entropy and --entropy-sd. Otherwise the run
/// stops and lists the differences, unless --session-force is given.
///
/// For now only SNP-based distances use sessions; Sankoff analyses and
/// the TNT, PhyG and IQ-TREE exports neither read nor write them.
#[arg(long, value_name = "DIR")]
pub session: Option<PathBuf>,
/// Replace a saved sample made with other parameters
///
/// With --session, discards the saved sample when its parameters differ
/// from this run's, and draws a new one. Without this option, a
/// difference is an error.
#[arg(long, requires = "session")]
pub session_force: bool,
/// Write the distance matrix as CSV instead of PHYLIP
///
/// By default the main matrix is written in relaxed PHYLIP format: the
/// number of genomes on the first line, then one row per genome made of
/// its label (never truncated) and its distances to the others. CSV is
/// easier to load in scripts or spreadsheets. Only the main matrix is
/// affected: the --shared-kmers matrix is always CSV.
#[arg(long)]
pub csv: bool,
/// Also write the number of k-mers shared by each pair of genomes
///
/// Writes a genome-by-genome CSV matrix of shared k-mer counts, to
/// `PREFIX_shared.csv`.
#[arg(long)]
pub shared_kmers: bool,
/// Build a Neighbor-Joining tree
///
/// Builds the tree from the distance matrix and writes it in Newick
/// format to `PREFIX_nj.nwk`. If --distance is not given, the Jaccard
/// distance is used.
#[arg(long)]
pub nj: bool,
/// Build a UPGMA tree
///
/// Builds a tree with the Unweighted Pair Group Method with Arithmetic
/// Mean and writes it in Newick format to `PREFIX_upgma.nwk`. If
/// --distance is not given, the Jaccard distance is used.
#[arg(long)]
pub upgma: bool,
}
+132
View File
@@ -0,0 +1,132 @@
//! Command-line arguments of `obikmer phylo`.
//!
//! The options are split by theme into flattened groups, each carrying its own
//! help heading and its own help texts (short for `-h`, long for `--help`).
//! Those texts are written for biologists: no internal names, no design
//! rationale — that belongs in the documentation.
mod distance;
mod outputs;
mod sampling;
mod select;
use std::path::PathBuf;
use clap::Args;
use obikphylo::siblings::{AmbiguityPolicy, AnnexSelection};
pub use distance::DistanceArgs;
pub use outputs::{AlignArgs, CostsArgs};
pub use sampling::SamplingArgs;
pub use select::{AnnexArgs, SelectArgs};
/// Text shown at the end of `obikmer phylo --help`.
pub const WORKFLOW_HELP: &str = "\
Typical workflows
Compare genome-wide k-mer content and infer a Neighbor-Joining tree:
obikmer phylo INDEX --distance jaccard --nj -o out
Compute SNP-based distances and infer a Neighbor-Joining tree:
obikmer phylo INDEX --distance snp-k2p --n-sites 200000 --nj -o out
Generate a SNP pseudo-alignment:
obikmer phylo INDEX --pseudo-alignment --n-sites 200000 -o out
Prepare a maximum-likelihood analysis for IQ-TREE:
obikmer phylo INDEX --iqtree --n-sites 200000 -o out
Option dependencies
--fasta, --vcf imply --pseudo-alignment
--tnt, --phyg, --iqtree imply --sankoff
--nj, --upgma, --shared-kmers use the Jaccard distance when --distance
is not given
--pseudo-alignment, --sankoff require --n-sites
--session-force requires --session";
/// Genome comparison and phylogenetic analysis
///
/// Compares the genomes stored in an index and performs phylogenetic
/// analyses. Two complementary approaches are available:
///
/// - Whole-genome distances compare the k-mer content of the genomes,
/// without any alignment.
/// - SNP-based distances and analyses compare nucleotide variants at the
/// central position of related k-mers.
///
/// Distance matrices can be used to build Neighbor-Joining or UPGMA trees.
/// SNP-based analyses can also produce pseudo-alignments and calibrated
/// substitution costs, for phylogenetic inference with TNT, PhyG or
/// IQ-TREE.
///
/// SNP families
///
/// SNP-based analyses use groups of k-mers that differ only at their
/// central nucleotide. These groups are called families. A variable family
/// is one character of the analysis, and the variants a genome carries
/// give its state for that character.
#[derive(Args)]
#[command(verbatim_doc_comment)]
pub struct PhyloArgs {
/// Index directory
pub index: PathBuf,
/// Prefix of the output files
///
/// Output files are named after this prefix: for example
/// `PREFIX_dist.phy` (or `PREFIX_dist.csv` with --csv), `PREFIX_nj.nwk`
/// and `PREFIX_upgma.nwk`, plus the files described with the other
/// options.
///
/// Without this option, the main distance matrix is written to standard
/// output, and the other files are written in the current directory
/// under their name without prefix (for example `nj.nwk`).
#[arg(short, long)]
pub output: Option<PathBuf>,
#[command(flatten)]
pub dist: DistanceArgs,
#[command(flatten)]
pub select: SelectArgs,
#[command(flatten)]
pub sample: SamplingArgs,
#[command(flatten)]
pub annex: AnnexArgs,
#[command(flatten)]
pub align: AlignArgs,
#[command(flatten)]
pub costs: CostsArgs,
}
impl PhyloArgs {
/// How genomes carrying several members of a family are treated.
pub fn ambiguity(&self) -> AmbiguityPolicy {
AmbiguityPolicy::from_flags(self.sample.no_ambiguity, self.sample.only_diploid)
}
/// The derived annexes the options of this invocation read, all under
/// [`ambiguity`](Self::ambiguity).
pub fn annex_selection(&self) -> AnnexSelection {
AnnexSelection {
policy: self.ambiguity(),
entropy: self.sample.entropy.is_some(),
quartet: self.sample.quartet,
overlap: self.annex.family_overlap
|| self.select.min_shared_family.is_some()
|| self.sample.pair_balance,
pair_weight: self.sample.pair_balance,
}
}
/// Whether a pseudo-alignment must be drawn and written (`--pseudo-alignment`,
/// or any of its output-format flags).
pub fn alignment_output(&self) -> bool {
self.align.pseudo_alignment || self.align.fasta || self.align.vcf
}
}
+132
View File
@@ -0,0 +1,132 @@
use clap::Args;
/// SNP pseudo-alignment.
///
/// A pseudo-alignment has one column per variable family and one state per
/// genome. Unlike a conventional sequence alignment, its columns come
/// directly from groups of related k-mers of the index.
#[derive(Args)]
#[command(next_help_heading = "SNP pseudo-alignment")]
pub struct AlignArgs {
/// Write a SNP pseudo-alignment
///
/// Writes an alignment with one column per selected variable family;
/// the states are the central nucleotides of the k-mers of the family.
/// The format is FASTA unless --vcf is given.
///
/// The number of sites is set with --n-sites (required). The options of
/// the "SNP character selection and sampling" group control which
/// families are included and how ambiguous states are written.
#[arg(long)]
pub pseudo_alignment: bool,
/// Write the pseudo-alignment in FASTA format
///
/// Writes `PREFIX_alignment.fasta`. This is the default format. Implies
/// --pseudo-alignment; can be combined with --vcf to get both formats.
#[arg(long)]
pub fasta: bool,
/// Write the pseudo-alignment in VCF format
///
/// Writes `PREFIX_alignment.vcf`. Each scanned index layer is a contig
/// named `obikmer_<partition>_<layer>`; `POS` is the position of the
/// family within the layer and `ID` is the masked canonical k-mer of the
/// family. Implies --pseudo-alignment; can be combined with --fasta to
/// get both formats.
#[arg(long)]
pub vcf: bool,
}
/// Sankoff cost calibration and exports for phylogenetic software.
///
/// Sankoff parsimony lets different changes between states have different
/// costs. These costs are estimated here from the observed variation, and
/// exported for external phylogenetic software.
#[derive(Args)]
#[command(next_help_heading = "Sankoff cost calibration and phylogenetic software exports")]
pub struct CostsArgs {
/// Estimate a Sankoff cost matrix and its alignment
///
/// Estimates, from the selected variable families, the cost of changing
/// from each of the 16 possible states to each other state, for weighted
/// parsimony. Writes `PREFIX_sankoff_matrix.csv` (costs),
/// `PREFIX_sankoff_params.yaml` (parameters) and
/// `PREFIX_sankoff.fasta` (alignment).
///
/// Needs --n-sites. The selection and sampling options are the same as
/// for pseudo-alignments, and a single sample of families serves both
/// the alignment and the estimation of the costs.
#[arg(long)]
pub sankoff: bool,
/// Leave very divergent genome pairs out of the calibration
///
/// Genome pairs whose raw SNP ratio exceeds this value are not used to
/// estimate the costs between nucleotides: at such divergence, repeated
/// substitutions at the same site blur the original substitution
/// pattern. The costs related to the number of variants are not
/// affected.
#[arg(long, default_value = "0.5")]
pub sankoff_ratio_ceiling: f64,
/// Export the Sankoff analysis for TNT
///
/// Writes `PREFIX_sankoff.tnt`, a script ready to run in TNT with
/// `proc FILE;`. States are recoded with TNT's default alphabet (0-9 and
/// A-F) and costs are turned into integers with --sankoff-cost-scale,
/// as TNT requires. Implies --sankoff.
#[arg(long)]
pub tnt: bool,
/// Export the Sankoff analysis for PhyG
///
/// Writes:
/// - `PREFIX_sankoff.tcm`: the cost matrix;
/// - `PREFIX_sankoff.pg`: the PhyG script.
/// The alignment is the `PREFIX_sankoff.fasta` written by --sankoff,
/// used without recoding. Costs are turned into integers with
/// --sankoff-cost-scale. Implies --sankoff.
#[arg(long, verbatim_doc_comment)]
pub phyg: bool,
/// Export a model and alignment for IQ-TREE maximum likelihood
///
/// Writes:
/// - `PREFIX_iqtree.model`: a substitution model derived from the
/// calibrated Sankoff costs;
/// - `PREFIX_iqtree.fasta`: the alignment with recoded states.
/// The model combines the calibrated costs with the frequencies of the
/// states observed in the alignment. Only the states that actually
/// occur are kept, renumbered consecutively.
///
/// Run IQ-TREE with:
/// iqtree3 -s PREFIX_iqtree.fasta --seqtype MORPH -m ...+ASC
/// giving the model file to -m. Unlike the parsimony analyses of TNT
/// and PhyG, maximum likelihood estimates branch lengths.
///
/// Implies --sankoff.
#[arg(long, verbatim_doc_comment)]
pub iqtree: bool,
/// Treat rare states as missing in the IQ-TREE export
///
/// With --iqtree and --free-loss, the states whose frequency in the
/// alignment is below this value are recoded as missing data (`?`).
/// States combining three or four nucleotides are typically that rare,
/// and are more likely noise than a real polymorphism.
///
/// No effect without --free-loss. The frequency actually applied is
/// reported in `PREFIX_iqtree_states.csv`.
#[arg(long, default_value = "0.001")]
pub iqtree_min_freq: f64,
/// Factor turning costs into integers for TNT and PhyG
///
/// TNT and PhyG only accept integer costs: the calibrated costs are
/// multiplied by this factor, then rounded. Keep it small. The tree
/// score is multiplied by the same factor, and a very large value can
/// overflow integers in TNT without any error.
#[arg(long, default_value = "100")]
pub sankoff_cost_scale: f64,
}
+123
View File
@@ -0,0 +1,123 @@
use clap::Args;
use super::super::values::{NSitesArg, parse_n_sites};
/// SNP character selection and sampling.
///
/// SNP-based analyses can use every eligible variable family, or a subset
/// drawn from the index. These options control which characters are
/// selected, which genomes and states are kept, and how the sample is spread.
#[derive(Args)]
#[command(next_help_heading = "SNP character selection and sampling")]
pub struct SamplingArgs {
/// Number of variable sites to select
///
/// Target number of variable families to draw from the index. Either a
/// positive integer, or `all` to keep every family that passes the other
/// filters, with no sampling.
///
/// Required for pseudo-alignments and Sankoff analyses. Optional for
/// SNP-based distances: when omitted, every eligible site is used.
///
/// Sites are drawn in proportion across the layers of the index, so the
/// number actually selected can differ slightly from the target.
#[arg(long = "n-sites", value_name = "N|all", value_parser = parse_n_sites)]
pub n_sites: Option<NSitesArg>,
/// Treat genomes lacking a family as missing data (?)
///
/// When a genome carries none of the variants found in a family, its
/// state is coded as missing data (`?`) instead of a real state.
///
/// Applies to every SNP-based analysis: distances, pseudo-alignments and
/// the Sankoff calibration with its exports.
#[arg(long)]
pub free_loss: bool,
/// Treat genomes with several variants as missing data (?)
///
/// A genome carrying more than one nucleotide variant of a family is
/// coded as missing data (`?`) instead of an IUPAC ambiguity code.
///
/// This also decides which genomes count as carriers for --quartet and
/// --pair-balance.
#[arg(long)]
pub no_ambiguity: bool,
/// Keep genomes with one or two variants per family
///
/// A genome with one variant is written as a single nucleotide, a genome
/// with two variants as the matching two-base IUPAC code. Genomes with
/// three or four variants are coded as missing data (`?`).
///
/// A milder alternative to --no-ambiguity; the two cannot be combined.
#[arg(long, conflicts_with = "no_ambiguity")]
pub only_diploid: bool,
/// Keep families that can tell tree topologies apart
///
/// A family is kept only when at least two different states are each
/// found in at least two genomes. A variant seen in a single genome, or
/// a family carried by fewer than four genomes, fits every arrangement
/// of the genomes and teaches nothing about the tree.
///
/// Which genomes count as carriers follows --no-ambiguity. Applies to
/// pseudo-alignments, Sankoff analyses and SNP-based distances.
#[arg(long)]
pub quartet: bool,
/// Favour families covering poorly represented genome pairs
///
/// Each family gets a weight: the mean, over the pairs of genomes
/// carrying it, of 1 / (number of families the pair shares). Families
/// covering pairs that share little information are therefore drawn
/// more often, which balances how well each pair is represented in the
/// sample.
///
/// Which genomes count as carriers follows --no-ambiguity. Applies to
/// pseudo-alignments, Sankoff analyses and SNP-based distances.
#[arg(long)]
pub pair_balance: bool,
/// Favour families of a given Shannon entropy
///
/// Families are drawn with a weight following a bell-shaped curve
/// centred on this entropy. Giving this option, or --entropy-sd, turns
/// the weighting on; the other one then takes its default (centre 1.0
/// bit, standard deviation 0.5 bit).
#[arg(long)]
pub entropy: Option<f64>,
/// Width of the entropy weighting
///
/// Standard deviation of the bell-shaped curve used by --entropy.
/// Giving this option also turns the weighting on.
#[arg(long)]
pub entropy_sd: Option<f64>,
/// Write statistics about the selected sample
///
/// Writes three CSV files describing the sites actually drawn:
/// - `PREFIX_sample_genomes.csv`: for each genome, the number of sites
/// where it has a called state and of informative sites;
/// - `PREFIX_sample_carriers.csv`: the number of sites and of
/// informative sites by number of carrier genomes;
/// - `PREFIX_sample_overlap.csv`: the genome-by-genome matrix of
/// families shared within the sample.
/// The overlap matrix can be compared with the one written by
/// --family-overlap, to check how well the sample represents the index.
///
/// Needs --pseudo-alignment, --sankoff or a SNP-based distance.
#[arg(long, verbatim_doc_comment)]
pub sample_stats: bool,
/// Write how the sites were spread over the index layers
///
/// Writes `PREFIX_sample_plan.csv`, one line per layer: number of
/// eligible families, their total weight, the layer's quota, the number
/// of families drawn and the number kept after masking.
///
/// Needs --pseudo-alignment, --sankoff or a SNP-based distance.
#[arg(long)]
pub sample_plan: bool,
}
+113
View File
@@ -0,0 +1,113 @@
use clap::Args;
/// Genome selection and filtering.
#[derive(Args)]
#[command(next_help_heading = "Genome selection and filtering")]
pub struct SelectArgs {
/// Exclude a genome from the analysis (repeatable)
///
/// Removes the genome identified by its exact label. Repeat the option
/// to exclude several genomes.
///
/// For SNP-based analyses, excluded genomes are removed before the
/// variable sites are selected: a family that was variable only because
/// of an excluded genome is no longer considered.
///
/// Excluded genomes are also removed from the distance and shared-k-mer
/// matrices; the distances between the remaining genomes are not
/// otherwise modified.
#[arg(long = "exclude-genome", value_name = "LABEL")]
pub exclude_genome: Vec<String>,
/// Exclude genomes sharing too few variable families
///
/// Removes the genomes whose average number of variable families shared
/// with the other genomes is below N. The average is the per-genome mean
/// of the matrix written by --family-overlap. This comes on top of
/// --exclude-genome.
///
/// The filter removes genomes that carry too little information for
/// SNP-based comparisons. It applies to SNP-based distances,
/// pseudo-alignments and Sankoff analyses, not to whole-genome distances
/// such as Jaccard: a genome with little SNP information is not
/// necessarily a genome whose overall k-mer content is divergent.
///
/// The family-overlap matrix is computed automatically if needed.
#[arg(long, value_name = "N")]
pub min_shared_family: Option<f64>,
}
/// SNP family preparation and diagnostics.
#[derive(Args)]
#[command(next_help_heading = "SNP family preparation and diagnostics")]
pub struct AnnexArgs {
/// Prepare in advance the tables used by SNP analyses
///
/// SNP-based distances, pseudo-alignments, Sankoff analyses and entropy
/// calculations rely on precomputed tables describing the families of
/// k-mers that differ only at their central nucleotide. They are
/// prepared automatically when first needed, so this option is never
/// required. It lets you prepare them beforehand, for example before a
/// series of analyses on the same index, or force them to be rebuilt.
///
/// Rebuilding the main table invalidates the tables derived from it.
/// Among those, only the ones requested in the same command are rebuilt
/// immediately (--entropy, --quartet, --pair-balance, --family-overlap
/// and --min-shared-family), following the treatment of ambiguous
/// states given by --no-ambiguity or --only-diploid. The others are
/// rebuilt when next needed.
#[arg(long)]
pub sibling_annex: bool,
/// Write the distribution of family sizes, by genome
///
/// Writes `PREFIX_siblings.csv`. For each genome, it gives the number of
/// families of each size (1 to 4 members) in which the genome carries at
/// least one member. A final `global` row gives the number of families
/// of each size over the whole index. Mostly a diagnostic.
#[arg(long)]
pub sibling_stats: bool,
/// Write the global distribution of family sizes
///
/// Writes `PREFIX_sibling_hist.csv`, the number of families having 1 to
/// 4 members over the whole index. These are the figures of the `global`
/// row of --sibling-stats, without the per-genome breakdown, and they
/// are faster to obtain.
#[arg(long)]
pub sibling_hist: bool,
/// Write the number of variable families shared by each genome pair
///
/// Writes `PREFIX_family_overlap.csv`, a genome-by-genome matrix giving,
/// for each pair of genomes, the number of variable families they share
/// over the whole index. It tells how much SNP information is available
/// to compare each pair, and helps spot genomes that are poorly covered.
///
/// Every genome is included, whatever --exclude-genome and
/// --min-shared-family say.
#[arg(long)]
pub family_overlap: bool,
/// Write the Shannon entropy of every family
///
/// Writes `PREFIX_entropy.csv`, one line per family. All families are
/// scanned, with no sampling: --n-sites, --entropy and --entropy-sd do
/// not apply.
#[arg(long)]
pub shannon: bool,
/// Summarise the distribution of family entropy
///
/// Same complete scan as --shannon, but writes a compact summary,
/// `PREFIX_shannon_summary.csv`, instead of one line per family. It
/// counts the families according to:
/// - entropy category;
/// - number of genomes carrying the family;
/// - number of those carriers without ambiguity;
/// - entropy bins of 0.05 bits.
/// It has a few hundred thousand lines at most, whatever the size of
/// the index.
#[arg(long, verbatim_doc_comment)]
pub shannon_summary: bool,
}
+47 -46
View File
@@ -1,5 +1,6 @@
mod alignment_out;
mod args;
mod values;
mod iqtree;
mod phyg;
mod phylip;
@@ -21,7 +22,7 @@ use obisys::{Reporter, Stage};
use tracing::info;
use alignment_out::write_alignment_outputs;
use args::{DistanceArg, NSitesArg, distance_to_compute};
use values::{DistanceArg, NSitesArg, distance_to_compute};
use iqtree::write_iqtree;
use phyg::write_sankoff_phyg;
use stats::{write_sample_plan, write_sample_stats};
@@ -29,7 +30,7 @@ use phylip::write_phylip_relaxed;
use sankoff::{write_sankoff_alignment_fasta, write_sankoff_matrix_csv, write_sankoff_params};
use tnt::write_sankoff_tnt;
pub use args::PhyloArgs;
pub use args::{PhyloArgs, WORKFLOW_HELP};
pub fn run(args: PhyloArgs) {
let idx = Arc::new(KmerIndex::open(&args.index).unwrap_or_else(|e| {
@@ -56,7 +57,7 @@ pub fn run(args: PhyloArgs) {
// `cache.distance(...)` computation is unaffected either way.
let exclude_mask: Vec<bool> = {
let mut mask = vec![false; n];
for label in &args.exclude_genome {
for label in &args.select.exclude_genome {
match labels.iter().position(|l| l == label) {
Some(i) => mask[i] = true,
None => {
@@ -79,7 +80,7 @@ pub fn run(args: PhyloArgs) {
// ── Sibling-count/minorant annex (independent of the distance metric) ──
// Meant to be (re)built routinely, ahead of any SNP-family distance
// computation that will later consume it.
if args.sibling_annex {
if args.annex.sibling_annex {
// Writes into the index directory; `build_sibling_annex` holds the
// index's exclusive lock for the duration (`KmerIndex::with_lock`),
// so a concurrent run on the same index can't corrupt these writes.
@@ -93,7 +94,7 @@ pub fn run(args: PhyloArgs) {
}
// ── Sibling-count distribution (`--sibling-stats`) ──────────────────────────
if args.sibling_stats {
if args.annex.sibling_stats {
let t = Stage::start("sibling_stats");
let stats = cache.sibling_annex_stats().unwrap_or_else(|e| {
eprintln!("error computing sibling-annex stats: {e}");
@@ -126,7 +127,7 @@ pub fn run(args: PhyloArgs) {
}
// ── Family-size histogram (`--sibling-hist`) ────────────────────────────────
if args.sibling_hist {
if args.annex.sibling_hist {
let t = Stage::start("sibling_hist");
let counts = cache.sibling_family_size_histogram().unwrap_or_else(|e| {
eprintln!("error computing sibling family-size histogram: {e}");
@@ -153,7 +154,7 @@ pub fn run(args: PhyloArgs) {
}
// ── Family Overlap matrix (`--family-overlap`) ──────────────────────────────
if args.family_overlap {
if args.annex.family_overlap {
let t = Stage::start("family_overlap");
let overlap = cache.family_overlap(args.ambiguity()).unwrap_or_else(|e| {
eprintln!("error computing family overlap: {e}");
@@ -180,7 +181,7 @@ pub fn run(args: PhyloArgs) {
}
// ── Shannon entropy report (`--shannon`) ────────────────────────────────────
if args.shannon {
if args.annex.shannon {
let path = args.output.as_ref()
.map(|p| format!("{}_entropy.csv", p.display()))
.unwrap_or_else(|| "entropy.csv".into());
@@ -195,7 +196,7 @@ pub fn run(args: PhyloArgs) {
}
// ── Shannon entropy distribution (`--shannon-summary`) ──────────────────────
if args.shannon_summary {
if args.annex.shannon_summary {
let path = args.output.as_ref()
.map(|p| format!("{}_shannon_summary.csv", p.display()))
.unwrap_or_else(|| "shannon_summary.csv".into());
@@ -215,7 +216,7 @@ pub fn run(args: PhyloArgs) {
// `--pseudo-alignment`/`--sankoff`/`snp-*` `--distance` only, never the
// whole-index metrics' `kept`/`--shared-kmers` output (see
// `args::PhyloArgs::min_shared_family`'s own docs on why).
let snp_exclude_mask: Vec<bool> = match args.min_shared_family {
let snp_exclude_mask: Vec<bool> = match args.select.min_shared_family {
Some(threshold) => {
let overlap = cache.family_overlap(args.ambiguity()).unwrap_or_else(|e| {
eprintln!("error computing family overlap: {e}");
@@ -243,19 +244,19 @@ pub fn run(args: PhyloArgs) {
// Shared by `--pseudo-alignment` and `--sankoff` — same activation rule:
// either flag given activates entropy-biased sampling, the other
// defaults to 1.0/0.5.
let entropy_bias = if args.entropy.is_some() || args.entropy_sd.is_some() {
let entropy_bias = if args.sample.entropy.is_some() || args.sample.entropy_sd.is_some() {
Some(EntropyBias {
mu: args.entropy.unwrap_or(1.0),
sigma: args.entropy_sd.unwrap_or(0.5),
mu: args.sample.entropy.unwrap_or(1.0),
sigma: args.sample.entropy_sd.unwrap_or(0.5),
})
} else {
None
};
let sampling = SamplingSpec {
free_loss: args.free_loss,
free_loss: args.sample.free_loss,
ambiguity: args.ambiguity(),
quartet: args.quartet,
pair_balance: args.pair_balance,
quartet: args.sample.quartet,
pair_balance: args.sample.pair_balance,
entropy_bias,
};
@@ -266,7 +267,7 @@ pub fn run(args: PhyloArgs) {
// `algorithms::scan`'s own module docs) — persistence needs to be
// rebuilt on top of the new single `sampled_scan` trunk instead of
// silently becoming a no-op.
if args.session.is_some() {
if args.dist.session.is_some() {
eprintln!(
"error: --session is temporarily unavailable (being rebuilt on top of the unified \
sampling trunk) — rerun without --session/--session-force"
@@ -284,23 +285,23 @@ pub fn run(args: PhyloArgs) {
// instead of each running its own scan (which used to silently draw a
// different sample per flag — see `obikphylo::siblings::LayerReducer`'s
// own module docs).
let sankoff_requested = args.sankoff || args.tnt || args.phyg || args.iqtree;
let distance = distance_to_compute(args.distance, args.nj, args.upgma, args.shared_kmers);
let sankoff_requested = args.costs.sankoff || args.costs.tnt || args.costs.phyg || args.costs.iqtree;
let distance = distance_to_compute(args.dist.distance, args.dist.nj, args.dist.upgma, args.dist.shared_kmers);
let snp_kind = distance.and_then(DistanceArg::as_snp);
let need_alignment = args.alignment_output() || sankoff_requested;
let need_pairwise = sankoff_requested || snp_kind.is_some();
// `None` = every site (`--n-sites all`, or `--n-sites` omitted where it is optional)
let target = args.n_sites.and_then(NSitesArg::target);
let target = args.sample.n_sites.and_then(NSitesArg::target);
if args.alignment_output() && args.n_sites.is_none() {
if args.alignment_output() && args.sample.n_sites.is_none() {
eprintln!("error: --pseudo-alignment/--fasta/--vcf require --n-sites <N|all>");
std::process::exit(1);
}
if sankoff_requested && args.n_sites.is_none() {
if sankoff_requested && args.sample.n_sites.is_none() {
eprintln!("error: --sankoff requires --n-sites <N|all>");
std::process::exit(1);
}
if (args.sample_stats || args.sample_plan) && !(need_alignment || need_pairwise) {
if (args.sample.sample_stats || args.sample.sample_plan) && !(need_alignment || need_pairwise) {
eprintln!(
"error: --sample-stats/--sample-plan describe a draw: they need --pseudo-alignment, \
--sankoff or a snp-* --distance"
@@ -312,7 +313,7 @@ pub fn run(args: PhyloArgs) {
need_alignment.then(|| obikphylo::siblings::AlignmentReducer::new(&cache, &snp_exclude_mask));
let mut pairwise_reducer = need_pairwise.then(|| obikphylo::siblings::PairwiseReducer::new(n));
let mut stats_reducer =
args.sample_stats.then(|| obikphylo::siblings::SampleStatsReducer::new(n, &snp_exclude_mask));
args.sample.sample_stats.then(|| obikphylo::siblings::SampleStatsReducer::new(n, &snp_exclude_mask));
let mut sample_plan = None;
if need_alignment || need_pairwise {
@@ -349,7 +350,7 @@ pub fn run(args: PhyloArgs) {
if let Some(reducer) = stats_reducer {
write_sample_stats(&reducer.finish(), &labels, &snp_exclude_mask, &args.output);
}
if args.sample_plan {
if args.sample.sample_plan {
write_sample_plan(&sample_plan.expect("scanned above: need_alignment || need_pairwise"), &args.output);
}
@@ -377,13 +378,13 @@ pub fn run(args: PhyloArgs) {
let b = obikphylo::siblings::SankoffBundle::finish(
alignment,
pairwise,
args.sankoff_ratio_ceiling,
args.costs.sankoff_ratio_ceiling,
&snp_exclude_mask,
);
let p_card = cardinality_transition_probs(&b.cardinality_tally);
let p_comp = composition_transition_probs(&b.base_pair_tally);
let matrix = pairwise_cost_matrix(&p_card, &p_comp, args.free_loss);
let matrix = pairwise_cost_matrix(&p_card, &p_comp, args.sample.free_loss);
write_sankoff_matrix_csv(&matrix, &args.output);
write_sankoff_params(
@@ -391,32 +392,32 @@ pub fn run(args: PhyloArgs) {
&p_card,
&b.base_pair_tally,
&p_comp,
args.sankoff_ratio_ceiling,
args.costs.sankoff_ratio_ceiling,
&args.output,
);
write_sankoff_alignment_fasta(&b.alignment, &labels, &args.output, args.free_loss);
write_sankoff_alignment_fasta(&b.alignment, &labels, &args.output, args.sample.free_loss);
if args.tnt {
if args.costs.tnt {
write_sankoff_tnt(
&matrix,
&b.alignment,
&labels,
&args.output,
args.sankoff_cost_scale,
args.free_loss,
args.costs.sankoff_cost_scale,
args.sample.free_loss,
);
}
if args.phyg {
write_sankoff_phyg(&matrix, &args.output, args.sankoff_cost_scale);
if args.costs.phyg {
write_sankoff_phyg(&matrix, &args.output, args.costs.sankoff_cost_scale);
}
if args.iqtree {
if args.costs.iqtree {
write_iqtree(
&matrix,
&b.alignment,
&labels,
&args.output,
args.free_loss,
args.iqtree_min_freq,
args.sample.free_loss,
args.costs.iqtree_min_freq,
);
}
bundle = Some(b);
@@ -436,10 +437,10 @@ pub fn run(args: PhyloArgs) {
let (matrix, shared_kmers) = match distance.as_classic() {
Some(metric) => {
info!("computing {metric:?} distances for {n} genome(s)");
let need_shared = args.shared_kmers || args.nj || args.upgma;
let need_shared = args.dist.shared_kmers || args.dist.nj || args.dist.upgma;
let t = Stage::start("distance");
let result = cache
.distance(metric, need_shared, args.presence_threshold)
.distance(metric, need_shared, args.dist.presence_threshold)
.unwrap_or_else(|e| {
eprintln!("error computing distances: {e}");
std::process::exit(1);
@@ -448,12 +449,12 @@ pub fn run(args: PhyloArgs) {
(result.matrix, result.shared_kmers)
}
None => {
if args.shared_kmers {
if args.dist.shared_kmers {
eprintln!("error: --shared-kmers has no meaning for a snp-* --distance value");
std::process::exit(1);
}
let kind = snp_kind.expect("DistanceArg is always classic or snp");
let gamma_shape = args.gamma_shape.map_or(GammaShape::Disabled, Into::into);
let gamma_shape = args.dist.gamma_shape.map_or(GammaShape::Disabled, Into::into);
let t = Stage::start("snp_distance");
let matrix = match &bundle {
Some(b) => {
@@ -485,7 +486,7 @@ pub fn run(args: PhyloArgs) {
// ── Distance matrix → relaxed PHYLIP (default) or CSV (`--csv`) ────────────
let write_dist = |w: &mut dyn Write| {
if args.csv {
if args.dist.csv {
write!(w, "genome").unwrap();
for &j in &kept { write!(w, ",{}", labels[j]).unwrap(); }
writeln!(w).unwrap();
@@ -503,7 +504,7 @@ pub fn run(args: PhyloArgs) {
match &args.output {
Some(prefix) => {
let suffix = if args.csv { "_dist.csv" } else { "_dist.phy" };
let suffix = if args.dist.csv { "_dist.csv" } else { "_dist.phy" };
let path = format!("{}{suffix}", prefix.display());
let mut f = BufWriter::new(std::fs::File::create(&path).unwrap_or_else(|e| {
eprintln!("error creating {path}: {e}");
@@ -520,7 +521,7 @@ pub fn run(args: PhyloArgs) {
}
// ── Shared-kmer matrix → CSV ──────────────────────────────────────────────
if args.shared_kmers {
if args.dist.shared_kmers {
if let Some(shared) = &shared_kmers {
let path = args.output.as_ref()
.map(|p| format!("{}_shared.csv", p.display()))
@@ -542,7 +543,7 @@ pub fn run(args: PhyloArgs) {
}
// ── NJ tree ────────────────────────────────────────────────────────────────
if args.nj {
if args.dist.nj {
let tree = neighbor_joining(&matrix, &labels).unwrap_or_else(|e| {
eprintln!("error computing NJ tree: {e}");
std::process::exit(1);
@@ -559,7 +560,7 @@ pub fn run(args: PhyloArgs) {
}
// ── UPGMA tree ───────────────────────────────────────────────────────────────
if args.upgma {
if args.dist.upgma {
let newick = upgma(&matrix, &labels).to_newick();
let path = args.output.as_ref()
.map(|p| format!("{}_upgma.nwk", p.display()))
+177
View File
@@ -0,0 +1,177 @@
use obikphylo::{DistanceMetric, GammaShape, SnpDistanceKind};
/// `--gamma-shape` CLI value: a fixed `alpha`, or `auto`/`estimate` to fit
/// it from the data (see [`GammaShape::Auto`]). Kept as its own tiny type
/// (rather than parsing straight to `GammaShape`) so the CLI layer stays
/// free of `GammaShape::Disabled`, which the `Option<GammaShapeArg>` around
/// this already expresses on its own (`None` = flag not given at all).
#[derive(Debug, Clone, Copy)]
pub enum GammaShapeArg {
Fixed(f64),
Auto,
}
impl From<GammaShapeArg> for GammaShape {
fn from(arg: GammaShapeArg) -> Self {
match arg {
GammaShapeArg::Fixed(a) => GammaShape::Fixed(a),
GammaShapeArg::Auto => GammaShape::Auto,
}
}
}
pub fn parse_gamma_shape(s: &str) -> Result<GammaShapeArg, String> {
if s.eq_ignore_ascii_case("auto") || s.eq_ignore_ascii_case("estimate") {
return Ok(GammaShapeArg::Auto);
}
s.parse::<f64>()
.map(GammaShapeArg::Fixed)
.map_err(|_| format!("invalid --gamma-shape value {s:?}: expected a positive number or \"auto\"/\"estimate\""))
}
/// `--n-sites` CLI value: a number of sites to draw, or `all` for every site
/// — the draw then keeps every variable family that passes the other filters,
/// with no sampling involved. Its own tiny type (like [`GammaShapeArg`]) so
/// the two cases stay distinct up to the call that needs the target, instead
/// of an in-band sentinel (a negative number, `0`, ...) that a typo could hit.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum NSitesArg {
All,
N(usize),
}
impl NSitesArg {
/// The target to hand to the sampler: `None` = exhaustive.
pub fn target(self) -> Option<usize> {
match self {
NSitesArg::All => None,
NSitesArg::N(n) => Some(n),
}
}
}
pub fn parse_n_sites(s: &str) -> Result<NSitesArg, String> {
if s.eq_ignore_ascii_case("all") {
return Ok(NSitesArg::All);
}
s.parse::<usize>()
.map(NSitesArg::N)
.map_err(|_| format!("invalid --n-sites value {s:?}: expected a non-negative integer or \"all\""))
}
/// `--distance` value — either one of `obikphylo::DistanceMetric`'s
/// whole-index metrics (routed to `IndexCache::distance`) or one of
/// `obikphylo::SnpDistanceKind`'s `snp-*` corrections (routed to
/// `obikphylo::siblings::distance_matrix`, over a tally built by
/// `sampled_scan`/`PairwiseReducer`, the sibling-annex pipeline) — two
/// genuinely different code paths behind one CLI vocabulary, see
/// `DevDocMD/theory/evolutionary_distances.md`, "`--distance` unification".
#[derive(clap::ValueEnum, Clone, Copy, Debug)]
pub enum DistanceArg {
Jaccard,
Mash,
Hamming,
BrayCurtis,
#[value(name = "relfreq-bray-curtis")]
RelfreqBrayCurtis,
Euclidean,
#[value(name = "relfreq-euclidean")]
RelfreqEuclidean,
Hellinger,
#[value(name = "hellinger-euclidean")]
HellingerEuclidean,
#[value(name = "snp-raw")]
SnpRaw,
#[value(name = "snp-jc")]
SnpJc,
#[value(name = "snp-k2p")]
SnpK2p,
#[value(name = "snp-k81")]
SnpK81,
#[value(name = "snp-f81")]
SnpF81,
#[value(name = "snp-t92")]
SnpT92,
#[value(name = "snp-tn93")]
SnpTn93,
#[value(name = "snp-tv")]
SnpTv,
}
/// The distance matrix this invocation must compute, if any: the one asked for
/// with `--distance`, else `jaccard` when `--nj`, `--upgma` or
/// `--shared-kmers` needs a matrix to work from, else none — a matrix is never
/// computed (nor written) just because nothing said otherwise.
pub fn distance_to_compute(
distance: Option<DistanceArg>,
nj: bool,
upgma: bool,
shared_kmers: bool,
) -> Option<DistanceArg> {
distance.or_else(|| (nj || upgma || shared_kmers).then_some(DistanceArg::Jaccard))
}
#[cfg(test)]
mod distance_tests {
use super::*;
#[test]
fn nothing_asked_nothing_computed() {
assert!(distance_to_compute(None, false, false, false).is_none());
}
#[test]
fn tree_and_shared_kmer_outputs_imply_jaccard() {
for (nj, upgma, shared) in [(true, false, false), (false, true, false), (false, false, true)] {
assert!(matches!(
distance_to_compute(None, nj, upgma, shared),
Some(DistanceArg::Jaccard)
));
}
}
#[test]
fn an_explicit_distance_wins() {
assert!(matches!(
distance_to_compute(Some(DistanceArg::Mash), true, true, true),
Some(DistanceArg::Mash)
));
assert!(matches!(
distance_to_compute(Some(DistanceArg::SnpJc), false, false, false),
Some(DistanceArg::SnpJc)
));
}
}
impl DistanceArg {
/// `Some` for the whole-index metrics, `None` for `snp-*` values.
pub fn as_classic(self) -> Option<DistanceMetric> {
Some(match self {
DistanceArg::Jaccard => DistanceMetric::Jaccard,
DistanceArg::Mash => DistanceMetric::Mash,
DistanceArg::Hamming => DistanceMetric::Hamming,
DistanceArg::BrayCurtis => DistanceMetric::BrayCurtis,
DistanceArg::RelfreqBrayCurtis => DistanceMetric::RelfreqBrayCurtis,
DistanceArg::Euclidean => DistanceMetric::Euclidean,
DistanceArg::RelfreqEuclidean => DistanceMetric::RelfreqEuclidean,
DistanceArg::Hellinger => DistanceMetric::Hellinger,
DistanceArg::HellingerEuclidean => DistanceMetric::HellingerEuclidean,
_ => return None,
})
}
/// `Some` for the `snp-*` values, `None` for the whole-index metrics.
pub fn as_snp(self) -> Option<SnpDistanceKind> {
Some(match self {
DistanceArg::SnpRaw => SnpDistanceKind::Raw,
DistanceArg::SnpJc => SnpDistanceKind::Jc,
DistanceArg::SnpK2p => SnpDistanceKind::K2p,
DistanceArg::SnpK81 => SnpDistanceKind::K81,
DistanceArg::SnpF81 => SnpDistanceKind::F81,
DistanceArg::SnpT92 => SnpDistanceKind::T92,
DistanceArg::SnpTn93 => SnpDistanceKind::Tn93,
DistanceArg::SnpTv => SnpDistanceKind::Tv,
_ => return None,
})
}
}
+6 -6
View File
@@ -13,10 +13,11 @@ use tracing_subscriber::{EnvFilter, fmt};
#[derive(Parser)]
#[command(name = "obikmer2", about = "DNA k-mer tools", version)]
struct Cli {
/// Hard ceiling on the number of CPU cores the process may use — bounds
/// both the command's worker pool and every internal rayon pool.
/// Can only lower the budget, never raise it above the cores actually
/// available to the process. Defaults to that available count.
/// Maximum number of CPU cores to use
///
/// Caps every thread pool of the process. It can only lower the number of
/// cores, never raise it above those available. By default all available
/// cores may be used.
#[arg(long, global = true, value_name = "N")]
cpu_max: Option<usize>,
@@ -52,8 +53,7 @@ enum Commands {
Utils(cmd::utils::UtilsArgs),
/// Convert an index's evidence representation (exact/approximate/hybrid), in place
Convert(cmd::convert::ConvertArgs),
/// Genome-vs-genome distance matrix (+ optional NJ/UPGMA tree, sibling-annex-based
/// SNP corrections, Sankoff/TNT/PhyG/IQ-TREE exports)
#[command(after_long_help = cmd::phylo::WORKFLOW_HELP)]
Phylo(cmd::phylo::PhyloArgs),
}