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_sites = alignment.sequences.first().map_or(0, Vec::len);
|
||||||
let n_genomes = alignment.genome_indices.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 path = path_for("fasta");
|
||||||
let mut f = create(&path);
|
let mut f = create(&path);
|
||||||
for (&g, seq) in alignment.genome_indices.iter().zip(alignment.sequences.iter()) {
|
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}");
|
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 path = path_for("vcf");
|
||||||
let mut f = create(&path);
|
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}");
|
eprintln!("error writing {path}: {e}");
|
||||||
std::process::exit(1);
|
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 alignment_out;
|
||||||
mod args;
|
mod args;
|
||||||
|
mod values;
|
||||||
mod iqtree;
|
mod iqtree;
|
||||||
mod phyg;
|
mod phyg;
|
||||||
mod phylip;
|
mod phylip;
|
||||||
@@ -21,7 +22,7 @@ use obisys::{Reporter, Stage};
|
|||||||
use tracing::info;
|
use tracing::info;
|
||||||
|
|
||||||
use alignment_out::write_alignment_outputs;
|
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 iqtree::write_iqtree;
|
||||||
use phyg::write_sankoff_phyg;
|
use phyg::write_sankoff_phyg;
|
||||||
use stats::{write_sample_plan, write_sample_stats};
|
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 sankoff::{write_sankoff_alignment_fasta, write_sankoff_matrix_csv, write_sankoff_params};
|
||||||
use tnt::write_sankoff_tnt;
|
use tnt::write_sankoff_tnt;
|
||||||
|
|
||||||
pub use args::PhyloArgs;
|
pub use args::{PhyloArgs, WORKFLOW_HELP};
|
||||||
|
|
||||||
pub fn run(args: PhyloArgs) {
|
pub fn run(args: PhyloArgs) {
|
||||||
let idx = Arc::new(KmerIndex::open(&args.index).unwrap_or_else(|e| {
|
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.
|
// `cache.distance(...)` computation is unaffected either way.
|
||||||
let exclude_mask: Vec<bool> = {
|
let exclude_mask: Vec<bool> = {
|
||||||
let mut mask = vec![false; n];
|
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) {
|
match labels.iter().position(|l| l == label) {
|
||||||
Some(i) => mask[i] = true,
|
Some(i) => mask[i] = true,
|
||||||
None => {
|
None => {
|
||||||
@@ -79,7 +80,7 @@ pub fn run(args: PhyloArgs) {
|
|||||||
// ── Sibling-count/minorant annex (independent of the distance metric) ──
|
// ── Sibling-count/minorant annex (independent of the distance metric) ──
|
||||||
// Meant to be (re)built routinely, ahead of any SNP-family distance
|
// Meant to be (re)built routinely, ahead of any SNP-family distance
|
||||||
// computation that will later consume it.
|
// 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
|
// Writes into the index directory; `build_sibling_annex` holds the
|
||||||
// index's exclusive lock for the duration (`KmerIndex::with_lock`),
|
// index's exclusive lock for the duration (`KmerIndex::with_lock`),
|
||||||
// so a concurrent run on the same index can't corrupt these writes.
|
// 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`) ──────────────────────────
|
// ── Sibling-count distribution (`--sibling-stats`) ──────────────────────────
|
||||||
if args.sibling_stats {
|
if args.annex.sibling_stats {
|
||||||
let t = Stage::start("sibling_stats");
|
let t = Stage::start("sibling_stats");
|
||||||
let stats = cache.sibling_annex_stats().unwrap_or_else(|e| {
|
let stats = cache.sibling_annex_stats().unwrap_or_else(|e| {
|
||||||
eprintln!("error computing sibling-annex stats: {e}");
|
eprintln!("error computing sibling-annex stats: {e}");
|
||||||
@@ -126,7 +127,7 @@ pub fn run(args: PhyloArgs) {
|
|||||||
}
|
}
|
||||||
|
|
||||||
// ── Family-size histogram (`--sibling-hist`) ────────────────────────────────
|
// ── Family-size histogram (`--sibling-hist`) ────────────────────────────────
|
||||||
if args.sibling_hist {
|
if args.annex.sibling_hist {
|
||||||
let t = Stage::start("sibling_hist");
|
let t = Stage::start("sibling_hist");
|
||||||
let counts = cache.sibling_family_size_histogram().unwrap_or_else(|e| {
|
let counts = cache.sibling_family_size_histogram().unwrap_or_else(|e| {
|
||||||
eprintln!("error computing sibling family-size histogram: {e}");
|
eprintln!("error computing sibling family-size histogram: {e}");
|
||||||
@@ -153,7 +154,7 @@ pub fn run(args: PhyloArgs) {
|
|||||||
}
|
}
|
||||||
|
|
||||||
// ── Family Overlap matrix (`--family-overlap`) ──────────────────────────────
|
// ── Family Overlap matrix (`--family-overlap`) ──────────────────────────────
|
||||||
if args.family_overlap {
|
if args.annex.family_overlap {
|
||||||
let t = Stage::start("family_overlap");
|
let t = Stage::start("family_overlap");
|
||||||
let overlap = cache.family_overlap(args.ambiguity()).unwrap_or_else(|e| {
|
let overlap = cache.family_overlap(args.ambiguity()).unwrap_or_else(|e| {
|
||||||
eprintln!("error computing family overlap: {e}");
|
eprintln!("error computing family overlap: {e}");
|
||||||
@@ -180,7 +181,7 @@ pub fn run(args: PhyloArgs) {
|
|||||||
}
|
}
|
||||||
|
|
||||||
// ── Shannon entropy report (`--shannon`) ────────────────────────────────────
|
// ── Shannon entropy report (`--shannon`) ────────────────────────────────────
|
||||||
if args.shannon {
|
if args.annex.shannon {
|
||||||
let path = args.output.as_ref()
|
let path = args.output.as_ref()
|
||||||
.map(|p| format!("{}_entropy.csv", p.display()))
|
.map(|p| format!("{}_entropy.csv", p.display()))
|
||||||
.unwrap_or_else(|| "entropy.csv".into());
|
.unwrap_or_else(|| "entropy.csv".into());
|
||||||
@@ -195,7 +196,7 @@ pub fn run(args: PhyloArgs) {
|
|||||||
}
|
}
|
||||||
|
|
||||||
// ── Shannon entropy distribution (`--shannon-summary`) ──────────────────────
|
// ── Shannon entropy distribution (`--shannon-summary`) ──────────────────────
|
||||||
if args.shannon_summary {
|
if args.annex.shannon_summary {
|
||||||
let path = args.output.as_ref()
|
let path = args.output.as_ref()
|
||||||
.map(|p| format!("{}_shannon_summary.csv", p.display()))
|
.map(|p| format!("{}_shannon_summary.csv", p.display()))
|
||||||
.unwrap_or_else(|| "shannon_summary.csv".into());
|
.unwrap_or_else(|| "shannon_summary.csv".into());
|
||||||
@@ -215,7 +216,7 @@ pub fn run(args: PhyloArgs) {
|
|||||||
// `--pseudo-alignment`/`--sankoff`/`snp-*` `--distance` only, never the
|
// `--pseudo-alignment`/`--sankoff`/`snp-*` `--distance` only, never the
|
||||||
// whole-index metrics' `kept`/`--shared-kmers` output (see
|
// whole-index metrics' `kept`/`--shared-kmers` output (see
|
||||||
// `args::PhyloArgs::min_shared_family`'s own docs on why).
|
// `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) => {
|
Some(threshold) => {
|
||||||
let overlap = cache.family_overlap(args.ambiguity()).unwrap_or_else(|e| {
|
let overlap = cache.family_overlap(args.ambiguity()).unwrap_or_else(|e| {
|
||||||
eprintln!("error computing family overlap: {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:
|
// Shared by `--pseudo-alignment` and `--sankoff` — same activation rule:
|
||||||
// either flag given activates entropy-biased sampling, the other
|
// either flag given activates entropy-biased sampling, the other
|
||||||
// defaults to 1.0/0.5.
|
// 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 {
|
Some(EntropyBias {
|
||||||
mu: args.entropy.unwrap_or(1.0),
|
mu: args.sample.entropy.unwrap_or(1.0),
|
||||||
sigma: args.entropy_sd.unwrap_or(0.5),
|
sigma: args.sample.entropy_sd.unwrap_or(0.5),
|
||||||
})
|
})
|
||||||
} else {
|
} else {
|
||||||
None
|
None
|
||||||
};
|
};
|
||||||
let sampling = SamplingSpec {
|
let sampling = SamplingSpec {
|
||||||
free_loss: args.free_loss,
|
free_loss: args.sample.free_loss,
|
||||||
ambiguity: args.ambiguity(),
|
ambiguity: args.ambiguity(),
|
||||||
quartet: args.quartet,
|
quartet: args.sample.quartet,
|
||||||
pair_balance: args.pair_balance,
|
pair_balance: args.sample.pair_balance,
|
||||||
entropy_bias,
|
entropy_bias,
|
||||||
};
|
};
|
||||||
|
|
||||||
@@ -266,7 +267,7 @@ pub fn run(args: PhyloArgs) {
|
|||||||
// `algorithms::scan`'s own module docs) — persistence needs to be
|
// `algorithms::scan`'s own module docs) — persistence needs to be
|
||||||
// rebuilt on top of the new single `sampled_scan` trunk instead of
|
// rebuilt on top of the new single `sampled_scan` trunk instead of
|
||||||
// silently becoming a no-op.
|
// silently becoming a no-op.
|
||||||
if args.session.is_some() {
|
if args.dist.session.is_some() {
|
||||||
eprintln!(
|
eprintln!(
|
||||||
"error: --session is temporarily unavailable (being rebuilt on top of the unified \
|
"error: --session is temporarily unavailable (being rebuilt on top of the unified \
|
||||||
sampling trunk) — rerun without --session/--session-force"
|
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
|
// instead of each running its own scan (which used to silently draw a
|
||||||
// different sample per flag — see `obikphylo::siblings::LayerReducer`'s
|
// different sample per flag — see `obikphylo::siblings::LayerReducer`'s
|
||||||
// own module docs).
|
// own module docs).
|
||||||
let sankoff_requested = args.sankoff || args.tnt || args.phyg || args.iqtree;
|
let sankoff_requested = args.costs.sankoff || args.costs.tnt || args.costs.phyg || args.costs.iqtree;
|
||||||
let distance = distance_to_compute(args.distance, args.nj, args.upgma, args.shared_kmers);
|
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 snp_kind = distance.and_then(DistanceArg::as_snp);
|
||||||
let need_alignment = args.alignment_output() || sankoff_requested;
|
let need_alignment = args.alignment_output() || sankoff_requested;
|
||||||
let need_pairwise = sankoff_requested || snp_kind.is_some();
|
let need_pairwise = sankoff_requested || snp_kind.is_some();
|
||||||
// `None` = every site (`--n-sites all`, or `--n-sites` omitted where it is optional)
|
// `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>");
|
eprintln!("error: --pseudo-alignment/--fasta/--vcf require --n-sites <N|all>");
|
||||||
std::process::exit(1);
|
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>");
|
eprintln!("error: --sankoff requires --n-sites <N|all>");
|
||||||
std::process::exit(1);
|
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!(
|
eprintln!(
|
||||||
"error: --sample-stats/--sample-plan describe a draw: they need --pseudo-alignment, \
|
"error: --sample-stats/--sample-plan describe a draw: they need --pseudo-alignment, \
|
||||||
--sankoff or a snp-* --distance"
|
--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));
|
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 pairwise_reducer = need_pairwise.then(|| obikphylo::siblings::PairwiseReducer::new(n));
|
||||||
let mut stats_reducer =
|
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;
|
let mut sample_plan = None;
|
||||||
|
|
||||||
if need_alignment || need_pairwise {
|
if need_alignment || need_pairwise {
|
||||||
@@ -349,7 +350,7 @@ pub fn run(args: PhyloArgs) {
|
|||||||
if let Some(reducer) = stats_reducer {
|
if let Some(reducer) = stats_reducer {
|
||||||
write_sample_stats(&reducer.finish(), &labels, &snp_exclude_mask, &args.output);
|
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);
|
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(
|
let b = obikphylo::siblings::SankoffBundle::finish(
|
||||||
alignment,
|
alignment,
|
||||||
pairwise,
|
pairwise,
|
||||||
args.sankoff_ratio_ceiling,
|
args.costs.sankoff_ratio_ceiling,
|
||||||
&snp_exclude_mask,
|
&snp_exclude_mask,
|
||||||
);
|
);
|
||||||
|
|
||||||
let p_card = cardinality_transition_probs(&b.cardinality_tally);
|
let p_card = cardinality_transition_probs(&b.cardinality_tally);
|
||||||
let p_comp = composition_transition_probs(&b.base_pair_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_matrix_csv(&matrix, &args.output);
|
||||||
write_sankoff_params(
|
write_sankoff_params(
|
||||||
@@ -391,32 +392,32 @@ pub fn run(args: PhyloArgs) {
|
|||||||
&p_card,
|
&p_card,
|
||||||
&b.base_pair_tally,
|
&b.base_pair_tally,
|
||||||
&p_comp,
|
&p_comp,
|
||||||
args.sankoff_ratio_ceiling,
|
args.costs.sankoff_ratio_ceiling,
|
||||||
&args.output,
|
&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(
|
write_sankoff_tnt(
|
||||||
&matrix,
|
&matrix,
|
||||||
&b.alignment,
|
&b.alignment,
|
||||||
&labels,
|
&labels,
|
||||||
&args.output,
|
&args.output,
|
||||||
args.sankoff_cost_scale,
|
args.costs.sankoff_cost_scale,
|
||||||
args.free_loss,
|
args.sample.free_loss,
|
||||||
);
|
);
|
||||||
}
|
}
|
||||||
if args.phyg {
|
if args.costs.phyg {
|
||||||
write_sankoff_phyg(&matrix, &args.output, args.sankoff_cost_scale);
|
write_sankoff_phyg(&matrix, &args.output, args.costs.sankoff_cost_scale);
|
||||||
}
|
}
|
||||||
if args.iqtree {
|
if args.costs.iqtree {
|
||||||
write_iqtree(
|
write_iqtree(
|
||||||
&matrix,
|
&matrix,
|
||||||
&b.alignment,
|
&b.alignment,
|
||||||
&labels,
|
&labels,
|
||||||
&args.output,
|
&args.output,
|
||||||
args.free_loss,
|
args.sample.free_loss,
|
||||||
args.iqtree_min_freq,
|
args.costs.iqtree_min_freq,
|
||||||
);
|
);
|
||||||
}
|
}
|
||||||
bundle = Some(b);
|
bundle = Some(b);
|
||||||
@@ -436,10 +437,10 @@ pub fn run(args: PhyloArgs) {
|
|||||||
let (matrix, shared_kmers) = match distance.as_classic() {
|
let (matrix, shared_kmers) = match distance.as_classic() {
|
||||||
Some(metric) => {
|
Some(metric) => {
|
||||||
info!("computing {metric:?} distances for {n} genome(s)");
|
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 t = Stage::start("distance");
|
||||||
let result = cache
|
let result = cache
|
||||||
.distance(metric, need_shared, args.presence_threshold)
|
.distance(metric, need_shared, args.dist.presence_threshold)
|
||||||
.unwrap_or_else(|e| {
|
.unwrap_or_else(|e| {
|
||||||
eprintln!("error computing distances: {e}");
|
eprintln!("error computing distances: {e}");
|
||||||
std::process::exit(1);
|
std::process::exit(1);
|
||||||
@@ -448,12 +449,12 @@ pub fn run(args: PhyloArgs) {
|
|||||||
(result.matrix, result.shared_kmers)
|
(result.matrix, result.shared_kmers)
|
||||||
}
|
}
|
||||||
None => {
|
None => {
|
||||||
if args.shared_kmers {
|
if args.dist.shared_kmers {
|
||||||
eprintln!("error: --shared-kmers has no meaning for a snp-* --distance value");
|
eprintln!("error: --shared-kmers has no meaning for a snp-* --distance value");
|
||||||
std::process::exit(1);
|
std::process::exit(1);
|
||||||
}
|
}
|
||||||
let kind = snp_kind.expect("DistanceArg is always classic or snp");
|
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 t = Stage::start("snp_distance");
|
||||||
let matrix = match &bundle {
|
let matrix = match &bundle {
|
||||||
Some(b) => {
|
Some(b) => {
|
||||||
@@ -485,7 +486,7 @@ pub fn run(args: PhyloArgs) {
|
|||||||
|
|
||||||
// ── Distance matrix → relaxed PHYLIP (default) or CSV (`--csv`) ────────────
|
// ── Distance matrix → relaxed PHYLIP (default) or CSV (`--csv`) ────────────
|
||||||
let write_dist = |w: &mut dyn Write| {
|
let write_dist = |w: &mut dyn Write| {
|
||||||
if args.csv {
|
if args.dist.csv {
|
||||||
write!(w, "genome").unwrap();
|
write!(w, "genome").unwrap();
|
||||||
for &j in &kept { write!(w, ",{}", labels[j]).unwrap(); }
|
for &j in &kept { write!(w, ",{}", labels[j]).unwrap(); }
|
||||||
writeln!(w).unwrap();
|
writeln!(w).unwrap();
|
||||||
@@ -503,7 +504,7 @@ pub fn run(args: PhyloArgs) {
|
|||||||
|
|
||||||
match &args.output {
|
match &args.output {
|
||||||
Some(prefix) => {
|
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 path = format!("{}{suffix}", prefix.display());
|
||||||
let mut f = BufWriter::new(std::fs::File::create(&path).unwrap_or_else(|e| {
|
let mut f = BufWriter::new(std::fs::File::create(&path).unwrap_or_else(|e| {
|
||||||
eprintln!("error creating {path}: {e}");
|
eprintln!("error creating {path}: {e}");
|
||||||
@@ -520,7 +521,7 @@ pub fn run(args: PhyloArgs) {
|
|||||||
}
|
}
|
||||||
|
|
||||||
// ── Shared-kmer matrix → CSV ──────────────────────────────────────────────
|
// ── Shared-kmer matrix → CSV ──────────────────────────────────────────────
|
||||||
if args.shared_kmers {
|
if args.dist.shared_kmers {
|
||||||
if let Some(shared) = &shared_kmers {
|
if let Some(shared) = &shared_kmers {
|
||||||
let path = args.output.as_ref()
|
let path = args.output.as_ref()
|
||||||
.map(|p| format!("{}_shared.csv", p.display()))
|
.map(|p| format!("{}_shared.csv", p.display()))
|
||||||
@@ -542,7 +543,7 @@ pub fn run(args: PhyloArgs) {
|
|||||||
}
|
}
|
||||||
|
|
||||||
// ── NJ tree ────────────────────────────────────────────────────────────────
|
// ── NJ tree ────────────────────────────────────────────────────────────────
|
||||||
if args.nj {
|
if args.dist.nj {
|
||||||
let tree = neighbor_joining(&matrix, &labels).unwrap_or_else(|e| {
|
let tree = neighbor_joining(&matrix, &labels).unwrap_or_else(|e| {
|
||||||
eprintln!("error computing NJ tree: {e}");
|
eprintln!("error computing NJ tree: {e}");
|
||||||
std::process::exit(1);
|
std::process::exit(1);
|
||||||
@@ -559,7 +560,7 @@ pub fn run(args: PhyloArgs) {
|
|||||||
}
|
}
|
||||||
|
|
||||||
// ── UPGMA tree ───────────────────────────────────────────────────────────────
|
// ── UPGMA tree ───────────────────────────────────────────────────────────────
|
||||||
if args.upgma {
|
if args.dist.upgma {
|
||||||
let newick = upgma(&matrix, &labels).to_newick();
|
let newick = upgma(&matrix, &labels).to_newick();
|
||||||
let path = args.output.as_ref()
|
let path = args.output.as_ref()
|
||||||
.map(|p| format!("{}_upgma.nwk", p.display()))
|
.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)]
|
#[derive(Parser)]
|
||||||
#[command(name = "obikmer2", about = "DNA k-mer tools", version)]
|
#[command(name = "obikmer2", about = "DNA k-mer tools", version)]
|
||||||
struct Cli {
|
struct Cli {
|
||||||
/// Hard ceiling on the number of CPU cores the process may use — bounds
|
/// Maximum number of CPU cores to use
|
||||||
/// both the command's worker pool and every internal rayon pool.
|
///
|
||||||
/// Can only lower the budget, never raise it above the cores actually
|
/// Caps every thread pool of the process. It can only lower the number of
|
||||||
/// available to the process. Defaults to that available count.
|
/// cores, never raise it above those available. By default all available
|
||||||
|
/// cores may be used.
|
||||||
#[arg(long, global = true, value_name = "N")]
|
#[arg(long, global = true, value_name = "N")]
|
||||||
cpu_max: Option<usize>,
|
cpu_max: Option<usize>,
|
||||||
|
|
||||||
@@ -52,8 +53,7 @@ enum Commands {
|
|||||||
Utils(cmd::utils::UtilsArgs),
|
Utils(cmd::utils::UtilsArgs),
|
||||||
/// Convert an index's evidence representation (exact/approximate/hybrid), in place
|
/// Convert an index's evidence representation (exact/approximate/hybrid), in place
|
||||||
Convert(cmd::convert::ConvertArgs),
|
Convert(cmd::convert::ConvertArgs),
|
||||||
/// Genome-vs-genome distance matrix (+ optional NJ/UPGMA tree, sibling-annex-based
|
#[command(after_long_help = cmd::phylo::WORKFLOW_HELP)]
|
||||||
/// SNP corrections, Sankoff/TNT/PhyG/IQ-TREE exports)
|
|
||||||
Phylo(cmd::phylo::PhyloArgs),
|
Phylo(cmd::phylo::PhyloArgs),
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|||||||
Reference in new issue
Block a user