calour.heatmap.plot

calour.heatmap.plot(exp: calour.experiment.Experiment, title=None, barx_fields=None, barx_width=0.3, barx_colors=None, barx_label=True, barx_label_kwargs=None, bary_fields=None, bary_width=0.3, bary_colors=None, bary_label=True, bary_label_kwargs=None, tree=None, tree_size=8, gui='cli', databases=None, **heatmap_kwargs)[source]

Plot the interactive heatmap and its associated axes.

The heatmap is interactive and can be dynamically updated with following key and mouse events:

Event Description
+ or ⇧ → zoom in on x axis
_ or ⇧ ← zoom out on x axis
= or ⇧ ↑ zoom in on y axis
- or ⇧ ↓ zoom out on y axis
left mouse click select the current row and column
⇧ and left mouse click select all the rows between previous selected and current rows
. move the selection down by one row
, move the selection up by one row
< move the selection left by one column
> move the selection right by one column
↑ or = scroll the heatmap up on y axis
↓ or - scroll the heatmap down on y axis
← or < scroll the heatmap left on x axis
→ or > scroll the heatmap right on x axis

Note

This function is also available as a class method Experiment.plot()

Parameters:
  • exp (Experiment) – Input experiment object.
  • title (str, optional) – The title of the figure.
  • barx_fields (str or list of str, optional) –
  • bary_fields (str or list of str, optional) – column name(s) in sample metadata (barx) / feature metadata (bary). It plots a bar for each column. It doesn’t plot color bars by default (None)
  • barx_width (float or list of float, optional) –
  • bary_width (float or list of float, optional) – The thickness of the each bar. The default thickness usually looks good enough.
  • barx_colors (dict, matplotlib.colors.ListedColormap, optional) –
  • bary_colors (dict, matplotlib.colors.ListedColormap, optional) – The colors for each unique values in the column of sample/feature metadata
  • barx_label (bool, optional) –
  • bary_label (bool, optional) – whether to show the labels on the bars.
  • barx_label_kwargs (dict, optional) –
  • bary_label_kwargs (dict, optional) – keyword arguments passing to matplotlib.axes.Axes.annotate() for labels on the bars
  • tree (skbio.TreeNode or None, optional) – None (default) to not plot a tree otherwise, plot the tree dendrogram on the left. NOTE: features are reordered according to the tree
  • tree_size (int, optional) – The width of the tree relative to the main heatmap (12 is identical size)
  • gui (str, optional) – GUI to use. Choice includes ‘cli’, ‘jupyter’, or ‘qt5’
  • databases (list of str or None) – a list of databases to access or add annotation None (default) to use the default field based on the experiment.
Keyword Arguments:
 
  • sample_field (str or None, optional) – The field of sample metadata to display on the x-axis or None (default) to not show x axis.
  • feature_field (str or None (optional)) – The field of feature meadata to display on the y-axis. None (default) to not show y axis.
  • xticklabel_kwargs –
  • yticklabel_kwargs (dict or None, optional) – keyword arguments passing as properties to matplotlib.text.Text for tick labels on x axis and y axis. As an example, xticklabel_kwargs={'color': 'r', 'ha': 'center', 'rotation': 90, 'family': 'serif', 'size'=7}
  • xticklabel_len (int or None) –
  • yticklabel_len (int or None) – The maximal length for the tick labels on x axis and y axis (will be cut to this length if longer). Used to prevent long labels from taking too much space. None indicates no shortening
  • xticks_max (int or None) –
  • yticks_max (int or None) – max number of ticks to render on the heatmap. If None, allow all ticks for each sample (xticks_max) or feature (yticks_max) in the table, which can be very slow if there are a large number of samples or features.
  • clim (tuple of (float, float), optional) – the min and max values for the heatmap color limits. It uses the min and max values in the input Experiment.data array by default.
  • cmap (str or matplotlib.colors.ListedColormap) – str to indicate the colormap name. Default is “viridis” colormap. For all available colormaps in matplotlib: https://matplotlib.org/users/colormaps.html
  • norm (matplotlib.colors.Normalize or None) – passed to norm parameter of matplotlib.pyplot.imshow. Default is log scale.
  • title (None or str, optional) – None (default) to not show title. str to set title to str.
  • rect (tuple of (int, int, int, int) or None, optional) – None (default) to set initial zoom window to the whole experiment. [x_min, x_max, y_min, y_max] to set initial zoom window
  • cax (matplotlib.axes.Axes, optional) – The axes where a legend colorbar for the heatmap is plotted.
  • ax (matplotlib.axes.Axes or None (default), optional) – The axes where the heatmap is plotted. None (default) to create a new figure and axes to plot the heatmap
Returns:

This object contains the figure of the plot (including all the subplots) as its .figure attribute
Return type:

PlottingGUI

See also

heatmap()