Clustergrammer Jupyter Widget

pypi-version npm-version

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 Widget enables users to easily produce interactive visualizations within a Jupyter notebook that can be shared with collaborators (using nbviewer). Clustergrammer-Widget can be used to visualize a matrix of data from a 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:

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

Jupyter Widget Dependencies

Clustergrammer-Widget works with Python 2 and 3.


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 (to save the 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). The clustergrammer_widget can the 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

Clustergrammer-Widget Workflow Example

The Jupyter notebook Running_clustergrammer_widget.ipynb (which is rendered using nbviewer) shows how to visualize a matrix from a file and a Pandas DataFrame. The following examples are taken from this notebook.

Here we are visualizing a matrix of data from a file (e.g. rc_two_cats.txt). We start by making an instance of the Network object, net, which is used to load and cluster the data. Then we pass the data to clustergrammer_widget to generate the visualization (for more information about the Network class, see Clustergrammer-PY API):

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

# load matrix file

# cluster using default parameters

# make interactive widget

Clustergrammer-Widget can also be used as a general purpose Pandas DataFrame viewer. Below is an example of how to visualize a Pandas DataFrame, df, by loading it into the same net object from above:

# load DataFrame

# cluster using default parameters

# make interactive widget

Loading new data into net clears out the old data, which allows net to be easily reused within the same notebook. The net object can also be used to filter and normalize your data before visualizing (note that filtering and normalization are permanent and irreversible). The example below performs Z-score normalization on the columns, and filters to keep the top 200 rows based on their absolute value sum:

# Z-score normalize columns
net.normalize(axis='col', norm_type='zscore', keep_orig=True)

# filter for the top 200 rows based on their absolute value sum
net.filter_N_top('row', 200, 'sum')

# make interactive widget

In the examples above, we clustered our matrix using the default parameters. For more information about the Network object and additional options; see the Clustergrammer-PY API.

Sharing with nbviewer

To enable rendering interactive widgets on nbviewer you must have ipywidgets version 6 or later installed and use the “Save Notebook with Widgets” action in the Widgets menu in the Jupyter notebook (see ipywidgets Rendering Interactive Widgets on nbviewer documentation and screenshot below):

Save Jupyter Widget

Users can save notebooks with interactive HTML widgets using the “Save Notebook with Widgets” action in the Jupyter Notebook Widgets menu as shown here. ipywidgets version 6 or later must be installed in order to enable this feature.

Clustergrammer-Widget Development

Clustergrammer-Widget’s source code can be found in the clustergrammer-widget GitHub repo. Clustergrammer-Widget is built using the ipywidgets framework (using the cookie cutter template).

Please Funding and Contact Nicolas Fernandez or Avi Ma’ayan with questions or use the GitHub issues feature to report an issue.