scanpy.pl.violin

Note

Both backends are accessible as scanpy.pl.violin. The active backend is chosen by scanpy.settings.preset: the default is the legacy matplotlib backend; set it to scanpy.Preset.ScanpyV2Preview to use the HoloViews backend.

New (HoloViews)

scanpy.plotting._v2.violin(adata, /, vdims, *, kdims=(), color=None)

Shortcut for a violin plot.

Overloads:

• adata (AnnData), vdims (AdDim), kdims (Collection[AdDim]), color (AdDim | None) → hv.Violin

• adata (AnnData), vdims (AdDim), kdims (Collection[AdDim]), color (Collection[AdDim]) → hv.Layout

• adata (AnnData), vdims (Collection[AdDim]), kdims (Collection[AdDim]), color (AdDim | None) → hv.Layout

• adata (AnnData), vdims (Collection[AdDim]), kdims (Collection[AdDim]), color (Collection[AdDim]) → hv.NdLayout

If vdims is an AdDim, a single violin is returned:

>>> hv.Violin(adata, kdims, [vdims, color]).opts(violin_fill_color=color, ...)

If either vdims or color is a collection (not both), a layout is returned:

>>> hv.Layout([violin(adata, kdims, vdim, ...) for vdim in vdims]).opts(...)

If both are collections, a 2D NdLayout grid is returned, one violin per (vdim, color) combination.

Parameters:

adata AnnData

The AnnData object.

vdims Collection[AdDim] | AdDim

The value dimension(s). If a collection is passed, multiple plots are created (see above).

kdims Collection[AdDim] (default: ())

The key dimensions (color will be added automatically).

color AdDim | Collection[AdDim] | None (default: None)

The (categorical) color dimension: for each category, a violin is drawn. If a collection is passed, multiple plots are created (see above).

Returns:

A Violin plot or a Layout / NdLayout containing multiple violin plots.

Examples

bokeh

import scanpy as sc
import holoviews as hv

sc.settings.preset = sc.Preset.ScanpyV2Preview
A = sc.pl.hv_init('bokeh')

adata = sc.datasets.pbmc68k_reduced()
sc.pl.violin(adata, A.obs[["percent_mito", "n_counts", "n_genes"]]).opts(
    hv.opts.Violin(ylim=(0, None))
)

matplotlib

import scanpy as sc
import holoviews as hv

sc.settings.preset = sc.Preset.ScanpyV2Preview
A = sc.pl.hv_init('matplotlib')

adata = sc.datasets.pbmc68k_reduced()
sc.pl.violin(adata, A.obs[["percent_mito", "n_counts", "n_genes"]]).opts(
    hv.opts.Violin(ylim=(0, None))
)

plotly

import scanpy as sc
import holoviews as hv

sc.settings.preset = sc.Preset.ScanpyV2Preview
A = sc.pl.hv_init('plotly')

adata = sc.datasets.pbmc68k_reduced()
sc.pl.violin(adata, A.obs[["percent_mito", "n_counts", "n_genes"]]).opts(
    hv.opts.Violin(ylim=(0, None))
)

bokeh

sc.pl.violin(adata, A.obs["S_score"], color=A.obs["bulk_labels"]).opts(
    width=500, xrotation=30
)

matplotlib

sc.pl.violin(adata, A.obs["S_score"], color=A.obs["bulk_labels"]).opts(
    width=500, xrotation=30
)

WARNING:param.main: Option 'violin_fill_color' for Violin type not valid for selected backend ('matplotlib'). Option only applies to following backends: ['bokeh']
WARNING:param.main: Option 'width' for Violin type not valid for selected backend ('matplotlib'). Option only applies to following backends: ['bokeh', 'plotly']

plotly

sc.pl.violin(adata, A.obs["S_score"], color=A.obs["bulk_labels"]).opts(
    width=500, xrotation=30
)

WARNING:param.main: Option 'violin_fill_color' for Violin type not valid for selected backend ('plotly'). Option only applies to following backends: ['bokeh']

bokeh

sc.pl.violin(
    adata,
    vdims=A.obs[["percent_mito", "n_counts", "n_genes"]],
    color=A.obs[["phase", "louvain"]],
)

matplotlib

sc.pl.violin(
    adata,
    vdims=A.obs[["percent_mito", "n_counts", "n_genes"]],
    color=A.obs[["phase", "louvain"]],
)

WARNING:param.main: Option 'violin_fill_color' for Violin type not valid for selected backend ('matplotlib'). Option only applies to following backends: ['bokeh']
WARNING:param.main: Option 'violin_fill_color' for Violin type not valid for selected backend ('matplotlib'). Option only applies to following backends: ['bokeh']
WARNING:param.main: Option 'violin_fill_color' for Violin type not valid for selected backend ('matplotlib'). Option only applies to following backends: ['bokeh']
WARNING:param.main: Option 'violin_fill_color' for Violin type not valid for selected backend ('matplotlib'). Option only applies to following backends: ['bokeh']
WARNING:param.main: Option 'violin_fill_color' for Violin type not valid for selected backend ('matplotlib'). Option only applies to following backends: ['bokeh']
WARNING:param.main: Option 'violin_fill_color' for Violin type not valid for selected backend ('matplotlib'). Option only applies to following backends: ['bokeh']

plotly

sc.pl.violin(
    adata,
    vdims=A.obs[["percent_mito", "n_counts", "n_genes"]],
    color=A.obs[["phase", "louvain"]],
)

WARNING:param.main: Option 'violin_fill_color' for Violin type not valid for selected backend ('plotly'). Option only applies to following backends: ['bokeh']
WARNING:param.main: Option 'violin_fill_color' for Violin type not valid for selected backend ('plotly'). Option only applies to following backends: ['bokeh']
WARNING:param.main: Option 'violin_fill_color' for Violin type not valid for selected backend ('plotly'). Option only applies to following backends: ['bokeh']
WARNING:param.main: Option 'violin_fill_color' for Violin type not valid for selected backend ('plotly'). Option only applies to following backends: ['bokeh']
WARNING:param.main: Option 'violin_fill_color' for Violin type not valid for selected backend ('plotly'). Option only applies to following backends: ['bokeh']
WARNING:param.main: Option 'violin_fill_color' for Violin type not valid for selected backend ('plotly'). Option only applies to following backends: ['bokeh']

Legacy (matplotlib)

scanpy.pl.violin(adata, keys, groupby=None, *, log=False, use_raw=None, stripplot=True, jitter=True, size=1, layer=None, density_norm='width', order=None, multi_panel=False, ncols=None, xlabel='', ylabel=None, rotation=None, show=None, ax=None, save=None, scale=density_norm, **kwds)

Violin plot.

Wraps seaborn.violinplot() for AnnData.

Parameters:

adata AnnData

Annotated data matrix.

keys str | Sequence[str]

Keys for accessing variables of .var_names or fields of .obs.

groupby str | None (default: None)

The key of the observation grouping to consider.

log bool (default: False)

Plot on logarithmic axis.

use_raw bool | None (default: None)

Whether to use raw attribute of adata. Defaults to True if .raw is present.

stripplot bool (default: True)

Add a stripplot on top of the violin plot. See stripplot().

jitter float | bool (default: True)

Add jitter to the stripplot (only when stripplot is True) See stripplot().

size int (default: 1)

Size of the jitter points.

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.

density_norm Literal['area', 'count', 'width'] (default: 'width')

The method used to scale the width of each violin. If ‘width’ (the default), each violin will have the same width. If ‘area’, each violin will have the same area. If ‘count’, a violin’s width corresponds to the number of observations.

order Sequence[str] | None (default: None)

Order in which to show the categories.

multi_panel bool (default: False)

Display keys in multiple panels also when groupby is not None.

ncols int | None (default: None)

Number of panels per row. If None (default), all panels are placed in a single row (the original layout). If set to an integer, panels wrap into a grid with this many columns. Effective in the multi_panel=True path (no groupby) and in the multi-key groupby path; ignored when only a single panel would be produced.

xlabel str (default: '')

Label of the x axis. Defaults to groupby if rotation is None, otherwise, no label is shown.

ylabel str | Sequence[str] | None (default: None)

Label of the y axis. If None and groupby is None, defaults to 'value'. If None and groubpy is not None, defaults to keys.

rotation float | None (default: None)

Rotation of xtick labels.

show bool | None (default: None)

Show the plot, do not return axis.

save bool | str | None (default: None)

If True or a str, save the figure. A string is appended to the default filename. Infer the filetype if ending on {'.pdf', '.png', '.svg'}. (deprecated in favour of sc.pl.plot(show=False).figure.savefig()).

ax Axes | None (default: None)

A matplotlib axes object. Only works if plotting a single component.

**kwds

Are passed to violinplot().

Return type:

Axes | FacetGrid | None

Returns:

A Axes object if ax is None else None.

Examples

import scanpy as sc
sc.settings.preset = sc.Preset.ScanpyV1
adata = sc.datasets.pbmc68k_reduced()
sc.pl.violin(adata, keys='S_score')

Plot by category. Rotate x-axis labels so that they do not overlap.

sc.pl.violin(adata, keys='S_score', groupby='bulk_labels', rotation=90)

Set order of categories to be plotted or select specific categories to be plotted.

groupby_order = ['CD34+', 'CD19+ B']
sc.pl.violin(adata, keys='S_score', groupby='bulk_labels', rotation=90,
    order=groupby_order)

Plot multiple keys.

sc.pl.violin(adata, keys=['S_score', 'G2M_score'], groupby='bulk_labels',
    rotation=90)

For large datasets consider omitting the overlaid scatter plot.

sc.pl.violin(adata, keys='S_score', stripplot=False)

Wrap multiple keys into a 2-column grid.

sc.pl.violin(adata, keys=['S_score', 'G2M_score', 'n_counts'],
    multi_panel=True, ncols=2)

See also

pl.stacked_violin