Protocol: sample-size-weighted metasignature pooling by body site and condition

Tier: C (BugSigDB paper) · Type: atomic · Category: Statistical Analysis

What

Aggregate the signatures sharing a body site and condition into a single weighted "metasignature", with each contributing signature weighted by its study's sample size, then compare metasignatures by best-match-average semantic similarity.

Why it matters

It is how the paper moves from thousands of individual signatures to an interpretable map of conditions. It also fixes the non-independence problem that the per-signature analyses have to apologize for: signatures from one large study stop counting the same as signatures from one small one.

Source material

• waldronlab/BugSigDBPaper — vignettes/Figure2.Rmd (clustering and the condition/body-site over-representation tests built on the pooled representation)
• Paper: 10.1038/s41587-023-01872-y

Scope

In: the weighting formula and which sample-size field it uses; what happens when sample size is missing; minimum number of signatures required to form a metasignature; direction handling (increased and decreased pooled separately); the similarity measure applied between metasignatures.

Out: the underlying semantic similarity computation (component protocol).

Frontmatter starting point

type: "atomic"
category: "Statistical Analysis"
citation: "10.1038/s41587-023-01872-y"   # Plausibly correct: the weighted metasignature construction
                                         # appears to be this paper's own. CONFIRM that it is not an
                                         # adaptation of prior pooling work before accepting it.
protocols_used:
  - name: "taxonomic-semantic-similarity"
tags: [bugsigdb, metasignature, pooling, weighting, body-site]

Acceptance criteria

• The weight is an explicit formula
• Missing sample size has a defined behavior
• States the minimum signature count for a metasignature to be reported

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, PROTOCOL_STANDARD.md, and the independent-filtering-variance protocol for format and level of detail. Inspect BugSigDBPaper's vignettes/Figure2.Rmd, trace the proposed method to its primary paper rather than relying on the candidate DOI, and document the formula, missing-size behavior, minimum count, direction handling, and similarity measure. Validate the completed protocol with Rscript agent-protocol-standard/scripts/validate-protocol.R protocols.