What it checks
In a study that samples the same people over time, each person's microbiome is a fingerprint. Their own samples resemble each other more than they resemble anyone else's. A sample that resembles somebody else better than its own person is a sign that something went wrong between the bench and the spreadsheet.
You give SwapSeq a feature table (ASVs, OTUs or taxa, as counts) and the sample sheet with a column saying who each sample came from. A plate and well column, a household column and a visit column are optional. Every person needs at least two samples.
Swapped tubes
Two samples carry each other's labels. SwapSeq names both and the pair.
Wrong labels
One sample carries someone else's label. SwapSeq says who it looks like.
Sample-sheet shifts
A run of tubes each carries its neighbour's label. SwapSeq reports the run and its wells.
Method
Everything runs in the browser, in plain JavaScript with no server. The same code (method/core.mjs) runs the benchmarks below.
Two fingerprints of every sample
Soft Jaccard keeps the presence of low-abundance strains, the part of a microbiome most specific to a person, and removes the effect of unequal sequencing depth without random rarefaction. Each feature gets its expected presence after subsampling to r reads:
ek = 1 − (1 − r / N)ck r = median depth ÷ 8
dJ(a,b) = 1 − Σ min(ea, eb) ⁄ Σ max(ea, eb)N is the sample's depth and ck its count for feature k. The second fingerprint is the Aitchison distance: Euclidean distance after a centred log-ratio transform of counts + 0.5, on features present in at least 5% of samples (up to the 3,000 most common).
Does a sample fit its own person?
si = log( down ⁄ dother )down is the soft Jaccard distance from sample i to the nearest other sample with the same label, and dother the distance to the nearest sample of anyone else. A score above zero means the sample sits closer to someone else; that person is reported as who it looks like.
Would swapping two labels fix both?
wij = log( owni ⁄ d(i, person of j) ) + log( ownj ⁄ d(j, person of i) )Averaged over both fingerprints, with the two samples themselves left out of each person's set. The maximum over every j with a different label is the swap score, and that j is the likely partner. A swap is reported only when two samples name each other and both carry swap evidence.
Learn what an error looks like in this study
The same score means different things on tongue swabs and on stool, or with daily and monthly sampling. So SwapSeq plants errors in a copy of the user's own labels, between 300 and 1,500 one-way relabels and as many reciprocal swaps, and records their scores. With f1 the density of planted-error scores and g the density of all observed scores:
P(error | s) = min( 1, π · f1(s) ⁄ g(s) ) π = 1% expected error rateDensities are Gaussian kernel estimates. P is made non-decreasing in the score, but only where observed scores actually lie, so a gap in the tail cannot create a false spike. The share of planted errors that would reach a strong flag is reported as the study's power, so a user knows when a clean result means little.
Strong flagKernel probability ≥ 0.5. Built for near-zero false alarms.
Check listA logistic fit of the same ratio ≥ 0.5, or kernel probability ≥ 0.2. Catches more, with some natural look-alikes. Hidden when fewer than 8 people have two or more samples.
Evidence for each flag
- Rare features. Of a flagged sample's rare features (in ≤ 5% of samples, with at least 2 reads), how many are also found in its own person and how many in the person it looks like.
- Households. If the look-alike lives in the same household, a strong flag moves to the check list.
- Wells. For a swap pair on one plate: adjacent, mirrored across the plate, diagonal or apart.
- Sheet shifts. Tubes are ordered down plate columns, along rows, or by a plating-order number. A run of three or more consecutive tubes, each closer to someone else and that someone being the person on its neighbour's label, is reported as a shift, and its tubes join the check list.
Data
Five public longitudinal studies, chosen to range from strong individual signal (adults, daily stool, shotgun) to almost none (newborns, mice all given one donor's stool). The last two act as negative controls: a good tool should say it cannot see, not invent flags.
| Study | Data | Tables used | Samples | People | Source |
|---|---|---|---|---|---|
| Student Microbiome ProjectFlores et al. 2014 | 16S OTUs, rarefied, weekly | gut tongue palm forehead | 638 692 515 675 | 75 80 61 80 | caporaso-lab |
| Immigration Microbiome ProjectVangay et al. 2018 | 16S de novo OTUs, monthly | gut, people with 2+ samples | 110 | 18 | knights-lab |
| Minnesota diet studyJohnson et al. 2019 | shallow shotgun, daily stool | strain level species | 526 483 | 37 34 | knights-lab |
| ECAMBokulich et al. 2016 | 16S, infants from birth | stool | 875 | 43 | q2-longitudinal |
| MDSINE2 miceGibson et al. 2025 | 16S, dense time series, one donor per group | healthy donor UC donor | 320 381 | 5 5 | gerberlab |
The species table of the diet study holds a subset of the strain-level samples, so the distinct total is 4,732 samples. Three before/after designs were also built by keeping only the first and last sample of each person in SMP gut, SMP forehead and the diet study. Blank and control samples were removed.
Test design
- Errors at about a 1% rate. In each repeat, 3 reciprocal swaps and 2 one-way relabels were planted in a copy of the labels; tables under 300 samples got 1 of each, and before/after designs 1 swap.
- 30 repeats per table with different random seeds (60 for the smaller IMP table).
- Clean ground truth. Errors were planted only into people with at least three samples, and never into samples SwapSeq already flagged on the untouched data.
- What was counted. The share of planted samples that reached a strong flag, and a flag or the check list. The share of swap pairs named exactly. False alarms per 1,000 untouched samples.
- Same settings throughout. The defaults the tool ships with: 1% expected error rate, flag at probability 0.5.
- A baseline. The identical pipeline with Bray-Curtis distance in place of the two fingerprints, the distance used by a recent mislabel detector for shotgun data. This isolates what the fingerprints add.
Results
On 16S data from adults, SwapSeq strongly flagged 40–92% of swapped samples, against 0–38% for Bray-Curtis in the same pipeline. On daily shotgun data, where every distance works well, the gap is small: 88–94% against 84–92%. Single mislabels are harder because there is no partner to confirm them; the check list recovers many of them.
Show the full results table
| Dataset | Samples | People | Swaps flagged | + check list | Bray-Curtis | Pairs named | Mislabels flagged | + check list | Bray-Curtis | False flags / 1000 | False checks / 1000 | Reported power |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| SMP gut | 638 | 75 | 92% | 97% | 23% | 91% | 77% | 88% | 12% | 0.1 | 0.4 | 94% |
| SMP tongue | 692 | 80 | 43% | 61% | 3% | 47% | 13% | 60% | 2% | 0.1 | 2.8 | 62% |
| SMP palm | 515 | 61 | 52% | 82% | 2% | 68% | 10% | 47% | 2% | 0.4 | 2.2 | 55% |
| SMP forehead | 675 | 80 | 89% | 98% | 38% | 84% | 62% | 68% | 8% | 0.3 | 1.3 | 80% |
| ECAM infants | 875 | 43 | 2% | 24% | 0% | 10% | 0% | 25% | 0% | 0.3 | 14.6 | 7% |
| SMP gut (2 per person) | 150 | 75 | 53% | 65% | 0% | 63% | – | – | – | 0.0 | 0.7 | 54% |
| SMP forehead (2 per person) | 160 | 80 | 40% | 80% | 3% | 80% | – | – | – | 0.0 | 0.2 | 25% |
| Diet study (strain-level) | 526 | 37 | 88% | 97% | 84% | 78% | 78% | 93% | 77% | 0.4 | 1.0 | 84% |
| Diet study (species) | 483 | 34 | 94% | 99% | 92% | 93% | 83% | 95% | 73% | 0.1 | 1.8 | 90% |
| MDSINE2 mice (healthy donor) | 320 | 5 | 3% | 48% | 0% | 17% | 0% | 32% | 0% | 0.1 | 13.2 | 3% |
| MDSINE2 mice (uc donor) | 381 | 5 | 0% | 16% | 0% | 2% | 0% | 18% | 0% | 0.0 | 15.7 | 0% |
| Diet study (strain-level) (2 per person) | 74 | 37 | 0% | 42% | 0% | 17% | – | – | – | 0.0 | 7.1 | 19% |
| IMP adults (16S) | 110 | 18 | 43% | 84% | 28% | 72% | 12% | 48% | 23% | 0.0 | 0.8 | 57% |
The power estimate tells the truth
Every run reports how many swaps SwapSeq could catch in that study. Across the 13 tables, that self-estimate sits close to the catch rate measured independently with the planted errors above. In the infant and mouse controls both are near zero, so a clean report there comes with a warning rather than false comfort.
Where it is weaker
- Tongue and palm. Single mislabels: 13% and 10% strongly flagged, 60% and 47% with the check list.
- IMP mislabels. 12% strongly flagged, 48% with the check list, where Bray-Curtis flagged 23%. One of the few places the baseline does better.
- Before/after with two samples each. With only two samples, a swap makes both people inconsistent and SwapSeq can name the two people more reliably than the tube. In the diet study's two-per-person design nothing reached a strong flag; 42% reached the check list.
- Check list in low-signal data. In infants and mice the check list carries 13–16 false entries per 1,000 samples. The power estimate is near zero there, and the tool says so.
Plate errors
Lab errors follow the plate. Neighbouring tubes get swapped, and a sample sheet that slips by one row shifts every label after it. These patterns were planted on the real plating order of the diet study (526 tubes over 6 plates), 30 repeats each.
Runs of five or more tubes were named as a shift in 90–100% of repeats. Three-tube runs were still flagged tube by tube (82%) but not named as a shift. No repeat produced a false shift report.
A real swap, found blind
In the Minnesota diet study the authors found two swapped stool tubes, MCT.f.0086 and MCT.f.0417, between participants MCTs06 and MCTs25, and corrected the labels in their published data. Restoring the original labels and running SwapSeq with its defaults, without telling it where to look:
Swap probability for the pair, in both the strain-level and the species table. The pair was the top result.
Rare strains of MCT.f.0417 also found in the person it was swapped with, against 3 in the person on its label.
Flags on the strain-level table once the authors' correction is put back.
With the original labels the strain-level table also gave one more strong flag and two check-list entries, each involving one of the two people in the swap, whose sample sets the swap had disturbed.
On the untouched data
Run on the published tables as they are, SwapSeq gave 12 strong flags among 4,732 samples. Ten were in the SMP tongue table, one in gut and one in palm; none in the IMP, diet, infant or mouse tables.
These may be real mix-ups or natural look-alikes. Tongue swabs carry the weakest individual signal of the four SMP sites, so its flags deserve the most caution. They have not been checked against lab records, so they are reported here as counts only. The SMP authors list samples they removed for suspected mix-ups; those samples are not in any published table, so they could not be used as a check.
Tried and dropped
Each idea below was built and run on the same benchmark. None caught more errors at the same false-alarm rate, or it broke a study design, so none shipped.
- Weighting rare features (IDF)Rare features already drive soft Jaccard; extra weight added noise.
- Whole-person count modelA negative binomial model of each person's counts. Slower and no better.
- Isotonic and tail-area calibrationLess smooth than the kernel, with worse false-alarm control at a 1% prior.
- Estimating the error rate (EM)Unstable when errors are rare, which is exactly the normal case.
- Ignoring same-visit look-alikesHelps when one batch makes samples look alike, but breaks before/after designs with two samples each.
- Blending nearest and median distanceDiluted the nearest-neighbour signal that a swap leaves.
Limits
- One confirmed real error. Everything else is planted. Planted errors are clean label exchanges; real mix-ups can also be partial, such as cross-contamination or a split sample.
- Narrow evidence base. Adult 16S results come from two studies, shotgun from one, and plate patterns from one real plating order.
- Development results. Settings were chosen on these tables.
- Needs repeat samples. At least two per person, better three. People who live together, antibiotics and illness all blur the fingerprint.
- Memory. All pairwise distances are held in the browser, so tables of many thousands of samples need a lot of memory. The largest table tested had 875 samples.
- A flag is a reason to check. Compare it with plate maps, extraction batches and sample sheets before relabelling or dropping anything. SwapSeq is a research QC tool, not a medical device.
Reproduce
Node.js 22 and nothing else. Clone the five source repositories into one folder (the layout is in method/load.mjs), then:
git clone https://github.com/bymankirat/swapseq cd swapseq export SWAPSEQ_DATA=~/swapseq-data # planted-error benchmark: 30 repeats, 1% prior SETS=gut,tongue,palm,forehead,ecam,gut2,forehead2 node method/bench.mjs 30 0.01 SETS=diet,dietsp,mdh,mdu,diet2 node method/bench.mjs 30 0.01 SETS=imp node method/bench.mjs 60 0.01 # same pipeline with Bray-Curtis SETS=gut,tongue,palm,forehead,ecam,gut2,forehead2 node method/bench.mjs 30 0.01 bc for L in 3 5 8; do node method/platebench.mjs burst 30 $L; done # plate swaps and sheet shifts node method/realswap.mjs # the real diet-study swap
Every number on this page is in the validation folder as JSON.
Cite and references
Singh M. (2026). SwapSeq: a sample mix-up checker for longitudinal microbiome studies (v1.0.1). Zenodo. https://doi.org/10.5281/zenodo.23963612
Studies and methods
- Flores GE et al. (2014). Temporal variability is a personalized feature of the human microbiome. Genome Biology 15:531. doi
- Vangay P et al. (2018). US immigration westernizes the human gut microbiome. Cell 175:962–972. doi
- Johnson AJ et al. (2019). Daily sampling reveals personalized diet-microbiome associations in humans. Cell Host & Microbe 25:789–802. doi
- Bokulich NA et al. (2016). Antibiotics, birth mode, and diet shape microbiome maturation during early life. Science Translational Medicine 8:343ra82. doi
- Gibson TE et al. (2025). Learning ecosystem-scale dynamics from microbiome data with MDSINE2. Nature Microbiology. PMC
- Aitchison J. (1986). The Statistical Analysis of Compositional Data. Chapman & Hall.