plot_volcano#

DE.plot_volcano(cell_type, filename=None, /, *, ax=None, figure_kwargs=None, x_column='logFC', y_column='p', significance_column='FDR', threshold=0.05, genes_to_label=10, attraction=0.05, repulsion=1e-06, max_iter=4000, seed=0, padding=4.0, box_padding=4.0, fontsize=10, linewidth=0.6, linecolor='0.45', upregulated_size=6, downregulated_size=6, non_significant_size=4, upregulated_color='#FC4E07', downregulated_color='#00AFBB', non_significant_color='lightgray', upregulated_scatter_kwargs=None, downregulated_scatter_kwargs=None, non_significant_scatter_kwargs=None, legend=True, legend_kwargs=None, title=None, title_kwargs=None, xlabel='$log_2(FC)$', xlabel_kwargs=None, ylabel=Ellipsis, ylabel_kwargs=None, despine=True, savefig_kwargs=None)[source]#

Generate a volcano plot of DE hits.

Plots negative log p-values (or another y_column) on the y-axis against log fold changes (or another x_column) on the x-axis. Upregulated, downregulated and non-significant genes are plotted in three different colors based on significance_column.

Parameters:

  • cell_type: str

    the cell type to generate the volcano 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 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.

  • x_column: str

    the name of a numeric column of self.table to plot on the x-axis

  • y_column: str

    the name of a numeric column of self.table to plot the negative log10 of on the y-axis

  • significance_column: str

    the name of a numeric column of self.table to determine significance from

  • threshold: int | float

    the significance threshold corresponding to significance_column

  • genes_to_label: int | str | Iterable[str] | None

    an integer number of top DE genes (according to y_column) to label, a name or sequence of names of genes to label, or None to not add labels. If an integer, only significant DE genes (according to significance_column) will be labeled, even if genes_to_label is larger than the number of DE genes.

  • attraction: float

    the strength of the spring that pulls each gene label back toward its own point when it touches nothing; larger values keep labels nearer their points.

  • repulsion: float

    the strength of the repulsion that pushes gene labels away from one another and from points; larger values spread the labels wider before they settle. Also the standard deviation of the small initial jitter, so it interacts with seed.

  • max_iter: int

    the maximum number of label force-simulation iterations to run. The simulation also stops early once no label box overlaps anything, so this is only reached for crowded plots.

  • seed: int

    the seed for the small initial jitter that breaks ties between symmetric labels. Fixed, so a given plot always yields the same label layout.

  • padding: float

    the clearance kept, in pixels, between a gene label box and any point (its own, another label’s, or a background gene). It is also the shortest connecting line drawn, so no label sits on its own point without a visible line.

  • box_padding: float

    the padding, in pixels, added around each gene label’s text box. It sets the minimum gap kept between any two labels.

  • fontsize: float

    the gene label font size, in points.

  • linewidth: float

    the width of the lines connecting each gene label to its point, in points.

  • linecolor: Color

    the color of the connecting lines. 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.

  • upregulated_size: int | float

    the size of each upregulated gene’s point

  • downregulated_size: int | float

    the size of each downregulated gene’s point

  • non_significant_size: int | float

    the size of each non-significant gene’s point

  • upregulated_color: Color

    the color of each upregulated gene’s point. 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.

  • downregulated_color: Color

    the color of each downregulated gene’s point. 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.

  • non_significant_color: Color

    the color of each non-significant gene’s point. 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.

  • upregulated_scatter_kwargs: dict[str, Any] | None

    a dictionary of keyword arguments to be passed to ax.scatter() for upregulated genes, 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 gene

    • 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 genes 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 upregulated_size and upregulated_color arguments, respectively.

  • downregulated_scatter_kwargs: dict[str, Any] | None

    a dictionary of keyword arguments to be passed to ax.scatter() for downregulated genes; see the documentation of the upregulated_scatter_kwargs argument for details

  • non_significant_scatter_kwargs: dict[str, Any] | None

    a dictionary of keyword arguments to be passed to ax.scatter() for non-significant genes; see the documentation of the upregulated_scatter_kwargs argument for details

  • legend: bool

    whether to add a legend showing the marker style for upregulated, downregulated, and non-significant points

  • 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 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, 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. Defaults to f’$-log_{{10}}({y_column})$’.

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