Protocol: centred log-ratio transformation of compositional abundances

Tier: D (cMD paper) · Type: atomic · Category: Data Transformation

What

Transform compositional relative abundances by taking the logarithm of each part divided by the geometric mean of all parts in that sample, after handling zeros with a stated rule.

Why it matters

CLR is a dependency of at least four other protocols in this batch — the effect-size protocols, the Aitchison beta-diversity protocol, and the covariate meta-analysis composite — and review asked that those analyses be runnable with or without it. That only works if CLR is a standalone protocol that a composite can include or omit, rather than a step baked into preprocessing.

It is also the clearest case in the batch for the original-citation rule: CLR was proposed by Aitchison in the compositional data literature. The cMD paper uses it. Only one of those is the citation.

Source material

• waldronlab/curatedMetagenomicDataAnalyses — python_tools/apply_a_transform.py, cMD3_paper_analyses/robustness arcsin vs clr/ (scatter_clr_vs_asin.py, do_the_figures.sh)
• Applied in: 10.1038/s41467-025-66888-1 — CLR with a 1×10⁻⁶ pseudocount, with an arcsin-square-root concordance analysis as sensitivity check

Scope

In: the CLR definition including exactly which parts enter the geometric-mean denominator; the zero-handling rule and the 1e-6 pseudocount as a stated default, with the acknowledgement that pseudocount choice propagates into every downstream distance and effect size; the interaction with upstream prevalence filtering and why order matters; what CLR values mean and the sub-compositional coherence caveat.

Out: prevalence filtering (separate protocol); the arcsin-square-root alternative, which is a different transformation with a different source and should be its own protocol if anyone wants it; the concordance comparison between the two, which belongs to a composite.

Frontmatter starting point

type: "atomic"
category: "Data Transformation"
citation: "10.1111/j.2517-6161.1982.tb01195.x"   # Aitchison 1982, JRSS-B — VERIFY; the 1986 book
                                                 # may be the better primary reference
tags: [clr, compositional, transformation, aitchison, microbiome]

Acceptance criteria

• Cites Aitchison, not the cMD paper
• Zero handling and the pseudocount are explicit, with the downstream-propagation caveat stated
• States the required ordering relative to prevalence filtering
• Can be omitted from a composite without breaking the protocols that declare it — i.e. the untransformed path is defined

Cite the method's origin, not its users

PROTOCOL_STANDARD.md is explicit: an atomic protocol carries "strictly 1 citation... corresponding
to the primary literature where the method was originally published." Find the paper that proposed
the method. Do not cite a paper that merely applied it — including the BugSigDB and curatedMetagenomicData
papers, which are the source of the analysis these protocols were extracted from but almost never the
source of the method.

Tracing a method back to its first publication is real work, and it is part of the task, not a
formality. Three things to expect:

• Candidate DOIs in this issue are leads, not answers. Anything marked VERIFY has not been checked.
• Some methods predate modern citation practice or have no single identifiable origin. If that is
  genuinely the case, say so in the pull request rather than reaching for a convenient recent paper.
  Raise it as an issue in waldronlab/agent-protocol-standard — the standard may need a way to express
  "classical method, no primary source".
• If you cannot name one paper that proposed everything the protocol does, it is more than one
  protocol. That test has now split four protocols out of this batch: enrichment into three methods,
  filtering from transformation, LODO from random forest, and PERMANOVA from ANOSIM.

Where the lab's own paper genuinely did propose the method — the oral-to-gut score, and LODO
cross-validation in Pasolli et al. 2016 — citing it is correct. That is the exception, not the pattern.

Before you start

Read CONTRIBUTING.md and
PROTOCOL_STANDARD.md.
The format is defined in the standard repo, not this one. Protocols are prose, not code: they say what to do
and why, precisely enough that two people — or two agents, in two languages — get the same answer. The existing
independent-filtering-variance
protocol is the model to imitate for tone and level of detail.

Validate locally before opening the PR:

git clone https://github.com/waldronlab/agent-protocol-standard.git
Rscript agent-protocol-standard/scripts/validate-protocol.R protocols

Read CONTRIBUTING.md and PROTOCOL_STANDARD.md first, then use protocols/independent-filtering-variance/protocol.md as the prose model. Check the cited Aitchison source and the listed curatedMetagenomicData materials, and define the CLR, zero handling, filtering order, caveat, and optional untransformed path. Validate the completed protocol with the provided Rscript command before opening a PR.