histogram#

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

histogram(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, bins: int | None = None, binwidth: float | 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, observations_name: str = 'Barcode', variables_name: str = 'Variable', interactive: bool = False, value_column: str = 'value', variable_column: str = 'variable', **geom_kwargs) → PlotSpec#

Histogram.

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 filter observations on. Only rows with a non-null value are kept.

  • 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 histogram (categorical). Shortcut for mapping=aes(color=…) e,g., ‘cell_type’ or ‘leiden’.

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

  • bins (int | None, default None) – Number of bins. Overridden by binwidth if both are provided.

  • binwidth (float | None, default None) – Width of each bin. Takes precedence over bins.

  • 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 bars in the histogram.

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

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

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

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

Returns:

PlotSpec – Histogram.

Raises:

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

Examples

import cellestial as cl
import scanpy as sc

from lets_plot import *

data = cl.datasets.pbmc3k()

histogram = (
    cl.histogram(data, "n_genes_by_counts", bins=50)
    + ggsize(800, 400)
)

histogram

Split by a categorical group.

histogram = (
    cl.histogram(data, "n_genes_by_counts", fill="cell_type_lvl1", bins=50)
    + ggsize(800, 400)
)

histogram
On this page