publiplots.scatterplot¶

publiplots.scatterplot(data, x, y, size=None, hue=None, style=None, color=None, palette=None, sizes=None, markers=None, size_norm=None, hue_norm=None, alpha=None, linewidth=None, edgecolor=None, background_marker=False, ax=None, title='', xlabel='', ylabel='', legend=True, legend_kws=None, margins=0.1, **kwargs)[source]¶

Create a scatterplot with publiplots styling.

This function creates scatterplots for both continuous and categorical data with extensive customization options. Supports size and color encoding, with distinctive double-layer markers for enhanced visibility.

Parameters:

data (pd.DataFrame) – Input data containing x, y, and optional size/hue columns.
x (str) – Column name for x-axis values (continuous or categorical).
y (str) – Column name for y-axis values (continuous or categorical).
size (str, optional) – Column name for marker sizes. If None, all markers have the same size.
hue (str, optional) – Column name for marker colors. Can be categorical or continuous. If None, uses default color or the value from color parameter.
style (str, optional) – Column name for marker styles. Produces points with different markers. Only categorical data is supported. If None, all markers use the same style.
color (str, optional) – Fixed color for all markers (only used when hue is None). Overrides default color. Example: “#ff0000” or “red”.
palette (str, dict, list, or None) – Color palette for hue values: - str: palette name (e.g., “viridis”, “pastel”) - dict: mapping of hue values to colors (categorical only) - list: list of colors - None: uses default palette
sizes (tuple of float, optional) – (min_size, max_size) in points^2 for marker sizes. Default: (20, 200) for continuous data, (100, 100) for no size encoding.
markers (bool, list, dict, optional) – Markers to use for different levels of the style variable: - True: use default marker set - list: list of marker symbols (e.g., [“o”, “^”, “s”]) - dict: mapping of style values to markers (e.g., {“A”: “o”, “B”: “^”}) - None: uses default marker “o” for all points
size_norm (tuple of float, optional) – (vmin, vmax) for size normalization. If None, computed from data.
hue_norm (tuple of float, optional) – (vmin, vmax) for continuous hue normalization. If None, computed from data. Providing this enables continuous color mapping.
alpha (float, optional) – Transparency level for marker fill (0-1). When None, resolved from publiplots.rcParams["alpha"].
linewidth (float, optional) – Width of marker edges. When None, resolved from publiplots.rcParams["lines.linewidth"].
edgecolor (str, optional) – Color for marker edges. If None, uses same color as fill. Can also be set globally via publiplots.rcParams["edgecolor"].
background_marker (bool or str, default=False) – Publiplots-specific: draw a solid background-colored marker behind each point to hide overlap. True uses white; a color string (e.g. "#eeeeee") overrides the background color. Off by default because duplicating every point doubles artist count and overlap is often informative.
ax (Axes, optional) – Matplotlib axes object. If None, creates new figure.
title (str, default="") – Plot title.
xlabel (str, default="") – X-axis label. If empty, uses x column name.
ylabel (str, default="") – Y-axis label. If empty, uses y column name.
legend_kws (dict, optional) –
Keyword arguments for legend builder:
- hue_title : str, optional - Title for the hue legend. If None, uses hue column name.
- size_title : str, optional - Title for the size legend. If None, uses size column name.
- style_title : str, optional - Title for the style legend. If None, uses style column name.
- size_reverse : bool, default=True - Whether to reverse the size legend (descending order).
legend (bool, default=True) – Whether to show legend.
margins (float or tuple, default=0.1) – Margins around the plot for categorical axes. If a float, sets both x and y margins to the same value. If a tuple, sets x and y margins separately.
**kwargs – Additional keyword arguments passed to seaborn.scatterplot().

Returns:

The axes where the plot was drawn.

Return type:

Axes

Examples

Simple scatterplot with continuous data: >>> ax = pp.scatterplot(data=df, x=”time”, y=”value”)

Scatterplot with size encoding: >>> ax = pp.scatterplot(data=df, x=”time”, y=”value”, … size=”magnitude”, sizes=(20, 200))

Scatterplot with categorical color encoding: >>> ax = pp.scatterplot(data=df, x=”time”, y=”value”, … hue=”group”, palette=”pastel”)

Scatterplot with continuous color encoding: >>> ax = pp.scatterplot(data=df, x=”time”, y=”value”, … hue=”score”, palette=”viridis”, … hue_norm=(0, 100))

Scatterplot with custom single color: >>> ax = pp.scatterplot(data=df, x=”time”, y=”value”, … color=”#e67e7e”)

Scatterplot with different marker styles: >>> ax = pp.scatterplot(data=df, x=”time”, y=”value”, … hue=”group”, style=”condition”, … markers=[“o”, “^”, “s”])

Categorical scatterplot (positions on grid): >>> ax = pp.scatterplot(data=df, x=”category”, y=”condition”, … size=”pvalue”, hue=”log2fc”)

Dense overlapping data with background markers for visual contrast: >>> ax = pp.scatterplot(data=df, x=”umap1”, y=”umap2”, … hue=”cluster”, background_marker=True)