stacked_violin#

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

stacked_violin(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 | None = None, scale: Literal['area', 'count', 'width'] = 'width', width_scale: float = 0.85, height_scale: float = 0.85, n_points: int = 64, kde_max_samples: int | None = 1200, fill_statistic: Literal['median', 'mean', 'group', 'variable'] | None = 'median', size: float = 0.2, color_low: str = '#F5F5F5', color_mid: str | None = None, color_high: str = '#00008B', midpoint: Literal['mean', 'median', 'mid'] | float = 'mid', geom_fill: str | None = None, geom_color: str | None = '#1f1f1f', dendrogram: bool = False, dendrogram_color: str = 'black', dendrogram_size: float = 0.5, dendrogram_key: str | None = None, rectangle: bool = True, 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, aggregate_column: str = 'expression', value_column: str = 'value', variable_column: str = 'variable', observation_id_column: str = 'Barcode', variable_id_column: str = 'Variable', tooltips: Literal['none'] | Sequence[str] | FeatureSpec | None = None, interactive: bool = False, **geom_kwargs) → PlotSpec#

Stacked Violin Plot.

Parameters:

data (AnnData | MuData) – The single-cell data object.
keys (Sequence[str] | Mapping[str, Sequence[str]] | None, default None) – Variable keys laid out along the x-axis, one column of violins per key. 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 used to group observations along the y-axis. 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 | None, default None) – If provided, filters out rows where the value column is below the threshold.
scale ({'area', 'count', 'width'}, default 'width') – Method for scaling violin widths. ‘width’, every violin has the same maximum width. ‘count’, width is proportional to the number of observations. ‘area’, widths preserve density area across groups within a variable.
width_scale (float, default 0.85) – Maximum total width of a violin in x units (1 unit = one variable column).
height_scale (float, default 0.85) – Total height of a violin in y units (1 unit = one group row).
n_points (int, default 64) – Number of grid points for the kernel density estimate.
kde_max_samples (int | None, default 1200) – If set, subsample each (variable, group) to at most this many cells before fitting the KDE. Color values (mean/median) and the “count” scale use the full sample size. Sampling is deterministic. None fits the KDE on every cell (slower at scale, no shape approximation).
fill_statistic ({'median', 'mean', 'group', 'variable'} | None, default 'median') – Which value drives the fill aesthetic of each violin. ‘median’ colors by median expression per (variable, group). ‘mean’ colors by mean expression per (variable, group). ‘group’ colors by group_by (categorical palette). ‘variable’ colors by variable_column (categorical palette). None disables fill mapping (use geom_fill for a static fill).
size (float, default 0.2) – Stroke size (edge width) of the violins.
color_low (str, default '#F5F5F5') – Color for low values in the gradient (used when fill_statistic=’mean’).
color_mid (str | None, default None) – Color for mid values in the gradient.
color_high (str, default '#00008B') – Color for high values in the gradient.
midpoint ({'mean', 'median', 'mid'} | float, default 'mid') – Midpoint for the color gradient.
geom_fill (str | None, default None) – Static fill color for all violins. Overrides any fill aesthetic.

geom_colorstr | None, default=’#1f1f1f’: Border color for all violins.
dendrogrambool, 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_colorstr, default=’black’: Color of the dendrogram segments.
dendrogram_sizefloat, default=0.5: Size (thickness) of the dendrogram segments.
dendrogram_keystr | None, default=None: Specific key holding the precomputed dendrogram. By default, dendrogram_{group_by} is used.
rectanglebool, default=True: Whether to add a rectangle border around the data area.
rectangle_sizefloat, default=0.8: Size (thickness) of the rectangle border.
rectangle_colorstr, default=’#3f3f3f’: Color of the rectangle border.
rectangle_kwargsdict | None, default=None: Additional parameters to pass to the rectangle geom_rect.
key_labelsbool, default=True: Whether to draw bracket labels above the plot when keys is a mapping.
key_labels_text_sizefloat, default=1.0: Scale multiplier on the auto-computed bracket label text size.
key_labels_bracket_sizefloat, default=0.6: Size (thickness) of the bracket lines.
key_labels_text_colorstr, default=’black’: Color of the bracket label text.
key_labels_bracket_colorstr, default=’black’: Color of the bracket lines.
key_labels_widthfloat, 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.
aggregate_columnstr, default=’expression’: Name of the per-(variable, group) aggregate column attached to each violin (median or mean, selected by fill_statistic).
value_columnstr, default=’value’: Name for the value column after unpivoting.
variable_columnstr, default=’variable’: Name for the variable column after unpivoting.
observation_id_columnstr, default=’Barcode’: The name of the observations column.
variable_id_columnstr, default=’Variable’: Name for the variables index column.
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.
interactivebool, default=False: Whether to make the plot interactive.
**geom_kwargs: Additional parameters for the geom_polygon layer. For further detail on geom_polygon. https://lets-plot.org/python/pages/api/lets_plot.geom_polygon.html

Returns:

PlotSpec – Stacked violin plot.

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 stacked violin plot of marker genes across cell types.

import scanpy as sc
from ggrust import *

import cellestial as cl

data = cl.datasets.pbmc3k()

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

cl.stacked_violin(
    data,
    keys=markers,
    group_by="cell_type_lvl1",
)

Reorder groups along the y-axis with a dendrogram.

cl.stacked_violin(
    data,
    keys=markers,
    group_by="cell_type_lvl1",
    dendrogram=True,
)

Color violins by group_by instead of the per-cell aggregate.

cl.stacked_violin(
    data,
    keys=markers,
    group_by="cell_type_lvl1",
    fill_statistic="group",
)

Plot the top genes from a precomputed ranking:

sc.tl.rank_genes_groups(data, groupby="cell_type_lvl1")
cl.stacked_violin(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.