Clustergrammer Jupyter Widget¶
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:
- Single Cell RNA-seq Visualization.ipynb
- Iris Dataset.ipynb
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 instantiating the
net and passing the widget, clustergrammer_widget as an argument. The net object is used to load data, filter, normalize, cluster, and finally to visualize using the widget (for more information about the
Network class, see Clustergrammer-PY API).
Load Data from File
# import classes and instantiate Network instance with the widget as an argument from clustergrammer_widget import * net = Network(clustergrammer_widget) # load matrix file net.load_file('rc_two_cats.txt') # cluster using default parameters net.cluster() # make interactive widget net.widget()
General Purpose DataFrame Viewer
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 net.load_df(df) # cluster using default parameters net.cluster() # make interactive widget net.widget()
Loading new data into
net clears out the old data, which allows
net to be easily reused within the same notebook.
Filtering, Downsampling, and Normalizing
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 net.widget()
In the examples above, we clustered our matrix using the default parameters.
Two-way Widget Communication
In addition to sending information from the back end kernel to the front-end as shown above, widgets can also send information from the visualization to the back end kernel. Clustergrammer-Widget uses this feature to enable users to export their possibly modified visualization as a DataFrame. This can be use to select a cluster of interest, by Cropping or using the Interactive Dendrogram, and pass this cluster to a new dataframe. Alternatively, this can be used to export the visualization as a DataFrame after performing enrichment analysis using Enrichrgram. See the
df_widget method below for an example:
# After modifying the visualization (e.g. dendrogram cropping) we can export the # modified matrix to the back end using the df_widget method df_new = net.df_widget()
For more information about the
Network object and additional options; see the Clustergrammer-PY API.