piaso.pl — plotting

Embeddings, dot plots and the other figure functions.

Function	What it does
`createCustomCmapFromHex`	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.
`dotplot`	Plot a dotplot of feature expression across cell groups.
`embedding`	Plot a 2-D embedding colored by a cell annotation or continuous value.
`heatmap`	Plot an expression heatmap.
`plot_dendrogram`	Plot a dendrogram of cell groups based on expression similarity.
`plot_embeddings_split`	Plot cell embeddings side by side based on a categorical variable.
`plot_features_violin`	Plots a violin plot for each feature specified in `feature_list`.
`plot_group_metrics`	Plot the per-group metrics DataFrame from :func:`piaso.pp.calculateGroupMetrics`.
`plotConfusionMatrix`	Plot a normalized and reordered confusion matrix from clustering results.
`plotDendrogram`	Plot a dendrogram of cell groups based on expression similarity.
`plotDotplot`	Plot a dotplot of feature expression across cell groups.
`plotEmbedding`	Plot a 2-D embedding colored by a cell annotation or continuous value.
`plotEmbeddingsSplit`	Plot cell embeddings side by side based on a categorical variable.
`plotFeaturesViolin`	Plots a violin plot for each feature specified in `feature_list`.
`plotGroupMetrics`	Plot the per-group metrics DataFrame from :func:`piaso.pp.calculateGroupMetrics`.
`plotHeatmap`	Plot an expression heatmap.
`plotLigandReceptorInteraction`	Generates plots with a bar plot of top interactions and a heatmap showing ligand and receptor specificity, with an option for vertical orientation.
`plotLigandReceptorLollipop`	Generates advanced bidirectional lollipop plots for one or more cell-type interactions with support for both vertical and horizontal layouts.
`plotSankey`	Plot a Sankey (alluvial) diagram between two categorical columns.
`plotScatter`	Scatter plot of two features colored by a third variable.
`plotUMAP`	Convenience wrapper for :func:`plotEmbedding` with `basis='X_umap'`.
`sankey`	Plot a Sankey (alluvial) diagram between two categorical columns.
`scatter`	Scatter plot of two features colored by a third variable.
`split_embedding`	Plot cell embeddings side by side based on a categorical variable.
`stacked_barplot`	Plot a stacked barplot of cell composition.
`stackedBarplot`	Plot a stacked barplot of cell composition.
`umap`	Convenience wrapper for :func:`plotEmbedding` with `basis='X_umap'`.
`violin`	Plots a violin plot for each feature specified in `feature_list`.

createCustomCmapFromHex

createCustomCmapFromHex(hex_colors)

Signature defaults

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

LinearSegmentedColormap

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

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()

dotplot

dotplot(
    data,
    features: list,
    groupby: str = 'leiden',
    layer: Optional[str] = None,
    use_raw: Optional[bool] = None,
    expression_cutoff: float = 0.0,
    mean_only_expressed: bool = False,
    standard_scale: Optional[str] = None,
    log: bool = False,
    cmap: str = 'Spectral_r',
    dot_max: Optional[float] = None,
    dot_min: float = 0,
    size_scale: float = 200,
    figsize: Optional[tuple] = None,
    square: bool = True,
    categories_order: Optional[list] = None,
    var_names_order: Optional[list] = None,
    var_group_labels: Optional[list] = None,
    var_group_positions: Optional[list] = None,
    dendrogram: bool = False,
    dendro_method: str = 'ward',
    use_rep: Optional[str] = None,
    swap_axes: bool = False,
    title: Optional[str] = None,
    fontsize: Optional[float] = None,
    grid: bool = False,
    show_border: bool = True,
    edgecolor: str = 'none',
    show: bool = True,
    save: Optional[str] = None,
    ax: Optional[matplotlib.axes._axes.Axes] = None,
    return_fig: bool = False,
    palette=None,
    modality: Optional[str] = None,
    cytome_layer: str = 'counts',
    compute_on_fly: bool = True,
    use_cached_stats: bool = True,
)

Signature defaults

data, features, groupby='leiden', layer=None, use_raw=None, expression_cutoff=0.0, mean_only_expressed=False, standard_scale=None, log=False, cmap='Spectral_r', dot_max=None, dot_min=0, size_scale=200, figsize=None, square=True, categories_order=None, var_names_order=None, var_group_labels=None, var_group_positions=None, dendrogram=False, dendro_method='ward', use_rep=None, swap_axes=False, title=None, fontsize=None, grid=False, show_border=True, edgecolor='none', show=True, save=None, ax=None, return_fig=False, palette=None, modality=None, cytome_layer='counts', compute_on_fly=True, use_cached_stats=True

Plot a dotplot of feature expression across cell groups.

Parameters

data — AnnData or cytome Dataset/path

Input data.

features — list, dict, or DataFrame

Feature names. A plain list of strings, a dict mapping group labels to gene lists ({'Excitatory': ['Slc17a7', 'Satb2'], ...}), or a DataFrame with 'group' and 'gene'/'feature' columns. When a dict or DataFrame is provided, var_group_labels and var_group_positions are inferred automatically.

groupby — str

Column in obs/cells for grouping.

layer — str, optional

AnnData layer. Ignored for cytome.

use_raw — bool, optional

Use raw attribute. Ignored for cytome.

expression_cutoff — float

Threshold for “expressing” (default 0).

mean_only_expressed — bool

Compute mean over expressing cells only.

standard_scale — str, optional

Min-max standardise the colour (mean expression) to [0, 1] (scanpy semantics): 'var' per gene (column), 'group' per group (row), or None for raw means. (Previously z-scored, which produced negative values — now min-max, so the colour bar is always [0, 1].)

log — bool

Log1p transform expression values.

cmap — str

Colormap for mean expression. Default 'Spectral_r' (changed from 'Reds'), which separates the middle of the range more strongly and matches the co-specificity heatmaps.

.. note:: 'Spectral_r' is a rainbow map and is not colourblind-safe — its red and green ends are hard to tell apart for the most common form of colour vision deficiency. For figures headed for a manuscript, pass a sequential map: cmap='Reds' (the previous default), 'magma_r' or 'viridis'. That also fits the data better when standard_scale is set, since the values are then 0–1 with no meaningful midpoint for a diverging map to mark.

dot_max — float, optional

Max dot size (fraction). Default: data max.

dot_min — float

Min dot size (fraction).

size_scale — float

Scaling factor for dot size.

figsize — tuple, optional

Auto-calculated if None.

square — bool, default True

Make every grid block a square (uniform per-cell sizing + ax.set_aspect('equal')) so the dots sit centered in square cells. False restores the legacy width∝features / height∝groups sizing.

categories_order — list, optional

Custom group ordering on Y axis.

var_names_order — list, optional

Custom gene ordering on X axis.

var_group_labels — list, optional

Labels for gene groups (displayed as brackets).

var_group_positions — list of tuple, optional

Start/end positions for gene group brackets, e.g. [(0,3), (4,7)].

dendrogram — bool

Show dendrogram on group axis.

dendro_method — str

Linkage method for dendrogram (default: ‘ward’).

use_rep — str, optional

Key in adata.obsm for computing dendrogram from cell embeddings (e.g. ‘X_gdr’, ‘X_svd’). If None, uses mean expression of features.

swap_axes — bool

Genes on Y, groups on X.

title — str, optional

Plot title.

grid — bool

Show light grid lines.

show_border — bool

Show outer border around the plot area (default: True).

edgecolor — str

Edge color for dots (default: ‘none’).

show — bool

Call plt.show().

save — str, optional

Save path.

ax — Axes, optional

Pre-existing axes.

return_fig — bool

Return (fig, ax) tuple.

palette

Not used for dotplot (color is continuous). Reserved for API consistency.

embedding

plotEmbedding(
    data,
    color='leiden',
    basis='X_umap',
    layer=None,
    title=None,
    figsize=None,
    point_size=None,
    alpha=1.0,
    frameon=None,
    save=None,
    show=True,
    ax=None,
    palette=None,
    legend_loc='right',
    legend_fontsize=10,
    legend_fontoutline=None,
    legend_ncol=None,
    rasterized=True,
    dpi=None,
    vmin=None,
    vmax=None,
    vmin_pct=None,
    vmax_pct=None,
    cmap=None,
    show_axes_arrow=False,
    axes_arrow_loc='bottom_left',
    modality=None,
    cytome_layer='counts',
    compute_on_fly=True,
    use_cached_stats=True,
    show_modality_in_title=False,
    ncol=None,
    col_size=4.0,
    row_size=4.0,
    fix_coordinate_ratio=True,
    show_axis_ticks=False,
    x_min=None,
    x_max=None,
    y_min=None,
    y_max=None,
    legend_marker_size=None,
    hspace=None,
    wspace=None,
    groups=None,
    na_color='lightgray',
    return_fig=False,
    **kwargs,
)

Signature defaults

data, color='leiden', basis='X_umap', layer=None, title=None, figsize=None, point_size=None, alpha=1.0, frameon=None, save=None, show=True, ax=None, palette=None, legend_loc='right', legend_fontsize=10, legend_fontoutline=None, legend_ncol=None, rasterized=True, dpi=None, vmin=None, vmax=None, vmin_pct=None, vmax_pct=None, cmap=None, show_axes_arrow=False, axes_arrow_loc='bottom_left', modality=None, cytome_layer='counts', compute_on_fly=True, use_cached_stats=True, show_modality_in_title=False, ncol=None, col_size=4.0, row_size=4.0, fix_coordinate_ratio=True, show_axis_ticks=False, x_min=None, x_max=None, y_min=None, y_max=None, legend_marker_size=None, hspace=None, wspace=None, groups=None, na_color='lightgray', return_fig=False, **kwargs

Plot a 2-D embedding colored by a cell annotation or continuous value.

Round 7: now returns None by default — pass return_fig=True to get (fig, ax) back (the legacy behaviour).

Supports both cytome.Dataset and AnnData objects.

Parameters

data

A cytome.Dataset or AnnData object.

color — str or list of str

Column in cells / obs for colouring, or a feature name (gene, peak, tile, or GA gene — resolved via the cytome modality registry; pass modality= to disambiguate). A single str draws one panel; a list/tuple of strings draws a multi-panel grid (one panel per entry, scanpy sc.pl.umap-style).

basis — str

Embedding key (e.g. 'X_umap', 'X_svd').

layer — str, optional

AnnData layer to read the feature value from when color is a feature name. If None, reads from adata.X.

title — str or list of str, optional

Plot title. Defaults to color. For a list color: a single string becomes a figure-level suptitle over the grid; a list of titles (length must match color) sets one title per panel.

figsize — tuple, optional

Figure size in inches. If None, uses rcParams['figure.figsize'] (set via piaso.settings.set_figure_params(figsize=...)).

point_size — float or None

Scatter point size. If None (default), automatically calculated from the number of cells: 30000 / n_cells clamped to [0.1, 4] (explicit value overrides).

alpha — float

Point transparency. Default 1.0 (opaque).

frameon — bool, optional

Whether to show axis frame (spines). If None, uses piaso.settings._frameon (default False).

save — str, bool, or None

Figure save behavior:

None: don’t save.
Full path ('/path/to/fig.png'): save directly.
Suffix ('_leiden'): save to piaso.settings.figdir.
True: auto-name and save to piaso.settings.figdir.

show — bool

Whether to call plt.show().

ax — matplotlib Axes, optional

Pre-existing axes to draw on.

palette — list[str], optional

Color palette for categorical data. If None, checks adata.uns['{color}_colors'] first, then falls back to piaso.pl.color.d_color4.

groups — str or list of str, optional

For a categorical color: highlight only these category values — they keep their palette colour while all other cells are greyed out (drawn behind), like sc.pl.umap(groups=...). Palette indices come from the full category list, so colours match an unfiltered plot. Raises ValueError if a name is not among the categories.

na_color — str, default 'lightgray'

Colour for the greyed-out (non-groups) cells.

legend_loc — str

'right' (outside), 'on_data' (centroid labels), or 'none'.

legend_fontsize — int

Font size for legend labels.

legend_fontoutline — float or None

Width of text outline for legend_loc='on_data' labels. Adds a contrasting stroke around text for readability. If None (default), no outline is drawn.

legend_ncol — int, optional

Number of legend columns. If None, auto-calculated (~12 per column).

rasterized — bool

Rasterize scatter points for smaller vector files.

dpi — int, optional

Display DPI. If None, uses rcParams['figure.dpi']. vmin, vmax : float Limits for continuous color scale. vmin_pct, vmax_pct : float, optional Percentile (0-100) used to derive vmin/vmax for continuous features when the explicit limit is not given — e.g. vmax_pct=99 clips the top 1% of cells so a few outliers don’t wash out the colour scale. None (default) = no percentile clipping. Ignored for categorical colours and overridden by an explicit vmin/vmax.

cmap

Colormap for continuous data.

show_axes_arrow — bool

Draw small coordinate arrows at a corner of the plot.

axes_arrow_loc — str

Position of axes arrow: 'bottom_left' or 'bottom_right'.

modality — str, optional

Cytome modality for feature lookup: 'RNA', 'GA', 'ATAC', 'tiles', or None for auto-detect. Auto-detect raises ValueError if the feature is in multiple modalities; pass an explicit string to disambiguate. Ignored for AnnData inputs.

cytome_layer — str, default 'counts'

Cytome matrix suffix to read; combined with modality to form {modality}_{cytome_layer}. Common values: 'counts', 'log1p', 'infog', 'tfidf'.

compute_on_fly — bool, default True

If the requested {modality}_{cytome_layer} matrix isn’t materialised in the cytome, compute the value per-feature on the fly from {modality}_counts using cached / freshly-computed params. Supported on-the-fly layers: 'log1p', 'infog', 'tfidf'. Set False for strict mode (raise on missing matrix).

use_cached_stats — bool, default True

Reuse per-modality cached params from ds.metadata (e.g. '{modality}_infog_params') when computing on the fly. Set False to ignore the cache and recompute.

show_modality_in_title — bool, default False

Append (modality) to the panel title when the colour was resolved through a cytome modality (e.g. 'Sox2 (RNA)'). Affects feature colours only — obs columns are unchanged.

ncol — int, optional

Columns in the multi-panel grid when color is a list. Defaults to ceil(sqrt(n_colors)). Aliased as ncols (scanpy convention). Ignored when color is a single string.

col_size — float, default 4.0

Per-panel width in inches when color is a list.

row_size — float, default 4.0

Per-panel height in inches when color is a list.

fix_coordinate_ratio — bool, default True

If True, sets ax.set_aspect('equal') so x and y axes are scaled equally — appropriate for UMAP / t-SNE / spatial coords where distances are meaningful. Set False to use 'auto' (let matplotlib stretch to fit the axes).

show_axis_ticks — bool, default False

Whether to display axis tick marks and labels. Off by default for embedding-style plots where coordinates are abstract. x_min, x_max, y_min, y_max : float, optional Custom axis limits. Each is independently optional; pass only the ones you want to override (others use the data range).

legend_marker_size — float, optional

Marker scale for the legend (categorical colours only). If None, auto-computed from point_size as max(3, 12 / point_size).

hspace — float, optional

Vertical spacing between rows of the multi-panel grid (only applies when color is a list). If None (default), uses 0.1 when show_axis_ticks=False and 0.25 when show_axis_ticks=True. Pass an explicit value to override (e.g. 0.05 for very tight, 0.4 for wide spacing).

wspace — float, optional

Horizontal spacing between columns of the multi-panel grid (only applies when color is a list). If None (default), uses 0.2. Override to tighten or widen.

color accepts str (single panel) OR list[str] / tuple[str] (one panel per entry, on a ncol-column grid). When a list is given together with ax, raises ValueError since a single axes can’t host a multi-panel grid.

Returns

fig, ax For single-color: (fig, ax) where ax is the matplotlib Axes that was drawn into. fig, axs For list-color: (fig, [ax0, ax1, ...]) — one Axes per entry in color; trailing empty grid cells are hidden via set_visible(False).

heatmap

heatmap(
    data,
    features: list,
    groupby: str = 'leiden',
    layer: Optional[str] = None,
    use_raw: Optional[bool] = None,
    standard_scale: Optional[str] = None,
    log: bool = False,
    cmap: str = 'viridis',
    figsize: Optional[tuple] = None,
    categories_order: Optional[list] = None,
    var_names_order: Optional[list] = None,
    dendrogram: bool = False,
    swap_axes: bool = False,
    title: Optional[str] = None,
    show_values: bool = False,
    fmt: str = '.2f',
    vmin: Optional[float] = None,
    vmax: Optional[float] = None,
    cell_level: bool = False,
    max_cells_per_group: int = 100,
    show_group_colors: bool = True,
    show: bool = True,
    save: Optional[str] = None,
    ax: Optional[matplotlib.axes._axes.Axes] = None,
    return_fig: bool = False,
    modality: Optional[str] = None,
    cytome_layer: str = 'counts',
    compute_on_fly: bool = True,
    use_cached_stats: bool = True,
)

Signature defaults

data, features, groupby='leiden', layer=None, use_raw=None, standard_scale=None, log=False, cmap='viridis', figsize=None, categories_order=None, var_names_order=None, dendrogram=False, swap_axes=False, title=None, show_values=False, fmt='.2f', vmin=None, vmax=None, cell_level=False, max_cells_per_group=100, show_group_colors=True, show=True, save=None, ax=None, return_fig=False, modality=None, cytome_layer='counts', compute_on_fly=True, use_cached_stats=True

Plot an expression heatmap.

Two modes:

Group-level (default): mean expression per group (groups x features).
Cell-level (cell_level=True): per-cell expression with group-stratified sampling, up to max_cells_per_group cells per group.

Parameters

data — AnnData or cytome Dataset/path

Input data.

features — list, dict, or DataFrame

Feature names. A plain list of strings, a dict mapping group labels to gene lists, or a DataFrame with 'group' and 'gene'/'feature' columns. When dict/DataFrame, gene groups are shown as colored brackets (cell-level) or vertical separators (group-level).

groupby — str

Grouping column. layer, use_raw AnnData layer / raw attribute. Ignored for cytome.

standard_scale — str, optional

'var' to z-score per feature, 'group' per group.

log — bool

Log1p transform.

cmap — str

Colormap.

figsize — tuple, optional

Auto-calculated if None.

categories_order — list, optional

Custom group order.

var_names_order — list, optional

Custom feature order.

dendrogram — bool

Cluster groups by hierarchical clustering (group-level only).

swap_axes — bool

Transpose: features on Y, groups on X.

title — str, optional

Title.

show_values — bool

Annotate cells with values (group-level only).

fmt — str

Number format for annotations. vmin, vmax : float, optional Colorscale limits.

cell_level — bool

If True, show per-cell expression instead of group means.

max_cells_per_group — int

Maximum cells per group when cell_level=True. Default 100.

show_group_colors — bool

Show colored sidebar for groups when cell_level=True. show, save, ax, return_fig Output options.

plot_dendrogram

plot_dendrogram(
    data,
    groupby: str = 'leiden',
    features: Optional[list] = None,
    use_rep: Optional[str] = 'auto',
    layer: Optional[str] = None,
    use_raw: Optional[bool] = None,
    n_top_genes: int = 50,
    method: str = 'average',
    metric: str = 'euclidean',
    orientation: str = 'top',
    palette=None,
    figsize: Optional[tuple] = None,
    title: Optional[str] = None,
    show: bool = True,
    save: Optional[str] = None,
    ax: Optional[matplotlib.axes._axes.Axes] = None,
    return_fig: bool = False,
    return_linkage: bool = False,
    modality: Optional[str] = None,
    cytome_layer: str = 'counts',
    compute_on_fly: bool = True,
    use_cached_stats: bool = True,
)

Signature defaults

data, groupby='leiden', features=None, use_rep='auto', layer=None, use_raw=None, n_top_genes=50, method='average', metric='euclidean', orientation='top', palette=None, figsize=None, title=None, show=True, save=None, ax=None, return_fig=False, return_linkage=False, modality=None, cytome_layer='counts', compute_on_fly=True, use_cached_stats=True

Plot a dendrogram of cell groups based on expression similarity.

Parameters

data — AnnData or cytome Dataset/path

Input data.

groupby — str

Grouping column.

features — list, optional

Features to use for clustering (marker-gene mode). If None, uses highly variable genes or top-variance genes. Only consulted when use_rep is None or resolves to no embedding.

use_rep — str or None, default 'auto'

Build the group tree from per-group centroids of a cell embedding (the standard scanpy-style dendrogram), which is usually what you want.

'auto' (default): use the first available embedding from X_gdr → X_pca → X_svd → X_diffmap → X_umap; if none exist, fall back to marker-gene expression similarity.
an explicit key (e.g. 'X_gdr', 'X_svd'): use that embedding.
None: marker-gene mode — cluster groups by similarity of their mean expression over features (or the top-n_top_genes variable genes / numeric cells columns). Use this when you specifically want the tree to reflect marker-gene programs rather than the global embedding geometry (e.g. comparing COSG top-n_top_genes markers). layer, use_raw AnnData layer / raw. Ignored for cytome.

n_top_genes — int

Number of top genes to use in marker-gene mode when features is None.

method — str

Linkage method ('average', 'ward', 'complete', 'single').

metric — str

Distance metric.

orientation — str

Dendrogram orientation: 'top', 'bottom', 'left', 'right'.

palette — list or dict, optional

Colors for leaf labels.

figsize — tuple, optional

Figure size.

title — str, optional

Title. show, save, ax, return_fig Output options.

return_linkage — bool

Also return the linkage matrix Z.

Returns

Optionally (fig, ax) and/or linkage matrix.

plot_embeddings_split

plot_embeddings_split(
    data,
    color,
    splitby,
    ncol: int = None,
    dpi: int = 80,
    col_size: int = 5,
    row_size: int = 5,
    alpha: float = 1.0,
    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',
    legend_marker_size: float = 6.0,
    groups=None,
    point_size: float = None,
    palette=None,
    cmap=None,
    frameon: bool = False,
    rasterized: bool = True,
    modality: str = None,
    cytome_layer: str = 'counts',
    compute_on_fly: bool = True,
    use_cached_stats: bool = True,
    show_modality_in_title: bool = False,
    x_min=None,
    x_max=None,
    y_min=None,
    y_max=None,
    **kwargs,
)

Signature defaults

data, color, splitby, ncol=None, dpi=80, col_size=5, row_size=5, alpha=1.0, vmax=None, vmin=None, show_figure=True, save=None, layer=None, basis='X_umap', fix_coordinate_ratio=True, show_axis_ticks=False, margin_ratio=0.05, legend_fontsize=10, legend_fontoutline=2, legend_loc='right', legend_marker_size=6.0, groups=None, point_size=None, palette=None, cmap=None, frameon=False, rasterized=True, modality=None, cytome_layer='counts', compute_on_fly=True, use_cached_stats=True, show_modality_in_title=False, 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.

Supports AnnData, cytome Dataset, or path to .cytome file.

Parameters

data — AnnData, cytome.Dataset, or str

An AnnData object, cytome Dataset, or path to .cytome file.

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=4.0)

Legend dot size. In the right-margin legend it is the marker scale (relative to the data points); in the global/multi-panel legend it is the absolute marker size in points. None auto-sizes from the data point_size (capped to avoid oversized dots on large datasets).

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.

point_size — float, optional

Scatter point size. An explicit value always overrides the auto-size. If None, auto-scaled (max(0.1, min(4, 30000 / n_cells)), clamped to [0.1, 8]). Accepts size= as an alias for scanpy-style call sites.

palette — list[str] or dict, optional

Categorical palette. If None, falls back to adata.uns['{color}_colors'] (or the cytome metadata equivalent), then to the PIASO default d_color4. Mapping is held consistent across panels so the same category gets the same colour in every subplot.

cmap — str or Colormap, optional

Colourmap for numeric color values. Forwarded to each panel.

frameon — bool, optional (default False)

Whether to show axis spines on each panel and on the global legend frame. Mirrors piaso.pl.plotEmbedding(frameon=...).

rasterized — bool, optional (default True)

Forward to per-panel scatter for compact vector output.

**kwargs — dict

Forwarded verbatim to :func:piaso.pl.plotEmbedding for each panel. Accepts the scanpy-style aliases ncols (→ ncol) and size (→ point_size) for compatibility with existing call sites.

Returns

None.

Examples

>>> import anndata
>>> import piaso
>>> adata = anndata.read_h5ad('pbmc3k.h5ad')  # 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')

plot_features_violin

plot_features_violin(
    data,
    feature_list,
    groupby: Optional[str] = None,
    use_raw: Optional[bool] = None,
    layer: Optional[str] = None,
    palette=None,
    jitter: bool = False,
    width_single: float = None,
    height_single: float = 2.0,
    size: float = 0.1,
    show_grid: bool = True,
    show_median: bool = True,
    median_color: str = 'lightgrey',
    show_figure: bool = True,
    save: Optional[str] = None,
    modality: Optional[str] = None,
    cytome_layer: str = 'counts',
    compute_on_fly: bool = True,
    use_cached_stats: bool = True,
    show: Optional[bool] = None,
)

Signature defaults

data, feature_list, groupby=None, use_raw=None, layer=None, palette=None, jitter=False, width_single=None, height_single=2.0, size=0.1, show_grid=True, show_median=True, median_color='lightgrey', show_figure=True, save=None, modality=None, cytome_layer='counts', compute_on_fly=True, use_cached_stats=True, show=None

Plots a violin plot for each feature specified in feature_list.

Uses matplotlib directly (no scanpy dependency). Supports AnnData and cytome Dataset / .cytome file path.

show is accepted as an alias for show_figure: every other plotting function in piaso.pl takes show, and a call that works for pl.embedding and pl.dotplot should not raise here for the sake of one function’s parameter name. When both are given, show wins.

Parameters

data — anndata.AnnData, cytome.Dataset, or str

The data source. For AnnData, reads from obs, layers, or raw. For cytome, reads from the cells SQL table.

feature_list — List[str]

Feature names to visualize. For cytome, these must be column names in the cells table.

groupby — str, optional

Column to group data points by. Default is None.

use_raw — bool, optional

Use raw attribute of adata. Ignored for cytome.

layer — str, optional

AnnData layer to use. Ignored for cytome.

palette — list or dict, optional

Color palette for groups. If None, checks adata.uns['{groupby}_colors'] first, then falls back to the default PIASO palette.

jitter — bool, optional

Show jitter scatter points on violins. Default is False.

width_single — float, optional

Figure width in inches. None (default) derives it from the number of groups — 1.6 + 0.42 * n_groups, clamped to [3, 16] — so a two-sample plot is not the same width as a forty-cluster one. Pass a number to override. Width of each subplot. Default is 14.0.

height_single — float, optional

Height of each subplot. Default is 2.0.

size — float, optional

Jitter point size (only used when jitter=True). Default is 0.1.

show_grid — bool, optional

Show grid lines. Default is True.

show_median — bool, optional

Show median line on violins. Default is True.

median_color — str, optional

Color of the median line. Default is 'lightgrey'.

show_figure — bool, optional

Show figure (plt.show()). Default is True.

save — str, optional

Path to save the figure. Default is None.

plot_group_metrics

plotGroupMetrics(
    df,
    data=None,
    groupby: Optional[str] = None,
    metrics: Optional[list] = None,
    kind: str = 'bar',
    palette=None,
    ncol: Optional[int] = None,
    figsize: Optional[tuple] = None,
    normalize: str = 'minmax',
    annotate: bool = True,
    cmap: str = 'Blues',
    fontsize: Optional[float] = None,
    rotation: float = 45,
    save: Optional[str] = None,
    show: bool = True,
    return_fig: bool = False,
)

Signature defaults

df, data=None, groupby=None, metrics=None, kind='bar', palette=None, ncol=None, figsize=None, normalize='minmax', annotate=True, cmap='Blues', fontsize=None, rotation=45, save=None, show=True, return_fig=False

Plot the per-group metrics DataFrame from :func:piaso.pp.calculateGroupMetrics.

Parameters

df — pandas.DataFrame

Output of calculateGroupMetrics (rows = groups, cols = metrics). data, groupby : optional Source dataset + grouping column, only used to re-resolve cell-type colours when the df doesn’t already carry them in df.attrs['colors'].

metrics — list of str, optional

Subset / order of metric columns to plot. Default: all numeric columns.

kind — 'bar' | 'heatmap'

'bar' (default): one panel per metric. 'heatmap': groups × metrics with per-column normalisation.

palette — dict or list, optional

Override group colours ({group: hex} or an ordered list).

ncol — int, optional

Columns in the faceted bar grid (default: ~sqrt(n_metrics)).

figsize — tuple, optional

Auto-sized if None.

normalize — 'minmax' | 'zscore' | None

Per-column scaling for the heatmap (ignored for bars).

annotate — bool, default True

Write the raw value in each heatmap cell.

cmap — str, default 'Blues'

Heatmap colormap.

fontsize — float, optional

Base font size (defaults to rcParams['font.size']).

rotation — float, default 45

Group-label rotation (anchored to the ticks so names don’t overlap). save, show, return_fig Output options.

plotConfusionMatrix

plotConfusionMatrix(
    data,
    groupby_query,
    groupby_reference,
    normalize='query',
    figsize=(11.5, 10),
    cmap='Purples',
    annot=False,
    fmt='.2f',
    title=None,
    save_path=None,
    dpi=300,
    return_objects=False,
    show_group_color_bars=False,
    **kwargs,
)

Signature defaults

data, groupby_query, groupby_reference, normalize='query', figsize=(11.5, 10), cmap='Purples', annot=False, fmt='.2f', title=None, save_path=None, dpi=300, return_objects=False, show_group_color_bars=False, **kwargs

Plot a normalized and reordered confusion matrix from clustering results.

This function creates a confusion matrix heatmap with SVD-based reordering for better visualization of cluster relationships. The matrix can be normalized in different ways and customized extensively.

Parameters: data (pandas.DataFrame or AnnData): DataFrame or AnnData object containing the data. If AnnData, will use data.obs for the analysis. groupby_query (str): Column name for the query labels (typically predicted clusters). groupby_reference (str): Column name for the reference labels (typically true labels). normalize (str): How to normalize the confusion matrix. Options: - ‘query’: normalize by query (row-wise) - default - ‘reference’: normalize by reference (column-wise)
- ‘all’: normalize by total count - None: no normalization figsize (tuple): Figure size for the plot. Default is (11.5, 10). cmap (str): Colormap for the heatmap. Default is ‘Purples’. annot (bool): Whether to show annotations in cells. Default is False. fmt (str): Format for annotations. Default is ‘.2f’. title (str): Custom title for the plot. If None, generates automatic title. save_path (str): Path to save the figure. If None, only displays. dpi (int): DPI for saved figure. Default is 300. return_objects (bool): If True, returns (confusion_matrix, fig, ax). Default is False. show_group_color_bars (bool): If True, shows colored bars next to ticks for categories that have colors defined in adata.uns (e.g., ‘CellTypes_colors’). Default is False. **kwargs: Additional arguments passed to sns.heatmap()

Returns: None (default) or tuple: If return_objects=True, returns (reordered_confusion_matrix, fig, ax) for further customization

Examples: Basic usage with AnnData object: >>> import anndata >>> import pandas as pd >>> # Load your data >>> adata = anndata.read_h5ad(‘your_data.h5ad’) >>> # Plot confusion matrix between cell types and Leiden clusters >>> plotConfusionMatrix(adata, groupby_query=‘CellTypes’, groupby_reference=‘Leiden’)

Using a pandas DataFrame:
>>> df = pd.DataFrame({
...     'CellTypes': ['T_cell', 'B_cell', 'Monocyte', 'T_cell', 'B_cell'],
...     'Leiden': ['0', '1', '2', '0', '1']
... })
>>> plotConfusionMatrix(df, groupby_query='CellTypes', groupby_reference='Leiden')

Different normalization methods:
>>> # Normalize by reference (column-wise)
>>> plotConfusionMatrix(adata, groupby_query='CellTypes', groupby_reference='Leiden',
...                     normalize='reference')
>>>
>>> # No normalization, show raw counts
>>> plotConfusionMatrix(adata, groupby_query='CellTypes', groupby_reference='Leiden',
...                     normalize=None)
>>>
>>> # Normalize by total count
>>> plotConfusionMatrix(adata, groupby_query='CellTypes', groupby_reference='Leiden',
...                     normalize='all')

Customization options:
>>> # Custom colors and show detailed values
>>> plotConfusionMatrix(adata, groupby_query='CellTypes', groupby_reference='Leiden',
...                     cmap='viridis', annot=True)
>>>
>>> # Custom figure size and save to file
>>> plotConfusionMatrix(adata, groupby_query='CellTypes', groupby_reference='Leiden',
...                     figsize=(15, 12),
...                     save_path='confusion_matrix.png',
...                     title='Cell Types vs Leiden Clusters')

Show detailed values in the plot:
>>> # Display percentage values in each cell
>>> plotConfusionMatrix(adata, groupby_query='CellTypes', groupby_reference='Leiden',
...                     annot=True, fmt='.1%')
>>>
>>> # Display raw counts (with no normalization)
>>> plotConfusionMatrix(adata, groupby_query='CellTypes', groupby_reference='Leiden',
...                     normalize=None, annot=True, fmt='d')

Show color bars for categories:
>>> # Display colored bars next to ticks (requires colors in adata.uns)
>>> plotConfusionMatrix(adata, groupby_query='CellTypes', groupby_reference='Leiden',
...                     show_group_color_bars=True)
>>> # This will look for 'CellTypes_colors' and 'Leiden_colors' in adata.uns

Advanced usage - getting results for further analysis:
>>> conf_matrix, fig, ax = plotConfusionMatrix(adata,
...                                           groupby_query='CellTypes',
...                                           groupby_reference='Leiden',
...                                           return_objects=True)
>>> # Access the reordered confusion matrix
>>> print(conf_matrix.head())
>>> # Further customize the plot
>>> ax.set_title('Custom Title', fontsize=16)
>>> plt.show()

Using with different data sources:
>>> # From Seurat object converted to pandas
>>> seurat_df = pd.read_csv('seurat_metadata.csv')
>>> plotConfusionMatrix(seurat_df, groupby_query='CellTypes', groupby_reference='Leiden')
>>>
>>> # From flow cytometry data
>>> flow_df = pd.read_csv('flow_cytometry_results.csv')
>>> plotConfusionMatrix(flow_df, groupby_query='CellTypes', groupby_reference='Leiden',
...                     normalize='reference', cmap='Reds', annot=True)

plotDendrogram

plot_dendrogram(
    data,
    groupby: str = 'leiden',
    features: Optional[list] = None,
    use_rep: Optional[str] = 'auto',
    layer: Optional[str] = None,
    use_raw: Optional[bool] = None,
    n_top_genes: int = 50,
    method: str = 'average',
    metric: str = 'euclidean',
    orientation: str = 'top',
    palette=None,
    figsize: Optional[tuple] = None,
    title: Optional[str] = None,
    show: bool = True,
    save: Optional[str] = None,
    ax: Optional[matplotlib.axes._axes.Axes] = None,
    return_fig: bool = False,
    return_linkage: bool = False,
    modality: Optional[str] = None,
    cytome_layer: str = 'counts',
    compute_on_fly: bool = True,
    use_cached_stats: bool = True,
)

Signature defaults

Plot a dendrogram of cell groups based on expression similarity.

Parameters

data — AnnData or cytome Dataset/path

Input data.

groupby — str

Grouping column.

features — list, optional

Features to use for clustering (marker-gene mode). If None, uses highly variable genes or top-variance genes. Only consulted when use_rep is None or resolves to no embedding.

use_rep — str or None, default 'auto'

Build the group tree from per-group centroids of a cell embedding (the standard scanpy-style dendrogram), which is usually what you want.

'auto' (default): use the first available embedding from X_gdr → X_pca → X_svd → X_diffmap → X_umap; if none exist, fall back to marker-gene expression similarity.
an explicit key (e.g. 'X_gdr', 'X_svd'): use that embedding.
None: marker-gene mode — cluster groups by similarity of their mean expression over features (or the top-n_top_genes variable genes / numeric cells columns). Use this when you specifically want the tree to reflect marker-gene programs rather than the global embedding geometry (e.g. comparing COSG top-n_top_genes markers). layer, use_raw AnnData layer / raw. Ignored for cytome.

n_top_genes — int

Number of top genes to use in marker-gene mode when features is None.

method — str

Linkage method ('average', 'ward', 'complete', 'single').

metric — str

Distance metric.

orientation — str

Dendrogram orientation: 'top', 'bottom', 'left', 'right'.

palette — list or dict, optional

Colors for leaf labels.

figsize — tuple, optional

Figure size.

title — str, optional

Title. show, save, ax, return_fig Output options.

return_linkage — bool

Also return the linkage matrix Z.

Returns

Optionally (fig, ax) and/or linkage matrix.

plotDotplot

dotplot(
    data,
    features: list,
    groupby: str = 'leiden',
    layer: Optional[str] = None,
    use_raw: Optional[bool] = None,
    expression_cutoff: float = 0.0,
    mean_only_expressed: bool = False,
    standard_scale: Optional[str] = None,
    log: bool = False,
    cmap: str = 'Spectral_r',
    dot_max: Optional[float] = None,
    dot_min: float = 0,
    size_scale: float = 200,
    figsize: Optional[tuple] = None,
    square: bool = True,
    categories_order: Optional[list] = None,
    var_names_order: Optional[list] = None,
    var_group_labels: Optional[list] = None,
    var_group_positions: Optional[list] = None,
    dendrogram: bool = False,
    dendro_method: str = 'ward',
    use_rep: Optional[str] = None,
    swap_axes: bool = False,
    title: Optional[str] = None,
    fontsize: Optional[float] = None,
    grid: bool = False,
    show_border: bool = True,
    edgecolor: str = 'none',
    show: bool = True,
    save: Optional[str] = None,
    ax: Optional[matplotlib.axes._axes.Axes] = None,
    return_fig: bool = False,
    palette=None,
    modality: Optional[str] = None,
    cytome_layer: str = 'counts',
    compute_on_fly: bool = True,
    use_cached_stats: bool = True,
)

Signature defaults

Plot a dotplot of feature expression across cell groups.

Parameters

data — AnnData or cytome Dataset/path

Input data.

features — list, dict, or DataFrame

groupby — str

Column in obs/cells for grouping.

layer — str, optional

AnnData layer. Ignored for cytome.

use_raw — bool, optional

Use raw attribute. Ignored for cytome.

expression_cutoff — float

Threshold for “expressing” (default 0).

mean_only_expressed — bool

Compute mean over expressing cells only.

standard_scale — str, optional

log — bool

Log1p transform expression values.

cmap — str

Colormap for mean expression. Default 'Spectral_r' (changed from 'Reds'), which separates the middle of the range more strongly and matches the co-specificity heatmaps.

dot_max — float, optional

Max dot size (fraction). Default: data max.

dot_min — float

Min dot size (fraction).

size_scale — float

Scaling factor for dot size.

figsize — tuple, optional

Auto-calculated if None.

square — bool, default True

Make every grid block a square (uniform per-cell sizing + ax.set_aspect('equal')) so the dots sit centered in square cells. False restores the legacy width∝features / height∝groups sizing.

categories_order — list, optional

Custom group ordering on Y axis.

var_names_order — list, optional

Custom gene ordering on X axis.

var_group_labels — list, optional

Labels for gene groups (displayed as brackets).

var_group_positions — list of tuple, optional

Start/end positions for gene group brackets, e.g. [(0,3), (4,7)].

dendrogram — bool

Show dendrogram on group axis.

dendro_method — str

Linkage method for dendrogram (default: ‘ward’).

use_rep — str, optional

Key in adata.obsm for computing dendrogram from cell embeddings (e.g. ‘X_gdr’, ‘X_svd’). If None, uses mean expression of features.

swap_axes — bool

Genes on Y, groups on X.

title — str, optional

Plot title.

grid — bool

Show light grid lines.

show_border — bool

Show outer border around the plot area (default: True).

edgecolor — str

Edge color for dots (default: ‘none’).

show — bool

Call plt.show().

save — str, optional

Save path.

ax — Axes, optional

Pre-existing axes.

return_fig — bool

Return (fig, ax) tuple.

palette

Not used for dotplot (color is continuous). Reserved for API consistency.

plotEmbedding

plotEmbedding(
    data,
    color='leiden',
    basis='X_umap',
    layer=None,
    title=None,
    figsize=None,
    point_size=None,
    alpha=1.0,
    frameon=None,
    save=None,
    show=True,
    ax=None,
    palette=None,
    legend_loc='right',
    legend_fontsize=10,
    legend_fontoutline=None,
    legend_ncol=None,
    rasterized=True,
    dpi=None,
    vmin=None,
    vmax=None,
    vmin_pct=None,
    vmax_pct=None,
    cmap=None,
    show_axes_arrow=False,
    axes_arrow_loc='bottom_left',
    modality=None,
    cytome_layer='counts',
    compute_on_fly=True,
    use_cached_stats=True,
    show_modality_in_title=False,
    ncol=None,
    col_size=4.0,
    row_size=4.0,
    fix_coordinate_ratio=True,
    show_axis_ticks=False,
    x_min=None,
    x_max=None,
    y_min=None,
    y_max=None,
    legend_marker_size=None,
    hspace=None,
    wspace=None,
    groups=None,
    na_color='lightgray',
    return_fig=False,
    **kwargs,
)

Signature defaults

Plot a 2-D embedding colored by a cell annotation or continuous value.

Round 7: now returns None by default — pass return_fig=True to get (fig, ax) back (the legacy behaviour).

Supports both cytome.Dataset and AnnData objects.

Parameters

data

A cytome.Dataset or AnnData object.

color — str or list of str

basis — str

Embedding key (e.g. 'X_umap', 'X_svd').

layer — str, optional

AnnData layer to read the feature value from when color is a feature name. If None, reads from adata.X.

title — str or list of str, optional

Plot title. Defaults to color. For a list color: a single string becomes a figure-level suptitle over the grid; a list of titles (length must match color) sets one title per panel.

figsize — tuple, optional

Figure size in inches. If None, uses rcParams['figure.figsize'] (set via piaso.settings.set_figure_params(figsize=...)).

point_size — float or None

Scatter point size. If None (default), automatically calculated from the number of cells: 30000 / n_cells clamped to [0.1, 4] (explicit value overrides).

alpha — float

Point transparency. Default 1.0 (opaque).

frameon — bool, optional

Whether to show axis frame (spines). If None, uses piaso.settings._frameon (default False).

save — str, bool, or None

Figure save behavior:

None: don’t save.
Full path ('/path/to/fig.png'): save directly.
Suffix ('_leiden'): save to piaso.settings.figdir.
True: auto-name and save to piaso.settings.figdir.

show — bool

Whether to call plt.show().

ax — matplotlib Axes, optional

Pre-existing axes to draw on.

palette — list[str], optional

Color palette for categorical data. If None, checks adata.uns['{color}_colors'] first, then falls back to piaso.pl.color.d_color4.

groups — str or list of str, optional

na_color — str, default 'lightgray'

Colour for the greyed-out (non-groups) cells.

legend_loc — str

'right' (outside), 'on_data' (centroid labels), or 'none'.

legend_fontsize — int

Font size for legend labels.

legend_fontoutline — float or None

Width of text outline for legend_loc='on_data' labels. Adds a contrasting stroke around text for readability. If None (default), no outline is drawn.

legend_ncol — int, optional

Number of legend columns. If None, auto-calculated (~12 per column).

rasterized — bool

Rasterize scatter points for smaller vector files.

dpi — int, optional

cmap

Colormap for continuous data.

show_axes_arrow — bool

Draw small coordinate arrows at a corner of the plot.

axes_arrow_loc — str

Position of axes arrow: 'bottom_left' or 'bottom_right'.

modality — str, optional

cytome_layer — str, default 'counts'

Cytome matrix suffix to read; combined with modality to form {modality}_{cytome_layer}. Common values: 'counts', 'log1p', 'infog', 'tfidf'.

compute_on_fly — bool, default True

use_cached_stats — bool, default True

Reuse per-modality cached params from ds.metadata (e.g. '{modality}_infog_params') when computing on the fly. Set False to ignore the cache and recompute.

show_modality_in_title — bool, default False

Append (modality) to the panel title when the colour was resolved through a cytome modality (e.g. 'Sox2 (RNA)'). Affects feature colours only — obs columns are unchanged.

ncol — int, optional

Columns in the multi-panel grid when color is a list. Defaults to ceil(sqrt(n_colors)). Aliased as ncols (scanpy convention). Ignored when color is a single string.

col_size — float, default 4.0

Per-panel width in inches when color is a list.

row_size — float, default 4.0

Per-panel height in inches when color is a list.

fix_coordinate_ratio — bool, default True

show_axis_ticks — bool, default False

legend_marker_size — float, optional

Marker scale for the legend (categorical colours only). If None, auto-computed from point_size as max(3, 12 / point_size).

hspace — float, optional

wspace — float, optional

Horizontal spacing between columns of the multi-panel grid (only applies when color is a list). If None (default), uses 0.2. Override to tighten or widen.

Returns

plotEmbeddingsSplit

plot_embeddings_split(
    data,
    color,
    splitby,
    ncol: int = None,
    dpi: int = 80,
    col_size: int = 5,
    row_size: int = 5,
    alpha: float = 1.0,
    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',
    legend_marker_size: float = 6.0,
    groups=None,
    point_size: float = None,
    palette=None,
    cmap=None,
    frameon: bool = False,
    rasterized: bool = True,
    modality: str = None,
    cytome_layer: str = 'counts',
    compute_on_fly: bool = True,
    use_cached_stats: bool = True,
    show_modality_in_title: bool = False,
    x_min=None,
    x_max=None,
    y_min=None,
    y_max=None,
    **kwargs,
)

Signature defaults

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.

Supports AnnData, cytome Dataset, or path to .cytome file.

Parameters

data — AnnData, cytome.Dataset, or str

An AnnData object, cytome Dataset, or path to .cytome file.

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=4.0)

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.

point_size — float, optional

palette — list[str] or dict, optional

cmap — str or Colormap, optional

Colourmap for numeric color values. Forwarded to each panel.

frameon — bool, optional (default False)

Whether to show axis spines on each panel and on the global legend frame. Mirrors piaso.pl.plotEmbedding(frameon=...).

rasterized — bool, optional (default True)

Forward to per-panel scatter for compact vector output.

**kwargs — dict

Forwarded verbatim to :func:piaso.pl.plotEmbedding for each panel. Accepts the scanpy-style aliases ncols (→ ncol) and size (→ point_size) for compatibility with existing call sites.

Returns

None.

Examples

>>> import anndata
>>> import piaso
>>> adata = anndata.read_h5ad('pbmc3k.h5ad')  # 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')

plotFeaturesViolin

plot_features_violin(
    data,
    feature_list,
    groupby: Optional[str] = None,
    use_raw: Optional[bool] = None,
    layer: Optional[str] = None,
    palette=None,
    jitter: bool = False,
    width_single: float = None,
    height_single: float = 2.0,
    size: float = 0.1,
    show_grid: bool = True,
    show_median: bool = True,
    median_color: str = 'lightgrey',
    show_figure: bool = True,
    save: Optional[str] = None,
    modality: Optional[str] = None,
    cytome_layer: str = 'counts',
    compute_on_fly: bool = True,
    use_cached_stats: bool = True,
    show: Optional[bool] = None,
)

Signature defaults

Plots a violin plot for each feature specified in feature_list.

Uses matplotlib directly (no scanpy dependency). Supports AnnData and cytome Dataset / .cytome file path.

Parameters

data — anndata.AnnData, cytome.Dataset, or str

The data source. For AnnData, reads from obs, layers, or raw. For cytome, reads from the cells SQL table.

feature_list — List[str]

Feature names to visualize. For cytome, these must be column names in the cells table.

groupby — str, optional

Column to group data points by. Default is None.

use_raw — bool, optional

Use raw attribute of adata. Ignored for cytome.

layer — str, optional

AnnData layer to use. Ignored for cytome.

palette — list or dict, optional

Color palette for groups. If None, checks adata.uns['{groupby}_colors'] first, then falls back to the default PIASO palette.

jitter — bool, optional

Show jitter scatter points on violins. Default is False.

width_single — float, optional

height_single — float, optional

Height of each subplot. Default is 2.0.

size — float, optional

Jitter point size (only used when jitter=True). Default is 0.1.

show_grid — bool, optional

Show grid lines. Default is True.

show_median — bool, optional

Show median line on violins. Default is True.

median_color — str, optional

Color of the median line. Default is 'lightgrey'.

show_figure — bool, optional

Show figure (plt.show()). Default is True.

save — str, optional

Path to save the figure. Default is None.

plotGroupMetrics

plotGroupMetrics(
    df,
    data=None,
    groupby: Optional[str] = None,
    metrics: Optional[list] = None,
    kind: str = 'bar',
    palette=None,
    ncol: Optional[int] = None,
    figsize: Optional[tuple] = None,
    normalize: str = 'minmax',
    annotate: bool = True,
    cmap: str = 'Blues',
    fontsize: Optional[float] = None,
    rotation: float = 45,
    save: Optional[str] = None,
    show: bool = True,
    return_fig: bool = False,
)

Signature defaults

Plot the per-group metrics DataFrame from :func:piaso.pp.calculateGroupMetrics.

Parameters

df — pandas.DataFrame

metrics — list of str, optional

Subset / order of metric columns to plot. Default: all numeric columns.

kind — 'bar' | 'heatmap'

'bar' (default): one panel per metric. 'heatmap': groups × metrics with per-column normalisation.

palette — dict or list, optional

Override group colours ({group: hex} or an ordered list).

ncol — int, optional

Columns in the faceted bar grid (default: ~sqrt(n_metrics)).

figsize — tuple, optional

Auto-sized if None.

normalize — 'minmax' | 'zscore' | None

Per-column scaling for the heatmap (ignored for bars).

annotate — bool, default True

Write the raw value in each heatmap cell.

cmap — str, default 'Blues'

Heatmap colormap.

fontsize — float, optional

Base font size (defaults to rcParams['font.size']).

rotation — float, default 45

Group-label rotation (anchored to the ticks so names don’t overlap). save, show, return_fig Output options.

plotHeatmap

heatmap(
    data,
    features: list,
    groupby: str = 'leiden',
    layer: Optional[str] = None,
    use_raw: Optional[bool] = None,
    standard_scale: Optional[str] = None,
    log: bool = False,
    cmap: str = 'viridis',
    figsize: Optional[tuple] = None,
    categories_order: Optional[list] = None,
    var_names_order: Optional[list] = None,
    dendrogram: bool = False,
    swap_axes: bool = False,
    title: Optional[str] = None,
    show_values: bool = False,
    fmt: str = '.2f',
    vmin: Optional[float] = None,
    vmax: Optional[float] = None,
    cell_level: bool = False,
    max_cells_per_group: int = 100,
    show_group_colors: bool = True,
    show: bool = True,
    save: Optional[str] = None,
    ax: Optional[matplotlib.axes._axes.Axes] = None,
    return_fig: bool = False,
    modality: Optional[str] = None,
    cytome_layer: str = 'counts',
    compute_on_fly: bool = True,
    use_cached_stats: bool = True,
)

Signature defaults

Plot an expression heatmap.

Two modes:

Group-level (default): mean expression per group (groups x features).
Cell-level (cell_level=True): per-cell expression with group-stratified sampling, up to max_cells_per_group cells per group.

Parameters

data — AnnData or cytome Dataset/path

Input data.

features — list, dict, or DataFrame

groupby — str

Grouping column. layer, use_raw AnnData layer / raw attribute. Ignored for cytome.

standard_scale — str, optional

'var' to z-score per feature, 'group' per group.

log — bool

Log1p transform.

cmap — str

Colormap.

figsize — tuple, optional

Auto-calculated if None.

categories_order — list, optional

Custom group order.

var_names_order — list, optional

Custom feature order.

dendrogram — bool

Cluster groups by hierarchical clustering (group-level only).

swap_axes — bool

Transpose: features on Y, groups on X.

title — str, optional

Title.

show_values — bool

Annotate cells with values (group-level only).

fmt — str

Number format for annotations. vmin, vmax : float, optional Colorscale limits.

cell_level — bool

If True, show per-cell expression instead of group means.

max_cells_per_group — int

Maximum cells per group when cell_level=True. Default 100.

show_group_colors — bool

Show colored sidebar for groups when cell_level=True. show, save, ax, return_fig Output options.

plotLigandReceptorInteraction

plotLigandReceptorInteraction(
    interactions_df: pandas.core.frame.DataFrame,
    specificity_df: pandas.core.frame.DataFrame,
    cell_type_pairs: list,
    top_n: int = 50,
    y_max: int = 10,
    cell_type_sep: str = '@',
    ligand_receptor_sep: str = '-->',
    heatmap_height_ratio: float = 1.5,
    heatmap_cmap: str = 'Purples',
    heatmap_cmap_ligand: str = None,
    heatmap_cmap_receptor: str = None,
    shared_legend: bool = False,
    heatmap_vmax: float = None,
    save_path: str = None,
    fig_width: int = 24,
    fig_height_per_pair: int = 9,
    col_interaction_score: str = 'interaction_score',
    col_ligand_receptor_pair: str = 'ligandXreceptor',
    col_cell_type_pair: str = 'CellTypeXCellType',
    col_annotation: str = 'annotation',
    col_ligand: str = 'ligand',
    col_receptor: str = 'receptor',
    vertical_layout: bool = False,
    color_labels_by_annotation: bool = False,
    barplot_palette: str = 'Paired',
    sort_by_category: bool = False,
    category_agg_method: str = 'sum',
    preserve_input_order: bool = False,
)

Signature defaults

interactions_df, specificity_df, cell_type_pairs, top_n=50, y_max=10, cell_type_sep='@', ligand_receptor_sep='-->', heatmap_height_ratio=1.5, heatmap_cmap='Purples', heatmap_cmap_ligand=None, heatmap_cmap_receptor=None, shared_legend=False, heatmap_vmax=None, save_path=None, fig_width=24, fig_height_per_pair=9, col_interaction_score='interaction_score', col_ligand_receptor_pair='ligandXreceptor', col_cell_type_pair='CellTypeXCellType', col_annotation='annotation', col_ligand='ligand', col_receptor='receptor', vertical_layout=False, color_labels_by_annotation=False, barplot_palette='Paired', sort_by_category=False, category_agg_method='sum', preserve_input_order=False

Generates plots with a bar plot of top interactions and a heatmap showing ligand and receptor specificity, with an option for vertical orientation.

Args: interactions_df (pd.DataFrame): DataFrame with interaction scores. specificity_df (pd.DataFrame): DataFrame with gene specificity scores. cell_type_pairs (list): A list of ‘CellTypeXCellType’ strings to plot. top_n (int): The number of top interactions to display. y_max (int): The maximum y-axis value for the bar plot. cell_type_sep (str): The separator for sender/receiver cell types. ligand_receptor_sep (str): The separator for ligand/receptor genes. heatmap_height_ratio (float): The height/width ratio of the heatmap relative to the bar plot. heatmap_cmap (str): The colormap for the specificity heatmap (used when ligand/receptor cmaps not specified). heatmap_cmap_ligand (str): The colormap for ligand specificity. If None, uses heatmap_cmap. heatmap_cmap_receptor (str): The colormap for receptor specificity. If None, uses heatmap_cmap. shared_legend (bool): If True, a single legend/colorbar is shown for all plots. heatmap_vmax (float): The maximum value for the heatmap color scale. save_path (str, optional): Path to save the figure (e.g., ‘plot.pdf’). fig_width (int): For horizontal layout, the total figure width. For vertical, this controls the total figure HEIGHT. fig_height_per_pair (int): For horizontal layout, height per subplot. For vertical, this controls the WIDTH of each subplot group. col_interaction_score (str): Column name for interaction scores. col_ligand_receptor_pair (str): Column name for ligand-receptor pair strings. col_cell_type_pair (str): Column name for cell type pair strings. col_annotation (str): Column name for pathway/annotation data. col_ligand (str): Column name for ligand after splitting. col_receptor (str): Column name for receptor after splitting. vertical_layout (bool): If True, plots are arranged horizontally (rotated 90 degrees). color_labels_by_annotation (bool): If True, color ligand-receptor labels by their annotation category. barplot_palette (str or list): Color palette for bar plots. Can be a seaborn palette name (e.g., ‘Paired’, ‘Set1’) or a list of hex colors (e.g., [‘#F198CC’, ‘#D6DAB9’, ‘#BC938B’]). sort_by_category (bool): If True, sort interactions by category first, then by interaction score within category. category_agg_method (str): Method to aggregate interaction scores by category (‘sum’ or ‘mean’) when sort_by_category=True. preserve_input_order (bool): If True, preserve the original order from interactions_df without any sorting.

Examples: # Preserve original input order plotLigandReceptorInteraction( interactions_df=specific_interactions, specificity_df=cosg_scores, cell_type_pairs=[‘L5 NP@SST-Chrna2’], preserve_input_order=True, # Use original DataFrame order vertical_layout=False )

# Horizontal layout with category sorting
plotLigandReceptorInteraction(
    interactions_df=specific_interactions,
    specificity_df=cosg_scores,
    cell_type_pairs=['L5 NP@SST-Chrna2', 'L5 PT@SST-Chrna2'],
    ligand_receptor_sep='-->',
    top_n=50,
    y_max=10,
    heatmap_cmap_ligand='Blues',
    heatmap_cmap_receptor='Reds',
    shared_legend=True,
    vertical_layout=False,
    sort_by_category=True,
    category_agg_method='sum',
    color_labels_by_annotation=True
)

# Vertical layout with custom hex colors
plotLigandReceptorInteraction(
    interactions_df=specific_interactions_cellchat,
    specificity_df=cosg_scores,
    cell_type_pairs=['L5 NP@SST-Chrna2'],
    ligand_receptor_sep='-->',
    top_n=50,
    y_max=10,
    heatmap_cmap_ligand='Purples',
    heatmap_cmap_receptor='Reds',
    shared_legend=True,
    vertical_layout=True,
    barplot_palette=['#F198CC', '#D6DAB9', '#BC938B', '#93DCFC', '#F4DBCD', '#bcf60c'],
    sort_by_category=True,
    category_agg_method='mean'
)

Raises: ValueError: If required columns are missing from DataFrames or if data is inconsistent. KeyError: If specified cell type pairs are not found in the data.

plotLigandReceptorLollipop

plotLigandReceptorLollipop(
    interactions_df: pandas.core.frame.DataFrame,
    cell_type_pairs: List[str],
    top_n: int = 25,
    sort_by_category: bool = False,
    preserve_input_order: bool = False,
    palette: str = 'tab20',
    vertical_layout: bool = True,
    fig_width: int = 10,
    fig_height_per_pair: int = 6,
    save_path: str = None,
    cell_type_sep: str = '@',
    ligand_receptor_sep: str = '-->',
    col_interaction_score: str = 'interaction_score',
    col_ligand_specificity: str = 'ligand_specificity',
    col_receptor_specificity: str = 'receptor_specificity',
    col_ligand_receptor_pair: str = 'ligandXreceptor',
    col_cell_type_pair: str = 'CellTypeXCellType',
    col_annotation: str = 'annotation',
    category_agg_method: str = 'sum',
    color_labels_by_annotation: bool = False,
    max_label_length: int = 25,
    background_colors: bool = False,
    col_circle_size: str = 'avg_log2FC',
    circle_size_title: str = 'avg_log2FC',
    base_circle_size: float = 15,
    circle_size_scale: float = 20,
    logfc_range: float = 1.0,
    size_dramatic_level: float = 1.5,
    show_grid: bool = True,
    score_range_min: float = None,
    score_range_max: float = None,
    range_padding: float = 0.15,
    specificity_df: pandas.core.frame.DataFrame = None,
)

Signature defaults

interactions_df, cell_type_pairs, top_n=25, sort_by_category=False, preserve_input_order=False, palette='tab20', vertical_layout=True, fig_width=10, fig_height_per_pair=6, save_path=None, cell_type_sep='@', ligand_receptor_sep='-->', col_interaction_score='interaction_score', col_ligand_specificity='ligand_specificity', col_receptor_specificity='receptor_specificity', col_ligand_receptor_pair='ligandXreceptor', col_cell_type_pair='CellTypeXCellType', col_annotation='annotation', category_agg_method='sum', color_labels_by_annotation=False, max_label_length=25, background_colors=False, col_circle_size='avg_log2FC', circle_size_title='avg_log2FC', base_circle_size=15, circle_size_scale=20, logfc_range=1.0, size_dramatic_level=1.5, show_grid=True, score_range_min=None, score_range_max=None, range_padding=0.15, specificity_df=None

Generates advanced bidirectional lollipop plots for one or more cell-type interactions with support for both vertical and horizontal layouts.

Args: interactions_df (pd.DataFrame): DataFrame with interaction and specificity data. cell_type_pairs (List[str]): A list of ‘CellTypeXCellType’ strings to plot. top_n (int): The number of top interactions to display per plot. sort_by_category (bool): If True, sort interactions by category first, then by score. preserve_input_order (bool): If True, use the original DataFrame order. palette (str): Seaborn color palette name for coloring categories. vertical_layout (bool): If True, subplots are arranged vertically. Otherwise, horizontally. fig_width (int): Base width for the figure (for vertical layout) or width per subplot (for horizontal). fig_height_per_pair (int): Height per subplot (for vertical layout) or base height (for horizontal). save_path (str, optional): Path to save the figure (e.g., ‘plot.png’). cell_type_sep (str): Separator for sender/receiver cell types (e.g., ’@’). ligand_receptor_sep (str): Separator for ligand/receptor pairs (e.g., ’—>’). col_interaction_score (str): Column name for interaction scores. col_ligand_specificity (str): Column name for ligand specificity scores. col_receptor_specificity (str): Column name for receptor specificity scores. col_ligand_receptor_pair (str): Column name for ligand-receptor pair strings. col_cell_type_pair (str): Column name for cell type pair strings. col_annotation (str): Column name for pathway/annotation data (default: ‘annotation’). category_agg_method (str): Method to aggregate interaction scores by category (‘sum’ or ‘mean’). color_labels_by_annotation (bool): If True, color ligand-receptor labels by their annotation. max_label_length (int): Maximum length for y-axis labels before truncation. background_colors (bool): If True, add transparent background colors to distinguish ligand/receptor sides. col_circle_size (str): Column name for controlling circle sizes (default: ‘avg_log2FC’). circle_size_title (str): Title for the circle size legend. base_circle_size (float): Base size for circles when col_circle_size value is 0. circle_size_scale (float): Scaling factor for circle sizes based on col_circle_size values. logfc_range (float): Expected range of logFC values for proper scaling (e.g., 1.0 for -1 to +1 range). size_dramatic_level (float): Controls how dramatic the size differences are (0.5=subtle, 1.0=moderate, 2.0=very dramatic). show_grid (bool): If True, show grid lines on the plot. score_range_min (float, optional): Minimum value for interaction score axis. Values below this will be clipped. score_range_max (float, optional): Maximum value for interaction score axis. Values above this will be clipped. range_padding (float): Padding to add beyond the score range to accommodate circles (default 0.15 = 15%). specificity_df (pd.DataFrame, optional): DataFrame with gene names as index and cell types as columns containing specificity scores. If provided, will override col_ligand_specificity and col_receptor_specificity columns.

Examples: # Vertical layout with default settings plotLigandReceptorLollipop( interactions_df=specific_interactions, cell_type_pairs=[‘L5 NP@SST-Chrna2’], vertical_layout=True )

# Using external specificity dataframe
plotLigandReceptorLollipop(
    interactions_df=specific_interactions,
    cell_type_pairs=['L5 NP@SST-Chrna2', 'L5 PT@SST-Chrna2'],
    specificity_df=gene_specificity_matrix,
    vertical_layout=False,
    save_path='lollipop_plot.png'
)

plotSankey

sankey(
    data,
    left: str,
    right: str,
    palette=None,
    color_by: str = 'left',
    figsize: Optional[tuple] = None,
    alpha: float = 0.4,
    node_width: float = 0.08,
    gap: float = 0.03,
    title: Optional[str] = None,
    fontsize: int = 9,
    show: bool = True,
    save: Optional[str] = None,
    ax: Optional[matplotlib.axes._axes.Axes] = None,
    return_fig: bool = False,
)

Signature defaults

data, left, right, palette=None, color_by='left', figsize=None, alpha=0.4, node_width=0.08, gap=0.03, title=None, fontsize=9, show=True, save=None, ax=None, return_fig=False

Plot a Sankey (alluvial) diagram between two categorical columns.

Parameters

data — AnnData or cytome Dataset/path

Input data.

left — str

Left-side category column.

right — str

Right-side category column.

palette — list or dict, optional

Colors. If None, uses d_color4.

color_by — str

Color flows by 'left' or 'right' categories.

figsize — tuple, optional

Figure size.

alpha — float

Flow ribbon transparency.

node_width — float

Width of category bars (in data coords).

gap — float

Vertical gap between bars (fraction of total height).

title — str, optional

Title.

fontsize — int

Label font size. show, save, ax, return_fig Output options.

plotScatter

scatter(
    data,
    x: str,
    y: str,
    color: Optional[str] = None,
    on: str = 'cells',
    layer: Optional[str] = None,
    use_raw: Optional[bool] = None,
    palette=None,
    cmap=None,
    point_size: Optional[float] = None,
    alpha: float = 1.0,
    density: str = 'auto',
    density_threshold: int = 20000,
    gridsize: int = 60,
    logx: bool = False,
    logy: bool = False,
    marginals: bool = False,
    vlines=None,
    hlines=None,
    figsize: Optional[tuple] = None,
    title: Optional[str] = None,
    xlabel: Optional[str] = None,
    ylabel: Optional[str] = None,
    legend_loc: str = 'right',
    legend_fontsize: int = 9,
    legend_marker_size: float = 6.0,
    square: bool = True,
    rasterized: bool = True,
    frameon: Optional[bool] = True,
    vmin: Optional[float] = None,
    vmax: Optional[float] = None,
    show: bool = True,
    save: Optional[str] = None,
    ax: Optional[matplotlib.axes._axes.Axes] = None,
    return_fig: bool = False,
    modality: Optional[str] = None,
    cytome_layer: str = 'counts',
    compute_on_fly: bool = True,
    use_cached_stats: bool = True,
)

Signature defaults

data, x, y, color=None, on='cells', layer=None, use_raw=None, palette=None, cmap=None, point_size=None, alpha=1.0, density='auto', density_threshold=20000, gridsize=60, logx=False, logy=False, marginals=False, vlines=None, hlines=None, figsize=None, title=None, xlabel=None, ylabel=None, legend_loc='right', legend_fontsize=9, legend_marker_size=6.0, square=True, rasterized=True, frameon=True, vmin=None, vmax=None, show=True, save=None, ax=None, return_fig=False, modality=None, cytome_layer='counts', compute_on_fly=True, use_cached_stats=True

Scatter plot of two features colored by a third variable.

Parameters

data — AnnData or cytome Dataset/path

Input data.

x — str

Feature for X axis (gene name, obs column, or peak).

y — str

Feature for Y axis.

color — str, optional

Column for coloring points. Can be categorical (e.g. 'leiden') or continuous (e.g. a gene name). If None, all points are grey.

layer — str, optional

AnnData layer. Ignored for cytome.

use_raw — bool, optional

Use raw attribute. Ignored for cytome.

palette — list or dict, optional

Colors for categorical data. Falls back to PIASO default.

cmap — str, optional

Colormap. Defaults to 'magma_r' when color is continuous (sequential, perceptually uniform, colourblind-safe) and to PIASO’s density map when density=True. Colormap for continuous data.

point_size — float or None

Point size. If None, auto-calculated from cell count.

alpha — float

Point transparency.

figsize — tuple, optional

Figure size.

title — str, optional

Plot title. xlabel, ylabel : str, optional Axis labels. Default to feature names.

legend_loc — str

'right', 'on_data', or 'none'.

legend_fontsize — int

Legend font size.

legend_marker_size — float

Fixed legend dot size (pt), independent of point_size.

square — bool, default True

Keep the scatter axes square (set_box_aspect(1)) and, for a categorical color with legend_loc='right', put the legend in its own panel so a long category legend no longer squeezes the plot.

rasterized — bool

Rasterize points for smaller vector files.

frameon — bool, optional

Show axis frame. If None, uses piaso.settings._frameon. vmin, vmax : float, optional Continuous colorscale limits.

on — str, default 'cells'

What each point is. 'cells' → one point per cell, x/y are per-cell features (gene/peak/tile name or a cells column). A feature entity ('peaks' / 'genes' / 'tiles' / 'GA_genes' for a cytome, or 'var'/any for AnnData) → one point per feature, x/y are columns of that entity’s table (e.g. 'neg_log10_pvalue', 'score', or the derived 'width' = end_ - start).

density — 'auto' | 'scatter' | 'hexbin'

'auto' switches to a log-count hexbin above density_threshold points (unless colour is categorical). 'scatter' forces points; 'hexbin' forces density. With a continuous color the hexbin shows the per-cell mean.

density_threshold — int

Point count above which density='auto' uses hexbin.

gridsize — int

Hexbin grid resolution. logx, logy : bool Log-scale the X / Y axis.

marginals — bool

Add marginal histograms of x/y (only when ax is None). vlines, hlines : list of float, optional Vertical / horizontal reference lines (e.g. a min_length or score_cutoff threshold). show, save, ax, return_fig Output options.

Returns

Optionally (fig, ax).

plotUMAP

plotUMAP(data, color='leiden', **kwargs)

Signature defaults

data, color='leiden', **kwargs

Convenience wrapper for :func:plotEmbedding with basis='X_umap'.

sankey

sankey(
    data,
    left: str,
    right: str,
    palette=None,
    color_by: str = 'left',
    figsize: Optional[tuple] = None,
    alpha: float = 0.4,
    node_width: float = 0.08,
    gap: float = 0.03,
    title: Optional[str] = None,
    fontsize: int = 9,
    show: bool = True,
    save: Optional[str] = None,
    ax: Optional[matplotlib.axes._axes.Axes] = None,
    return_fig: bool = False,
)

Signature defaults

Plot a Sankey (alluvial) diagram between two categorical columns.

Parameters

data — AnnData or cytome Dataset/path

Input data.

left — str

Left-side category column.

right — str

Right-side category column.

palette — list or dict, optional

Colors. If None, uses d_color4.

color_by — str

Color flows by 'left' or 'right' categories.

figsize — tuple, optional

Figure size.

alpha — float

Flow ribbon transparency.

node_width — float

Width of category bars (in data coords).

gap — float

Vertical gap between bars (fraction of total height).

title — str, optional

Title.

fontsize — int

Label font size. show, save, ax, return_fig Output options.

scatter

scatter(
    data,
    x: str,
    y: str,
    color: Optional[str] = None,
    on: str = 'cells',
    layer: Optional[str] = None,
    use_raw: Optional[bool] = None,
    palette=None,
    cmap=None,
    point_size: Optional[float] = None,
    alpha: float = 1.0,
    density: str = 'auto',
    density_threshold: int = 20000,
    gridsize: int = 60,
    logx: bool = False,
    logy: bool = False,
    marginals: bool = False,
    vlines=None,
    hlines=None,
    figsize: Optional[tuple] = None,
    title: Optional[str] = None,
    xlabel: Optional[str] = None,
    ylabel: Optional[str] = None,
    legend_loc: str = 'right',
    legend_fontsize: int = 9,
    legend_marker_size: float = 6.0,
    square: bool = True,
    rasterized: bool = True,
    frameon: Optional[bool] = True,
    vmin: Optional[float] = None,
    vmax: Optional[float] = None,
    show: bool = True,
    save: Optional[str] = None,
    ax: Optional[matplotlib.axes._axes.Axes] = None,
    return_fig: bool = False,
    modality: Optional[str] = None,
    cytome_layer: str = 'counts',
    compute_on_fly: bool = True,
    use_cached_stats: bool = True,
)

Signature defaults

Scatter plot of two features colored by a third variable.

Parameters

data — AnnData or cytome Dataset/path

Input data.

x — str

Feature for X axis (gene name, obs column, or peak).

y — str

Feature for Y axis.

color — str, optional

Column for coloring points. Can be categorical (e.g. 'leiden') or continuous (e.g. a gene name). If None, all points are grey.

layer — str, optional

AnnData layer. Ignored for cytome.

use_raw — bool, optional

Use raw attribute. Ignored for cytome.

palette — list or dict, optional

Colors for categorical data. Falls back to PIASO default.

cmap — str, optional

Colormap. Defaults to 'magma_r' when color is continuous (sequential, perceptually uniform, colourblind-safe) and to PIASO’s density map when density=True. Colormap for continuous data.

point_size — float or None

Point size. If None, auto-calculated from cell count.

alpha — float

Point transparency.

figsize — tuple, optional

Figure size.

title — str, optional

Plot title. xlabel, ylabel : str, optional Axis labels. Default to feature names.

legend_loc — str

'right', 'on_data', or 'none'.

legend_fontsize — int

Legend font size.

legend_marker_size — float

Fixed legend dot size (pt), independent of point_size.

square — bool, default True

Keep the scatter axes square (set_box_aspect(1)) and, for a categorical color with legend_loc='right', put the legend in its own panel so a long category legend no longer squeezes the plot.

rasterized — bool

Rasterize points for smaller vector files.

frameon — bool, optional

Show axis frame. If None, uses piaso.settings._frameon. vmin, vmax : float, optional Continuous colorscale limits.

on — str, default 'cells'

density — 'auto' | 'scatter' | 'hexbin'

density_threshold — int

Point count above which density='auto' uses hexbin.

gridsize — int

Hexbin grid resolution. logx, logy : bool Log-scale the X / Y axis.

marginals — bool

Returns

Optionally (fig, ax).

split_embedding

plot_embeddings_split(
    data,
    color,
    splitby,
    ncol: int = None,
    dpi: int = 80,
    col_size: int = 5,
    row_size: int = 5,
    alpha: float = 1.0,
    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',
    legend_marker_size: float = 6.0,
    groups=None,
    point_size: float = None,
    palette=None,
    cmap=None,
    frameon: bool = False,
    rasterized: bool = True,
    modality: str = None,
    cytome_layer: str = 'counts',
    compute_on_fly: bool = True,
    use_cached_stats: bool = True,
    show_modality_in_title: bool = False,
    x_min=None,
    x_max=None,
    y_min=None,
    y_max=None,
    **kwargs,
)

Signature defaults

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.

Supports AnnData, cytome Dataset, or path to .cytome file.

Parameters

data — AnnData, cytome.Dataset, or str

An AnnData object, cytome Dataset, or path to .cytome file.

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=4.0)

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.

point_size — float, optional

palette — list[str] or dict, optional

cmap — str or Colormap, optional

Colourmap for numeric color values. Forwarded to each panel.

frameon — bool, optional (default False)

Whether to show axis spines on each panel and on the global legend frame. Mirrors piaso.pl.plotEmbedding(frameon=...).

rasterized — bool, optional (default True)

Forward to per-panel scatter for compact vector output.

**kwargs — dict

Forwarded verbatim to :func:piaso.pl.plotEmbedding for each panel. Accepts the scanpy-style aliases ncols (→ ncol) and size (→ point_size) for compatibility with existing call sites.

Returns

None.

Examples

>>> import anndata
>>> import piaso
>>> adata = anndata.read_h5ad('pbmc3k.h5ad')  # 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')

stacked_barplot

stacked_barplot(
    data,
    groupby: str = 'leiden',
    splitby: str = 'batch',
    normalize: bool = True,
    palette=None,
    figsize: Optional[tuple] = None,
    title: Optional[str] = None,
    legend_ncol: Optional[int] = None,
    legend_fontsize: int = 9,
    show: bool = True,
    save: Optional[str] = None,
    ax: Optional[matplotlib.axes._axes.Axes] = None,
    return_fig: bool = False,
)

Signature defaults

data, groupby='leiden', splitby='batch', normalize=True, palette=None, figsize=None, title=None, legend_ncol=None, legend_fontsize=9, show=True, save=None, ax=None, return_fig=False

Plot a stacked barplot of cell composition.

Parameters

data — AnnData or cytome Dataset/path

Input data.

groupby — str

Column for cell groups (bar segments).

splitby — str

Column for conditions/samples (bar positions on X axis).

normalize — bool

Normalize to fractions per splitby category.

palette — list or dict, optional

Colors for groups. Falls back to adata.uns then d_color4.

figsize — tuple, optional

Figure size.

title — str, optional

Plot title.

legend_ncol — int, optional

Legend columns. Auto-calculated if None.

legend_fontsize — int

Legend font size.

show — bool

Call plt.show().

save — str, optional

Save path.

ax — Axes, optional

Pre-existing axes.

return_fig — bool

Return (fig, ax).

stackedBarplot

stacked_barplot(
    data,
    groupby: str = 'leiden',
    splitby: str = 'batch',
    normalize: bool = True,
    palette=None,
    figsize: Optional[tuple] = None,
    title: Optional[str] = None,
    legend_ncol: Optional[int] = None,
    legend_fontsize: int = 9,
    show: bool = True,
    save: Optional[str] = None,
    ax: Optional[matplotlib.axes._axes.Axes] = None,
    return_fig: bool = False,
)

Signature defaults

Plot a stacked barplot of cell composition.

Parameters

data — AnnData or cytome Dataset/path

Input data.

groupby — str

Column for cell groups (bar segments).

splitby — str

Column for conditions/samples (bar positions on X axis).

normalize — bool

Normalize to fractions per splitby category.

palette — list or dict, optional

Colors for groups. Falls back to adata.uns then d_color4.

figsize — tuple, optional

Figure size.

title — str, optional

Plot title.

legend_ncol — int, optional

Legend columns. Auto-calculated if None.

legend_fontsize — int

Legend font size.

show — bool

Call plt.show().

save — str, optional

Save path.

ax — Axes, optional

Pre-existing axes.

return_fig — bool

Return (fig, ax).

umap

plotUMAP(data, color='leiden', **kwargs)

Signature defaults

data, color='leiden', **kwargs

Convenience wrapper for :func:plotEmbedding with basis='X_umap'.

violin

plot_features_violin(
    data,
    feature_list,
    groupby: Optional[str] = None,
    use_raw: Optional[bool] = None,
    layer: Optional[str] = None,
    palette=None,
    jitter: bool = False,
    width_single: float = None,
    height_single: float = 2.0,
    size: float = 0.1,
    show_grid: bool = True,
    show_median: bool = True,
    median_color: str = 'lightgrey',
    show_figure: bool = True,
    save: Optional[str] = None,
    modality: Optional[str] = None,
    cytome_layer: str = 'counts',
    compute_on_fly: bool = True,
    use_cached_stats: bool = True,
    show: Optional[bool] = None,
)

Signature defaults

Plots a violin plot for each feature specified in feature_list.

Uses matplotlib directly (no scanpy dependency). Supports AnnData and cytome Dataset / .cytome file path.

Parameters

data — anndata.AnnData, cytome.Dataset, or str

The data source. For AnnData, reads from obs, layers, or raw. For cytome, reads from the cells SQL table.

feature_list — List[str]

Feature names to visualize. For cytome, these must be column names in the cells table.

groupby — str, optional

Column to group data points by. Default is None.

use_raw — bool, optional

Use raw attribute of adata. Ignored for cytome.

layer — str, optional

AnnData layer to use. Ignored for cytome.

palette — list or dict, optional

Color palette for groups. If None, checks adata.uns['{groupby}_colors'] first, then falls back to the default PIASO palette.

jitter — bool, optional

Show jitter scatter points on violins. Default is False.

width_single — float, optional

height_single — float, optional

Height of each subplot. Default is 2.0.

size — float, optional

Jitter point size (only used when jitter=True). Default is 0.1.

show_grid — bool, optional

Show grid lines. Default is True.

show_median — bool, optional

Show median line on violins. Default is True.

median_color — str, optional

Color of the median line. Default is 'lightgrey'.

show_figure — bool, optional

Show figure (plt.show()). Default is True.

save — str, optional

Path to save the figure. Default is None.

Moved to cytorete

These names still work, but the method they call now lives in cytorete — pip install cytorete, then use it directly as cytorete.tl.<name>. Calling them through PIASO raises a pointer to that package if it is not installed.

regulonActivity, regulonEmbedding, regulonNetwork, regulonSpecificityScatter