Protocol: assemble a case-control cohort from curatedMetagenomicData

Tier: B (bridge) · Type: atomic · Category: Curation & Data Preparation

What

Given a condition of interest, find the curatedMetagenomicData studies containing it, pull the case samples and that study's own controls, and merge them into a single feature-by-sample object with harmonized sample metadata — recording the study of origin for every sample.

Why it matters

This is the foundation of every cMD analysis in the family, and it encodes non-obvious decisions that are currently living in function bodies and comments: controls come from the same study only (never borrowed across studies), NielsenHB_2014 controls are duplicates of LeChatelierE_2013 and must be dropped, and the cMD version number belongs in the output filename. Those are exactly the things that quietly break an update to new data.

Source material

• waldronlab/curatedMetagenomicDataAnalyses — R/makeSEforCondition.R, R/dataDump.R (the NielsenHB_2014 deduplication and version stamping), vignettes/MLdatasets.Rmd, vignettes/identify_CRC_species.Rmd, vignettes/explorecirrhosis.Rmd
• Dataset inclusion criteria: vignettes/Age_metaanalysis_vignette.Rmd and Sex_metaanalysis_vignette.Rmd, "Retrieval of datasets from cMD meeting a series of requirements"

Scope

In: cMD version pinning; the dataset inclusion requirements (minimum sample size per group, required covariates present, body site, sequencing platform); same-study control rule; known duplicate-sample exclusions; counts-vs-relative-abundance choice; the per-sample study-of-origin label.

Out: transformation and filtering (Tier D); any modelling.

Frontmatter starting point

type: "atomic"
category: "Curation & Data Preparation"
citation: ~   # Data preparation, not a published method. See the note in A2.   # cMD meta-analysis, Nat Commun 2025
tags: [curatedmetagenomicdata, cohort-assembly, metadata, reproducibility]

Acceptance criteria

• Inclusion criteria are stated as explicit thresholds, not "as appropriate"
• The known duplicate-sample exclusions are listed by name, with the rule for adding to that list
• Output carries cMD version, per-study sample counts, and the study-of-origin variable

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 inspect R/makeSEforCondition.R, R/dataDump.R, and the listed cMD vignettes for inclusion rules, duplicate exclusions, and version handling. Draft the atomic protocol with explicit thresholds, same-study controls, provenance and output requirements, and verify its citation against the method's primary paper. Run the supplied Rscript validation command before opening the PR.