> ## 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.
# PCA explorer on Cosmos-Hub 2.0
This page covers how the PCA Explorer works in Cosmos-Hub 2.0: the plot and tables it produces, how to read them, and the parameters you can tune. For the theory behind PCA, see the [PCA explorer overview](/analysis/pca/overview).
# Module output and customization
* **PCA biplot**: a customizable biplot summarizing how samples relate to each other, with options for how it is displayed.
## 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 encoding categorical variables of interest (e.g: sample source, health status, treatment group) to different colors and shapes you can visualize whether samples from different groups differ in terms of overall microbial community.
#### Color by one categorical variable
Choose the main categorical variable of interest using the [Grouping Variable](https://docs.cosmosid.com/#grouping-variable) parameter to encode grouping with colors.
This shows whether samples from different groups (e.g: Sample source, Treatment group, Gender) occupy different regions of the plot. This lets you visually assess whether there's any difference in compositional pattern between your cohorts.
#### Add a second variable with shapes
Overlay a second categorical variable using the [Shape Variable](https://docs.cosmosid.com/#shape-variable) parameter.
This is useful when two factors might both influence the data: for example, coloring points by treatment and shaping them by cohort lets you see whether the separation follows treatment, cohort, or both, without needing a second plot.
#### Handling missing metadata
Samples with missing values in the grouping variable can be excluded using [Drop samples with missing metadata](https://docs.cosmosid.com/#drop-samples-with-missing-grouping-metadata).
Keeping samples with missing metadata can be useful to see where unlabeled samples fall relative to well-annotated groups, and infer whether they likely belong to or resemble a particular category based on their position.
This is especially informative when the grouping variable (e.g. disease status, body site, treatment) is a major driver of clustering: if missing-label samples consistently sit inside or near one group’s cluster, that’s a useful visual hint.
### Group ellipses
Ellipses can be drawn around each group's points to summarize where the group sits and how spread out it is.
#### Adding group ellipses
The [Max ellipses](#max-ellipses) parameter sets how many ellipses are shown. Ellipses make overlap or separation easier to judge than scattered points alone, giving a quick visual summary of how distinct the groups are.
#### Setting the ellipses area
How large each ellipse is drawn is set by the [Confidence level](#confidence-level): a higher value draws a wider ellipse that covers more of the group's samples, a lower value a tighter one. Adjusting it changes only how the spread is *drawn*, not the underlying PCA, so treat the ellipses as a visual summary of group position and variability, not as a strict boundary.
### Loading vectors
The loading vectors describe how much each microbial feature of the data table contributes to each principal component. Loading vectors connect the structure in the plot to specific features, indicating which taxa or functions drive the separation between samples.
They are shown as arrows (vectors) overlaid on the PCA plot:
* The direction of the arrow indicates which component(s) that feature is associated with.
* The length of the arrow indicates how strongly it influences the separation along those axes.
In the example above, the arrow for *Prevotella melaninogenica* points up into the orange cluster, showing that higher abundance of this species pushes samples toward higher PC2 values. Its direction indicates association with the positive side of PC2, and its length shows it is a strong contributor to that axis.
#### Include loading vectors
Set the [Number of vectors](#number-of-vectors) parameter to display the top N contributing taxa or function features.
### Output tables
Scroll past the the end of the output page and click **Download Tables and Images** to export the numbers behind the plot.
| Output | What it contains | Why it matters |
| :----------------------------------- | :------------------------------------------------------- | :------------------------------------------------------------------------------------------------ |
| **Sample coordinates (scores)** | Each sample's position on the principal components. | Useful for downstream analysis or custom plotting. |
| **Loadings (component × feature)** | The contribution of each feature to each component. | Identifies the features that define each axis. |
| **Proportion of variance explained** | The share of total variation captured by each component. | Indicates how much structure the plot represents, and how many components are worth interpreting. |
## Recommended parameters
Select your workflow. The pre-processing parameters that vary by data type (taxonomic rank, relative-abundance threshold, read depth) are filled in per tab; the analysis parameters are the same across all workflows.
| 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, using the optimal depth from the [Rarefaction module](/analysis/rarefaction)
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](/analysis/rarefaction). Samples below it are discarded, so depth trades against sample size.
|
| 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 colored and how ellipses are drawn |
| Drop samples with missing metadata values in grouping variable | ✅ |
| Number of Vectors | - `2` for a standard 2D scatter plot
- `3` if a third axis reveals additional separation not visible in 2D
|
| Max Ellipses | Number of groups in your grouping variable (up to about `5`) |
| Confidence Level | - `0.95` as standard.
- `0.70` for tighter ellipses on crowded plots.
|
| Shape Variable | Optional second categorical variable. For example, color 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 standardize the whole cohort to a common read depth, using the optimal depth from the [Rarefaction module](/analysis/rarefaction)
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](/analysis/rarefaction). 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 colored 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` for a standard 2D scatter plot
- `3` if a third axis reveals additional separation not visible in 2D
|
| Max Ellipses | Number of groups in your grouping variable (up to about `5`) |
| Confidence Level | - `0.95` as standard.
- `0.70` for tighter ellipses on crowded plots.
|
| Shape Variable | Optional second categorical variable. For example, color 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 standardize the whole cohort to a common read depth, using the optimal depth from the [Rarefaction module](/analysis/rarefaction)
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](/analysis/rarefaction). 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 colored 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` for a standard 2D scatter plot
- `3` if a third axis reveals additional separation not visible in 2D
|
| Max Ellipses | Number of groups in your grouping variable (up to about `5`) |
| Confidence Level | - `0.95` as standard.
- `0.70` for tighter ellipses on crowded plots.
|
| Shape Variable | Optional second categorical variable. For example, color 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 standardize the whole cohort to a common read depth, using the optimal depth from the [Rarefaction module](/analysis/rarefaction)
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](/analysis/rarefaction). 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 colored 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` for a standard 2D scatter plot
- `3` if a third axis reveals additional separation not visible in 2D
|
| Max Ellipses | Number of groups in your grouping variable (up to about `5`) |
| Confidence Level | - `0.95` as standard.
- `0.70` for tighter ellipses on crowded plots.
|
| Shape Variable | Optional second categorical variable. For example, color 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 colored 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` for a standard 2D scatter plot
- `3` if a third axis reveals additional separation not visible in 2D
|
| Max Ellipses | Number of groups in your grouping variable (up to about `5`) |
| Confidence Level | - `0.95` as standard.
- `0.70` for tighter ellipses on crowded plots.
|
| Shape Variable | Optional second categorical variable. For example, color 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 colored 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` for a standard 2D scatter plot
- `3` if a third axis reveals additional separation not visible in 2D
|
| Max Ellipses | Number of groups in your grouping variable (up to about `5`) |
| Confidence Level | - `0.95` as standard.
- `0.70` for tighter ellipses on crowded plots.
|
| Shape Variable | Optional second categorical variable. For example, color 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 colored 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` for a standard 2D scatter plot
- `3` if a third axis reveals additional separation not visible in 2D
|
| Max Ellipses | Number of groups in your grouping variable (up to about `5`) |
| Confidence Level | - `0.95` as standard.
- `0.70` for tighter ellipses on crowded plots.
|
| Shape Variable | Optional second categorical variable. For example, color by `treatment` and shape by `timepoint` to see whether groups separate only at later timepoints. |
## Parameter reference
The metadata column used to define sample groups. It colors the points, letting you visually assess 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 analysis
**Default** · `None`
**Suggested** · 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-based coloring. Use a grouping variable to check whether the main variation is associated with a known sample characteristic: for example, coloring by `treatment` shows whether treated and control samples separate, while coloring by `batch` helps detect technical effects.
Whether samples with missing values in the grouping variable are excluded from the plot.
**Options** · `TRUE` or `FALSE`
**Default** · `TRUE` (samples with missing values are dropped)
**Suggested** · Use `TRUE` when clear group comparisons matter, since it removes samples that can't be assigned to a group. Use `FALSE` only when keeping all samples is more important for exploratory visualization.
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`.
The number of feature vectors (loadings) shown in the plot. Vectors indicate which taxa or functions contribute most strongly to the displayed components.
**Options** · Integer from `1` to `10`
**Default** · `2`
**Suggested** · 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 presentation and more for exploratory analysis.
The maximum number of group ellipses shown. Ellipses summarize the position and spread of groups defined by the grouping variable.
**Options** · Integer from `0` to `10`
**Default** · `0`
**Suggested** · 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 a subset is shown (by the platform's plotting order). Ellipses don't affect the PCA calculation. For example, grouping by `body site` can show whether stool, oral, and skin samples occupy different regions.
The confidence level used to draw group ellipses, which controls their size.
**Options** · Integer percentage from `50` to `100`
**Default** · `95`
**Suggested** · Use the default for standard visualization. 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 variable profiles; well-separated ellipses suggest the grouping variable is associated with a main source of variation.
An optional metadata column shown as different point shapes, letting you visualize a second characteristic on top of the grouping variable.
**Options** · Metadata variables from the metadata table associated with the query used to create the analysis
**Default** · `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 colored by `treatment`, the shape could show which cohort or collection site each sample came from.