rsomics-composition

rsomics-composition is a single product for compositional-data geometry, log-ratio transforms, balance construction, zero handling, proportionality, structural-zero detection, and composition-native differential abundance.

It provides one binary with coherent subcommands instead of one crate per mathematical operation. Every table carries explicit sample and component identities, and operations align by identity rather than silently trusting row or column order.

cargo install rsomics-composition
rsomics-composition clr --input abundances.tsv --output clr.tsv
rsomics-composition ancom \
  --input abundances.tsv \
  --metadata samples.tsv \
  --group treatment \
  --output ancom.tsv \
  --percentiles-output percentiles.tsv

The input table is samples by components. The first field identifies samples; the remaining header fields are unique component names.

sample  taxon-a  taxon-b  taxon-c
s1      12       4        8
s2      3        9        6

TSV is the default grammar and --format csv selects CSV. A single input may use - for standard input. Results go to standard output unless --output names a transactional file. --json reserves standard output for the shared rsomics machine-readable success or error envelope, so data must then use a named output.

The command surface includes:

• Aitchison geometry: closure, perturb, power, centralize, and inner;
• log-ratio transforms: alr, clr, rclr, and ilr;
• balance construction from a default basis, SBP table, or bifurcating Newick tree;
• zero handling and proportionality: multi-replace, vlr, and struc-zero;
• one-way ANCOM with explicit degenerate-pair accounting and complete percentile output.

basis emits a named orthonormal table that can be reused directly with ilr --basis. Forward and inverse transforms preserve sample identities, and tree/SBP bases preserve component and balance identities.

Dense inner, pairwise vlr, and ancom matrices are checked before allocation. Their default ceiling is 25,000,000 cells and can be changed per command with --max-dense-cells; exceeding it fails before a result file is created.

Compatibility is checked against scikit-bio 0.7.3. The pinned live oracle contains 47 differential and failure checks, including randomized matrices; see oracle/scikit_bio_0_7_3.py. Representative full-workflow performance and raw measurements are in benchmarks/.