class, var_names, groupby, use_raw=None, log=False, num_categories=7, categories_order=None, title=None, figsize=None, gene_symbols=None, var_group_positions=None, var_group_labels=None, var_group_rotation=None, layer=None, standard_scale=None, ax=None, values_df=None, vmin=None, vmax=None, vcenter=None, norm=None, **kwds)

Allows the visualization of values using a color map.

adata : AnnData

Annotated data matrix.

var_names : Union[str, Sequence[str], Mapping[str, Union[str, Sequence[str]]]]

var_names should be a valid subset of adata.var_names. If var_names is a mapping, then the key is used as label to group the values (see var_group_labels). The mapping values should be sequences of valid adata.var_names. In this case either coloring or ‘brackets’ are used for the grouping of var names depending on the plot. When var_names is a mapping, then the var_group_labels and var_group_positions are set.

groupby : Union[str, Sequence[str]]

The key of the observation grouping to consider.

use_raw : Optional[bool] (default: None)

Use raw attribute of adata if present.

log : bool (default: False)

Plot on logarithmic axis.

num_categories : int (default: 7)

Only used if groupby observation is not categorical. This value determines the number of groups into which the groupby observation should be subdivided.

categories_order : Optional[Sequence[str]] (default: None)

Order in which to show the categories. Note: add_dendrogram or add_totals can change the categories order.

figsize : Optional[Tuple[float, float]] (default: None)

Figure size when multi_panel=True. Otherwise the rcParam['figure.figsize] value is used. Format is (width, height)


If True or a valid dendrogram key, a dendrogram based on the hierarchical clustering between the groupby categories is added. The dendrogram information is computed using If tl.dendrogram has not been called previously the function is called with default parameters.

gene_symbols : Optional[str] (default: None)

Column name in .var DataFrame that stores gene symbols. By default var_names refer to the index column of the .var DataFrame. Setting this option allows alternative names to be used.

var_group_positions : Optional[Sequence[Tuple[int, int]]] (default: None)

Use this parameter to highlight groups of var_names. This will draw a ‘bracket’ or a color block between the given start and end positions. If the parameter var_group_labels is set, the corresponding labels are added on top/left. E.g. var_group_positions=[(4,10)] will add a bracket between the fourth var_name and the tenth var_name. By giving more positions, more brackets/color blocks are drawn.

var_group_labels : Optional[Sequence[str]] (default: None)

Labels for each of the var_group_positions that want to be highlighted.

var_group_rotation : Optional[float] (default: None)

Label rotation degrees. By default, labels larger than 4 characters are rotated 90 degrees.

layer : Optional[str] (default: None)

Name of the AnnData object layer that wants to be plotted. By default adata.raw.X is plotted. If use_raw=False is set, then adata.X is plotted. If layer is set to a valid layer name, then the layer is plotted. layer takes precedence over use_raw.

title : Optional[str] (default: None)

Title for the figure.


Expression cutoff that is used for binarizing the gene expression and determining the fraction of cells expressing given genes. A gene is expressed only if the expression value is greater than this threshold.


If True, gene expression is averaged only over the cells expressing the given genes.

standard_scale : Optional[Literal['var', 'group']] (default: None)

Whether or not to standardize that dimension between 0 and 1, meaning for each variable or group, subtract the minimum and divide each by its maximum.

values_df : Optional[DataFrame] (default: None)

Optionally, a dataframe with the values to plot can be given. The index should be the grouby categories and the columns the genes names.


Are passed to matplotlib.pyplot.scatter().

See also


Simpler way to call MatrixPlot but with less options.


to plot marker genes identified using the rank_genes_groups() function.


Simple visualization of the average expression of a few genes grouped by the category ‘bulk_labels’.

import scanpy as sc
adata = sc.datasets.pbmc68k_reduced()
markers = ['C1QA', 'PSAP', 'CD79A', 'CD79B', 'CST3', 'LYZ'], markers, groupby='bulk_labels').show()

Same visualization but passing var_names as dict, which adds a grouping of the genes on top of the image:

markers = {'T-cell': 'CD3D', 'B-cell': 'CD79A', 'myeloid': 'CST3'}, markers, groupby='bulk_labels').show()














add_dendrogram([show, dendrogram_key, size])

Show dendrogram based on the hierarchical clustering between the groupby categories.

add_totals([show, sort, size, color])

Show barplot for the number of cells in in groupby category.



legend([show, title, width])

Configure legend parameters


Renders the image but does not call

savefig(filename[, bbox_inches])

Save the current figure


Show the figure

style([cmap, edge_color, edge_lw])

Modifies plot visual parameters.


Plots a transposed image.