From 14433e80a53933862b6c576008849726c17690c9 Mon Sep 17 00:00:00 2001 From: Eric Coissac Date: Thu, 19 Nov 2026 06:18:57 +0100 Subject: [PATCH] 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`). --- src/obikmer/src/cmd/phylo/alignment_out.rs | 6 +- src/obikmer/src/cmd/phylo/args.rs | 558 --------------------- src/obikmer/src/cmd/phylo/args/distance.rs | 137 +++++ src/obikmer/src/cmd/phylo/args/mod.rs | 132 +++++ src/obikmer/src/cmd/phylo/args/outputs.rs | 132 +++++ src/obikmer/src/cmd/phylo/args/sampling.rs | 123 +++++ src/obikmer/src/cmd/phylo/args/select.rs | 113 +++++ src/obikmer/src/cmd/phylo/mod.rs | 93 ++-- src/obikmer/src/cmd/phylo/values.rs | 177 +++++++ src/obikmer/src/main.rs | 12 +- 10 files changed, 870 insertions(+), 613 deletions(-) delete mode 100644 src/obikmer/src/cmd/phylo/args.rs create mode 100644 src/obikmer/src/cmd/phylo/args/distance.rs create mode 100644 src/obikmer/src/cmd/phylo/args/mod.rs create mode 100644 src/obikmer/src/cmd/phylo/args/outputs.rs create mode 100644 src/obikmer/src/cmd/phylo/args/sampling.rs create mode 100644 src/obikmer/src/cmd/phylo/args/select.rs create mode 100644 src/obikmer/src/cmd/phylo/values.rs diff --git a/src/obikmer/src/cmd/phylo/alignment_out.rs b/src/obikmer/src/cmd/phylo/alignment_out.rs index 179828b4..01f05985 100644 --- a/src/obikmer/src/cmd/phylo/alignment_out.rs +++ b/src/obikmer/src/cmd/phylo/alignment_out.rs @@ -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); }); diff --git a/src/obikmer/src/cmd/phylo/args.rs b/src/obikmer/src/cmd/phylo/args.rs deleted file mode 100644 index 11dd2632..00000000 --- a/src/obikmer/src/cmd/phylo/args.rs +++ /dev/null @@ -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` 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 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 { - if s.eq_ignore_ascii_case("auto") || s.eq_ignore_ascii_case("estimate") { - return Ok(GammaShapeArg::Auto); - } - s.parse::() - .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 { - match self { - NSitesArg::All => None, - NSitesArg::N(n) => Some(n), - } - } -} - -fn parse_n_sites(s: &str) -> Result { - if s.eq_ignore_ascii_case("all") { - return Ok(NSitesArg::All); - } - s.parse::() - .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, - nj: bool, - upgma: bool, - shared_kmers: bool, -) -> Option { - 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 { - 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 { - 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, - - /// 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, - - /// 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 - /// (`_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 ` 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 (`_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 (`_alignment.vcf`): one - /// contig `obikmer__` 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, - - /// 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`): `_sample_genomes.csv` (per genome, the sites it - /// has a call in and the informative sites it takes part in), - /// `_sample_carriers.csv` (sites and informative sites per number - /// of carriers) and `_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`): `_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, - - /// Entropy-biased sampling kernel width (Gaussian standard deviation) - /// for `--pseudo-alignment` — see `--entropy`. - #[arg(long)] - pub entropy_sd: Option, - - /// 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, - - /// 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 `, 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 _sankoff.tnt, a ready-to-run TNT script (`proc - /// ;`) 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 _sankoff.tcm and _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 _iqtree.model and _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). `_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, - - /// 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, - - /// 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 - /// `labelvalue...` 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: _dist.csv, _shared.csv, _nj.nwk, - /// _upgma.nwk. If omitted, the distance matrix is written to stdout. - #[arg(short, long)] - pub output: Option, -} - -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 - } -} diff --git a/src/obikmer/src/cmd/phylo/args/distance.rs b/src/obikmer/src/cmd/phylo/args/distance.rs new file mode 100644 index 00000000..29a3e94c --- /dev/null +++ b/src/obikmer/src/cmd/phylo/args/distance.rs @@ -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, + + /// 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, + + /// 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, + + /// 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, +} diff --git a/src/obikmer/src/cmd/phylo/args/mod.rs b/src/obikmer/src/cmd/phylo/args/mod.rs new file mode 100644 index 00000000..cdc693d7 --- /dev/null +++ b/src/obikmer/src/cmd/phylo/args/mod.rs @@ -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, + + #[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 + } +} diff --git a/src/obikmer/src/cmd/phylo/args/outputs.rs b/src/obikmer/src/cmd/phylo/args/outputs.rs new file mode 100644 index 00000000..00eb3151 --- /dev/null +++ b/src/obikmer/src/cmd/phylo/args/outputs.rs @@ -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__`; `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, +} diff --git a/src/obikmer/src/cmd/phylo/args/sampling.rs b/src/obikmer/src/cmd/phylo/args/sampling.rs new file mode 100644 index 00000000..f0c4bf0d --- /dev/null +++ b/src/obikmer/src/cmd/phylo/args/sampling.rs @@ -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, + + /// 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, + + /// 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, + + /// 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, +} diff --git a/src/obikmer/src/cmd/phylo/args/select.rs b/src/obikmer/src/cmd/phylo/args/select.rs new file mode 100644 index 00000000..3619905a --- /dev/null +++ b/src/obikmer/src/cmd/phylo/args/select.rs @@ -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, + + /// 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, +} + +/// 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, +} diff --git a/src/obikmer/src/cmd/phylo/mod.rs b/src/obikmer/src/cmd/phylo/mod.rs index 1497713c..66944e89 100644 --- a/src/obikmer/src/cmd/phylo/mod.rs +++ b/src/obikmer/src/cmd/phylo/mod.rs @@ -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 = { 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 = match args.min_shared_family { + let snp_exclude_mask: Vec = 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 "); 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 "); 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())) diff --git a/src/obikmer/src/cmd/phylo/values.rs b/src/obikmer/src/cmd/phylo/values.rs new file mode 100644 index 00000000..b420bf62 --- /dev/null +++ b/src/obikmer/src/cmd/phylo/values.rs @@ -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` 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 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 { + if s.eq_ignore_ascii_case("auto") || s.eq_ignore_ascii_case("estimate") { + return Ok(GammaShapeArg::Auto); + } + s.parse::() + .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 { + match self { + NSitesArg::All => None, + NSitesArg::N(n) => Some(n), + } + } +} + +pub fn parse_n_sites(s: &str) -> Result { + if s.eq_ignore_ascii_case("all") { + return Ok(NSitesArg::All); + } + s.parse::() + .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, + nj: bool, + upgma: bool, + shared_kmers: bool, +) -> Option { + 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 { + 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 { + 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, + }) + } +} diff --git a/src/obikmer/src/main.rs b/src/obikmer/src/main.rs index f0ff8baa..6649437f 100644 --- a/src/obikmer/src/main.rs +++ b/src/obikmer/src/main.rs @@ -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, @@ -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), }