scanpex.pl package

Subpackages

Module contents

scanpex.pl.curate_phase(adata, thresh, ax, s=1, lw=0.5, color='.2')[source]

Assign cell cycle phases and visualize the classification boundaries.

This function first executes the phase curation logic (via scanpex.tl.curate_phase) using the specified threshold. It then generates a scatter plot of ‘S_score’ versus ‘G2M_score’ and overlays the linear boundaries that demarcate the G1, S, and G2M phases.

The decision boundaries are drawn as follows: - Vertical line: Separates G1/G2M from S (at x = thresh). - Horizontal line: Separates G1/S from G2M (at y = thresh). - Diagonal line: Separates S from G2M when both scores are high.

Parameters:

  • adata (ad.AnnData) – The annotated data matrix. Must contain ‘S_score’ and ‘G2M_score’ in .obs. The object is modified in-place to add the ‘phase’ column.

  • thresh (float) – The score threshold used to distinguish proliferating cells from G1. This value determines the position of the boundary lines.

  • ax (matplotlib.axes.Axes) – The axis on which to draw the plot.

  • s (int, optional) – The marker size for the scatter plot points. By default 1.

  • lw (float, optional) – The line width for the decision boundary lines. By default 0.5.

  • color (str, optional) – The color of the decision boundary lines. By default “.2” (dark grey).

Returns:

The plot is drawn directly onto the provided ax object.

Return type:

None

scanpex.pl.gene_list(gl, group_key='leiden', method='pearson', abs_corr=False, use_gene_names=True, cbar_pos=(1, 0.4, 0.025, 0.2), cbar_kws=None, dendrogram_ratio=0.1, cmap='RdYlBu_r', rasterized=True, **kwargs)[source]

Compute and plot the correlation matrix of genes in the GeneList.

This function aggregates expression data based on the provided group_key, calculates pairwise correlations between genes using the specified method, and visualizes the result as a hierarchically clustered heatmap using seaborn.clustermap.

Parameters:

  • gl (ft.GeneList) – The GeneList object containing the genes of interest and methods to retrieve aggregated data.

  • group_key (str, optional) – The key in the observation metadata used to aggregate the data (e.g., cell clusters). Passed to gl._get_aggregated_df. By default “leiden”.

  • method (str, optional) – The method to compute correlation (e.g., ‘pearson’, ‘spearman’, ‘kendall’). Passed to pandas.DataFrame.corr. By default “pearson”.

  • abs_corr (bool, optional) – If True, plots the absolute value of the correlation coefficients. Useful for focusing on the strength of the relationship regardless of direction. By default False.

  • use_gene_names (bool, optional) – If True, uses gene symbols (gl.genes) as axis labels. If False, uses gene IDs (gl.ids). By default True.

  • cbar_pos (tuple of float, optional) – The position of the colorbar (left, bottom, width, height). By default (1, 0.4, 0.025, 0.2).

  • cbar_kws (dict, optional) – Keyword arguments for the colorbar. If None, automatically sets the label to rho or |rho|.

  • dendrogram_ratio (float or tuple of float, optional) – Proportion of the figure size devoted to the dendrograms. By default 0.1.

  • cmap (str, optional) – The mapping from data values to color space. By default “RdYlBu_r”.

  • rasterized (bool, optional) – If True, rasterizes the heatmap mesh to reduce file size when saving as vector graphics (PDF/SVG). By default True.

  • kwargs (dict) – Additional keyword arguments passed to seaborn.clustermap.

Returns:

The ClusterGrid object returned by seaborn.clustermap.

Return type:

seaborn.matrix.ClusterGrid

scanpex.pl.scrublet(adata, ax, x='total_counts', y='n_genes_by_counts', **kwargs)[source]

Visualize predicted doublets on quality control metrics.

This function checks if the Scrublet prediction exists in adata.obs. If not, it executes the prediction using pp.scrublet. It then generates a scatter plot where predicted doublets are highlighted. The data is sorted prior to plotting to ensure that doublets (True) are plotted on top of singlets (False) for better visibility.

Parameters:

  • adata (ad.AnnData) – The annotated data matrix.

  • ax (matplotlib.axes.Axes) – The axis on which to draw the scatter plot.

  • x (str, optional) – The column name in adata.obs for the x-axis. By default “total_counts”.

  • y (str, optional) – The column name in adata.obs for the y-axis. By default “n_genes_by_counts”.

  • **kwargs – Additional keyword arguments passed to scanpy.pl.scatter. If palette is not provided, it defaults to coloring singlets “lightgrey” and doublets “tab:red”.

Returns:

The plot is drawn directly onto the provided ax object.

Return type:

None

scanpex.pl.subplots(nrows=None, ncols=None, n=None, base=(4, 4), figsize=None, vertical=True, flatten=True, **kwargs)[source]

Create a figure and a set of subplots with automatic layout calculation.

This wrapper around matplotlib.pyplot.subplots determines the optimal grid dimensions (nrows x ncols) based on the total number of plots (n). It also automatically scales the figure size based on a base size per subplot.

Parameters:

  • nrows (int, optional) – Number of rows of the subplot grid. If None and n is provided, it may be calculated automatically.

  • ncols (int, optional) – Number of columns of the subplot grid. If None and n is provided, it may be calculated automatically.

  • n (int, optional) –

    Total number of subplots required.

    • If nrows and ncols are None, the grid is calculated to be nearly square (controlled by vertical).

    • If only one of nrows or ncols is provided, the other is calculated to accommodate n plots.

  • base (tuple of float, optional) – The width and height of a single subplot (width, height). Used to calculate figsize if it is not explicitly provided. By default (4, 4).

  • figsize (tuple of float, optional) – The total figure size (width, height). If None, it is calculated as (base[0] * ncols, base[1] * nrows).

  • vertical (bool, optional) – Controls the aspect ratio logic when calculating grid dimensions from n. If True, prioritizes more rows (taller figure). If False, prioritizes more columns (wider figure). By default True.

  • flatten (bool, optional) – If True, returns the axes as a 1D NumPy array (even if there is only one subplot). This ensures consistent iteration (e.g., for ax in axs:). By default True.

  • **kwargs – Additional keyword arguments passed to matplotlib.pyplot.subplots.

Returns:

  • fig (matplotlib.figure.Figure) – The created figure object.

  • axs (matplotlib.axes.Axes or numpy.ndarray) – The axes of the subplots. If flatten is True, this is always a 1D numpy array of Axes objects. Otherwise, it follows the standard matplotlib behavior (Axes object or array of Axes).

Return type:

Tuple[Figure, Axes | ndarray | List[Axes]]

scanpex.pl.umap(adata, title=None, **kwargs)[source]

Generate a UMAP plot with customized aesthetics and legend placement.

This function wraps scanpy.pl.umap to provide a cleaner look by removing axis spines/ticks, enforcing an equal aspect ratio, and positioning the legend (for categorical data) or colorbar (for continuous data) outside the plotting area.

Parameters:

  • adata (ad.AnnData) – The annotated data matrix containing UMAP coordinates.

  • title (str, optional) – The title to display for the legend or colorbar. If None, the capitalized name of the color column is used. By default None.

  • **kwargs –

    Additional keyword arguments passed to scanpy.pl.umap. Notable arguments handled specifically by this wrapper:

    • color (str): Key in adata.obs to color observations by.

    • ax (matplotlib.axes.Axes): The axis to plot on. If not provided, a new figure and axis are created.

Returns:

Returns a tuple of (fig, ax) if a new figure was created (i.e., ax was not provided in kwargs). Returns None if an existing ax was passed (modifies the axis in-place).

Return type:

(matplotlib.figure.Figure, matplotlib.axes.Axes) or None