This page covers how the PCA Explorer works in Cosmos-Hub 2.0: the plot it produces, how to read it, the files you can export and the parameters you can tune. For the theory behind PCA, see the PCA explorer overview.

Module output and customisation

PCA biplot: a biplot showing how samples relate to each other, with options for how groups and features are displayed.
Exported files: the plot, the data tables before and after pre-processing, and the numbers behind the plot.

PCA biplot

Each point is one sample, positioned along the first two principal components (PC1 and PC2). The percentage on each axis is how much of the total variation that component explains. A higher percentage means the axis captures a larger share of the differences between samples.

Sample points and grouping

Each point of the plot represents a single sample of the cohort. By assigning categorical variables of interest (for example sample source, health status or treatment group) to colours and shapes, you can see whether samples from different groups differ in their overall microbial community.

Colour by one categorical variable

Choose the main categorical variable of interest with the Grouping Variable parameter to colour the points by group. This shows whether samples from different groups (for example sample source, treatment group or sex) occupy different regions of the plot, and lets you judge visually whether their composition differs.

Add a second variable with shapes

Overlay a second categorical variable with the Shape Variable parameter. This is useful when two factors might both influence the data. For example, colouring points by treatment and shaping them by cohort shows whether the separation follows treatment, cohort or both, without a second plot.

Handling missing metadata

Samples with missing values in the grouping variable can be excluded with Drop samples with missing grouping metadata.

Keeping samples with missing metadata shows where unlabelled samples fall relative to the annotated groups. If an unlabelled sample sits deep inside one group’s cluster, check its metadata for a missing or wrong entry. Position on two components is not reliable enough to assign a sample to a group.

Group ellipses

Ellipses can be drawn around each group’s points to summarise where the group sits and how spread out it is.

Adding group ellipses

The Max Ellipses parameter sets how many ellipses are shown. Ellipses make overlap or separation easier to judge than scattered points alone.

Setting the ellipse size

The Confidence Level sets how large each ellipse is drawn. A higher value draws a wider ellipse that covers more of the group’s samples, a lower value a tighter one. The value changes only how the spread is drawn, not the underlying PCA, so treat ellipses as a visual summary of group position and variability rather than as a strict boundary. Ellipses describe PC1 and PC2 only. Groups that overlap on the plot can still differ along later components, and separated ellipses are not a statistical test. To test whether groups differ in overall composition, use PERMANOVA in Beta diversity.

Loading vectors

Loading vectors show how much each feature of the data table contributes to the principal components. They link the structure in the plot to specific taxa or functions. They are drawn as arrows from the centre of the plot:

The direction of an arrow shows towards which side of PC1 and PC2 the feature moves the samples that contain more of it.
The length of an arrow shows how strongly the feature contributes to PC1 and PC2, compared with the other arrows on the plot.

The arrows are enlarged so they stay visible next to the sample points, and the plot title reports the enlargement factor. Compare arrow lengths with each other, not with the axis values. In the example above, the arrow for Prevotella melaninogenica points upwards into the orange cluster. Samples with more of this species sit higher on PC2, and the length of the arrow shows that it is one of the main contributors to that axis. The longest arrows usually belong to abundant features whose levels vary a lot between samples. A short arrow does not mean that a feature is biologically unimportant.

An arrow pointing towards a group is a visual hint, not a test. To test whether a feature differs between groups, use Univariate comparison.

Include loading vectors

Set the Number of Vectors parameter to display the top N contributing taxa or functional features.

Exported files

Click Export to download the plot together with the tables behind it. The export contains the files below. In most of the tables the first column is an unnamed row number, which you can ignore.

File	What it contains	Use it to
`pca_biplot.png`	The biplot as shown on screen.	Add the figure to a report or presentation.
`parameters.txt`	The parameter values used.	Record how the plot was made, or repeat the run with the same settings.
`input_metadata.csv`	The sample metadata of the cohort defined in the query, one row per sample.	Check which samples and metadata columns entered the module.
`input_features.csv`	The data table before pre-processing.	Compare the original profiles with the filtered table.
`transformed_metadata.csv`	The sample metadata after pre-processing (e.g: without the samples dropped for missing grouping values)	Inspect which samples are in the plot.
`transformed_features.csv`	The data table the PCA was computed on.	Check which features passed the filters.
`pca_data.csv`	The sample coordinates (scores) on every principal component, one row per sample.	Re-plot the samples with your own tools, or plot components other than PC1 and PC2.
`loadings.csv`	The contribution of each feature to each component, one row per component and one column per feature.	Find the features that define each axis, beyond the vectors shown on the plot.
`explained_variance.csv`	The percentage of total variation explained by each component. The values sum to 100.	Decide how many components are worth interpreting.

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 standardise the whole cohort to a common read depth, using the optimal depth from the Rarefaction module Uneven depth makes samples separate by sequencing effort, not biology.
Read Depth	`default` with `Raw` or `Filter` With `Rarefaction`, use the optimal depth from the Rarefaction module. Samples below it are discarded, so depth trades against sample size.
Seed	`default`, only when method is `Rarefaction`
Feature Relative Abundance Threshold	`0.001`
Feature Prevalence Threshold	`0.01` to `0.05` Filtering removes very rare, sparsely detected taxa before computing the PCA, keeping the ordination from being driven by noise.
Grouping Variable	Categorical metadata of interest. Grouping defines how points are coloured and how ellipses are drawn. It is not used for statistical testing in PCA.
Drop samples with missing metadata values in grouping variable	✅
Number of Vectors	`2` to `3` for a readable plot Up to `10` to explore more of the features behind the main patterns
Max Ellipses	Number of groups in your grouping variable (up to about `5`)
Confidence Level	`95` as standard `70` for tighter ellipses on crowded plots
Shape Variable	Optional second categorical variable. For example, colour by `treatment` and shape by `timepoint` to see whether groups separate only at later timepoints.

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 standardise the whole cohort to a common read depth, using the optimal depth from the Rarefaction module Uneven depth makes samples separate by sequencing effort, not biology.
Read Depth	`default` with `Raw` or `Filter` With `Rarefaction`, use the optimal depth from the Rarefaction module. Samples below it are discarded, so depth trades against sample size.
Seed	`default`, only when method is `Rarefaction`
Feature Relative Abundance Threshold	`0.0001`
Feature Prevalence Threshold	`0.01` to `0.05` Filtering removes very rare, sparsely detected taxa before computing the PCA, keeping the ordination from being driven by noise.
Grouping Variable	Categorical metadata of interest. Grouping defines how points are coloured and how ellipses are drawn. It is not used for statistical testing in PCA.
Drop samples with missing metadata values in grouping variable	✅
Number of Vectors	`2` to `3` for a readable plot Up to `10` to explore more of the features behind the main patterns
Max Ellipses	Number of groups in your grouping variable (up to about `5`)
Confidence Level	`95` as standard `70` for tighter ellipses on crowded plots
Shape Variable	Optional second categorical variable. For example, colour by `treatment` and shape by `timepoint` to see whether groups separate only at later timepoints.

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 standardise the whole cohort to a common read depth, using the optimal depth from the Rarefaction module Uneven depth makes samples separate by sequencing effort, not biology.
Read Depth	`default` with `Raw` or `Filter` With `Rarefaction`, use the optimal depth from the Rarefaction module. Samples below it are discarded, so depth trades against sample size.
Seed	`default`, only when method is `Rarefaction`
Feature Relative Abundance Threshold	`0.001`
Feature Prevalence Threshold	`0.01` to `0.05` Filtering removes rare, sparsely detected taxa before computing the PCA, keeping the ordination from being driven by noise.
Grouping Variable	Categorical metadata of interest. Grouping defines how points are coloured and how ellipses are drawn. It is not used for statistical testing in PCA.
Drop samples with missing metadata values in grouping variable	✅
Number of Vectors	`2` to `3` for a readable plot Up to `10` to explore more of the features behind the main patterns
Max Ellipses	Number of groups in your grouping variable (up to about `5`)
Confidence Level	`95` as standard `70` for tighter ellipses on crowded plots
Shape Variable	Optional second categorical variable. For example, colour by `treatment` and shape by `timepoint` to see whether groups separate only at later timepoints.

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 standardise the whole cohort to a common read depth, using the optimal depth from the Rarefaction module Uneven depth makes samples separate by sequencing effort, not biology. Long-read runs are usually shallower, so check sequencing depth variability on your cohort before relying on `Raw`.
Read Depth	With `Rarefaction`: `100,000`, or the depth from the Rarefaction module. Samples below it are discarded, so depth trades against sample size. With `Filter`: `20,000`, adjusted to remove only the samples with notably lower depth.
Seed	`default`, only when method is `Rarefaction`
Feature Relative Abundance Threshold	`0.001`
Feature Prevalence Threshold	`0.01` to `0.05` Filtering removes very rare, sparsely detected taxa before computing the PCA, keeping the ordination from being driven by noise.
Grouping Variable	Categorical metadata of interest. Grouping defines how points are coloured and how ellipses are drawn. It is not used for statistical testing in PCA.
Drop samples with missing metadata values in grouping variable	✅
Number of Vectors	`2` to `3` for a readable plot Up to `10` to explore more of the features behind the main patterns
Max Ellipses	Number of groups in your grouping variable (up to about `5`)
Confidence Level	`95` as standard `70` for tighter ellipses on crowded plots
Shape Variable	Optional second categorical variable. For example, colour by `treatment` and shape by `timepoint` to see whether groups separate only at later timepoints.

Parameter	Recommended value
Analysis Metric	`relative_abundance`
Data Table Pre-processing Method	`Raw`
Read Depth	`default`
Feature Relative Abundance Threshold	`0.0001`
Feature Prevalence Threshold	`0.01` to `0.05` Filtering removes very rare, sparsely detected functions before computing the PCA, keeping the ordination from being driven by noise. Functional tables hold many more features than taxonomic ones, so filtering also keeps the calculation manageable.
Grouping Variable	Categorical metadata of interest. Grouping defines how points are coloured and how ellipses are drawn. It is not used for statistical testing in PCA.
Drop samples with missing metadata values in grouping variable	✅
Number of Vectors	`2` to `3` for a readable plot Up to `10` to explore more of the features behind the main patterns
Max Ellipses	Number of groups in your grouping variable (up to about `5`)
Confidence Level	`95` as standard `70` for tighter ellipses on crowded plots
Shape Variable	Optional second categorical variable. For example, colour by `treatment` and shape by `timepoint` to see whether groups separate only at later timepoints.

Parameter	Recommended value
Analysis Metric	`cellular_abundance`
Data Table Pre-processing Method	`Raw`
Read Depth	`default`
Feature Relative Abundance Threshold	`0.0001`
Feature Prevalence Threshold	`0.01` to `0.05` GMM, GBM and KEGG Modules tables are already aggregated into pathways or modules, so they are less sparse than gene-level tables and tolerate lighter filtering.
Grouping Variable	Categorical metadata of interest. Grouping defines how points are coloured and how ellipses are drawn. It is not used for statistical testing in PCA.
Drop samples with missing metadata values in grouping variable	✅
Number of Vectors	`2` to `3` for a readable plot Up to `10` to explore more of the features behind the main patterns
Max Ellipses	Number of groups in your grouping variable (up to about `5`)
Confidence Level	`95` as standard `70` for tighter ellipses on crowded plots
Shape Variable	Optional second categorical variable. For example, colour by `treatment` and shape by `timepoint` to see whether groups separate only at later timepoints.

Parameter	Recommended value
Analysis Metric	`relative_abundance`
Data Table Pre-processing Method	`Raw`
Read Depth	`default`
Feature Relative Abundance Threshold	`0.0001`
Feature Prevalence Threshold	`0.01` to `0.05` Filtering removes very rare, sparsely detected resistance or virulence genes before computing the PCA, keeping the ordination from being driven by noise.
Grouping Variable	Categorical metadata of interest. Grouping defines how points are coloured and how ellipses are drawn. It is not used for statistical testing in PCA.
Drop samples with missing metadata values in grouping variable	✅
Number of Vectors	`2` to `3` for a readable plot Up to `10` to explore more of the features behind the main patterns
Max Ellipses	Number of groups in your grouping variable (up to about `5`)
Confidence Level	`95` as standard `70` for tighter ellipses on crowded plots
Shape Variable	Optional second categorical variable. For example, colour by `treatment` and shape by `timepoint` to see whether groups separate only at later timepoints.

Parameter reference

Grouping Variable

The metadata column used to define sample groups. It colours the points, so you can see whether samples cluster by a biological, experimental or technical category.Options · Categorical variables from the metadata table associated with the query used to create the analysisDefault · NoneSuggested · A categorical variable relevant to your study question, such as treatment, disease status, condition, body site, cohort, time point or sequencing batch.

When no grouping variable is selected, samples are shown without group colours. Use a grouping variable to check whether the main variation is associated with a known sample characteristic. For example, colouring by treatment shows whether treated and control samples separate, while colouring by batch helps detect technical effects.

Drop samples with missing grouping metadata

Whether samples with missing values in the grouping variable are excluded from the plot.Options · TRUE or FALSEDefault · TRUE (samples with missing values are dropped)Suggested · Use TRUE when clear group comparisons matter, since it removes samples that cannot be assigned to a group. Use FALSE only when keeping all samples matters more for exploratory visualisation.

Dropping samples with missing group metadata makes the plot easier to interpret, since every displayed sample belongs to a defined group. If disabled, samples with missing values are assigned to NaN_group.

Number of Vectors

The number of loading vectors drawn on the plot. Vectors indicate which taxa or functions contribute most strongly to the displayed components. This parameter does not change the number of axes, which is always two.Options · Integer from 1 to 10Default · 2Suggested · Use 2 or 3 for a simple, readable plot. Increase it to inspect more features that may contribute to the main patterns.

More vectors give more detail but make the plot harder to read. Use few vectors for presentations and more for exploratory analysis. The full list of feature contributions is in loadings.csv in the export.

Max Ellipses

The maximum number of group ellipses shown. Ellipses summarise the position and spread of the groups defined by the grouping variable.Options · Integer from 0 to 10Default · 0Suggested · Use 0 to hide ellipses, or 1 to 5 to show them for a small number of groups while keeping the plot readable.

If the grouping variable has more groups than the maximum, only some groups get an ellipse. Ellipses do not affect the PCA calculation. For example, grouping by body site can show whether stool, oral and skin samples occupy different regions.

Confidence Level

The confidence level used to draw group ellipses, which controls their size.Options · Integer percentage from 50 to 99Default · 95Suggested · Use the default for standard visualisation. Lower values draw tighter ellipses, higher values draw wider ones.

Ellipses are visual summaries of group position and spread, not strict statistical boundaries, and not proof that exactly 95% of samples fall inside. Overlapping ellipses suggest similar or highly variable profiles. Well-separated ellipses suggest that the grouping variable is associated with one of the main sources of variation shown on PC1 and PC2.

Shape Variable

An optional categorical metadata column shown as different point shapes, so you can display a second characteristic on top of the grouping variable.Options · Categorical variables from the metadata table associated with the query used to create the analysisDefault · None (all samples share one shape)Suggested · A categorical variable that adds context, such as sex, cohort, sample type, time point or body site. For example, with points coloured by treatment, the shape can show which cohort or collection site each sample came from.

Getting Started

Workspace and Studies

Import Data on Cosmos-Hub 2.0

Building Cohorts

Analysis Projects

PCA explorer on Cosmos-Hub 2.0

Module output and customisation

PCA biplot

Sample points and grouping

Colour by one categorical variable

Add a second variable with shapes

Handling missing metadata

Group ellipses

Adding group ellipses

Setting the ellipse size

Loading vectors

Include loading vectors

Exported files

Recommended parameters

Parameter reference

​Module output and customisation

​PCA biplot

​Sample points and grouping

​Colour by one categorical variable

​Add a second variable with shapes

​Handling missing metadata

​Group ellipses

​Adding group ellipses

​Setting the ellipse size

​Loading vectors

​Include loading vectors

​Exported files

​Recommended parameters

​Parameter reference

Module output and customisation

PCA biplot

Sample points and grouping

Colour by one categorical variable

Add a second variable with shapes

Handling missing metadata

Group ellipses

Adding group ellipses

Setting the ellipse size

Loading vectors

Include loading vectors

Exported files

Recommended parameters

Parameter reference