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, figsize=None, 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: (50, 500) 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, default=0.1) – Transparency level for marker fill (0-1).

  • linewidth (float, default=2.0) – Width of marker edges.

  • edgecolor (str, optional) – Color for marker edges. If None, uses same color as fill.

  • figsize (tuple, default=(6, 4)) – Figure size (width, height) if creating new figure.

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

  • fig (Figure) – Matplotlib figure object.

  • ax (Axes) – Matplotlib axes object.

Return type:

Tuple[Figure, Axes]

Examples

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

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

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

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

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

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

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