plot_markers#

SingleCell.plot_markers(genes, cell_type_column, filename=None, /, *, cells_to_plot_column='passed_QC', color='expression', cell_types=None, excluded_cell_types=None, alphabetical_cell_types=True, figure_kwargs=None, colormap=None, infinity_color='limegreen', NaN_color='lightgray', colorbar=True, colorbar_kwargs=None, swap_axes=False, scatter_kwargs=None, legend_kwargs=None, title=None, title_kwargs=None, xlabel=None, xlabel_kwargs=None, ylabel=None, ylabel_kwargs=None, despine=True, savefig_kwargs=None, num_threads=None)[source]#

Make a dot plot of a set of marker genes of interest across cell types.

The size of a gene’s dot represents its “detection rate” in that cell type: the fraction of cells of that type where the gene has non-zero count. By default (color=’expression’), the color of a gene’s dot represents its expression.

When color=’fold_change’, the color instead represents the gene’s fold change in detection rate between cells of that cell type and cells of every other cell type; this is one of two metrics (along with the detection rate) that are used to select marker genes in find_markers(). color=’fold_change’ gives the same result whether it is run before or after normalization, since it only depends on the pattern of non-zero entries in the data, which is unaffected by normalization.

Unlike the other plotting functions, this is a figure-level rather than an axis-level function, and does not take an axis argument.

Parameters:

genes: str | Iterable[str]
a list of genes to plot: for instance, marker genes found by find_markers(), or marker genes from the literature
cell_type_column: SingleCellColumn
a String, Enum, Categorical, or integer column of obs containing cell-type labels. 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.
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.
color: Literal['expression', 'fold_change']
whether the color of a gene’s dot represents its expression (color=’expression’, the default) or its fold change in detection rate between cells of that cell type and cells of every other cell type (color=’fold_change’). When color=’fold_change’, the colorbar ticks show the raw fold changes, but on a log scale, so that a fold change of 4 is twice as red as a fold change of 2, and a fold change of 0.1 is twice as blue as a fold change of 0.2.
cell_types: str | Iterable[str] | int | Iterable[int] | None
one or more cell types to plot; by default, plots all cell types in cell_type_column. Can also be used to change the order in which cell types are displayed, even if plotting all cell types. Mutually exclusive with excluded_cell_types.
excluded_cell_types: str | Iterable[str] | int | Iterable[int] | None
one or more cell types to exclude from the plot. Mutually exclusive with cell_types.
alphabetical_cell_types: bool
whether to force the cell types to be listed in alphabetical order, even when cell_type_column is a Categorical or Enum column where the categories are in non-alphabetical order. If alphabetical_cell_types=False, cell types will appear in the order specified by the Categorical or Enum column. Has no effect when cell_type_column is a String column, since cell types will always be plotted in alphabetical order by default. alphabetical_cell_types=False can only be specified when cell_types is None, since when cell_types is specified, it defines the order of the cell types regardless.
figure_kwargs: dict[str, Any] | None
a dictionary of keyword arguments to be passed to plt.figure(), 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 ax.scatter() for representing expression values or (if color=’fold_change’) fold changes. Defaults to ‘Reds’ for expression and ‘RdBu_r’ for fold changes.
infinity_color: Color
when color=’fold_change’, the color used to plot infinite log-fold changes (i.e. where a gene is only expressed in the cell type where it is a marker). Can be any valid Matplotlib color, like a hex string (e.g. ‘#FF0000’), a named color (e.g. ‘red’), a 3- or 4-element RGB/RGBA tuple of integers 0-255 or floats 0-1, or a single float 0-1 for grayscale.
NaN_color: Color
when color=’fold_change’, the color used to plot NaN log-fold changes (i.e. where a gene is not expressed in any cell type). Can be any valid Matplotlib color, like a hex string (e.g. ‘#FF0000’), a named color (e.g. ‘red’), a 3- or 4-element RGB/RGBA tuple of integers 0-255 or floats 0-1, or a single float 0-1 for grayscale.
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.
swap_axes: bool
if True, plot genes on the y-axis and cell types on the x-axis, instead of the other way around
scatter_kwargs: dict[str, Any] | None
a dictionary of keyword arguments to be passed to ax.scatter(), such as:
- rasterized: whether to convert the scatter plot points to a raster (bitmap) image when saving to a vector format like PDF. Defaults to False.
- marker: the shape to use for plotting each cell
- norm, vmin, and vmax: control how the colormap maps the numbers in color_column to colors, if color_column is numeric. If neither vmin nor vmax are specified, the default behavior depends on what is being plotted. When color=’expression’ and all expression values are positive, vmin will be set to 0 so that the color scale includes 0. When color=’fold_change’, vmin will be set to -M and vmax to M where M is the magnitude of the largest fold change, so that that the colors for positive and negative fold changes are symmetrical.
- alpha: the transparency of each point
- linewidths and edgecolors: the width and color of the borders around each marker. These are absent by default (linewidths=0, edgecolors=(0, 0, 0, 0)), unlike Matplotlib’s default. Both arguments can be either single values or sequences.
- zorder: the order in which the cells are plotted, with higher values appearing on top of lower ones.
Specifying s, c/color, or cmap will raise an error, since the size and color of each point are set automatically, and cmap conflicts with the colormap argument.
legend_kwargs: dict[str, Any] | None
a dictionary of keyword arguments to be passed to ax.legend() to modify the legend, such as:
- loc, bbox_to_anchor, and bbox_transform to set its location. The legend will be placed in its own axis in the top right of the plot, and by default, loc is set to ‘center’.
- ncols to set its number of columns
- prop, fontsize, and labelcolor to set its font properties
- facecolor and framealpha to set its background color and transparency
- frameon=True or edgecolor to add or color its border. frameon defaults to False, instead of Matplotlib’s default of True.
- title to modify the legend title. Defaults to ‘Detection rate’.
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 | None
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 | None
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 top and right spines (borders of the plot area) from the plot
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.
num_threads: int | None
the number of threads to use when tabulating each gene’s detection rate and fold change. Set num_threads=-1 to use all available cores, as determined by os.cpu_count(), or leave unset to use self.num_threads cores.

Return type:

None

Note

This function may give an incorrect output if the count matrix contains explicit zeros (i.e. if (sc.X.data == 0).any()): this is not checked for, due to speed considerations. In the unlikely event that your dataset contains explicit zeros, remove them by running sc.X.eliminate_zeros() (an in-place operation) first.

Note

This function may give an incorrect output if the count matrix contains negative values: this is not checked for, due to speed considerations.