scanpy.pl.DotPlot

class scanpy.pl.DotPlot(adata, 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, expression_cutoff=0.0, mean_only_expressed=False, standard_scale=None, dot_color_df=None, dot_size_df=None, ax=None, vmin=None, vmax=None, vcenter=None, norm=None, **kwds)

Allows the visualization of two values that are encoded as dot size and color. The size usually represents the fraction of cells (obs) that have a non-zero value for genes (var).

For each var_name and each groupby category a dot is plotted. Each dot represents two values: mean expression within each category (visualized by color) and fraction of cells expressing the var_name in the category (visualized by the size of the dot). If groupby is not given, the dotplot assumes that all data belongs to a single category.

Note

A gene is considered expressed if the expression value in the adata (or adata.raw) is above the specified threshold which is zero by default.

An example of dotplot usage is to visualize, for multiple marker genes, the mean value and the percentage of cells expressing the gene across multiple clusters.

Parameters:

adata AnnData

Annotated data matrix.

var_names str | Sequence[str] | Mapping[str, 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 str | Sequence[str]

The key of the observation grouping to consider.

use_raw bool | None (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 Sequence[str] | None (default: None)

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

figsize tuple[float, float] | None (default: None)

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

dendrogram

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 scanpy.tl.dendrogram(). If tl.dendrogram has not been called previously the function is called with default parameters.

gene_symbols str | None (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 Sequence[tuple[int, int]] | None (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 Sequence[str] | None (default: None)

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

var_group_rotation float | None (default: None)

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

layer str | None (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 str | None (default: None)

Title for the figure

expression_cutoff float (default: 0.0)

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.

mean_only_expressed bool (default: False)

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.

kwds

Are passed to matplotlib.pyplot.scatter().

See also

dotplot()

Simpler way to call DotPlot but with less options.

rank_genes_groups_dotplot()

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

Examples

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

Using var_names as dict:

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

Attributes

DEFAULT_CATEGORY_HEIGHT
DEFAULT_CATEGORY_WIDTH
DEFAULT_COLORMAP
DEFAULT_COLOR_LEGEND_TITLE
DEFAULT_COLOR_ON
DEFAULT_DOT_EDGECOLOR
DEFAULT_DOT_EDGELW
DEFAULT_DOT_MAX
DEFAULT_DOT_MIN
DEFAULT_LARGEST_DOT
DEFAULT_LEGENDS_WIDTH
DEFAULT_PLOT_X_PADDING
DEFAULT_PLOT_Y_PADDING
DEFAULT_SAVE_PREFIX
DEFAULT_SIZE_EXPONENT
DEFAULT_SIZE_LEGEND_TITLE
DEFAULT_SMALLEST_DOT
DEFAULT_WSPACE
MAX_NUM_CATEGORIES
MIN_FIGURE_HEIGHT

Methods

add_dendrogram(*[, show, dendrogram_key, size])
add_totals(*[, show, sort, size, color])
get_axes()
getdoc()
legend(*[, show, show_size_legend, ...])	Configures dot size and the colorbar legends
make_figure()	Renders the image but does not call matplotlib.pyplot.show().
savefig(filename[, bbox_inches])	Save the current figure
show([return_axes])	Show the figure
style(*[, cmap, color_on, dot_max, dot_min, ...])
swap_axes(*[, swap_axes])	Plots a transposed image.