boxplot#

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

boxplot(data: AnnData, key: str | Sequence[str], *, frame: DataFrame | None = None, group_by: str | None = None, groups: Sequence[str] | str | None = None, drop: Sequence[str] | str | None = None, mapping: FeatureSpec | None = None, axis: Literal[0, 1] | None = None, color: str | None = None, fill: str | None = None, threshold: float | None = None, add_keys: Sequence[str] | str | None = None, tooltips: Literal['none'] | Sequence[str] | FeatureSpec | None = None, geom_fill: str | None = None, geom_color: str | None = None, point_color: str = '#1f1f1f', point_alpha: float = 0.7, point_size: float = 0.5, point_geom: Literal['jitter', 'point', 'sina'] = 'jitter', point_mapping: FeatureSpec | None = None, observations_name: str = 'Barcode', variables_name: str = 'Variable', show_points: bool = True, interactive: bool = False, value_column: str = 'value', variable_column: str = 'variable', point_kwargs: dict[str, Any] | None = None, **geom_kwargs) → PlotSpec#

Boxplot.

Parameters:

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

  • key (str | Sequence[str]) – The key(s) to get the values (numerical). e.g., ‘total_counts’ or a gene name.

  • frame (DataFrame | None, default None) – A prebuilt frame to plot from. If provided, the frame is used directly and building from data is skipped. Must contain the key and grouping columns.

  • group_by (str | None, default None) – Column to group observations on the x-axis. If not provided, falls back to fill, color, or the variable column.

  • groups (str | Sequence[str] | None, default None) – Show only specific groups, keeping rows where group_by matches any of them. Categorical grouping columns only.

  • drop (str | Sequence[str] | None, default None) – Drop specific groups, filtering out rows where group_by matches any of them. Categorical grouping columns only.

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

  • axis ({0,1} | None, default None) – axis of the data, 0 for observations and 1 for variables.

  • color (str | None, default None) – Color aesthetic to split the boxplot (categorical). Shortcut for mapping=aes(color=…) e,g., ‘cell_type’ or ‘leiden’.

  • fill (str | None, default None) – Fill aesthetic to split the boxplot (categorical). Shortcut for mapping=aes(fill=…) e,g., ‘cell_type’ or ‘leiden’.

  • threshold (float | None, default None) – If provided, filters out rows where the value column is below the threshold.

  • add_keys (Sequence[str] | str | None, default None) – Additional keys to include in the dataframe.

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

  • geom_fill (str | None, default None) – Fill color for all boxplots in the boxplot.

  • geom_color (str | None, default None) – Border color for all boxplots in the boxplot.

  • point_color (str, default '#1f1f1f') – Color for the points in the boxplot.

  • point_alpha (float, default 0.7) – Alpha (transparency) for the points in the boxplot.

  • point_size (float, default 0.5) – Size for the points in the boxplot.

  • point_geom ({'jitter','point','sina'}, default is 'jitter') – Geom type of the points, default is geom_jitter.

  • point_mapping (FeatureSpec | None, default None) – Additional aesthetic mappings for the points, the result of aes().

  • observations_name (str, default 'Barcode') – The name to give to barcode (or index) column in the dataframe.

  • variables_name (str, default 'Variable') – The name to give to variable index column in the dataframe.

  • show_points (bool, default True) – Whether to show points.

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

  • variable_column (str, default 'variable') – The name of the variable column in the dataframe.

  • value_column (str, default 'value') – The name of the value column in the dataframe.

  • point_kwargs (dict[str, Any] | None, default None) – Additional parameters for the geom_point layer. For more information on geom_point parameters, see: https://lets-plot.org/python/pages/api/lets_plot.geom_point.html

  • **geom_kwargs – Additional parameters for the geom_boxplot layer. For more information on geom_boxplot parameters, see: https://lets-plot.org/python/pages/api/lets_plot.geom_boxplot.html

Returns:

PlotSpec – Boxplot.

Raises:

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

  • ValueError – If point_geom is not one of the supported point geoms.

Examples

import cellestial as cl
import scanpy as sc

from lets_plot import *

data = cl.datasets.pbmc3k(cache_directory="data")

boxplot = (
    cl.boxplot(
        data,
        "CD14",
        fill="cell_type_lvl1",
        point_size=2,
        threshold=0.1,
    )
    + ggsize(800, 400)
    + scale_fill_brewer(palette="Set2")
    + guides(fill=guide_legend(ncol=2))
)

boxplot

Remove the points.

import cellestial as cl
import scanpy as sc

from lets_plot import *

data = cl.datasets.pbmc3k(cache_directory="data")

boxplot = (
    cl.boxplot(
        data,
        "CD14",
        fill="cell_type_lvl1",
        point_size=2,
        threshold=0.1,
        show_points=False,
    )
    + ggsize(800, 400)
    + scale_fill_brewer(palette="Set2")
    + guides(fill=guide_legend(ncol=2))
)

boxplot

Providing a list of keys.

import cellestial as cl
import scanpy as sc

from lets_plot import *

data = cl.datasets.pbmc3k(cache_directory="data")

boxplot = (
    cl.boxplot(
        data,
        ["pct_counts_in_top_200_genes", "n_genes_by_counts"],
        fill="cell_type_lvl1",
        point_size=0.3,
        point_alpha=0.4,
    )
    + scale_y_log2()
    + ggsize(800, 400)
)
boxplot
On this page