plot_heatmap

SingleCell.plot_heatmap(x, y, filename=None, /, *, cells_to_plot_column='passed_QC', normalize_rows=False, normalize_columns=False, ax=None, figure_kwargs=None, colormap=None, heatmap_kwargs=None, label=False, label_format=None, label_kwargs=None, colorbar=True, colorbar_kwargs=None, title=None, title_kwargs=None, xlabel=True, xlabel_kwargs=None, ylabel=True, ylabel_kwargs=None, despine=True, savefig_kwargs=None)

Plot a heatmap of the count of each combination of two categorical columns, x and y. If normalize_rows or normalize_columns is specified, plot percentages instead of counts, so that each row or column sums to 100%.

Parameters:

• x: SingleCellColumn

  the first column; must be String, Enum, Categorical, or integer

• y: SingleCellColumn

  the second column; must be String, Enum, Categorical, or integer

• filename: str | Path | None

  the file to save to. If None, generate the plot but do not save it, which allows it to be shown interactively or modified further before saving.

• cells_to_plot_column: SingleCellColumn | None

  an optional Boolean column of obs indicating which cells to plot. Can be a column name, a polars expression, a polars Series, a 1D NumPy array, or a function that takes in this SingleCell dataset and returns a polars Series or 1D NumPy array. Set to None to plot all cells passing QC.

• normalize_rows: bool

  whether to plot percentages instead of counts, so that each row sums to 100%. Mutually exclusive with normalize_columns.

• normalize_columns: bool

  whether to plot percentages instead of counts, so that each column sums to 100%. Mutually exclusive with normalize_rows.

• ax: 'Axes' | None

  the Matplotlib axes to save the plot onto; if None, create a new figure with Matpotlib’s constrained layout and plot onto it

• figure_kwargs: dict[str, Any] | None

  a dictionary of keyword arguments to be passed to plt.figure() when ax is None, such as:

  • figsize: a two-element sequence of the width and height of the figure in inches. The default is a complicated formula based on the number of genes and cell types being plotted, unlike Matplotlib’s default of [6.4, 4.8].

  • layout: the layout mechanism used by Matplotlib to avoid overlapping plot elements. Defaults to ‘constrained’, instead of Matplotlib’s default of None.

• colormap: str | 'Colormap' | None

  a string or Colormap object indicating the Matplotlib colormap to use in the heatmap, or None to use Seaborn’s ‘rocket_r’ colormap.

• heatmap_kwargs: dict[str, Any] | None

  a dictionary of keyword arguments to be passed to ax.pcolormesh() when generating the heatmap, such as:

  • rasterized: whether to convert the heatmap cells to a raster (bitmap) image when saving to a vector format like PDF. Defaults to True, instead of Matplotlib’s default of False.

  • norm, vmin, and vmax: control how the colormap maps counts or percentages to heatmap colors

  • edgecolors: the border color of each heatmap cell; defaults to ‘none’, meaning no borders. Specifying cmap will raise an error, since it conflicts with the colormap argument.

• label: bool

  whether to label each cell of the heatmap with its count (or percentage, if normalize_rows=True or normalize_columns=True)

• label_format: str | None

  a format string to apply to the label for each count or percentage. If None, use ‘{:,}’ for counts and ‘{:.2f}%’ for percentages. Can only be specified when label=True.

• label_kwargs: dict[str, Any] | None

  a dictionary of keyword arguments to be passed to ax.text() when adding labels to control the text properties, such as:

  • color and size to modify the text color/size. By default, the color is dark gray for light-colored cells, and white for dark-colored ones.

  • verticalalignment and horizontalalignment to control vertical and horizontal alignment. By default, unlike Matplotlib, these are both set to ‘center’.

  Can only be specified when label=True.

• colorbar: bool

  whether to add a colorbar

• colorbar_kwargs: dict[str, Any] | None

  a dictionary of keyword arguments to be passed to plt.colorbar(), such as:

  • location: ‘left’, ‘right’, ‘top’, or ‘bottom’

  • orientation: ‘vertical’ or ‘horizontal’

  • fraction: the fraction of the axes to allocate to the colorbar. Defaults to 0.15.

  • shrink: the fraction to multiply the size of the colorbar by. Defaults to 0.5, instead of Matplotlib’s default of 1.

  • aspect: the ratio of the colorbar’s long to short dimensions. Defaults to 20.

  • pad: the fraction of the axes between the colorbar and the rest of the figure. Defaults to 0.01, instead of Matplotlib’s default of 0.05 if vertical and 0.15 if horizontal.

  Can only be specified when colorbar=True.

• title: str | None

  the title of the plot, or None to not add a title

• title_kwargs: dict[str, Any] | None

  a dictionary of keyword arguments to be passed to ax.set_title() to control text properties, such as color and size. Can only be specified when title is not None.

• xlabel: str | True | None

  the x-axis label, True to use the name of x as the x-axis label, or None to not label the x-axis

• xlabel_kwargs: dict[str, Any] | None

  a dictionary of keyword arguments to be passed to ax.set_xlabel() to control text properties, such as color and size. Can only be specified when xlabel is not None.

• ylabel: str | True | None

  the y-axis label, True to use the name of y as the y-axis label, or None to not label the y-axis

• ylabel_kwargs: dict[str, Any] | None

  a dictionary of keyword arguments to be passed to ax.set_ylabel() to control text properties, such as color and size. Can only be specified when ylabel is not None.

• despine: bool

  whether to remove the spines (borders of the plot area) from the plot; unlike the other plotting functions in this library, this also removes the left and bottom spines

• savefig_kwargs: dict[str, Any] | None

  a dictionary of keyword arguments to be passed to plt.savefig(), such as:

  • dpi: defaults to 300 instead of Matplotlib’s default of 150

  • bbox_inches: the bounding box of the portion of the figure to save; defaults to ‘tight’ (crop out any blank borders) instead of Matplotlib’s default of None (save the entire figure)

  • pad_inches: the number of inches of padding to add on each of the four sides of the figure when saving. Defaults to ‘layout’ (use the padding from the constrained layout engine, when ax is not None) instead of Matplotlib’s default of 0.1.

  • transparent: whether to save with a transparent background; defaults to True if saving to a PDF (i.e. when filename ends with ‘.pdf’) and False otherwise, instead of Matplotlib’s default of always being False.

  Can only be specified when filename is specified.

Return type:

None