Getting Started

Clustergrammer is a web-based tool for visualizing and analyzing high-dimensional data as interactive and shareable hierarchically clustered heatmaps (see Introduction to Clustergrams for more information). Clustergrammer can be used in three main ways:

  1. Clustergrammer Web App:
  2. Clustergrammer Jupyter Widget
  3. Clustergrammer-JS and Clustergrammer-PY libraries

This section will provide information on how to interact with the visualization and how to quickly visualize your own data using the Clustergrammer Web App and the Clustergrammer Jupyter Widget. See Case Studies and Examples for examples of how Clustergrammer can be used to explore and analyze real world data. For developers interested in building their own web page using Clustergrammer, please refer to the Web-Development with Clustergrammer section.

Interacting with Clustergrammer Heatmaps

Clustergrammer produces highly interactive visualizations that enable intuitive exploration of high-dimensional data including:

Press play or interact with the gene-expression demo below to see some of Clustergrammer’s interactive features and see Interacting with the Visualization for more information:

Clustergrammer also has Biology-Specific Features for working with gene-level data including:

  • Mouseover gene names and description look-up (using Harmonizome)
  • Enrichment analysis to find biological information (e.g. up-stream transcription factors) specific to your set of genes (using Enrichr)

Clustergrammer Web-App

Users can easily generate an interactive and shareable heatmap visualization using the Clustergrammer Web App (see upload section screenshot below). Simply upload a tab-separated matrix file (see Matrix Formats and Input/Output for more information) at the homepage to be redirected to a permanent and shareable visualization of your data.

Clustergrammer Web

Users can upload their data using the web app homepage. Simply choose your file and upload to be redirected to your permanent and shareable visualization.

Once you upload your data, the Clustergrammer Web App clusters your data and produces three views: a heatmap of your input matrix, a similarity matrix of your columns, and a similarity matrix of your rows. See the screenshots below and the example visualization for an example results page.

Heatmap View

Web application heatmap

Above is an example clustergram visualization produced by the Clustergrammer Web App. Clustergrammer produces three views of your data; the clustered heatmap view is shown above.

Similarity Matrix View

Web application sim-mat

Clustergrammer produces similarity matrices of rows and columns to provide additional perspectives on your data. Above is an example column similarity matrix.

Users can share their interactive visualizations using their permanent link. See Interacting with the Visualization for more information.


Jupyter notebooks are ideal for generating reproducible workflows and analysis. They are also the best way to share Clustergrammer’s interactive visualizations while providing context, analysis, and the underlying data to enable reproducibility (see Sharing with nbviewer). The Clustergrammer Jupyter Widget enables users to easily produce interactive visualizations within a Jupyter notebook that can be shared with collaborators (using nbviewer). The Clustergrammer Jupyter Widget can be used to visualize a matrix of data from a matrix file or from a Pandas DataFrame (see Matrix Formats and Input/Output for more information).

Clustergrammer has been applied to visualize and analyze a wide variety of biological and non-biological data. See the Jupyter notebook examples below and Case Studies and Examples for more information:

To use the Clustergrammer Jupyter Widget users need to install: Python, Jupyter notebook, the widget dependencies (see Jupyter Widget Dependencies), and ipywidgets version >6.0.0 (required for saving notebook with widgets). Users can install Anaconda, a Python distribution that includes the Jupyter notebook as well as other scientific computing libraries, to easily obtain the necessary dependencies (except ipywidgets version >6.0.0). Once these requirements have been met, clustergrammer_widget can then be installed (with pip) and enabled using the following commands:

pip install --upgrade clustergrammer_widget
jupyter nbextension enable --py --sys-prefix widgetsnbextension
jupyter nbextension enable --py --sys-prefix clustergrammer_widget

With the clustergrammer_widget installed and enabled users can visualize their data (from a file) using the following Python commands:

# import clustergrammer_widgets and initialize network object
from clustergrammer_widget import *
net = Network(clustergrammer_widget)

# load matrix file and cluster using default parameters

# make interactive widget

See the screenshot below for an example widget visualization:

Jupyter Widget NBViewer

Clustergrammer can be used as an interactive widget within a Jupyter notebook and shared using nbviewer (see Running_clustergrammer_widget.ipynb example).

Users can download and reproduce the example notebook, Running_clustergrammer_widget.ipynb, by cloning its GitHub repo. For more information about using the widget (e.g. visualizing data from a Pandas DataFrame and sharing notebooks) see Clustergrammer Jupyter Widget.