plot_voom#

DE.plot_voom(cell_type, filename=None, /, *, ax=None, figure_kwargs=None, point_color=None, point_size=1, line_color=None, line_width=1.5, scatter_kwargs=None, plot_kwargs=None, legend=True, legend_kwargs=None, title=None, title_kwargs=None, xlabel='Average log2(count + 0.5)', xlabel_kwargs=None, ylabel='sqrt(standard deviation)', ylabel_kwargs=None, despine=True, savefig_kwargs=None)[source]#

Generate a voom plot for a cell type that differential expression was calculated for.

Voom plots consist of a scatter plot with one point per gene. They visualize how the mean expression of each gene across samples (x) relates to the gene’s variation in expression across samples (y). The plot also includes a LOESS (also called LOWESS) curve, a type of non-linear curve fit, of the mean-variance (x-y) trend.

Specifically, the x position of a gene’s point is the average, across samples, of the base-2 logarithm of the gene’s count in each sample, plus a pseudocount of 0.5: in other words, mean(log2(count + 0.5)). The y position is the square root of the standard deviation, across samples, of the gene’s log counts per million after regressing out, across samples, the differential expression design matrix.

When running differential expression with voomByGroup, voom is run separately within each group, so the voom plot will show a separate LOESS trendline for each group, with the points and trendlines for each group shown in distinct colors.

Many arguments to this function can be either a single value or a dictionary mapping group names to values. The group names can be viewed with self.groups[cell_type].

Parameters:

  • cell_type: str

    the cell type to generate the voom plot for

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

  • 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. Defaults to [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.

  • point_color: Color | dict[str, Color] | None

    the color of the points in the voom plot. Can be a single color or a dictionary mapping each of the group names in self.groups[cell_type] to colors. When not using voomByGroup, defaults to ‘#666666’ (gray). When using voomByGroup with two groups, defaults to ‘#666666’ for the first group in self.groups[cell_type] and ‘#FF6666’ (red) for the second. When using voomByGroup with more than two groups, must be specified manually. 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.

  • point_size: int | float | dict[str, int | float]

    the size of the points in the voom plot. Can be a single number or a dictionary mapping each of the group names in self.groups[cell_type] to numbers.

  • line_color: Color | dict[str, Color] | None

    the color of the LOESS trendline. Can be a single color or a dictionary mapping each of the group names in self.groups[cell_type] to colors. When not using voomByGroup, defaults to ‘#000000’ (black). When using voomByGroup with two groups, defaults to ‘#000000’ for the first group and ‘#FF0000’ (red). for the second. When using voomByGroup with more than two groups, must be specified manually. 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.

  • line_width: int | float | dict[str, int | float]

    the width of the LOESS trendline. Can be a single number or a dictionary mapping each of the group names in self.groups[cell_type] to numbers.

  • scatter_kwargs: dict[str, Any] | None | dict[str, dict[str, Any] | None]

    a dictionary (or dictionary mapping each of the group names in self.groups[cell_type] to dictionaries) 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 True, instead of Matplotlib’s default of False.

    • marker: the shape to use for plotting each cell

    • norm, vmin, and vmax: control how the numbers in color_column are converted to colors, if color_column is numeric

    • 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 or c/color/norm/vmin/vmax will raise an error, since these arguments conflict with the point_size and point_color arguments, respectively.

  • plot_kwargs: dict[str, Any] | None | dict[str, dict[str, Any] | None]

    a dictionary (or dictionary mapping each of the group names in self.groups[cell_type] to dictionaries) of keyword arguments to be passed to ax.plot() when plotting the trendlines, such as linestyle=’–’ for dashed trendlines. Specifying color/c or linewidth will raise an error, since these arguments conflict with the line_color and line_width arguments, respectively.

  • legend: bool

    whether to add a legend with the colors for each group when using voomByGroup. Only legend=False has an effect, and it can only be specified when using voomByGroup. Without groups, there will never be a legend, so specifying legend=False would be redundant.

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

    • 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 add a legend title

    Can only be specified when using voomByGroup with legend=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 | 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 | 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 top and right spines (borders of the plot area) from the voom 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), 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 PNG=False) and False if saving to a PNG, instead of Matplotlib’s default of always being False.

    Can only be specified when filename is specified.

Return type:

None

On this page