This page covers how beta-diversity analysis works on Cosmos-Hub 2.0: the outputs it produces, how to read them, and the parameters you can tune. For the theory behind beta diversity and the ordination methods, see the Beta diversity overview.

Module output and customization

Beta-diversity ordination plot(s): one ordination plot for each method currently available on Cosmos-Hub 2.0 (PCoA, MDS, t-SNE, and UMAP).
PCoA scree plot: a PCoA-specific plot showing the proportion of distance variation captured by each PCoA axis.
Beta-diversity Statistical testing (Permanova and Anosim): a heatmap showing statistical support for differences between the groups defined by the grouping variable, one cell per pairwise comparison.
Statistical output tables (5): the data behind the PCoA ordination and scree plot, plus the PERMANOVA and ANOSIM results for the overall and pairwise group comparisons.

Beta-diversity ordination plot(s)

P Co A Scatter — Beta-diversity ordination. Each point is one sample, colored by sex_text (male/female) and shaped by hiv_serostatus_text (positive/negative). Ellipses summarize the spread of the sex groups, showing whether they separate or overlap.

The ordination plot maps how microbial communities relate to one another across samples, based on how similar or different their compositions are.

Each point represents one sample: the distance separating two points in the ordination plot is proportional to how different their microbial feature profiles are. When working with taxonomic profiles, distance tells you how similar their microbial communities are. When looking at functional profiles, it tells you how similar their functional profiles are.

1. Choose how to measure sample distances.

Choose the method used to calculate the sample-to-sample pairwise distance matrix from the Beta-diversity metric dropdown. This choice is important, as it actively changes how the distance matrix used by the ordination methods for plotting is generated. Different beta-diversity metrics can lead to profoundly different ordination plots.

A few of the most popular metrics include:

Bray-Curtis: for relative-abundance data, when you want differences in composition to be weighted by how abundant each taxon is. It is a popular, intuitive default.
Jaccard: specific for presence/absence data. Useful when you care about which taxa are shared or not shared, regardless of their abundance.
Aitchison: when you want to keep into account the compositional nature of sequencing data. Because sequencing measures relative, not absolute, abundances, an apparent rise in one taxon can just reflect a drop in another, which can create spurious patterns.

How Aitchison works? The Aitchison metric addresses compositionality by comparing samples using log-ratios between features. It first applies a CLR (centered log-ratio) transformation, where each feature in a sample is divided by a per-sample reference value and then log-transformed. When Aitchison is selected as distance metric from the parameter, the Centroid Method lets you set this per-sample reference value. You can choose between:

Mean: the geometric mean of the sample (the standard CLR choice). Best when the data is fairly clean.
Median: more robust to outliers and noisy low-abundance taxa, often useful for sparse data.

2. Customize the ordination plot

Once distances are computed, these parameters control how the plot is built and annotated:

From your categorical metadata variables, choose one of interest from the Grouping Variable parameter dropdown. Data points in the ordination plots are assigned different colors depending on which group of that variable they belong to. This is the main way to visually inspect whether the variable you chose (treatment, body site, and so on) displays any pattern in the community structure.

Choice of the Grouping Variable governs between which groups PERMANOVA/ANOSIM testing is done.
Overlay a second categorical variable as point shape using the Shape Variable parameter. This is useful to keep track of another categorical variable (for example, Treatment encoded as the Grouping variable + Timepoint encoded as the Shape variable).
Choose to display the ordination plot in 2D or 3D: change the Number of Components parameter. A 2D ordination plot is usually the best choice to maintain readability of the plot, but a 3D plot can be useful when the first two components do not capture enough of the variation, so an important separation between groups stays hidden in 2D but becomes visible once a third axis is added.
The Max ellipses and Confidence level parameters control the group ellipses drawn on the plot, which summarize where each group of samples sits and how spread out it is.
Drop samples with missing grouping metadata removes samples that have no value for the grouping variable, keeping the plot and the comparison clean.
Keeping them can instead be useful to get a sense of where an unlabeled sample falls, for example whether it sits near a known group.

Why it’s useful

Explore overall similarity: close samples have similar communities; distant samples differ.
Assess whether your metadata explains community structure: color samples by a variable (treatment, disease status, body site, and so on) and check whether it lines up with visible patterns. If the groups are mixed, that variable may not explain much of the variation; if they cluster or separate, it may be associated with community differences, but first rule out study-design or technical variables (batch, cohort, sampling site).
Spot batch or technical effects: if samples cluster by sequencing batch, study site, run, extraction method, processing date, or cohort, consider this before reading the pattern as biology.
Detect outlier or suspicious samples: samples expected to be similar (replicates, or longitudinal samples from one subject) should sit close together. If one clusters with an unrelated subject, it may be a true biological shift, or a sample swap, label mismatch, contamination, or processing issue worth checking.

3. Statistical testing

The ordination plot shows whether your groups appear to separate. Statistical testing checks whether that separation is real or could be due to chance. The module runs two permutation tests, PERMANOVA and ANOSIM, for every pair of groups in your grouping variable. Both use the same distance matrix as the ordination plot, so the test and the plot describe the same differences between samples.

What is a permutation test? Common tests such as the t-test compare one measured value per sample, for example the abundance of a single species, and calculate the p-value from a known distribution such as the bell curve. Beta diversity gives a different kind of data. The result is a distance between every pair of samples, so each sample contributes to many values at once, and these distances do not follow a known distribution. A permutation test solves this by building its reference distribution directly from your own data.Take gut samples from 10 antibiotic-treated mice and 10 control mice. If the antibiotic had no effect on the gut community, the labels “treated” and “control” would carry no information, and swapping them between mice would make no difference. The test measures how well the real labels separate the samples, then shuffles the labels at random and measures the separation again. After 999 shuffles, it counts how many random labellings separate the samples as well as the real one. If only 4 of the 999 shuffles do as well, the p-value is about 0.005, and the separation between treated and control mice is unlikely to be due to chance. The number of shuffles is set by the Number of permutations parameter.

Two parameters control the testing:

The Grouping Variable defines the groups being compared. It is the same variable you used to colour the plot, so the visual pattern and the statistical result refer to the same groups.
The Number of permutations controls the precision of the p-value. With 999 permutations, the smallest p-value the test can return is 0.001. More permutations give a more precise p-value and take longer to run.

The results are summarised in the PERMANOVA/ANOSIM heatmap.

Pairwise Beta Tests Matrix — Pairwise PERMANOVA and ANOSIM results for dermotypes in skin samples, with 999 permutations. The lower triangle shows PERMANOVA results. The upper triangle shows ANOSIM results. Each cell shows the FDR adjusted q-value for one pair of dermotypes. An asterisk marks a significant comparison. Darker cells indicate lower q-values on a log scale. Numbers in parentheses on the y-axis show the sample size of each dermotype.

The heatmap is split along the diagonal. Cells below the diagonal show PERMANOVA results and cells above the diagonal show ANOSIM results. Each pair of groups therefore appears twice, once in each triangle, in mirrored positions. For example, if group A is listed above group B on the y-axis, the PERMANOVA result for the pair sits in row B, column A, and the ANOSIM result sits in row A, column B. Each cell shows the FDR adjusted q-value for one pairwise comparison. A q-value is a p-value adjusted for multiple testing. Every additional pairwise comparison adds a chance of a false positive, and the false discovery rate (FDR) correction keeps the expected proportion of false positives among the significant cells low. Lower q-values mean stronger evidence that the two groups differ in composition. A q-value shows how unlikely a difference is to be due to chance, and it gives no information about the size of the difference. Use the ordination plot to judge how large the separation is.

PERMANOVA and ANOSIM in brief. Both tests ask whether samples from the same group are more similar to each other than to samples from other groups, that is, whether your grouping variable separates the data better than random chance would.

PERMANOVA tests whether the centroids of the groups differ. A centroid is the average position of a group’s samples in the space defined by the distances. The test statistic, pseudo-F, compares distances between groups with distances within groups, in a similar way to ANOVA. PERMANOVA works on the actual distance values.
ANOSIM ranks all distances from smallest to largest and compares the average rank between groups with the average rank within groups. Its statistic R ranges from about −1 to 1. Values near 0 indicate no separation and values near 1 indicate strong separation.

Choosing between PERMANOVA and ANOSIM. Read the PERMANOVA result first. It uses the actual distance values, it generally has more statistical power (the ability to detect a difference that really exists), and it is the test most microbiome studies report. Use ANOSIM as a second check on the same pair of groups.Both tests are sensitive to dispersion, that is, how widely the samples of a group are spread around their centroid. Two groups with the same average composition can still give a significant result if one group is much more variable than the other. ANOSIM is more affected by differences in dispersion than PERMANOVA. PERMANOVA becomes more affected when the groups have very different sample sizes.When the two tests disagree, compare the result with the ordination plot.

PERMANOVA	ANOSIM	What it usually means	What to check
Significant	Significant	Strong evidence that the two groups differ in composition.	Confirm in the ordination plot that the groups are shifted relative to each other, and that one group is not only more spread out.
Significant	Not significant	The groups differ, but the difference is modest. A few very different samples can drive PERMANOVA, because it uses the distance values, while ANOSIM gives them less weight because it uses ranks. With small groups, the lower power of ANOSIM can also explain the result.	Look for outlier samples in the ordination plot. If one group is much wider than the other and the group sizes are unequal, interpret the PERMANOVA result with caution.
Not significant	Significant	Less common. This pattern usually reflects a difference in spread between the groups rather than in their average composition.	Check whether one group forms a tight cluster and the other is widely scattered. Describe the result as a difference in variability between the groups.
Not significant	Not significant	No evidence of a difference in composition between the two groups.	Check the sample sizes in parentheses. With few samples per group, both tests may lack the power to detect a real difference.

PCoA scree plot

Screeplot Betadiv — PCoA scree plot. The top panel shows the proportion of variation explained by each axis; the bottom panel shows the corresponding eigenvalues. Axes explaining more variation capture stronger patterns.

The scree plot displays the amount of variability in the data that is explained by each PCoA axis. This allows you to understand how well the two-dimensional plot represents the overall differences in community composition across all the samples. Axes that explain more of the variability are more important for understanding the main factors that cause the samples to be different from each other. Why it’s useful

Judge how well the 2D plot summarizes the data: if PCoA1 and PCoA2 explain a large share of variation, the ordination is a strong summary; if they explain only a small share, the plot still helps but represents only part of the full differences.
See whether differences come from one strong pattern or many: if PCoA1 explains far more than the others, one dominant source separates the samples; if variation is spread across many axes, the differences are more complex and distributed, rather than driven by a single gradient.

Ordination and statistical test tables

Scroll past the of the output page to download intermediate files and statistical summaries of the Beta-diversity Analysis module

Table	What it contains
PCoA: proportion explained and eigenvalues	The numerical form of the scree plot: the proportion of variation explained by each PCoA axis and its eigenvalue.
PCoA: sample coordinates	The PCoA coordinates of every sample across 150 axes. The first two columns are the coordinates used to place the dots on the ordination plot.
PERMANOVA summary	Sample size, number of groups, pseudo-F statistic, p-value, and permutation count for the overall test.
ANOSIM summary	Sample size, number of groups, R statistic, p-value, and permutation count for the overall test.
Pairwise PERMANOVA / ANOSIM results	Each pairwise group comparison: group names, sample sizes, test statistics, p-values, FDR-adjusted q-values, and permutation counts.

Recommended parameters

Kepler - Host-Agnostic Taxonomic Profiling (WGS)
CHAMP - Human Taxonomic Profiling (WGS)
16S SR Amplicon Classification - Taxonomic
16S LR Amplicon profiling - Taxonomic
Host-Agnostic Functional Profiling (WGS)
CHAMP - Human Functional Profiling (GBM, GMM, KEGG)
AMR/VF - Functional

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 Sequencing depth heavily affects output with presence-absence Beta-diversity metric (e.g:`Jaccard`). Compositional-aware distances (e.g: `Braycurtis`or `Aitchison` ) are robust to variability in sequencing depth.
Read Depth	When using `rarefaction`, use the Rarefaction module to detect an optimal read depth to avoid discarding too many samples. Samples below it are discarded, so depth trades against sample size. With `filter`, set a threshold that removes only the samples with notably lower depth. The retention plot helps spot them.
Feature Relative Abundance Threshold	`0.0001`
Feature Prevalence Threshold	`0` with `Jaccard` `0.01` to `0.05` with `Bray Curtis` `0.05` to `0.1` with `Aitchison` Use minimal but nonzero filtering for Jaccard, since each detected taxon contributes equally regardless of abundance and rare detections can be noise-sensitive. Apply modest filtering for Bray–Curtis and stronger filtering before conventional Aitchison analysis, where high sparsity makes results sensitive to zero replacement rather than measured relative abundances.
Beta Diversity Metric	`Aitchison` or `Bray-Curtis` : you care about differences in relative community structure `Jaccard :` your question is whether samples differ in which taxa are detected
Centroid Method (if available)	`median`
Number of Components	`2` when the first two axes capture most of the variation `3` if the third PCoA axis explains nearly as much as the second (use the PCoA scree plot). Note: A static 3D plot gets easily crowded with many samples.
Grouping Variable	Categorical metadata of interest. Grouping defines the groups compared by PERMANOVA and ANOSIM. Avoid variables with very few samples per category.
Drop samples with missing metadata values in grouping variable	✅
Number of Permutations	Exploring: `999` For more confidence in the p-value, especially near your threshold: `9999` With `999` permutations the smallest p-value obtainable is `0.001`.
Max Ellipses	Number of groups in your grouping variable (up to about `5`)
Shape Variable	Optional second categorical variable. For example, color by `treatment` and shape by `timepoint` to see whether groups separate only at later timepoints.
Confidence Level	`0.95` as standard. `0.70` for tighter ellipses on crowded plots.

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 Sequencing depth heavily affects output with presence-absence Beta-diversity metric (e.g:`Jaccard`). Compositional-aware distances (e.g: `Braycurtis`or `Aitchison` ) are robust to variability in sequencing depth.
Read Depth	When using `rarefaction`, use the Rarefaction module to detect an optimal read depth to avoid discarding too many samples. Samples below it are discarded, so depth trades against sample size. With `filter`, set a threshold that removes only the samples with notably lower depth. The retention plot helps spot them.
Feature Relative Abundance Threshold	`0.0001`
Feature Prevalence Threshold	`0` with `Jaccard` `0.01` to `0.05` with `Bray Curtis` `0.05` to `0.1` with `Aitchison` Use minimal but nonzero filtering for Jaccard, since each detected taxon contributes equally regardless of abundance and rare detections can be noise-sensitive. Apply modest filtering for Bray–Curtis and stronger filtering before conventional Aitchison analysis, where high sparsity makes results sensitive to zero replacement rather than measured relative abundances.
Beta Diversity Metric	`Aitchison` or `Bray-Curtis` : you care about differences in relative community structure `Jaccard :` your question is whether samples differ in which taxa are detected
Centroid Method (if available)	`median`
Number of Components	`2` when the first two axes capture most of the variation `3` if the third PCoA axis explains nearly as much as the second (use the PCoA scree plot). Note: A static 3D plot gets easily crowded with many samples.
Grouping Variable	Categorical metadata of interest. Grouping defines the groups compared by PERMANOVA and ANOSIM. Avoid variables with very few samples per category.
Drop samples with missing metadata values in grouping variable	✅
Number of Permutations	Exploring: `999` For more confidence in the p-value, especially near your threshold: `9999` With `999` permutations the smallest p-value obtainable is `0.001`.
Max Ellipses	Number of groups in your grouping variable (up to about `5`)
Shape Variable	Optional second categorical variable. For example, color by `treatment` and shape by `timepoint` to see whether groups separate only at later timepoints.
Confidence Level	`0.95` as standard. `0.70` for tighter ellipses on crowded plots.

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 Sequencing depth heavily affects output with presence-absence Beta-diversity metric (e.g:`Jaccard`). Compositional-aware distances (e.g: `Braycurtis`or `Aitchison` ) are robust to variability in sequencing depth.
Read Depth	When using `rarefaction`, use the Rarefaction module to detect an optimal read depth to avoid discarding too many samples. Samples below it are discarded, so depth trades against sample size. With `filter`, set a threshold that removes only the samples with notably lower depth. The retention plot helps spot them.
Feature Relative Abundance Threshold	`0.0001`
Feature Prevalence Threshold	`0` with `Jaccard` `0.01` to `0.05` with `Bray Curtis` `0.05` to `0.1` with `Aitchison` Use minimal but nonzero filtering for Jaccard, since each detected taxon contributes equally regardless of abundance and rare detections can be noise-sensitive. Apply modest filtering for Bray–Curtis and stronger filtering before conventional Aitchison analysis, where high sparsity makes results sensitive to zero replacement rather than measured relative abundances.
Beta Diversity Metric	`Aitchison` or `Bray-Curtis` : you care about differences in relative community structure `Jaccard :` your question is whether samples differ in which taxa are detected
Centroid Method (if available)	`median`
Number of Components	`2` when the first two axes capture most of the variation `3` if the third PCoA axis explains nearly as much as the second (use the PCoA scree plot). Note: A static 3D plot gets easily crowded with many samples.
Grouping Variable	Categorical metadata of interest. Grouping defines the groups compared by PERMANOVA and ANOSIM. Avoid variables with very few samples per category.
Drop samples with missing metadata values in grouping variable	✅
Number of Permutations	Exploring: `999` For more confidence in the p-value, especially near your threshold: `9999` With `999` permutations the smallest p-value obtainable is `0.001`.
Max Ellipses	Number of groups in your grouping variable (up to about `5`)
Shape Variable	Optional second categorical variable. For example, color by `treatment` and shape by `timepoint` to see whether groups separate only at later timepoints.
Confidence Level	`0.95` as standard. `0.70` for tighter ellipses on crowded plots.

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. Sequencing depth heavily affects output with presence-absence Beta-diversity metric (e.g:`Jaccard`). Compositional-aware distances (e.g: `Braycurtis`or `Aitchison` ) are robust to variability in sequencing depth.
Read Depth	When using `rarefaction`, use the Rarefaction module to detect an optimal read depth to avoid discarding too many samples. Samples below it are discarded, so depth trades against sample size. With `filter`, set a threshold that removes only the samples with notably lower depth. The retention plot helps spot them.
Feature Relative Abundance Threshold	`0.0001`
Feature Prevalence Threshold	`0` with `Jaccard` `0.01` to `0.05` with `Bray Curtis` `0.05` to `0.1` with `Aitchison` Use minimal but nonzero filtering for Jaccard, since each detected taxon contributes equally regardless of abundance and rare detections can be noise-sensitive. Apply modest filtering for Bray–Curtis and stronger filtering before conventional Aitchison analysis, where high sparsity makes results sensitive to zero replacement rather than measured relative abundances.
Beta Diversity Metric	`Aitchison` or `Bray-Curtis` : you care about differences in relative community structure `Jaccard :` your question is whether samples differ in which taxa are detected
Centroid Method (if available)	`median`
Number of Components	`2` when the first two axes capture most of the variation `3` if the third PCoA axis explains nearly as much as the second (use the PCoA scree plot). Note: A static 3D plot gets easily crowded with many samples.
Grouping Variable	Categorical metadata of interest. Grouping defines the groups compared by PERMANOVA and ANOSIM. Avoid variables with very few samples per category.
Drop samples with missing metadata values in grouping variable	✅
Number of Permutations	Exploring: `999` For more confidence in the p-value, especially near your threshold: `9999` With `999` permutations the smallest p-value obtainable is `0.001`.
Max Ellipses	Number of groups in your grouping variable (up to about `5`)
Shape Variable	Optional second categorical variable. For example, color by `treatment` and shape by `timepoint` to see whether groups separate only at later timepoints.
Confidence Level	`0.95` as standard. `0.70` for tighter ellipses on crowded plots.

Parameter	Recommended value
Analysis Metric	`relative_abundance`
Data Table Pre-processing Method	`raw`
Read Depth	With `filter`, set a threshold that removes only the samples with notably lower depth.
Feature Relative Abundance Threshold	`0.0001`
Feature Prevalence Threshold	`0` with `Jaccard` `0.01` to `0.05` with `Bray Curtis` `0.05` to `0.1` with `Aitchison`
Beta Diversity Metric	`Aitchison` or `Bray-Curtis` : you care about differences in relative functional composition `Jaccard :` your question is whether samples differ in which functions are detected
Number of Components	`2` when the first two axes capture most of the variation `3` if the third PCoA axis explains nearly as much as the second (use the PCoA scree plot). Note: A static 3D plot gets easily crowded with many samples.
Grouping Variable	Categorical metadata of interest. Grouping defines the groups compared by PERMANOVA and ANOSIM. Avoid variables with very few samples per category.
Drop samples with missing metadata values in grouping variable	✅
Number of Permutations	Exploring: `999` For more confidence in the p-value, especially near your threshold: `9999` With `999` permutations the smallest p-value obtainable is `0.001`.
Max Ellipses	Number of groups in your grouping variable (up to about `5`)
Shape Variable	Optional second categorical variable. For example, color by `treatment` and shape by `timepoint` to see whether groups separate only at later timepoints.
Confidence Level	`0.95` as standard. `0.70` for tighter ellipses on crowded plots.

Parameter	Recommended value
Analysis Metric	`cellular_abundance`
Data Table Pre-processing Method	`raw`
Read Depth	When using `rarefaction`, use the Rarefaction module to detect an optimal read depth to avoid discarding too many samples. Samples below it are discarded, so depth trades against sample size. With `filter`, set a threshold that removes only the samples with notably lower depth. The retention plot helps spot them.
Feature Relative Abundance Threshold	`0.0001`
Feature Prevalence Threshold	`0` with `Jaccard` `0.01` to `0.05` with `Bray Curtis` `0.05` to `0.1` with `Aitchison`
Beta Diversity Metric	`Bray-Curtis` or `Aitchison`: you care about differences in relative functional module composition `Jaccard :` your question is whether samples differ in which functional modules or pathways are detected
Number of Components	`2` when the first two axes capture most of the variation `3` if the third PCoA axis explains nearly as much as the second (use the PCoA scree plot). Note: A static 3D plot gets easily crowded with many samples.
Grouping Variable	Categorical metadata of interest. Grouping defines the groups compared by PERMANOVA and ANOSIM. Avoid variables with very few samples per category.
Drop samples with missing metadata values in grouping variable	✅
Number of Permutations	Exploring: `999` For more confidence in the p-value, especially near your threshold: `9999` With `999` permutations the smallest p-value obtainable is `0.001`.
Max Ellipses	Number of groups in your grouping variable (up to about `5`)
Shape Variable	Optional second categorical variable. For example, color by `treatment` and shape by `timepoint` to see whether groups separate only at later timepoints.
Confidence Level	`0.95` as standard. `0.70` for tighter ellipses on crowded plots.

Parameter	Recommended value
Analysis Metric	`relative_abundance`
Data Table Pre-processing Method	`raw`
Read Depth	When using `rarefaction`, use the Rarefaction module to detect an optimal read depth to avoid discarding too many samples. Samples below it are discarded, so depth trades against sample size. With `filter`, set a threshold that removes only the samples with notably lower depth. The retention plot helps spot them.
Feature Relative Abundance Threshold	`0.0001`
Feature Prevalence Threshold	`0` with `Jaccard` `0.01` to `0.05` with `Bray Curtis` `0.05` to `0.1` with `Aitchison`
Beta Diversity Metric	`Aitchison` or `Bray-Curtis` : you care about differences in relative resistance/virulence gene composition `Jaccard :` your question is whether samples differ in which resistance or virulence genes are detected
Number of Components	`2` when the first two axes capture most of the variation `3` if the third PCoA axis explains nearly as much as the second (use the PCoA scree plot). Note: A static 3D plot gets easily crowded with many samples.
Grouping Variable	Categorical metadata of interest. Grouping defines the groups compared by PERMANOVA and ANOSIM. Avoid variables with very few samples per category.
Drop samples with missing metadata values in grouping variable	✅
Number of Permutations	Exploring: `999` For more confidence in the p-value, especially near your threshold: `9999` With `999` permutations the smallest p-value obtainable is `0.001`.
Max Ellipses	Number of groups in your grouping variable (up to about `5`)
Shape Variable	Optional second categorical variable. For example, color by `treatment` and shape by `timepoint` to see whether groups separate only at later timepoints.
Confidence Level	`0.95` as standard. `0.70` for tighter ellipses on crowded plots.

Parameter reference

Grouping Variable

The categorical metadata column that defines the groups you want to compare. It plays two roles at once: it sets the color of the points in the ordination plot (one color per category), and it defines the groups that the PERMANOVA / ANOSIM tests use to ask whether community composition actually differs between them. Choose the variable that encodes your biological question, the factor you expect to separate the microbial communities (for example, case versus control, or body site).

Options · Categorical variables from the metadata table associated with the query used to create the analysis
Default · None: no grouping is applied, all samples share one color and the plot shows their overall spread without group comparisons. Choose a grouping variable to color samples by metadata and compare groups.
Suggested · A categorical variable relevant to your study design, such as treatment, disease status, condition, body site, cohort, or time point. Avoid variables with too many categories or categories represented by very few samples, these clutter the plot and reduce the reliability of statistical testing.

Beta-diversity metric

The rule used to turn any two microbial profiles into a single distance, a number summarizing how different two samples are. Computing it for every pair of samples produces the distance matrix that everything downstream is built on: the ordination plot and the PERMANOVA / ANOSIM tests. The choice matters because each metric weighs the data differently: some respond to differences in abundance, some only to which features are present or absent, and some are designed for compositional data (where sequencing measures relative, not absolute, abundances).

Options · 23 metrics
Default · Euclidean
Suggested · Match the metric to your question and feature type:

Goal	Feature type	Metric	Why	Note
Differ in overall composition based on abundance?	Relative abundance	Bray-Curtis	Popular, intuitive abundance-based distance; a safe default	Sensitive to abundance differences; doesn’t address compositionality
Contain different taxa, regardless of abundance?	Presence/absence	Jaccard or Dice	Focuses on shared versus non-shared features	Ignores abundance, so rare and abundant taxa count equally
Differ as compositional profiles?	Relative abundance / compositional	Aitchison	Built for compositional data; compares log-ratios between features	Needs appropriate zero handling before the log-ratio transformation
Are low-abundance features important?	Counts or relative abundance	Canberra	Gives more weight to proportional differences in low-abundance features	Sensitive to zeros, noise, and very rare features
Have similar functional profile shapes?	Functional profiles	Cosine or Correlation	Compares overall profile shape rather than direct abundance	More exploratory; depends heavily on preprocessing and scaling

Centroid Method

Available only when the Beta-diversity Metric is Aitchison

The Aitchison metric first applies a CLR (centered log-ratio) transformation: within each sample, every feature’s abundance is divided by a single per-sample reference value and then log-transformed, which removes the compositional constraint and makes samples comparable. This parameter chooses which summary statistic is used as that reference value, so it controls how each sample is centered before distances are computed.
Options · mean, median
Default · mean
Suggested
- mean: the geometric mean of abundances (the standard CLR choice). Best when the data is fairly clean and most taxa carry meaningful signal.
- median: more robust to outliers and noisy low-abundance taxa, often useful for sparse microbiome data.

Number of Components

The number of ordination axes shown in the plot. An ordination method compresses the full distance matrix into a handful of axes, ordered by how much sample-to-sample variation each one captures; this sets how many of those leading axes are displayed.

Options · 2 (2D) or 3 (3D)
Default · 2
Suggested:
- 2: a standard 2D scatter plot: easier to read, annotate, and export, and usually enough when the first two components capture most variation.
- 3: when the first two components don’t capture enough structure, or an extra axis reveals separation hidden in 2D. Shown as a static 3D plot.

Drop samples with missing grouping metadata

Controls what happens to samples that have no value for the grouping variable (missing metadata).

Default · TRUE (samples with missing values are dropped)
Options:
- Enabled: samples with missing metadata are removed before the analysis runs. The distance matrix, ordination, and tests are computed only on samples with a valid group, keeping comparisons clean.
- Disabled: samples with missing values are kept and assigned to a separate NaN_group, appearing as their own group and included in calculations.
Suggested ·
Enable to compare well-defined groups, run PERMANOVA, or produce a clean publication plot (missing values can otherwise distort group centroids, within-group spread, and test results).
Disable when it’s useful to see where unlabelled samples fall in the ordination, for example to check whether they cluster with any known group.

Max ellipses

The maximum number of group confidence ellipses drawn on the 2D plot. Each ellipse summarizes one group’s center and spread in the ordination space, making it easy to see at a glance whether groups overlap or pull apart. Ellipses are drawn only for groups present in the plotted data with an assigned color; if more groups are eligible than this maximum, only the first ones in plotting order get an ellipse.

Options · 0 to 10
Default · 0
Suggested · With few, well-separated groups (≤5), showing all is fine. For more complex datasets, limiting the number improves readability.

Confidence level

How much of each group its ellipse covers: the percentage of that group’s samples expected to fall inside it. Higher values draw wider ellipses; lower values draw tighter ones.

Options · 50 to 99%
Default · 95%

This parameter only affects the visualization of group ellipses. It does not change the beta-diversity calculation, sample positions, or statistical results. Ellipses are visual aids: don’t read them as strict statistical boundaries or as proof of group separation.

Number of permutations

The number of random permutations used to calculate significance for PERMANOVA or ANOSIM. The group labels are shuffled this many times (with the distances held fixed) to build a null distribution, the range of group separation you’d expect to see if the labels were random. The separation actually observed is then compared against it to produce the p-value.

Options · 99 to 10000
Default · 999
Suggested · Use 999 for standard exploratory analysis. Use 4999 or 9999 when results will be reported formally, or when the p-value is close to the significance threshold. Higher values give more precise p-values but take longer.

This parameter affects only the significance testing, it does not change the distances, the ordination, or sample positions.

Shape Variable

An optional categorical metadata column mapped to different point shapes, letting you overlay a second factor on top of the color-coded grouping variable. It’s purely visual, it doesn’t change the distance matrix, the ordination, or the statistics.Options · Metadata variables from the metadata table associated with the query used to create the analysisDefault · None (all samples share the same shape)Suggested · A categorical variable that adds context, such as sex, cohort, sample type, time point, or body site. For example, with samples colored by treatment, the shape could show which cohort or collection site each came from.

References

Anderson, M. (2014). “Permutational Multivariate Analysis of Variance (PERMANOVA).” Wiley StatsRef: Statistics Reference Online. https://doi.org/10.1002/9781118445112.stat07841
Jaccard Index. Jaccard, P. (1901). “Étude comparative de la distribution florale dans une portion des Alpes et des Jura.” Bulletin de la Société vaudoise des sciences naturelles, 37(142), 547-579. Jaccard, P. (1912). “The Distribution of the Flora in the Alpine Zone. 1.” New Phytologist, 11(2), 37-50. doi:10.1111/j.1469-8137.1912.tb05611.x
Bray-Curtis Dissimilarity. Bray, J. R. & Curtis, J. T. (1957). “An ordination of the upland forest communities of southern Wisconsin.” Ecological Monographs, 27, 325-349.

Getting Started

Workspace and Studies

Import Data on Cosmos-Hub 2.0

Building Cohorts

Analysis Projects

Beta diversity on Cosmos-Hub 2.0

Module output and customization

Beta-diversity ordination plot(s)

1. Choose how to measure sample distances.

2. Customize the ordination plot

Why it’s useful

3. Statistical testing

PCoA scree plot

Ordination and statistical test tables

Recommended parameters

Parameter reference

References

​Module output and customization

​Beta-diversity ordination plot(s)

​1. Choose how to measure sample distances.

​2. Customize the ordination plot

​Why it’s useful

​3. Statistical testing

​PCoA scree plot

​Ordination and statistical test tables

​Recommended parameters

​Parameter reference

​References

Module output and customization

Beta-diversity ordination plot(s)

1. Choose how to measure sample distances.

2. Customize the ordination plot

Why it’s useful

3. Statistical testing

PCoA scree plot

Ordination and statistical test tables

Recommended parameters

Parameter reference

References