Protocol: per-dataset covariate-adjusted effect sizes (standardized mean difference)

Tier: D (cMD paper) · Type: atomic · Category: Statistical Analysis

What

Within each dataset separately, fit a per-feature linear model adjusting for the specified covariates (sequencing depth, sex, age, BMI as applicable), and convert the resulting t-statistic into a standardized mean difference with its standard error, for a binary exposure.

Why it matters

It is the first stage of every meta-analysis in the cMD paper, and the t-to-SMD conversion is precisely the step people get wrong or leave implicit. Writing it down as a protocol also forces a decision about what to do when a covariate is missing in a dataset — currently handled by the dataset inclusion criteria, but not stated anywhere as a rule.

Source material

• waldronlab/curatedMetagenomicDataAnalyses — vignettes/Sex_metaanalysis_vignette.Rmd ("linear modelling controlling for age & BMI", "Defining functions used to perform the analysis"), python_modules/meta_analyses.py (singleStudyEffect), python_tools/metaanalyze.py
• Paper: 10.1038/s41467-025-66888-1

Scope

In: the model formula and covariate set; the t-statistic to SMD conversion formula and the SE formula; handling of datasets where a covariate is absent or constant; features that fail to fit; the per-dataset output table schema that the pooling protocol consumes.

Out: pooling across datasets (separate protocol); the transformation (separate protocol).

Frontmatter starting point

type: "atomic"
category: "Statistical Analysis"
citation: "10.2307/1164588"   # Hedges 1981, the standardized mean difference — VERIFY; Cohen 1969
                              # sits behind it. NOT the cMD paper, which applies the estimator.
protocols_used:
  - name: "prevalence-filtering"
  - name: "clr-transformation"      # optional: see note
tags: [effect-size, smd, linear-model, covariate-adjustment, meta-analysis]

The transformation is a swappable slot, per review feedback — this analysis must be runnable with
or without CLR. Say explicitly what the untransformed path is and what changes in the interpretation,
rather than treating CLR as mandatory preprocessing.

Acceptance criteria

• Both the SMD and its SE are given as explicit formulas from the t-statistic and group sizes
• Missing/constant covariate behavior is defined
• Output schema is specified well enough that the pooling protocol can consume it unchanged

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 first. Compare the cited Rmd and Python entry points—Sex_metaanalysis_vignette.Rmd, python_modules/meta_analyses.py, and python_tools/metaanalyze.py—with the standard’s required format. Done means a validated protocol with one verified primary citation, explicit formulas and covariate handling, an unchanged-consumable output schema, and a passing Rscript validation run.