piaso.plotting package#

piaso.plotting.plot_features_violin(adata, feature_list, groupby: str | None = None, use_raw: bool | None = None, layer: str | None = None, width_single: float = 14.0, height_single: float = 2.0, size: float = 0.1, show_grid: bool = True, show_figure: bool = True, save: str | None = None)#

Plots a violin plot for each feature specified in feature_list using the Scanpy library (sc.pl.violin).

Parameters:

  • adata (anndata.AnnData) – The annotated data matrix of shape n_obs × n_vars. Rows correspond to cells and columns to genes.

  • feature_list (List[str]) – A list of strings denoting the feature names (gene names and cell metrics, e.g., number of genes detected and doublet score) to be visualized.

  • groupby (str, optional) – A key in the observation DataFrame (adata.obs) used to group data points in the violin plot. Default is None, which means no grouping is applied.

  • use_raw (bool, optional) – A boolean indicating whether to use the raw attribute of adata. If True, uses raw data if available.

  • layer (str, optional) – A key from the layers of adata. If provided, the specified layer is used for visualization.

  • width_single (float, optional) – The width of each subplot. Default is 14.0.

  • height_single (float, optional) – The height of each subplot. Default is 2.0.

  • size (float, optional) – The size of the jitter points in the violin plot. Default is 0.1.

  • show_grid (bool, optional) – Whether to display grid lines in the plots. Default is True (grid lines shown).

  • show_figure (bool, optional) – Whether to show the figure (plt.show()). Default is True.

  • save (str, optional) – If provided, the path where the plot should be saved, e.g., ./violin_plot_by_piaso.pdf. If None, the plot is not saved to a file.

Returns:

This function does not return any value but visualizes the violin plots and optionally saves the figure.

Return type:

None

piaso.plotting.plot_embeddings_split(adata, color, splitby, ncol: int = None, dpi: int = 80, col_size: int = 5, row_size: int = 5, vmax: float = None, vmin: float = None, show_figure: bool = True, save: bool = None, layer: str = None, basis: str = 'X_umap', fix_coordinate_ratio: bool = True, show_axis_ticks: bool = False, margin_ratio: float = 0.05, legend_fontsize: int = 10, legend_fontoutline: int = 2, legend_loc: str = 'right margin', legend_marker_size: float = 1.6, x_min=None, x_max=None, y_min=None, y_max=None, **kwargs)#

Plot cell embeddings side by side based on a categorical variable.

The plots are split by a specified categorical variable, with each unique category producing a separate subplot. Data points in each subplot are colored according to the color variable.

Parameters:

  • adata (AnnData) – An AnnData object.

  • color (str) – Used to specify a gene name to plot, or a key in adata.obs used to assign colors to the cells in the embedding plot.

  • splitby (str) – Key in adata.obs used to split the dataset into multiple panels. Each unique value under this key will result in a separate subplot.

  • ncol (int or None, optional (default: None)) – If specified, defines the number of columns per row. If None, the number of columns is computed as the ceiling of n divided by the integer square root of n.

  • dpi (int, optional (default: 80)) – Dots per inch (DPI) setting for the figure.

  • col_size (int, optional (default=5)) – Width (in inches) of each subplot column.

  • row_size (int, optional (default=5)) – Height (in inches) of each subplot row.

  • vmax (float or None, optional (default=None)) – Maximum value for the color scale. If not provided, the upper limit is determined automatically.

  • vmin (float or None, optional (default=None)) – Minimum value for the color scale. If not provided, the lower limit is determined automatically.

  • show_figure (bool, optional (default=True)) – Whether to display the figure after plotting.

  • save (str or None, optional (default=None)) – File path to save the resulting figure. If None, the figure will not be saved.

  • layer (str or None, optional (default=None)) – If specified, the name of the layer in adata.layers from which to obtain the gene expression values.

  • basis (str, optional (default='X_umap')) – Key in adata.obsm that contains the embedding coordinates (e.g., X_umap or X_pca).

  • fix_coordinate_ratio (bool, optional (default=True)) – If True, the aspect ratio of each subplot is fixed so that the x- and y-axes are scaled equally.

  • show_axis_ticks (bool, optional (default=False)) – Whether to display axis ticks and tick labels on the plots.

  • margin_ratio (float, optional (default=0.05)) – Margin ratio for both the x-axis and y-axis limits, relative to the range of the data. This provides additional spacing around the plotted points.

  • legend_fontsize (int, optional (default=9)) – Font size in pt.

  • legend_fontoutline (int, optional (default=2)) – Line width of the legend font outline in pt.

  • legend_loc (str, optional (default='right margin')) – Location of legend, defaults to ‘right margin’.

  • legend_marker_size (float, optional (default=1.5)) – Scaling factor for legend markers (dot size).

  • x_min (float or None, optional (default=None)) – Minimum limit for the x-axis. If None, the limit is computed automatically based on the data.

  • x_max (float or None, optional (default=None)) – Maximum limit for the x-axis. If None, the limit is computed automatically based on the data.

  • y_min (float or None, optional (default=None)) – Minimum limit for the y-axis. If None, the limit is computed automatically based on the data.

  • y_max (float or None, optional (default=None)) – Maximum limit for the y-axis. If None, the limit is computed automatically based on the data.

  • **kwargs (dict) – Additional keyword arguments passed to the scanpy.pl.embedding function.

Return type:

None.

Examples

>>> import scanpy as sc
>>> import piaso
>>> adata = sc.datasets.pbmc3k()  # Load an example dataset
>>> # Plot embeddings colored by a gene expression value and split by clusters
>>> piaso.pl.plot_embeddings_split(adata, color='CDK9', splitby='louvain', col_size=6, row_size=6)
>>> # Save the figure to a file
>>> piaso.pl.plot_embeddings_split(adata, color='CDK9', splitby='louvain', save='./CST3_embeddingsSplit.pdf')
piaso.plotting.createCustomCmapFromHex(hex_colors)#

Create a custom colormap from a list of hex colors. This function converts a sequence of hex colors into an RGB-based colormap that can be used for visualizations in Matplotlib.

Parameters:

hex_colors (list of str) – A list of color codes in hexadecimal format (e.g., [‘#faefef’, ‘#e8aebc’, ‘#d96998’, ‘#b1257a’, ‘#572266’]).

Returns:

A Matplotlib LinearSegmentedColormap object that can be applied to plots using the cmap parameter.

Return type:

LinearSegmentedColormap

Example

>>> import matplotlib.pyplot as plt
>>> import numpy as np
>>> import piaso
>>> # Define custom hex colors
>>> hex_colors = ['#faefef', '#e8aebc', '#d96998', '#b1257a', '#572266']
>>>
>>> # Create the colormap
>>> c_color4 = piaso.pl.color.createCustomCmapFromHex(hex_colors)
>>>
>>> # Generate a gradient to visualize the colormap
>>> gradient = np.linspace(0, 1, 256).reshape(1, -1)
>>>
>>> # Display the colormap
>>> plt.figure(figsize=(6, 1))
>>> plt.imshow(gradient, aspect="auto", cmap=c_color4)
>>> plt.axis("off")
>>> plt.show()