Protocol: assemble and QC a BugSigDB signature subset for a condition

Tier: A (fieldwork / first protocol) · Type: atomic · Category: Curation & Data Preparation

What

Every downstream BugSigDB analysis starts with the same handful of decisions, and today each student re-invents them in the first 40 lines of their vignette. This protocol specifies them once: importing a versioned BugSigDB export, selecting the studies/experiments relevant to a condition, dropping empty signatures, restricting to a single taxonomic level (exactly, not cumulatively), choosing an increased/decreased direction, and deciding what to do about near-duplicate signatures from the same study.

Why it matters

Nothing else in the BugSigDB protocol family is reproducible if the input set isn't defined. This is also the protocol that pins the data version — analyses currently differ silently because they were run against different hourly exports.

Source material

• waldronlab/bugSigSimple — R/simple.R (subsetByCurator, .isTaxLevel, .getTip), and the opening sections of vignettes/goldstandard_vignette_peace.Rmd ("Download BugSigDB data", "Remove empty signatures", "Select MASLD-related signatures", "Remove similar signatures")
• bugsigdbr::importBugSigDB(), bugsigdbr::getSignatures()
• Stable releases: https://zenodo.org/records/6468009

Selection must support several ways of naming the study set

Different users arrive with different starting points, and the protocol should accept all of them rather than forcing everyone through a condition string. At minimum:

The protocol must state how criteria combine (conjunction across criteria, disjunction within a vector), whether exclude beats include, and what happens when a criterion names something that matches nothing — silently returning an empty set is the failure mode to rule out.

Scope

In: data version pinning; the inclusion/exclusion criteria above and their combination rules; empty-signature removal; exact vs. cumulative taxonomic level; direction selection; near-duplicate handling; the record of counts at each filtering step.

Out: any statistical test; any plotting.

Frontmatter starting point

type: "atomic"
category: "Curation & Data Preparation"
citation: "10.1038/s41587-023-01872-y"   # BugSigDB, Nat Biotechnol 2023
tags: [bugsigdb, signatures, filtering, taxonomic-level, reproducibility]

Acceptance criteria

• Language-agnostic prose steps (no R code), per PROTOCOL_STANDARD.md
• Explicit, recorded outputs: the filtered signature set plus a table of how many studies/experiments/signatures survived each step
• States the rule for "similar signature" removal precisely enough that two people get the same answer
• Every selection criterion above is supported, with combination rules stated
• A criterion matching zero records is an error or a recorded warning, never a silent empty result
• Passes Rscript agent-protocol-standard/scripts/validate-protocol.R protocols

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 protocols/independent-filtering-variance/protocol.md first, then inspect R/simple.R and the named sections of vignettes/goldstandard_vignette_peace.Rmd. Trace the primary source for the protocol's method, document the selection and QC rules in language-agnostic prose, and validate the completed protocol with Rscript agent-protocol-standard/scripts/validate-protocol.R protocols.