Measure subgingival dysbiosis with the indices the literature already uses.
q2-periobiome turns a feature table and its taxonomy into the Socransky complexes, the Subgingival Microbial Dysbiosis Index (SMDI) and the Pérez-Chaparro 2014 fraction. Every taxon is traced to its source, every sample carries its own quality control, and the indices were tested on 16 public datasets.
$ qiime periobiome collapse-complexes \ --i-table table.qza \ --i-taxonomy taxonomy.qza \ --o-complex-table complexes.qza \ --o-indices indices.qza \ --o-mapping mapping.qza Saved PeriodontalIndices to: indices.qza sample group SMDI Red qc_sp ESP37 health -1.94 0.00 0.84 ESP58 health -2.52 0.00 0.58 ESP16 gingiv. -0.18 0.00 0.57 ESP19 gingiv. 0.75 0.00 0.86 ESP1 perio. 1.70 0.32 0.93 ESP3 perio. 1.00 0.38 0.89
Three published views of the same shift.
Periodontitis comes with a change in the subgingival community: late-colonizing anaerobes gain ground and early colonizers recede. Each measure captures that shift through a different, published lens. The plugin implements them as published and adds nothing of its own.
- Red · P. gingivalis, T. forsythia, T. denticola. Strongly associated with pocket depth and bleeding.
- Orange · Fusobacterium, Prevotella intermedia, Parvimonas micra, Campylobacter and others. The bridge to the Red complex.
- Yellow · S. mitis, S. oralis, S. sanguinis, S. gordonii, S. intermedius.
- Green · Capnocytophaga, E. corrodens, C. concisus.
- Purple · Veillonella parvula, Schaalia odontolytica.
- Blue · Actinomyces, the only group the 2002 figure names at genus level.
- Red … Blue, OtherSocransky 1998, 2002
- Fraction of all reads in each complex. Only species on the published panel are assigned; rows sum to 1.
- SMDIChen et al. 2022
- Mean CLR of 31 dysbiotic species minus mean CLR of 18 normobiotic species (MDG ≥ 0.4), computed as in the authors' R code.
- SMDI_simplifiedChen et al. 2022
- Fretibacterium and Treponema against Actinomyces. Needs genus names only.
- SMDI_customyour own signature
- Any list of dysbiotic and normobiotic taxa, computed with the SMDI method.
- PC2014_moderatePérez-Chaparro et al. 2014
- Fraction of reads from the 17 taxa with moderate evidence of association with periodontitis, matched by name or HMT number.
- qc_*computed by the plugin
- Sequencing depth, fraction of reads in any complex, fraction of reads named to species.
Many taxa that sequencing later tied to periodontitis (Fretibacterium, Filifactor alocis, Saccharibacteria, most Treponema) could not be cultivated in 1998 and are not on the Socransky panel. They stay in Other, and the SMDI and PC2014 capture them.
The arithmetic is simple. Getting it right is not.
These measures are usually computed by hand, each lab with its own species lists, name versions and pseudocounts, so the numbers do not compare across studies. The plugin fixes every choice, documents it and records it in QIIME 2 provenance.
Every taxon cites its source
Each row of the complex reference names the figure or sentence of Socransky 1998 or 2002 that supports it. Nothing is extrapolated to whole genera, except the one group the paper names as a genus.
The SMDI as published
The original code adds half the smallest non-zero relative abundance of the whole table to every entry, which is not what the paper's text says. The plugin follows the code, and offers a fixed pseudocount when run-independent values are needed.
Names that keep changing
Historical names are resolved (Bacteroides forsythus → Tannerella forsythia), eHOMD placeholders are parsed, and unnamed phylotypes are matched by HMT number whatever genus label a database version uses.
Quality control per sample
Depth, the fraction of reads in any complex and the fraction named to species are reported for every sample, and SMDI taxa absent from the table are listed in a warning.
An audit of every feature
The mapping table states, for each feature, the parsed name, the complex and why: species, genus, ambiguous, unassigned or low confidence.
Statistics that count patients once
summarize tests one pre-specified grouping and averages the sites of each subject first, so several sites from one mouth do not inflate the evidence.
Research use only. The indices summarize microbial composition. They are not diagnostic or prognostic tests and do not replace a clinical periodontal examination.
From a feature table to dysbiosis measures.
Four steps inside collapse-complexes. Each one leaves a trace in the outputs.
Parse the taxonomy
Genus, species, subspecies, eHOMD clades and HMT numbers are read from each label. Features below --p-min-confidence are set aside.
Assign the complexes
Species are matched against the published panel after synonym resolution. Labels that span two complexes become ambiguous and go to Other.
Compute the indices
Counts are aggregated to the signature's level, closed, given the published pseudocount and CLR-transformed. The SMDI is the difference of the two CLR means.
Report and check
Complex fractions, indices and qc_* columns per sample, plus the per-feature mapping. All three can be used as QIIME 2 Metadata.
Actions
- collapse-complexes
- Complexes, SMDI, SMDI_simplified, PC2014_moderate, QC and the mapping audit.
- summarize
- Offline HTML report: profiles, index distributions by group, one group test with effect size and q-values.
- delta-indices
- Follow-up minus baseline for every index, per subject or per site.
Input
- table
- Raw counts. Do not rarefy or normalize.
- taxonomy
- Classified to species against an oral reference, ideally eHOMD. Classifiers for V4, V3-V4 and V1-V2 can be trained with
scripts/train_classifiers.sh. - metadata
- Group and subject columns for
summarizeanddelta-indices.
Tested on 16 public datasets, negative results included.
Raw reads from public cohorts were reprocessed with one pipeline and analysed under a plan fixed in advance. Six cohorts independent of the SMDI's derivation enter the primary meta-analysis. The full report, with every deviation from the plan, is in docs/VALIDATION.md.
A two-sided, consistent shift
Higher Red complex and lower early colonizers, above all Actinomyces, in every cohort, 16S region and classifier.
Tracks severity
The SMDI correlates with probing depth, attachment loss and bleeding in the two cohorts with clinical data.
Falls after therapy
The median SMDI fell in every treated cohort (p < 0.05 in four) and rose in an untreated control arm.
SMDI vs Red complex
The 49-species SMDI beats the three Red species only slightly (95% CI 0.008–0.038). The simplified SMDI does not.
Groups, not individuals
Pooled sensitivity and specificity at the best published cut-off (SMDI > 0.5): about one patient in eight and one healthy subject in five fall on the wrong side.
No prognosis
Baseline values did not identify the sites or patients that failed to respond to therapy.
The validation was run under the plugin's earlier name, q2-periodontitis, with the same code. Absolute SMDI values shift with 16S region and pseudocount; ranking and AUC do not. Compare values computed with one pipeline.
One line inside a QIIME 2 environment.
- QIIME 2 2026.10, or the QIIME 2 amplicon 2024.10 distribution.
- No extra dependencies: everything the plugin needs ships with QIIME 2, hence
--no-deps. - Linux or macOS, as for QIIME 2.
- Check the installation with
qiime periobiome --help.
Since 2026.4 the amplicon plugins ship in the main QIIME 2 distribution.
wget https://raw.githubusercontent.com/qiime2/distributions/refs/heads/dev/2026.10/qiime2/released/rachis-qiime2-linux-64-conda.yml conda env create -n qiime2-2026.10 --file rachis-qiime2-linux-64-conda.yml conda activate qiime2-2026.10 pip install --no-deps git+https://github.com/LaBiOmicS/q2-periobiome.git qiime dev refresh-cache qiime periobiome --help
The last release of the separate amplicon distribution that the plugin is tested on.
wget https://data.qiime2.org/distro/amplicon/qiime2-amplicon-2024.10-py310-linux-conda.yml conda env create -n qiime2-2024.10 --file qiime2-amplicon-2024.10-py310-linux-conda.yml conda activate qiime2-2024.10 pip install --no-deps git+https://github.com/LaBiOmicS/q2-periobiome.git qiime dev refresh-cache
A QIIME 2 Library environment file that installs QIIME 2 and the plugin together (environment-files/).
wget https://raw.githubusercontent.com/LaBiOmicS/q2-periobiome/main/environment-files/q2-periobiome-rachis-qiime2-2026.10.yml conda env create -n q2-periobiome --file q2-periobiome-rachis-qiime2-2026.10.yml conda activate q2-periobiome
An editable install with the test and lint tools from environment.yml.
git clone https://github.com/LaBiOmicS/q2-periobiome.git cd q2-periobiome conda env update -n qiime2-2026.10 --file environment.yml conda activate qiime2-2026.10 pip install -e . --no-deps pytest && flake8
Common recipes.
Every action also ships usage examples: qiime periobiome <action> --example-data <dir> writes them out. A complete run on public data is in the tutorial.
Complexes, indices and QC
The core action. Raw counts and a species-level taxonomy in.
qiime periobiome collapse-complexes \ --i-table table.qza \ --i-taxonomy taxonomy.qza \ --o-complex-table complexes.qza \ --o-indices indices.qza \ --o-mapping mapping.qza
Group report, one unit per patient
Tests only the column you name, after averaging each subject's sites.
qiime periobiome summarize \ --i-complexes complexes.qza \ --i-indices indices.qza \ --i-mapping mapping.qza \ --m-metadata-file metadata.tsv \ --p-group-column status \ --p-subject-column subject \ --o-visualization summary.qzv
Change after therapy
Follow-up minus baseline for every index, per subject (or per site).
qiime periobiome delta-indices \ --i-indices indices.qza \ --m-metadata-file metadata.tsv \ --p-subject-col subject \ --p-group-col visit \ --p-baseline-group baseline \ --p-target-group follow-up \ --o-delta-table deltas.qza
Your own dysbiosis signature
Any list of dysbiotic and normobiotic taxa, computed with the SMDI method as SMDI_custom.
qiime tools import --type DysbiosisSignature \ --input-path my-signature.tsv \ --output-path my-signature.qza qiime periobiome collapse-complexes ... \ --i-smdi-signature my-signature.qza
SMDI comparable across runs
A fixed pseudocount makes each sample's SMDI independent of the rest of the table. Published cut-offs then shift.
qiime periobiome collapse-complexes ... \ --p-smdi-pseudocount 1e-5
Oral classifiers on eHOMD
Naive Bayes classifiers for V4, V3-V4 and V1-V2, trained in your own QIIME 2 environment.
bash scripts/train_classifiers.sh classifiers/
What the evidence covers.
q2-periobiome tells you
- How far a subgingival community has shifted towards the profile of periodontitis, by published and comparable measures.
- Which part of that shift comes from the Red complex, from the loss of early colonizers, or from taxa outside the Socransky panel.
- Whether a group differs from another, or changes after therapy, with one unit per patient.
- How much of each sample the measures actually cover, through the
qc_*columns.
It does not tell you
- Whether an individual has periodontitis: values overlap between groups, and no index is a diagnostic test.
- Who will respond to therapy: baseline values did not predict it.
- Absolute values that transfer between protocols: the SMDI shifts with 16S region, database and pseudocount.
- Whether the Socransky complexes exist as co-occurring groups: the plugin assumes them; it does not test them.
Everything behind the numbers.
Using q2-periobiome in your work.
The accompanying article is in preparation. Until it is published, please cite the software version you ran, together with the papers that define the measures. qiime periobiome --citations prints all of them as BibTeX.
@software{q2periobiome,
author = {Menegidio, Fabiano Bezerra and {LaBiOmicS}},
title = {{q2-periobiome}: Socransky complexes and dysbiosis indices
for subgingival 16S rRNA data},
version = {2026.10.0},
year = {2026},
url = {https://github.com/LaBiOmicS/q2-periobiome}
}Socransky et al. 1998, J Clin Periodontol 25:134. Socransky & Haffajee 2002, Periodontol 2000 28:12. Chen, Marsh & Al-Hebshi 2022, J Dent Res 101:331. Pérez-Chaparro et al. 2014, J Dent Res 93:846.