> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cosmosid.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Alpha diversity on Cosmos-Hub 2.0
> Run alpha-diversity analysis on Cosmos-Hub 2.0: the outputs it produces, how to read them, and the parameters that shape them.
The **Alpha diversity** module measures microbial taxonomic and functional diversity within a single sample. Alpha-diversity metrics calculated across all samples of your cohort are then compared across your groups of interest through panels of boxplots. The module also handles the statistics behind each comparison and produces exportable tables of statistical values for every comparison. For more on what alpha diversity is and how to interpret it, see the [Alpha diversity overview](https://docs.cosmosid.com/analysis/alpha-diversity/overview).
# Module output and customization
* **Alpha-diversity boxplot panels:** one panel per metric and statistical test, comparing alpha diversity across your groups of interest.
* **Alpha-diversity table (1):** a table of per-sample alpha diversity values for all samples in the analysis.
* **Statistical testing tables (3):** tables of statistical test results for every pairwise group comparison.
## Alpha-diversity boxplot panels
Each panel compares alpha-diversity distributions between the groups of interest, with pairwise brackets and q-values marking which group pairs differ significantly for the statistical test used.
Each panel reports:
* **Title**: the statistical test, the metric shown, and the grouping variable (for example, *Mann-Whitney test: richness by hiv\_riskgroup\_text*).
* **Axes**: the selected metric on the y-axis; the grouping variable on the x-axis, one boxplot per group.
* **Brackets between boxplots**: every significant pairwise comparison, labelled with its FDR-adjusted q-value.
The module produces one panel for each combination of selected **Alpha-diversity metric** and **Statistical Test Type**.
The [**Alpha-diversity metric**](#alpha-diversity-metric) sets which measure(s) of diversity are plotted. You can select more than one, and each produces its own set of panels.
| Metric | What it captures | Choose it when |
| :-------------------- | :----------------------------------------------------------------- | :-------------------------------------------------------------------------------------------- |
| **Observed richness** | How many different taxa/features are present | You want to compare the raw count of taxa or features detected in your samples. |
| **Shannon** | Richness and evenness; sensitive to rare taxa | You want a balanced measure, and changes in rare or moderately abundant taxa matter |
| **Simpson** | Weighted toward dominant taxa; stable when rare features are noisy | You care about the main community members and want to downweight noisy low-abundance features |
The [**Grouping Variable**](#grouping-variable) parameter sets how samples are split into groups along the x-axis: pick the metadata variable whose effect you want to study, such as disease status, treatment, or body site.
The [**Statistical Test Type**](#statistical-test-type) sets which test is run between groups. Each selected test runs **pairwise** on every pair of groups, and a bracket is drawn for a pair when its FDR-adjusted q-value falls below the [FDR threshold](#fdr-threshold). You must select at least one, and each selected test produces its own panel.
P-values below a certain value (typically 0.05) indicate a statistically significant difference between those groups, meaning they have distinct alpha diversity distributions.
| Test | When to use? |
| :--------------- | :--------------------------------------------------------------------------------------------------------------------------- |
| **Mann-Whitney** | Independent groups with non-normal data; the safest default for most microbiome studies (for example, cases versus controls) |
| **Wilcoxon** | Paired or matched samples (for example, the same subjects before and after treatment) |
| **T-test** | Independent groups whose alpha-diversity distributions are approximately normal with comparable variance |
#### **Which test fits my design?**
First ask: *are the same subjects measured in more than one group, or are all subjects different?*
* **Use `Mann–Whitney U` for independent groups.**
Example: You compare alpha diversity between 10 treated mice and 10 untreated mice. Each mouse appears in only one group, so values cannot be paired across groups. The groups are independent → `Mann–Whitney U` is appropriate.
* **Use `Wilcoxon` for paired or matched samples.**
Example: You compare alpha diversity in the same 10 mice before and after treatment. Each mouse contributes one “before” and one “after” value, so every value has a natural partner from the same animal. The samples are paired → `Wilcoxon` tests the within-subject change.
**Reminder:** Equal group sizes do **not** make a design paired. Two groups of 10 different mice are still independent, and `Mann–Whitney U` is the correct nonparametric test.
**How Statistical testing works on this module:**
Each test you choose from the **Statistical Test Type** parameter is applied pairwise: it runs on every pair of groups that can possibly be composed from your groups, comparing their alpha diversity distributions two at a time. With three groups, for example, this means three comparisons (A versus B, A versus C, B versus C), whereas four groups means 6 comparisons, and 8 groups means 28.
More comparisons means more hypotheses tested, something that inflates the chance of false positives, results that by chance fall below the significance threshold even when the two groups are truly equal.
This is the multiple comparisons problem. For this reason, the list of p-values for all the comparisons must be corrected for multiple testing using FDR (Benjamini-Hochberg), which raises each p-value according to how many comparisons were made, so a difference is called significant only if it would still stand out among that many tests.
If a pairwise comparison is still significant after correction (below the [FDR threshold](https://docs.cosmosid.com/#fdr-threshold)), the corrected value, the q-value, is what appears on the bracket.
We recommend treating a comparison as statistically significant only when its FDR-adjusted q-value falls below your chosen FDR threshold.
### A special statistical test: Kruskal-Wallis and Dunn's test
Alongside the pairwise tests you select, the module always runs a **Kruskal-Wallis** test followed by **Dunn's post-hoc test**. These answer a different question from your chosen tests, which is why it helps to read them together.
* **Kruskal-Wallis** is a single non-parametric test (it does not assume normal data) that asks one global question: does at least one group differ from the rest? Because it is one test rather than many, its false-positive rate does not grow with the number of groups the way a set of separate pairwise tests does, so it is a useful first check of whether there is any group effect at all. It does not say which groups differ.
* **Dunn's post-hoc test** identifies which pairs drive a significant Kruskal-Wallis result. It ranks all samples together and compares each pair using the whole dataset, so its pairwise results stay consistent with the global test and with each other. The false-positive rate across Dunn's pairs is then held in check by the FDR correction described above, not by Kruskal-Wallis itself.
You can explore full statistical output of KW + Dunn's test in files `df_kruskal.csv` and `df_dunn.csv`, included in the output export of the module.
### Why is this plot useful?
* **Assess the impact of biological factors on within-sample diversity:** boxplots sitting at clearly different heights, with a significant bracket, suggest that the biological factor (disease, treatment, diet) might be a driver of community composition and richness.
* **Spot outliers within single groups:** single dots far from the main distribution might flag a contaminated sample (usually richer, depending on how rich the contamination source is), a mislabelled sample, or a genuine outlier pointing to a distinct responder.
* **Which part of the community changed:** comparing the richness, Shannon, and Simpson panels shows where the change sits. A difference in richness but not Simpson means rare taxa shifted while the dominant members held steady, pointing to a different mechanism than a change among the dominant community.
* **Dose-response trend:** when the grouping variable has a natural order, such as disease stage or time after treatment, a stepwise rise or fall across the boxes suggests a monotonic relationship between alpha-diversity and the variable.
## Statistical output tables
Export the per-sample alpha-diversity values and the full statistical results of the pairwise comparisons by scrolling to the end of the output page and clicking **Download Tables and Images**:
| Table | What it contains |
| :----------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`df_alpha.csv`** | Sample-level alpha-diversity values: one row per sample, with a column for each calculated metric (`richness`, `shannon`, `simpson`). Useful for inspecting, exporting, or reusing the diversity values directly. |
| **`df_kruskal.csv`** | The overall Kruskal-Wallis result for each metric (`feature`, `H_stat`, `p_value`, `fdr`), testing whether that metric differs across the groups of the grouping variable. A significant `fdr` means at least one group differs, but not which pair. |
| **`df_dunn.csv`** | Dunn's post-hoc pairwise comparisons following Kruskal-Wallis (`feature`, `group_value1`, `group_value2`, `q_value`), showing which specific group pairs differ for each metric. |
| **`df_diff_abundance_pairwise.csv`** | Pairwise comparisons of alpha-diversity values between groups for the tests you selected (Mann-Whitney, Wilcoxon, t-test): group names, sample sizes, group medians, effect size, test statistics, p-values, FDR-adjusted values, and significance flags. |
## Recommended parameters
Select your workflow to see the recommended values. Note that pre-processing parameters vary per data type.
| Parameter | Recommended value |
| :------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Analysis Metric | `relative_abundance` |
| Taxonomic Rank | `species` |
| Data Table Pre-processing Method | - `raw` if samples have comparable read depths
- `filter` if a few samples have notably lower read depth than the rest of the cohort
- `rarefaction` to standardize the whole cohort to a common read depth
Observed Richness depends strongly on read depth: deeper samples yield more detected taxa. Check how much read depth varies across your cohort in the [rarefaction module](https://docs.cosmosid.com/DAP_docs/rarefaction-on-the-dap), and if variability is high, apply `rarefaction` before concluding that richness differs between groups. |
| Read Depth | - With `rarefaction`, use the [Rarefaction module](DAP_docs/rarefaction-on-the-dap) to choose the optimal depth. Any sample below the chosen depth is discarded, so the depth sets a trade-off between depth and sample size.
- With `filter`, choose a threshold that removes only the samples with notably lower depth than the rest of the cohort. Use the [Rarefaction module](DAP_docs/rarefaction-on-the-dap) retention plot helps identify them.
|
| Feature Relative Abundance Threshold | `0` |
| Feature Prevalence Threshold | `0` |
| Grouping Variable | Categorical metadata of interest |
| Drop samples with missing metadata values in grouping variable | ✅ |
| Alpha-diversity metric | See [Alpha-diversity](#alpha-diversity-boxplot-panels) metrics |
| Statistical Test Type | - `Mann-Whitney` independent groups, each subject in one group only (for example case versus control)
- `Wilcoxon` paired samples, each subject in both groups (for example pre versus post treatment)
- `t-test` independent groups, roughly normal values, at least 20 samples per group
[Which test fits my design?](#which-test-fits-my-design) |
| P-value threshold | `0.05` |
| FDR threshold | - Exploratory analyses: `0.2`
- Confirmatory analyses: `0.05`
|
| Parameter | Recommended value |
| :------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Analysis Metric | `relative_abundance` |
| Taxonomic Rank | `species` |
| Data Table Pre-processing Method | - `raw` if samples have comparable read depths
- `filter` if a few samples have notably lower read depth than the rest of the cohort
- `rarefaction` to standardize the whole cohort to a common read depth
Observed Richness depends strongly on read depth: deeper samples yield more detected taxa. Check how much read depth varies across your cohort in the [rarefaction module](https://docs.cosmosid.com/DAP_docs/rarefaction-on-the-dap), and if variability is high, apply `rarefaction` before concluding that richness differs between groups. |
| Read Depth | - With `rarefaction`, use the [Rarefaction module](DAP_docs/rarefaction-on-the-dap) to choose the optimal depth. Any sample below the chosen depth is discarded, so the depth sets a trade-off between depth and sample size.
- With `filter`, choose a threshold that removes only the samples with notably lower depth than the rest of the cohort. Use the [Rarefaction module](DAP_docs/rarefaction-on-the-dap) retention plot helps identify them.
|
| Feature Relative Abundance Threshold | `0.0001` |
| Feature Prevalence Threshold | `0` |
| Grouping Variable | Categorical metadata of interest |
| Drop samples with missing metadata values in grouping variable | ✅ |
| Alpha-diversity metric | See [Alpha-diversity](#alpha-diversity-boxplot-panels) metrics |
| Statistical Test Type | - `Mann-Whitney` independent groups, each subject in one group only (for example case versus control)
- `Wilcoxon` paired samples, each subject in both groups (for example pre versus post treatment)
- `t-test` independent groups, roughly normal values, at least 20 samples per group
[Which test fits my design?](#which-test-fits-my-design) |
| P-value threshold | `0.05` |
| FDR threshold | - Exploratory analyses: `0.2`
- Confirmatory analyses: `0.05`
|
| Parameter | Recommended value |
| :------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Analysis Metric | `relative_abundance`
|
| Taxonomic Rank | `genus` |
| Data Table Pre-processing Method | - `raw` if samples have comparable read depths
- `filter` if a few samples have notably lower read depth than the rest of the cohort
- `rarefaction` to standardize the whole cohort to a common read depth
Observed Richness depends strongly on read depth: deeper samples yield more detected taxa. Check how much read depth varies across your cohort in the [rarefaction module](https://docs.cosmosid.com/DAP_docs/rarefaction-on-the-dap), and if variability is high, apply `rarefaction` before concluding that richness differs between groups. |
| Read Depth | - With `rarefaction`, use the [Rarefaction module](DAP_docs/rarefaction-on-the-dap) to choose the optimal depth. Any sample below the chosen depth is discarded, so the depth sets a trade-off between depth and sample size.
- With `filter`, choose a threshold that removes only the samples with notably lower depth than the rest of the cohort. Use the [Rarefaction module](DAP_docs/rarefaction-on-the-dap) retention plot helps identify them.
|
| Feature Relative Abundance Threshold | `0.001` |
| Feature Prevalence Threshold | `0` |
| Grouping Variable | Categorical metadata of interest |
| Drop samples with missing metadata values in grouping variable | ✅ |
| Alpha-diversity metric | See [Alpha-diversity](#alpha-diversity-boxplot-panels) metrics |
| Statistical Test Type | - `Mann-Whitney` independent groups, each subject in one group only (for example case versus control)
- `Wilcoxon` paired samples, each subject in both groups (for example pre versus post treatment)
- `t-test` independent groups, roughly normal values, at least 20 samples per group
[Which test fits my design?](#which-test-fits-my-design) |
| P-value threshold | `0.05` |
| FDR threshold | - Exploratory analyses: `0.2`
- Confirmatory analyses: `0.05`
|
| Parameter | Recommended value |
| :------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Analysis Metric | `relative_abundance` |
| Taxonomic Rank | `species` |
| Data Table Pre-processing Method | - `raw` if samples have comparable read depths
- `filter` if a few samples have notably lower read depth than the rest of the cohort
- `rarefaction` to standardize the whole cohort to a common read depth
Observed Richness depends strongly on read depth: deeper samples yield more detected taxa. Check how much read depth varies across your cohort in the [rarefaction module](https://docs.cosmosid.com/DAP_docs/rarefaction-on-the-dap), and if variability is high, apply `rarefaction` before concluding that richness differs between groups. |
| Read Depth | - With `rarefaction`, use the [Rarefaction module](DAP_docs/rarefaction-on-the-dap) to choose the optimal depth. Any sample below the chosen depth is discarded, so the depth sets a trade-off between depth and sample size.
- With `filter`, choose a threshold that removes only the samples with notably lower depth than the rest of the cohort. Use the [Rarefaction module](DAP_docs/rarefaction-on-the-dap) retention plot helps identify them.
|
| Feature Relative Abundance Threshold | `0.0001` |
| Feature Prevalence Threshold | `0` |
| Grouping Variable | Categorical metadata of interest |
| Drop samples with missing metadata values in grouping variable | ✅ |
| Alpha-diversity metric | See [Alpha-diversity](#alpha-diversity-boxplot-panels) metrics |
| Statistical Test Type | - `Mann-Whitney` independent groups, each subject in one group only (for example case versus control)
- `Wilcoxon` paired samples, each subject in both groups (for example pre versus post treatment)
- `t-test` independent groups, roughly normal values, at least 20 samples per group
[Which test fits my design?](#which-test-fits-my-design) |
| P-value threshold | `0.05` |
| FDR threshold | - Exploratory analyses: `0.2`
- Confirmatory analyses: `0.05`
|
| Parameter | Recommended value |
| :----------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Analysis Metric | `relative abundance` |
| Data Table Pre-processing Method | - `raw`
- `filter` if a few samples have notably lower read depth than the rest of the cohort
|
| Feature Relative Abundance Threshold | `0.0001` |
| Feature Prevalence Threshold | `0` |
| Grouping Variable | Categorical metadata of interest |
| Alpha-diversity metric | See [Alpha-diversity](#alpha-diversity-boxplot-panels) metrics |
| Statistical Test Type | - `Mann-Whitney` independent groups, each subject in one group only (for example case versus control)
- `Wilcoxon` paired samples, each subject in both groups (for example pre versus post treatment)
- `t-test` independent groups, roughly normal values, at least 20 samples per group
[Which test fits my design?](#which-test-fits-my-design) |
| P-value threshold | `0.05` |
| FDR threshold | - Exploratory analyses: `0.2`
- Confirmatory analyses: `0.05`
|
| Parameter | Recommended value |
| :------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Analysis Metric | `cellular abundance` |
| Data Table Pre-processing Method | - `raw`
- `filter` if a few samples have notably lower read depth than the rest of the cohort
|
| Feature Relative Abundance Threshold | `0.0001` |
| Feature Prevalence Threshold | `0` |
| Grouping Variable | Categorical metadata of interest |
| Drop samples with missing metadata values in grouping variable | ✅ |
| Alpha-diversity metric | See [Alpha-diversity](#alpha-diversity-boxplot-panels) metrics |
| Statistical Test Type | - `Mann-Whitney` independent groups, each subject in one group only (for example case versus control)
- `Wilcoxon` paired samples, each subject in both groups (for example pre versus post treatment)
- `t-test` independent groups, roughly normal values, at least 20 samples per group
[Which test fits my design?](#which-test-fits-my-design) |
| P-value threshold | `0.05` |
| FDR threshold | - Confirmatory analyses: `0.05`
|
| Parameter | Recommended value |
| :----------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Analysis Metric | `relative abundance` |
| Data Table Pre-processing Method | - `raw` if samples have comparable read depths
- `filter` if a few samples have notably lower read depth than the rest of the cohort
|
| Feature Relative Abundance Threshold | `0.0001` |
| Feature Prevalence Threshold | `0` |
| Grouping Variable | Categorical metadata of interest |
| Alpha-diversity metric | See [Alpha-diversity](#alpha-diversity-boxplot-panels) metrics |
| Statistical Test Type | - `Mann-Whitney` independent groups, each subject in one group only (for example case versus control)
- `Wilcoxon` paired samples, each subject in both groups (for example pre versus post treatment)
- `t-test` independent groups, roughly normal values, at least 20 samples per group
[Which test fits my design?](#which-test-fits-my-design) |
| P-value threshold | `0.05` |
| FDR threshold | - Exploratory analyses: `0.2`
- Confirmatory analyses: `0.05`
|
## Analysis parameter reference
The metadata column used to define the groups compared in the analysis. It should reflect the biological question or study hypothesis you want to test.
**Options** · Categorical variables from the metadata table associated with the query used to create the analysis
**Default** · `None`
**Suggested** · A categorical variable relevant to your study design, such as `treatment`, `disease status`, `condition`, `body site`, `cohort`, or `time point`.
When no grouping variable is selected, alpha-diversity values are shown for the whole cohort, with no group-based comparison.
The diversity metric(s) calculated per sample and plotted on the y-axis. You can select more than one; each produces its own set of panels.
**Options** · `richness`, `shannon`, `simpson`
**What's the difference between Shannon and Simpson?**
Shannon diversity is calculated from each taxon's relative abundance multiplied by its logarithm, so it reflects both richness and evenness and is more sensitive to rare taxa. Simpson diversity is based on squared relative abundances, so it gives more weight to dominant taxa and is less affected by rare ones.
**In practice:** Shannon is usually more informative when changes in rare or moderately abundant taxa matter. Simpson is more stable when low-abundance features are noisy, but it may hide differences that occur mainly among rare taxa.
The statistical test used to compare alpha-diversity values between groups. Available when a **Grouping Variable** is selected. The right test depends on your study design, in particular whether samples are independent or paired/matched. In addition to the test(s) you choose here, **Kruskal-Wallis (followed by Dunn's post-hoc) is always run and reported**.
**Options** · `Wilcoxon`, `Mann-Whitney`, `T-test`
**Which test fits my design?**
First ask: *are the same subjects measured in more than one group, or are all subjects different?*
* **Use** `Mann–Whitney U `**for independent groups.**
Example: You compare alpha diversity between 10 treated mice and 10 untreated mice. Each mouse appears in only one group, so values cannot be paired across groups. The groups are independent → `Mann–Whitney U` is appropriate.
* **Use** `Wilcoxon `**for paired or matched samples.**
Example: You compare alpha diversity in the same 10 mice before and after treatment. Each mouse contributes one “before” and one “after” value, so every value has a natural partner from the same animal. The samples are paired → `Wilcoxon` tests the within-subject change.
**Reminder:** Equal group sizes do **not** make a design paired. Two groups of 10 different mice are still independent, and `Mann–Whitney U` is the correct nonparametric test.
Using the wrong test can be misleading. Don't use `Wilcoxon` for independent groups; it's meant for paired or matched comparisons. Don't use `Mann-Whitney` for paired samples, since it ignores the pairing structure and can reduce statistical power.
The p-value cutoff that controls which pairwise comparisons get a significance bracket on the boxplots. It's applied to the raw p-value of **every pairwise test you selected**, in each panel (one panel per alpha-diversity metric), so it governs the significance brackets shown between groups, not which features or metrics are analyzed.
**Options** · Numeric value between `0` and `1`
**Default** · `0.05`
**Suggested** · Use `0.05` as the standard threshold. A more stringent value such as `0.01` reduces the chance of reporting false positives.
This threshold is applied to the **original** (unadjusted) test p-value. Use the **FDR threshold** below to gate significance on the multiple-testing-corrected value instead.
The threshold used to report significance **after** multiple-testing correction (Benjamini-Hochberg). This matters most when the grouping variable has **many categories**: more groups means more pairwise comparisons, and FDR adjustment keeps the overall rate of false positives across all of them in check.
**Options** · Numeric value between `0` and `1`
**Default** · `0.05`
**Suggested** · Use `0.05` as standard. A more stringent value such as `0.01` gives stronger control over false positives when many comparisons are performed.
### References
**Chao1 Index** (Chao, A. (1987). “Estimating the population size for capture-recapture data with unequal catchability.” Biometrics 43(4): 783–791.+
**Shannon-Weaver Index** (Shannon, C. E. (1948). “A mathematical theory of communication.” Bell System Technical Journal, 27, 379–423 & 623–656.)
**Simpson Index** (Simpson, E. H. (1949). “Measurement of diversity.” Nature, 163(4148), 688.)