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:
1 parent
7f829ea557
commit
14433e80a5
10 files changed
+870
-613
No files matched your search
@@ -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);
|
||||
});
|
||||
|
||||
@@ -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
|
||||
}
|
||||
}
|
||||
@@ -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,
|
||||
}
|
||||
@@ -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
|
||||
}
|
||||
}
|
||||
@@ -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,
|
||||
}
|
||||
@@ -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,
|
||||
}
|
||||
@@ -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,
|
||||
}
|
||||
@@ -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()))
|
||||
|
||||
@@ -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,
|
||||
})
|
||||
}
|
||||
}
|
||||
@@ -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),
|
||||
}
|
||||
|
||||
|
||||
Reference in new issue
Block a user