Protocol: Jaccard similarity between signatures at a single taxonomic level

Tier: A (fieldwork) · Type: atomic · Category: Statistical Analysis

What

Compute pairwise Jaccard similarity — intersection over union — between microbial signatures whose taxa have first been harmonized to a single taxonomic rank. The output is a signature-by-signature similarity matrix and nothing more.

Why it matters

It is the cheapest and most interpretable way to ask whether two signatures overlap, and it is what three separate student analyses each reimplemented slightly differently.

Note the narrowed scope. This issue originally bundled the similarity calculation with clustering and plotting. Those moved to a separate protocol (signature-similarity-clustering) so that the same clustering step can be fed by either Jaccard or semantic similarity. See the discussion in that issue.

Source material

• waldronlab/bugSigSimple — vignettes/healthysig.Rmd ("Calculate pairwise overlaps"), vignettes/goldstandard_vignette_peace.Rmd ("Pairwise overlaps", "Jaccard similarity matrix")
• waldronlab/BugSigDBPaper — vignettes/Figure2.Rmd ("Jaccard matrix on genus level")

Scope

In: the rank-harmonization step that must precede the calculation and what information it discards; the minimum signature length to include (the vignettes use ≥ 2 taxa); whether increased and decreased signatures are compared to each other; the diagonal and same-study pairs; the treatment of signatures left empty by harmonization.

Out: clustering, distance conversion, heatmaps, dendrograms — all now in signature-similarity-clustering. Similarity across mixed ranks — that is taxonomic-semantic-similarity.

Frontmatter starting point

type: "atomic"
category: "Statistical Analysis"
citation: "10.1111/j.1469-8137.1912.tb05611.x"   # Jaccard 1912 — VERIFY; see the citation note below
tags: [jaccard, similarity, signatures, taxonomic-level]

Jaccard first set out the coefficient in his alpine flora work; the 1912 New Phytologist paper is the usual English-language primary citation, with an earlier 1901 Bulletin de la Société Vaudoise paper behind it. Establish which is correct and cite that — not the BugSigDB paper, which merely uses the measure.

Acceptance criteria

• Cites the original source of the Jaccard coefficient, not a paper that applies it
• Minimum signature length is a stated, justified parameter
• Says what happens to signatures emptied by rank harmonization
• Output is a similarity matrix with a documented layout that signature-similarity-clustering consumes 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 and PROTOCOL_STANDARD.md first, then use independent-filtering-variance as the format model. Compare the pairwise-overlap sections in the cited R Markdown vignettes while resolving the rank harmonization, length, empty-signature, and matrix-layout requirements. Done means a validated protocol with one verified primary Jaccard citation; run the provided Rscript validator before opening a PR.