dotplot#

API pages include interactive (HTML) plots that would possibly not render correctly on a mobile device.

dotplot(data: AnnData | MuData, keys: Sequence[str] | Mapping[str, Sequence[str]] | None = None, group_by: str | None = None, *, modality: str | None = None, markers: bool | str = False, n_genes: int = 5, groups: Sequence[str] | None = None, mapping: FeatureSpec | None = None, threshold: float = 0, size_scale: float = 1.0, variable_column: str = 'variable', color_low: str = '#e6e6e6', color_mid: str | None = None, color_high: str = '#D2042D', midpoint: Literal['mean', 'median', 'mid'] | float = 'mid', sort_by: str | Sequence[str] | None = None, sort_order: Literal['ascending', 'descending'] = 'descending', percentage_column: str = 'pct_exp', mean_column: str = 'avg_exp', rectangle: bool = True, dendrogram: bool = False, dendrogram_color: str = 'black', dendrogram_size: float = 0.5, dendrogram_key: str | None = None, rectangle_size: float = 0.8, rectangle_color: str = '#3f3f3f', rectangle_kwargs: dict | None = None, key_labels: bool = True, key_labels_text_size: float = 1.0, key_labels_bracket_size: float = 0.6, key_labels_text_color: str = 'black', key_labels_bracket_color: str = 'black', key_labels_width: float = 0.6, tooltips: Literal['none'] | Sequence[str] | FeatureSpec | None = None, interactive: bool = False, **geom_kwargs) → PlotSpec#

Dotplot.

Parameters:

  • data (AnnData | MuData) – The single-cell data object.

  • keys (Sequence[str] | Mapping[str, Sequence[str]] | None, default None) – Variable keys to include, placed on the x-axis. A mapping assigns keys to group labels (no key in more than one group). Must be None when markers is set.

  • modality (str | None, default None) – Which modality’s stored analysis results to use when markers or dendrogram is enabled. Required for a multimodal object holding more than one modality, and not accepted otherwise.

  • group_by (str | None, default None) – The key to group the data by. Inferred from a precomputed ranking when markers is set.

  • markers (bool | str, default False) – Derive keys from a precomputed ranking. Pass True to use the default ranking key, or a string to read a custom key (e.g. “rank_genes_groups_wilcoxon”).

  • n_genes (int, default 5) – Number of top genes to take per group when markers is set.

  • groups (Sequence[str] | None, default None) – Subset of groups to include when markers is set; None keeps all groups in their stored order.

  • mapping (FeatureSpec | None, default None) – Aesthetic mappings for the plot, the result of aes().

  • threshold (float, default 0) – The expression threshold to consider a gene as expressed.

  • size_scale (float, default 1.0) – Scaling factor for the point sizes in the plot.

  • variable_column (str, default 'variable') – Name for the variable column after unpivoting.

  • color_low (str, default '#e6e6e6') – Color for low values in the gradient.

  • color_mid (str | None, default None) – Color for mid values in the gradient.

  • color_high (str, default '#D2042D') – Color for high values in the gradient.

  • midpoint ({'mean', 'median', 'mid'} | float, default 'mid') – Midpoint for the color gradient.

  • sort_by (str | Sequence[str] | None, default None) – The column or columns to sort the results by.

  • sort_order (str, default 'descending') – The sort order, either ‘ascending’ or ‘descending’.

  • percentage_column (str, default 'pct_exp') – The name of the percentage column.

  • mean_column (str, default 'avg_exp') – The name of the mean expression column.

  • rectangle (bool, default True) – Whether to add a rectangle border around the data area

  • dendrogram (bool, default False) – Whether to add a dendrogram for the group_by axis. Uses scanpy.tl.dendrogram if not already computed. When True, group order is determined by the dendrogram.

  • dendrogram_color (str, default 'black') – Color of the dendrogram segments.

  • dendrogram_size (float, default 0.5) – Size (thickness) of the dendrogram segments.

  • dendrogram_key (str | None, default None) – Specific key holding the precomputed dendrogram. By default, dendrogram_{group_by} is used.

  • rectangle_size (float, default 0.8) – Size (thickness) of the rectangle border.

  • rectangle_color (str, default '#3f3f3f') – Color of the rectangle border.

  • rectangle_kwargs (dict | None, default None) – Additional parameters to pass to the rectangle geom_rect.

  • key_labels (bool, default True) – Whether to draw bracket labels above the plot when keys is a mapping.

  • key_labels_text_size (float, default 1.0) – Scale multiplier on the auto-computed bracket label text size.

  • key_labels_bracket_size (float, default 0.6) – Size (thickness) of the bracket lines.

  • key_labels_text_color (str, default 'black') – Color of the bracket label text.

  • key_labels_bracket_color (str, default 'black') – Color of the bracket lines.

  • key_labels_width (float, default 0.6) – Bracket width (in column units) for a singleton group. Multi-key groups extend key_labels_width / 2 past the first and last key on each side.

  • tooltips ({'none'} | Sequence[str] | FeatureSpec | None, default None) – Tooltips to show when hovering over the geom. Accepts Sequence[str] or result of layer_tooltips() for more complex tooltips. Use ‘none’ to disable tooltips.

  • interactive (bool, default False) – Whether to make the plot interactive.

  • **geom_kwargs (Any) – Additional keyword arguments for the geom_point layer.

Returns:

PlotSpec – Dotplot.

Raises:

  • UnsupportedDataTypeError – If data is not a supported single-cell data object.

  • KeyNotFoundError – If markers is enabled and the requested ranking result or group is missing.

  • DuplicateKeysError – If a mapping passed to keys assigns the same key to multiple groups.

  • ValueError – If keys and group_by are missing while markers is disabled.

Notes

When dendrogram=True and the requested dendrogram is absent from data.uns, plot construction calls scanpy.tl.dendrogram and stores the result in data.uns. This mutates the input AnnData. Precompute the dendrogram under dendrogram_key to avoid mutation during plotting.

Examples

A simple dotplot.

import scanpy as sc
from ggrust import *

import cellestial as cl

data = cl.datasets.pbmc3k()

markers = ["C1QA", "PSAP", "CD79A", "CD79B", "CST3", "LYZ"]

dot = cl.dotplot(
    data,
    keys=markers,
    group_by="cell_type_lvl1",
)
dot
C1QA PSAP CD79A CD79B CST3 LYZ Lymphocytes B Cells Monocytes Erythroid avg_exp 0 1 2 3 pct_exp 25 50 75 100

Dotplot allows dendrograms among the groups.

dot = cl.dotplot(
    data,
    keys=markers,
    group_by="cell_type_lvl1",
    dendrogram=True,
)
dot
C1QA PSAP CD79A CD79B CST3 LYZ B Cells Monocytes Erythroid Lymphocytes avg_exp 0 1 2 3 pct_exp 25 50 75 100

Modify the dendrogram and rectangle borders.

dot = cl.dotplot(
    data,
    keys=markers,
    group_by="cell_type_lvl1",
    dendrogram=True,
    dendrogram_color="gray",
    dendrogram_size=1,
    rectangle_color="gray",
    rectangle_size=3,
)
dot
C1QA PSAP CD79A CD79B CST3 LYZ B Cells Monocytes Erythroid Lymphocytes avg_exp 0 1 2 3 pct_exp 25 50 75 100

Plot the top genes from a precomputed ranking:

sc.tl.rank_genes_groups(data, groupby="cell_type_lvl1")
cl.dotplot(data, markers=True, n_genes=5)

WARNING: It seems you use rank_genes_groups on the raw count data. Please logarithmize your data before calling rank_genes_groups.
B Cells Erythroid Lymphocytes Monocytes HBB HBA1 HBA2 UBB ALAS2 CD37 HLA-DRA CD79A CD74 CD79B BCL11B CD3E CD3D CD3G IL32 S100A6 MNDA TYROBP S100A4 GRN B Cells Lymphocytes Monocytes Erythroid avg_exp 2 4 6 8 pct_exp 25 50 75 100
On this page