> ## 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.

# Stacked bar charts on Cosmos-Hub 2.0

This page covers how the stacked bar chart works in Cosmos-Hub 2.0: how to read each part of the figure and which parameter shapes it. For what a stacked bar chart is and when to use one, see the [Stacked bar chart overview](/analysis/stacked-bar-chart/overview). Because the chart is highly customizable, the output and its controls are described together below.

# Module output and customization

* **Annotated Stacked Bar Chart:** a stacked bar chart to inspect and compare microbial composition across your cohort, one bar per sample or per group. Sample metadata can be highlighted above the bars, and samples can be sorted, faceted, or collapsed by your variables of interest.

<Frame caption="Stacked bar chart of phylum-level relative abundances across skin samples, faceted by body site and sorted by dermotype within each facet. Each bar represents one sample, with segments colored by phylum. Low-abundance phyla are grouped under &#x22;Others.&#x22; Color-coded annotation strips above each facet indicate the body site and dermotype of each sample.">
  <img src="https://mintcdn.com/cmbio/rXnT_KRi2R3YfV3p/images/stacked_barchart-1.png?fit=max&auto=format&n=rXnT_KRi2R3YfV3p&q=85&s=2a3cd472d7bb0a7945ccc568232f426d" alt="Stacked Barchart 1" width="5975" height="1671" data-path="images/stacked_barchart-1.png" />
</Frame>

## Annotated Stacked Bar Chart

### 1. Set the bar values and scale

<Note>
  All figures on this page show **relative abundance** (each bar scaled to the same height). You can display composition expressed as counts by setting [Y-axis values](#y-axis-values) to `absolute` and Analysis Metric to `counts`
</Note>

The sample bar is the basic unit of stacked bar charts: one bar per sample, divided into stacked colored segments, where each segment's size is that feature's abundance in the sample (a **feature** being a single taxon or function). A single bar is a snapshot of the sample's whole composition.

The scale of y-axis depends on the selected metric used to express feature abundance. Set the scale with [Y-axis values](#y-axis-values):

* `relative` shows the proportion of every feature within the sample.  Sample bars reach the same height. Best for comparing composition across samples.
* **`absolute`** shows feature counts, so bar heights may also reflect differences in sequencing depth or total counts between samples.

### 2. Choose how features to show per each Bar

The colored segments are the microbial features (taxa or functions). A single sample profile can include hundreds of features (thousands or more for functional profiles), which can make it hard to visualize all of them within the same Bar. To facilitate comparison between samples, it is suggested to limit the number of features shown per bar by visualizing the most abundant, prevalent or variable features across the cohort, and group remaining features into an aggregate category (**Others)**.

* Use the [Top features (N)](#top-features-n) parameter to set *how many* features are displayed individually,  and [Feature ranking method](#feature-ranking-method) to decide the ranking criteria to sort microbial features to be selected:

| Ranking method | What it prioritizes                                        | When to use it                                                                     |
| :------------- | :--------------------------------------------------------- | :--------------------------------------------------------------------------------- |
| `mean`         | Highest average abundance across the cohort                | Show the dominant taxa or functions.                                               |
| `prevalence`   | Detected in the largest fraction of samples                | Highlight common features shared across many samples.                              |
| `variance`     | Abundance varies most across samples                       | Highlight features that may separate groups.                                       |
| `percentile`   | Reaches high abundance in a meaningful fraction of samples | Capture features important in specific subgroups, even if not dominant everywhere. |

<Tip>
  **How `percentile` ranking works.** Each feature is ranked by the 90th percentile of its abundance across samples. This favors features that reach a high abundance in at least part of the cohort, making it a balanced middle ground between `mean`, which favors features that are abundant on average, and `prevalence`, which favors features detected in many samples.
</Tip>

Where the aggregated category sits in the stack and legend is set by [Place "Others" / "Unassigned"](#place-others-unassigned), usually `last`, since these represent less informative features.

### 3. Annotate samples with metadata

The colored strips above the bars display sample metadata chosen.

* Choose which  metadata to display through [Sample annotation](#sample-annotation) parameter: **categorical** variables (sex, treatment, disease status, cohort) appear as distinct colors, and **numerical** variables (age, BMI) as a continuous scale. <br />
* Remove from the plot samples lacking chosen annotation by checking  [Drop samples with missing annotation](#drop-samples-with-missing-annotation).

<Tip>
  **Why annotations matter.** Compositional patterns become meaningful once they can be linked to sample characteristics. With metadata aligned across many samples, a shift that consistently follows a variable like treatment or disease status stands out, suggesting how the variable may shape the community.
</Tip>

### 4. Set the feature colors

The colors of the feature segments are set by the [Feature color palette](#feature-color-palette). Since communities are compared visually by color, a clear, distinguishable palette is what lets real compositional differences stand out rather than blur together among similar shades. This affects appearance only, not the data.

### 5. Arrange and group the samples

How the bars are organized is controlled by [Sample arrangement](#sample-arrangement), with three options:

| Option     | What changes visually                                         | When to use it                                                                            |
| :--------- | :------------------------------------------------------------ | :---------------------------------------------------------------------------------------- |
| `Sort`     | Keeps all samples in one chart, ordered by selected metadata. | Inspect all samples together while stratifying by metadata (sex, cohort, disease status). |
| `Facet`    | Splits the chart into separate panels by metadata.            | Compare groups while still seeing individual sample bars.                                 |
| `Collapse` | Combines samples by group, one bar per group.                 | A compact summary of overall composition per group.                                       |

Each option unlocks one or two follow-up parameters:

**`Sort`** uses [Sample ordering metadata](#sample-ordering-metadata) to set the order, with [Samples in ascending order](#samples-in-ascending-order) for the direction. This places samples that share a value (same treatment, cohort, or disease status) next to each other. The ordering options come from whatever you selected in [Sample annotation](#sample-annotation).<br />

<Frame caption="Stacked Bar Chart obtained by setting Sample Arrangement to 'sort', and using 'bodysite ' and 'dermotype' as Sample ordering metadata">
  <img src="https://mintcdn.com/cmbio/rXnT_KRi2R3YfV3p/images/stacked_barchart_sort.png?fit=max&auto=format&n=rXnT_KRi2R3YfV3p&q=85&s=c880eee72061c62a4b8029f41574f394" alt="Stacked Barchart Sort" width="5105" height="1509" data-path="images/stacked_barchart_sort.png" />
</Frame>

* **`Facet`** also uses [Sample ordering metadata](#sample-ordering-metadata) to order samples within each panel, and adds [Metadata columns for faceting](#metadata-columns-for-faceting) to choose the variable that splits the panels.
  <Frame caption="Stacked Bar Chart faceted by Bodysite and sorted by Dermotype">
    <img src="https://mintcdn.com/cmbio/rXnT_KRi2R3YfV3p/images/stacked_barchart-2.png?fit=max&auto=format&n=rXnT_KRi2R3YfV3p&q=85&s=aca384fd078a1aaccad43881179f8850" alt="Stacked Barchart 2" width="5975" height="1671" data-path="images/stacked_barchart-2.png" />
  </Frame>
* **`Collapse`** also uses [Sample ordering metadata](#sample-ordering-metadata) to define the groups, and shows one bar per group. Each feature segment is the collapsed (summed) composition of the samples in that group, displayed as relative abundance. This is useful for spotting features that shift on group average, but it hides sample-to-sample variability, so it is best when group-level patterns matter more than individual samples.

<Frame caption="Stacked barchart obtained by setting Sample Arrangement to 'collapse' and 'ethnicity' as Sample Ordering Metadata">
  <img src="https://mintcdn.com/cmbio/rXnT_KRi2R3YfV3p/images/stacked_barchart_collapsed.png?fit=max&auto=format&n=rXnT_KRi2R3YfV3p&q=85&s=68075604752a830825e17b0bf918dc2e" alt="Stacked Barchart Collapsed" width="2507" height="1475" data-path="images/stacked_barchart_collapsed.png" />
</Frame>

<Note>
  **Which parameters appear depends on the arrangement.** `Sort`, `Facet`, and `Collapse` all reveal [Sample ordering metadata](#sample-ordering-metadata) (and its direction). `Facet` additionally reveals [Metadata columns for faceting](#metadata-columns-for-faceting). In every case, the metadata available for ordering is whatever you chose in [Sample annotation](#sample-annotation).
</Note>

### 6. Show or hide sample labels

[Show sample labels](#show-sample-labels) toggles the sample names along the x-axis. Keep them on for small cohorts where identifying individual samples helps, and off for large cohorts where labels would crowd the plot.

<Warning>
  Stacked bar charts are descriptive and exploratory. A visible difference in composition should be confirmed with appropriate statistical analysis (differential abundance testing, diversity analysis, or machine-learning models) depending on the question.
</Warning>

## Recommended parameters

### Pre-processing

Select your workflow. These pre-processing values vary by data type; the display settings below are the same regardless of workflow.

<Tabs>
  <Tab title="Kepler - Host-Agnostic Taxonomic Profiling (WGS)">
    | Parameter                            | Recommended value                                                                                                                                          |
    | :----------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | Taxonomic Rank                       | `species`                                                                                                                                                  |
    | Data Table Pre-processing Method     | <ul><li>`Raw` if samples have comparable read depths</li><li>`Filter` if a few samples have notably lower read depth than the rest of the cohort</li></ul> |
    | Read Depth                           | `default`                                                                                                                                                  |
    | Feature Relative Abundance Threshold | `0.0001`                                                                                                                                                   |
    | Feature Prevalence Threshold         | `0`                                                                                                                                                        |
  </Tab>

  <Tab title="CHAMP - Human Taxonomic Profiling (WGS)">
    | Parameter                            | Recommended value                                                                                                                                          |
    | :----------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | Taxonomic Rank                       | `species`                                                                                                                                                  |
    | Data Table Pre-processing Method     | <ul><li>`Raw` if samples have comparable read depths</li><li>`Filter` if a few samples have notably lower read depth than the rest of the cohort</li></ul> |
    | Read Depth                           | `default`                                                                                                                                                  |
    | Feature Relative Abundance Threshold | `0.0001`                                                                                                                                                   |
    | Feature Prevalence Threshold         | `0`                                                                                                                                                        |
  </Tab>

  <Tab title="16S SR Amplicon Classification - Taxonomic">
    | Parameter                            | Recommended value                                                                                                                                          |
    | :----------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | Taxonomic Rank                       | `genus`                                                                                                                                                    |
    | Data Table Pre-processing Method     | <ul><li>`Raw` if samples have comparable read depths</li><li>`Filter` if a few samples have notably lower read depth than the rest of the cohort</li></ul> |
    | Read Depth                           | `default`                                                                                                                                                  |
    | Feature Relative Abundance Threshold | `0.0001`                                                                                                                                                   |
    | Feature Prevalence Threshold         | `0`                                                                                                                                                        |
  </Tab>

  <Tab title="16S LR Amplicon profiling - Taxonomic">
    | Parameter                            | Recommended value                                                                                                                                          |
    | :----------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | Taxonomic Rank                       | `species`                                                                                                                                                  |
    | Data Table Pre-processing Method     | <ul><li>`Raw` if samples have comparable read depths</li><li>`Filter` if a few samples have notably lower read depth than the rest of the cohort</li></ul> |
    | Read Depth                           | `default`                                                                                                                                                  |
    | Feature Relative Abundance Threshold | `0.0001`                                                                                                                                                   |
    | Feature Prevalence Threshold         | `0`                                                                                                                                                        |
  </Tab>

  <Tab title="Host-Agnostic Functional Profiling (WGS)">
    | Parameter                            | Recommended value |
    | :----------------------------------- | :---------------- |
    | Data Table Pre-processing Method     | `Raw`             |
    | Feature Relative Abundance Threshold | `0.0001`          |
    | Feature Prevalence Threshold         | `0`               |
  </Tab>

  <Tab title="CHAMP Functional (GMM, GBM, KEGG)">
    | Parameter                            | Recommended value |
    | :----------------------------------- | :---------------- |
    | Data Table Pre-processing Method     | `Raw`             |
    | Feature Relative Abundance Threshold | `0.0001`          |
    | Feature Prevalence Threshold         | `0`               |
  </Tab>

  <Tab title="AMR/VF - Functional">
    | Parameter                            | Recommended value |
    | :----------------------------------- | :---------------- |
    | Data Table Pre-processing Method     | `Raw`             |
    | Feature Relative Abundance Threshold | `0.0001`          |
    | Feature Prevalence Threshold         | `0`               |
  </Tab>
</Tabs>

### Stacked Bar Chart settings

| Parameter                     | Recommended value                                                                                                                                                                                                                                                                                                                                                                                                                        |
| :---------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Y-axis Values                 | `relative`                                                                                                                                                                                                                                                                                                                                                                                                                               |
| Top Features (N)              | `30`                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Feature Ranking Method        | <ul><li>`percentile` : balances prevalence and abundance.</li><li>`mean` : to highlight highly abundant features</li><li>`prevalence` : select the most common features across samples.</li><li>`variance` : highlight most variable features.</li></ul>                                                                                                                                                                                 |
| Feature Color Palette         | `tab20b`                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Sample Arrangement            | <ul><li>`none` : quick default overview.</li><li>`sort` : group samples by metadata</li><li>`facet`:  re-group the cohort by a metadata variable.</li><li>`collapse` : collapses composition of same group samples into a single bar. Useful to get a compact view of cohort composition.</li></ul> NOTE: to sort, facet or collapse by one or more metadata fields, specify the variable through the Sample Ordering Metadata parameter |
| Place "Others" / "Unassigned" | `last`                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Show Sample Labels            | ✅ with small cohorts (\< 40 samples)                                                                                                                                                                                                                                                                                                                                                                                                     |
| Sample Annotation             | Metadata of interest (avoid selecting too many)                                                                                                                                                                                                                                                                                                                                                                                          |

## Parameter reference

<AccordionGroup>
  <Accordion title="Sample Annotation" icon="table-columns">
    One or more metadata columns shown as colored strips above the bars, connecting composition patterns to sample metadata.

    **Options** · Columns from the metadata table associated with the query used to create the analysis

    **Default** · `None`

    **Suggested** · Variables relevant to the biological question, such as `treatment`, `disease status`, `body site`, `cohort`, `time point`, `age group`, `sex`, or `sequencing batch`. Avoid selecting too many, or the plot becomes hard to read.
  </Accordion>

  <Accordion title="Drop samples with missing annotation" icon="filter-circle-xmark">
    Whether samples with missing values in the selected annotation are removed from the plot.

    **Options** · `TRUE` (drop them) or `FALSE` (keep them)

    **Default** · `TRUE`

    **Suggested** · Leave `TRUE` when the annotation is essential and unannotated samples should not appear. Use `FALSE` to preserve sample size and see where unannotated samples fall.

    <Note>
      When `TRUE`, samples missing the chosen annotation are removed from the plot. When `FALSE`, they are kept and assigned to a default missing-value group.
    </Note>
  </Accordion>

  <Accordion title="Feature Ranking Method" icon="arrow-down-wide-short">
    How features are ranked before the top *N* are chosen for display.

    **Options** · `mean`, `prevalence`, `variance`, `percentile`

    **Default** · `mean`

    **Suggested** · `percentile` is balanced, surfacing features that reach high abundance in a meaningful fraction of samples. Use `mean` for dominant features, `prevalence` for widely shared ones, and `variance` for features that change strongly across samples.

    <Note>
      The ranking method controls which features get their own colors. `percentile` ranks each feature by the 90th percentile of its abundance across samples (zeros included), so sparse features that spike in only a few samples still rank low. Different methods surface different biological patterns.
    </Note>
  </Accordion>

  <Accordion title="Top Features (N)" icon="list-ol">
    The number of top-ranked features shown with individual colors.

    **Options** · Integer from `1` to `30` **Default** · `10`

    **Suggested** · `5–20` depending on dataset complexity and readability; `10` is a practical default.

    <Note>
      Features are first ranked by the chosen method, then the top `N` are displayed individually; the rest are grouped into `Others` / `Unassigned`. For example, `mean` ranking with `N = 10` shows the 10 features with the highest average abundance.
    </Note>
  </Accordion>

  <Accordion title="Y-axis Values" icon="percent">
    Whether the y-axis shows absolute read counts or relative abundance.

    **Options** · `absolute`, `relative`

    **Default** · `absolute`

    **Suggested** · `relative` for most cross-sample comparisons, since it makes bars directly comparable. `absolute` when read-count differences are biologically or technically relevant.

    <Note>
      Relative abundance is usually easier to interpret; absolute counts vary with sequencing depth, so compare them carefully.
    </Note>
  </Accordion>

  <Accordion title="Feature Color Palette" icon="palette">
    The palette used to color feature segments.

    **Options** · Discrete palettes configured in the platform

    **Default** · `tab20b`

    **Suggested** · A palette that makes features easy to tell apart. Discrete palettes are recommended, since each color represents a different taxon or function.
  </Accordion>

  <Accordion title="Show Sample Labels" icon="tag">
    Whether sample names are displayed along the x-axis.

    **Options** · `TRUE` or `FALSE`

    **Default** · `TRUE`

    **Suggested** · `TRUE` for small cohorts where identifying samples helps; `FALSE` for many samples where labels crowd the plot.
  </Accordion>

  <Accordion title="Sample Arrangement" icon="chart-column">
    How samples are organized in the chart.

    **Options** · `None`, `sort`, `facet`, `collapse`

    **Default** · `None` (samples are ordered alphabetically by sample name)

    **Suggested** ·

    * `None`, no metadata ordering; samples are ordered alphabetically by sample name.
    * `sort`, order samples by metadata so similar samples sit together.
    * `facet`, split into panels by a categorical variable to compare groups while keeping individual bars.
    * `collapse`, summarize into group-level bars for a compact overview.

    <Note>
      Arrangement changes only how the chart is organized, not the underlying values. It also determines which follow-up parameters appear: `sort`, `facet`, and `collapse` all enable [Sample ordering metadata](#sample-ordering-metadata), and `facet` additionally enables [Metadata columns for faceting](#metadata-columns-for-faceting). Example: to compare taxonomic profiles across cancer subtypes while showing treatment status, facet by subtype and annotate by treatment.
    </Note>
  </Accordion>

  <Accordion title="Sample Ordering Metadata" icon="arrow-down-a-z">
    *Available when Sample arrangement is set to `sort`, `facet`, or `collapse`.*

    The metadata column(s) used to order samples. The available choices are the variables you selected in [Sample annotation](#sample-annotation).

    **Options** · Any metadata chosen in Sample annotation

    **Default** · `None`

    **Suggested** · A variable that makes the plot easier to read, such as `disease status`, `treatment`, `cohort`, `time point`, `body site`, or `read depth`. Sorting by read depth, for instance, can reveal whether composition tracks sequencing depth.
  </Accordion>

  <Accordion title="Samples in Ascending Order" icon="arrow-up-arrow-down">
    *Available when at least one column is chosen in Sample ordering metadata.*

    The direction of sorting for the selected ordering metadata.

    **Options** · `TRUE` (ascending) or `FALSE` (descending)

    **Default** · `TRUE`

    **Suggested** · Whichever direction makes the plot easiest to interpret. Affects visual order only, not feature values or sample inclusion.
  </Accordion>

  <Accordion title="Place &#x22;Others&#x22; / &#x22;Unassigned&#x22;" icon="layer-group">
    Whether the aggregated `Others` / `Unassigned` segment, which combines the abundance of all features outside the top `N`, appears at the top or the bottom of each sample's bar.

    **Options** · `first`, `last`

    **Default** · `last`

    **Suggested** · `last` for most plots, since this segment represents aggregated, less informative features.

    <Note>
      Features outside the top `N` are grouped into `Others` / `Unassigned` to keep the chart readable; this controls where that group sits in the bar.
    </Note>
  </Accordion>

  <Accordion title="Metadata Columns for Faceting" icon="table-cells">
    *Available when Sample arrangement is set to `facet`.*

    The categorical column used to create panels when the chart is faceted.

    **Options** · Categorical columns chosen in [Sample ordering metadata](#sample-ordering-metadata)

    **Default** · `None`

    **Suggested** · A categorical variable defining the main groups to divide the chart into, such as `disease status`, `treatment`, `cohort`, `body site`, `cancer subtype`, or `time point`.

    <Note>
      Used only when arrangement is `facet`. Example: faceting by `cancer subtype` creates a panel per subtype, while sample annotations can still show treatment, sex, or cohort.
    </Note>
  </Accordion>
</AccordionGroup>