stacked_violin#

stacked_violin(data: AnnData, keys: Sequence[str] | Mapping[str, Sequence[str]], group_by: str, *, 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, color_by: Literal['median', 'mean', 'group', 'variable'] | None = 'median', size: float = 0.2, color_low: str = '#F5F5F5', color_mid: str | None = None, color_high: str = '#00008B', mid_point: 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_kwargs: dict | None = None, rectangle: bool = True, rectangle_size: float = 0.8, rectangle_color: str = '#3f3f3f', rectangle_kwargs: dict | None = None, key_labels: bool = True, aggregate_key: str = 'expression', value_column: str = 'value', variable_column: str = 'variable', observations_name: str = 'Barcode', variables_name: str = 'Variable', tooltips: Literal['none'] | Sequence[str] | FeatureSpec | None = None, interactive: bool = False, **geom_kwargs) → PlotSpec#

Stacked Violin Plot.

Parameters:

  • data (AnnData) – The AnnData object of the single cell data.

  • keys (Sequence[str] | Mapping[str, Sequence[str]]) – Variable keys laid out along the x-axis. One column of violins per key. When a mapping is provided, each entry maps a group label to the keys belonging to that group; the keys are placed on the x-axis in mapping order. The same key cannot appear in more than one group.

  • group_by (str) – The key used to group observations along the y-axis.

  • 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.

  • color_by ({'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 color_by='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.

  • mid_point ({'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.

    Accepts:

  • geom_color (str | None, default None) – Border color for all violins.

  • 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_kwargs (dict | None, default None) – Additional parameters to pass to the dendrogram geom_path.

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

  • 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.

  • aggregate_key (str, default 'expression') – Name of the per-(variable, group) aggregate column attached to each violin (median or mean, selected by color_by).

  • value_column (str, default 'value') – Name for the value column after unpivoting.

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

  • observations_name (str, default 'Barcode') – The name of the observations column.

  • variables_name (str, 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.

  • interactive (bool, 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.

Examples

A simple stacked violin plot of marker genes across cell types.

import scanpy as sc
from lets_plot import *

import cellestial as cl

data = sc.read_h5ad("data/pbmc3k_pped.h5ad")

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",
    color_by="group",
)
On this page