> ## 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. # Heatmap on Cosmos-Hub 2.0 This page covers how the heatmap module works in Cosmos-Hub 2.0: how to read each part of the figure and which parameters customize it. For what a heatmap is and when to use one, see the [Heatmap overview](/analysis/heatmap/overview). # Module output and customization * **Annotated Heatmap:** a highly customizable heatmap to inspect patterns microbial feature abundances across your cohort. Heatmap Docs ## **Annotated Heatmap** ### Customize the heatmap cells The cell is the basic unit of the heatmap. Each cell sits at the intersection of a microbial feature (rows by default) and a sample (columns by default), and its color indicates how abundant that feature is in that sample, with low and high values shown as opposite ends of the color scale. #### Setting the feature color palette * Set the color palette for feature abundance using the [Feature Color Palette](#feature-color-palette) dropdown. **Can I display features as columns and samples as rows?** Yes, use the [Heatmap orientation](#heatmap-orientation) parameter to switch whether rows represent features or samples. #### Transforming abundance values By default, when working with relative abundances (Analysis metric = `relative_abundance`), the color scale spans the full range (0 to 100%). This is intuitive, but microbiome data usually has a long tail of low-abundance features, where subtle - but informative - compostional patterns between your groups can be overshadowed by the high intensity of the dominant species. The [Value Scaling](#value-scaling) parameter transforms the values before they're mapped to color. This is useful to 'inflate' low relative abundance values to make it easier to detect differences between low-abundance features: | Transformation | What it does | When to use it | | :------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------- | | `Log2` / `Log10` | Compresses the high end and spreads out the low end, making small differences among low-abundance features visible. | To explore variation among low-abundance features. | | `CLR` (centered log-ratio) | Accounts for the compositional nature of microbiome data (abundances sum to a fixed total), making cross-feature comparisons more meaningful. | When you need compositionally aware comparisons across features. | | `Presence/absence` | Reduces each cell to simply "present" or "absent." | When you care whether a feature is there rather than how much. | ### Samples (column) and features (rows) metadata annotations Annotations are colored bars above the sample columns that overlay metadata onto the heatmap, so you can track sample characteristics alongside the microbial data. #### Adding Sample (column) annotations Use the [Sample Annotation](#sample-annotation) parameter to choose which metadata variables to add to the samples. **Categorical** variables (treatment group, body site, disease status) appear as distinct colors, and **numerical** variables (age, pH, BMI) appear as a graduated scale. The [Drop samples with missing annotation](#drop-samples-with-missing-annotation) option controls whether samples that lack the chosen annotation are removed. #### Adding Feature (row) annotations You can also annotate the **features** (rows) to add context about the features themselves, such as taxonomic information or other feature-level attributes. Use the [Feature Annotation](#feature-annotation) parameter to choose which feature-level variables to display, and [Keep features with missing annotation](#keep-features-with-missing-annotation) to decide whether unannotated features are kept. Annotations are especially useful alongside column clustering. If samples cluster by their microbial profiles *and* the annotation bar shows they share a clinical or experimental trait, that is a strong visual cue of a real association. #### Decide how many features to display A typical dataset can have hundreds or thousands of features, which makes it difficult to display them all on a single heatmap. * Limit how many rows appear by setting the [Top features (N)](#top-features-n) parameter. For example, choosing 10 shows the top 10 features from the full matrix, ordered by your ranking method. * Decide how features are ranked by choosing a criterion with the [Feature Ranking Method](#feature-ranking-method) parameter. This sorts the features and keeps the top N: | Ranking method | What it selects | | :------------- | :----------------------------------------------------------------------------------------------------------------------------- | | `Mean` | Features with the highest average abundance across all samples. | | `Prevalence` | Features detected in the largest number of samples. | | `Variance` | Features that vary most across samples. These are often the most biologically interesting, since they help distinguish groups. | | `Percentile` | Features ranked by a chosen percentile of their abundance distribution. | ### 3. Hierarchical Clustering: Ordering and clustering of rows and columns Clustering reorders rows and columns so that similar profiles sit next to each other, which reveals patterns that a fixed order would hide. The heatmap uses **hierarchical clustering**, a method that builds a tree (called a dendrogram) grouping samples or features by similarity. **How does hierarchical clustering work?** It starts with each sample (or feature) on its own, then repeatedly joins the two most similar ones into a group, then joins groups into larger groups, until everything sits in one tree. To decide what "most similar" means, it measures the distance between two profiles using the same metrics as in [beta-diversity analysis](#beta-diversity-overview). The **distance metric** sets how that similarity is measured, and the **linkage** sets how groups are joined step by step. The [Clustered axis](#clustered-axis) parameter sets whether you cluster columns, rows, both, or neither. * **Columns (samples)** groups together samples with similar overall profiles. This is useful for seeing whether, for example, treatment and control samples separate. Paired with sample annotations, a cluster that matches a shared trait is a strong cue of a biological pattern. * **Rows (features)** groups together features with similar abundance patterns across samples. This is useful for spotting co-occurring taxa that may share ecological niches or interactions. * **Both** reorganizes the heatmap so that co-abundant features align with similar samples, revealing **blocks**, which are sets of features that are characteristically high or low in a particular set of samples. This is often where the most informative patterns emerge, such as a microbial signature specific to a treatment or disease group. Hierarchical clustering is performed on the top N features. #### Choosing the distance metric \[Advanced] Choose how the similarity between pairs of profiles or features should be measured in terms of beta-diversity by selecting [Distance metric](https://docs.cosmosid.com/#distance-metric). To see which distance metrics are supported and how to choose, refer to [Beta Diversity on the Cosmos-Hub 2.0](/DAP_docs/beta-diversity-on-the-dap##1-choose-how-to-measure-sample-distances#choose-distance-metric) #### Choose the linkage method \[Advanced] Choose [Clustering method (linkage)](https://docs.cosmosid.com/#clustering-method), which then sets how clusters are progressively merged into the tree. In hierarchical clustering, **linkage** defines how the distance *between clusters* is calculated at each step as they are merged into a tree (dendrogram). Different linkage methods use different rules for “cluster–cluster distance,” for example We recommend trying a few combinations of Distance metrics and Linkage methods to find the most interpretable structure for your data. ### 4. Exporting the heatmap Scroll to the end of the output page and click **Download Tables and Images** to export the heatmap in .svg and .png format, and the data table with the numerical input used to plot it. ## Recommended parameters ### Pre-processing | Parameter | Recommended value | | :----------------------------------- | :------------------- | | Analysis Metric | `relative_abundance` | | Taxonomic Rank | `species` | | Data Table Pre-processing Method | `Raw` or `Filter` | | Read Depth | `default` | | Feature Relative Abundance Threshold | `0.0001` | | Feature Prevalence Threshold | `0` | | Parameter | Recommended value | | :----------------------------------- | :------------------- | | Analysis Metric | `relative_abundance` | | Taxonomic Rank | `species` | | Data Table Pre-processing Method | `Raw` or `Filter` | | Read Depth | `default` | | Feature Relative Abundance Threshold | `0.0001` | | Feature Prevalence Threshold | `0` | | Parameter | Recommended value | | :----------------------------------- | :------------------- | | Analysis Metric | `relative_abundance` | | Taxonomic Rank | `genus` | | Data Table Pre-processing Method | `Raw` or `Filter` | | Read Depth | `default` | | Feature Relative Abundance Threshold | `0.0001` | | Feature Prevalence Threshold | `0` | | Parameter | Recommended value | | :----------------------------------- | :------------------- | | Analysis Metric | `relative_abundance` | | Taxonomic Rank | `species` | | Data Table Pre-processing Method | `Raw` or `Filter` | | Read Depth | `default` | | Feature Relative Abundance Threshold | `0.0001` | | Feature Prevalence Threshold | `0` | | 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` | | 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` | | 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` | ### Heatmap settings | Parameter | Recommended value | | :--------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Top Features (N) | | | Feature Ranking Method | | | Value Scaling | | | Feature Color Palette | `viridis` | | Clustered Axis | `both` | | Distance Metric | | | Clustering Method | `average` | | Heatmap Orientation | `features_rows` | | Sample Annotation | Metadata of interest | | Feature Annotation | A higher taxonomic level (for example `phylum`) for taxonomic heatmaps | ## Parameter reference One or more metadata columns used to annotate samples, shown as colored bars above the heatmap. **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`, or `sex`. Annotations help interpret patterns, but selecting too many makes the figure harder to read. Whether samples with missing values in the selected sample annotation are kept in the heatmap. **Options** · `TRUE` or `FALSE` **Default** · `FALSE` a default group value is assigned to all features with missing values. **Suggested** · Use `TRUE` when the annotation is essential and unannotated samples should be removed. Use `FALSE` to preserve sample size, or to see where unannotated samples cluster relative to annotated ones. An annotation used to group or label features (rows). **Options** · Available feature annotations, depending on the type of profiles in the Data Table (currently available only for taxonomic profiles)  **Default** · `None` **Suggested** · For taxonomic heatmaps, use a higher taxonomic level (`phylum`, `class`, `family`) to annotate lower-level features such as species. . Feature annotations help show whether related features behave similarly, for example annotating species by phylum reveals whether specific taxonomic groups are enriched in certain samples. Whether features with missing annotation values are kept. * **Options** · `TRUE` or `FALSE` * **Default** · `FALSE` a default group value is assigned to all features with missing values. * **Suggested** · Use `FALSE` for most taxonomic analyses, where annotations are usually complete. Use `TRUE` if missing annotations are expected and you don't want to drop those features. If enabled, unannotated features are kept and assigned to a default missing-value group; if disabled, they are removed from the annotated heatmap. The method used to rank features across the whole cohort before the top *N* are selected for display. * **Options** · `mean`, `prevalence`, `variance`, `percentile` * **Default** · `mean` * **Suggested** : * `percentile` is a balanced option for features that are both abundant and informative. * Use `mean` to prioritize highly abundant features * `prevalence` for features seen in many samples * `variance` for features that vary strongly across samples. The number of top-ranked features to display. * **Options** · Integer from `1` to `30` * **Default** · `10` * **Suggested** · `10` for a concise, readable heatmap; `20` to `30` for a broader exploratory view. More features give more detail but reduce readability, use fewer for presentation, more for exploration. The color palette used to display feature values. * **Options** · Palettes configured in the platform * **Default** · `viridis` * **Suggested** · Colorblind-friendly continuous palettes such as `viridis` for most heatmaps; alternatives like `inferno` when stronger contrast is needed. The palette only affects display, not the underlying data. Choose one that makes high and low values easy to tell apart. Whether values are transformed before plotting. **Options** · `None`, `linear`, `log2`, `log10`, `asinh`, `clr`, `presence/absence` **Default** · `None` **Suggested**: * `None`: display values as directly as possible, especially for relative abundance. * `log2` / `log10`: reduce the visual dominance of highly abundant features. * `asinh`: a log-like transform that handles zero values more easily. * `clr`: a composition-aware transformation. * `presence/absence`: reduces each cell to whether a feature is detected, ignoring how much. Scaling strongly affects interpretation. Without it, highly abundant features can dominate the color range; with it, lower-abundance patterns become easier to see. Whether features or samples are displayed as rows. * **Options** · `features_rows`, `samples_rows` * **Default** · `features_rows` * **Suggested** · Use `features_rows` as standard. Use `samples_rows` when there are more features than samples, or when it improves readability. Orientation affects only the layout, not the values or clustering results. Which axis is clustered and shown with a dendrogram. * **Options** · `None`, `rows`, `columns`, `both` * **Default** · `None` * **Suggested** · Use `both` to cluster samples and features; `rows` or `columns` to focus on one dimension; `None` to keep the original order. Sample clustering can show whether samples from the same condition have similar profiles; feature clustering can reveal taxa or functions that behave similarly across samples. How distances between rows or columns are calculated when clustering is enabled. **Options** · `braycurtis`, `canberra`, `correlation`, `cosine`, `euclidean`, `jaccard`, and others **Default** · `euclidean` Different metrics define community similarity differently and can produce different dendrograms. How distances are converted into a dendrogram (the linkage method). * **Options** · `single`, `complete`, `average`, `centroid`, `median`, `ward`, `weighted` * **Default** · `single` The linkage method affects the dendrogram shape and the row/column order, but not the underlying values.