TABLE OF CONTENTS

• Introduction
• 1. Create plot and choose algorithm
• 2. Select data
• 3. Set parameters
  • 3.1. Input
  • 3.2 Scaling
  • 3.3 Feature Selection
    • 3.3.1 Custom
    • 3.3.2 Highly variable
    • 3.3.3 Predefined groups of genes
    • 3.3.4 All
  • 3.4. Clustering
  • 3.5. Advanced
• 4. Running the feature heatmap algorithm
• 5. Feature heatmap interactive plot page
  • 5.1 Order Elements
  • 5.2 Plot Parameters
  • 5.3 Marker format color
  • 5.4 Export setting
• 5. Video tutorial
• 6.Useful links
• Heatmaps

Introduction

A heatmap is a two-dimensional representation of data, in which the data quantification is represented as colors. A heatmap can provide a comprehensive summary of the whole data, and for that reason heatmaps are invaluable tools to explore and understand complex datasets. In short, heatmaps use colors to communicate the relationships between data values, that would be much harder to understand if presented numerically in a spreadsheet. Heatmaps may also be combined with hierarchical clustering, which groups features and/or observations together based on the similarity of their expression/abundance pattern. This can be useful for identifying features that are commonly regulated, or biological signatures associated with a particular condition.

The UniApp provides two types of heatmaps: the features heatmap and the correlation heatmap. In features heatmaps, the data is displayed as a grid (cells), where each column represents an observation, and each row represents a feature. The color and intensity of the cells is used to represent changes in the feature expression/abundance. In correlation heatmaps, both the rows and the columns represent observations, and the color and intensity of the boxes is used to represent the correlation coefficient between all observations. 

In this section, we explain how to create a feature heatmap using the UniApp.

1. Create plot and choose algorithm

To begin, you should assign a name, write a description for your plot and choose "Feature heatmap" as your analysis algorithm. You can find these on the Create Plot field. Then, you should choose "Feature heatmap" from the Choose algorithm to run your analysis dropdown menu. Once you input all desired information, you can click on Select algorithm button to finish this stage. 

2. Select data

In this step, you need to present the right data to UniApp to be processed. By clicking on Choose track element dropdown menu, you can select the input data. Additionally, you can subset the observations that you want to have included in the feature heatmap via the Select observations button which will lead you to the Select observations page.

3. Set parameters

In this step, you need to set the desired parameters for your feature heatmap plot. These parameters are further explained below.

3.1. Input

In the Input tab you can specify how your data will be grouped. From the Observation variable dropdown menu you can select a categorical metadata variable based on which your observations will be grouped.

Note that you can only select variables that group your data into 250 groups or less. If you try to run the feature heatmap with an inappropriate variable selected a warning message will be displayed.

3.2 Scaling

Scaling determines the way you want to scale your data. For more information about data scaling, see section on Useful concepts. 

3.3 Feature Selection

In the Feature selection tab you can specify which features will be included in your feature heatmap. From the Features selected dropdown menu you can select the following options:

• Custom
• Highly variable
• Metabolic
• Transcription factors
• Transporters
• Cell surface
• All

3.3.1 Custom

When selecting the "Custom" option a new multi-select dropdown menu will be displayed called Custom features. Here you can input one or more features of interest present in your input data.

Note that the order in which you select the features is the same order in which the features will appear in the feature heatmap. If no clustering was perfomed on the features you can later modify the order of features in the interactive plot page of the feature heatmap.

3.3.2 Highly variable

When selecting the "Highly variable" option a new numerical input menu will be displayed called Number of highly variable features. Here you can specify how many of the top most variable features will you have plotted in your feature heatmap.

3.3.3 Predefined groups of genes

Selecting the options "Metabolic", "Transcription factors", "Transporters" or "Cell surface" will include only the features from these predefined gene groups in your feature heatmap.

3.3.4 All

Selecting the option "All" will include all the features present in the input data in your feature heatmap.

3.4. Clustering

In the clustering tab you can on which location and how clustering will be performed. With the toggle buttons under Clustering location you can choose whether to perform the clustering on:

• Rows - the features
• Columns - the observation groups
• Both - by selecting both the "Rows" and "Columns" options
• None - by leaving the not selecting either option

If you do select a clustering location you can set the following clustering parameters:

Distance measure: the distance measure to use during the distance calculation step. See the section on useful concepts for an in-depth explaination of different distance measure options.

Agglomeration method: the agglomeration method to use during the hierarchical clustering. See the section on useful concepts for an in-depth explaination of different agglomeration method options.

Use squared distance: whether to use the squared distances or not. This can be useful when using some agglomeration methods, like "Centroid". 

Tree cutting: determines whether to define the colors of the dendrogram:

• "Manualy" -  by defining how many colors should be used in the interactive plot page
• "p-value" - automatically by using the p-value calculated with multiscale bootstrap analysis.

If you select the "p-value" option two additional options will appear: 

p-value cutoff: Traditionally, the cut-off value to reject the null hypothesis is 0.05, which means that when no difference exists, such an extreme value for the test statistic is expected less than 5% of the time.

Number of bootstrapping: you can choose the number of replications of the multiscale bootstrap analysis.

3.5. Advanced

Here you can set whether to force positive values or not.

4. Running the feature heatmap algorithm

After you finish setting up the Create plot page you click on the Run button to run the feature heatmap algorithm. You will be re-directed to the your starting analysis track where you can view the feature heatmap as an interactive plot.

5. Feature heatmap interactive plot page

The visualization settings enables the user to configure various parameters and to format the plot according to their preferences. The following four tabs can be expanded to configure the visualisation settings of the plot.

5.1 Order Elements

Order elements help you to arrange the order of the feature on the x-axis and/or observation groups on the y-axis of your feature heatmap. You can do so, simply by dragging and dropping the elements in the order you want. 

Note that if clustering was performed you will not be able to override the order determined by clustering.

    You can make your feature heatmaps more aesthetically pleasing by ordering elements to make a ladderized appearance.

5.2 Plot Parameters

You can change the display of your plot and its properties through following parameters:

• Plot type: can be regular heatmap or dot plot heatmap. In a dot plot heatmap the size of the dots are relative to the number of cells expressing the feature in a certain cluster.

• Show table: displays numerical values for the heatmap in a table.

• Show unscaled table: displays unscaled numerical values for the heatmap in a table.

• Reverse colors: reverses color code. 

• Reverse dendrogram: reverses dendrogram.

• Show color bar: toggles color bar.

• Ladderize dendrogram: Ladderize dendrogram.

• Show legend: toggles legend. 

• Hide observation names: toggle to show or hide observation names.

• Hide feature names: toggle to show or hide feature names.

• Override column order: overrides column order determined by clustering.

• Color scheme: select color scheme.

• Number of colors: set number of colors on the heatmap.

• Grid size: sets grid size.

• Column font size: sets column font size.

• Row font size: sets row font size.

• Row margin: sets row margin size.

• Column margin: sets column margin size.

• Number of colors row dendrogram: sets number of colors for the row dendogram. Note that this option works only if you selected the Manual option in the Heatmap analysis - Algorithm - Parameters - Tree cutting.

• Number of colors column dendrogram: sets number of colors for the column dendogram. Note that this option works only if you selected the Manual option in the Heatmap analysis - Algorithm - Parameters - Tree cutting.

• Width of dendrogram: sets width of dendogram. 

• Legend size: sets legend size. 

• Maximum number of features to plot: sets the maximum number of features to plot.

5.3 Marker format color

Under the marker format and color tab a color scale can be selected for the plot.

Gene expression colour scale: By clicking on the pull down menu the user is will be able to choose a colour scale from various available options.

Reverse color scale: The reverse color scale allows for the user to flip the color scale relative to the default settings. By clicking on toggle at default settings the toggle will move from no to yes the color scale leading to the color scale being flipped. In order to restore the original settings the user must simply click on the toggle, as it moves back to no the color scale will be reversed.

5.4 Export setting

The export settings allows for the user to export the plot based on a preferred formats.

Export format: By clicking on the pull down menu the user will be able to select a preferred export format (png, pdf, etc).

Width of the plot: The width of the plot can be manually configured by inputting a preferred width in the open field

Height of the plot: The height of the plot can be manually configured by inputting a preferred height into the open field

File name: The user can also assign a file name by inputting a preferred name into the open field

By clicking the download plot button, the graph will automatically downloaded with the given file name based on the inputted features.

5. Video tutorial

Coming soon.

• Heatmaps

• Creating clustered heatmaps (heatmaply)
• Assessing uncertainty in hierarchical clustering (pvclust)
• Data scaling