scatter_plot()

Create a scatter plot with flexible configuration.

Usage

Source

scatter_plot(
    df,
    conditions,
    condition_col="condition",
    selector_col=None,
    selector_val=None,
    x_feature=None,
    y_feature="intensity_mean_EdU_nucleus_norm",
    cell_number=3000,
    hue=None,
    hue_order=None,
    palette=None,
    x_scale=None,
    x_scale_base=2,
    y_scale=None,
    y_scale_base=2,
    x_limits=None,
    y_limits=None,
    x_ticks=None,
    y_ticks=None,
    size=2,
    alpha=1.0,
    kde_overlay=None,
    kde_cmap="rocket_r",
    kde_alpha=0.1,
    vline=None,
    hline=None,
    line_style="--",
    line_color="black",
    grid=False,
    show_title=False,
    title=None,
    x_label=None,
    y_label=None,
    show_legend=False,
    legend_loc="best",
    legend_title=None,
    threshold=None,
    fig_size=None,
    size_units="cm",
    dpi=300,
    save=False,
    path=None,
    file_format="pdf",
    tight_layout=False,
    axes=None
)

This function provides a high-level API for creating scatter plots with support for multiple conditions, log scales, KDE overlays, and threshold-based coloring.

Data Filtering df : pd.DataFrame DataFrame containing the data. conditions : str | list[str] Single condition string or list of conditions. condition_col : str, default=“condition” Column containing condition labels. selector_col : str | None, default=None Optional column for additional filtering. selector_val : str | None, default=None Optional value for selector_col filtering.

Plot Features ^ x_feature : str | None, default=None Column name for x-axis. When None (the default), resolves to the normalised DNA-content column via find_dna_norm_column() (e.g. integrated_int_DAPI_norm for legacy plates, integrated_int_Hoechst_norm for new plates). y_feature : str, default=“intensity_mean_EdU_nucleus_norm” Column name for y-axis (default: EdU intensity). cell_number : int | None, default=3000 Number of cells to sample per condition (None = all).

Display Options ^ hue : str | None, default=None Column name for color mapping (auto-detects cell_cycle). hue_order : list[str] | None, default=None Order for hue categories. palette : list[str] | dict[str, str] | None, default=None Colors for hue categories. size : float, default=2 Size of scatter points. alpha : float, default=1.0 Transparency of points. kde_overlay : bool | None, default=None Whether to add KDE overlay (auto for DNA vs EdU). kde_cmap : str, default=“rocket_r” Colormap for KDE. kde_alpha : float, default=0.1 Transparency of KDE. grid : bool, default=False Whether to show grid. show_legend : bool, default=False Whether to show legend. legend_loc : str, default=“best” Legend location. legend_title : str | None, default=None Legend title.

Axes Settings ^ x_scale : Literal[“linear”, “log”] | None, default=None Scale type for x-axis (“linear” or “log”, auto-detected). x_scale_base : int, default=2 Base for log scale on x-axis. y_scale : Literal[“linear”, “log”] | None, default=None Scale type for y-axis (“linear” or “log”, auto-detected). y_scale_base : int, default=2 Base for log scale on y-axis. x_limits : tuple[float, float] | None, default=None Limits for x-axis (auto-set for DNA content). y_limits : tuple[float, float] | None, default=None Limits for y-axis. x_ticks : list[float] | None, default=None Custom x-axis tick positions. y_ticks : list[float] | None, default=None Custom y-axis tick positions. x_label : str | None, default=None X-axis label. y_label : str | None, default=None Y-axis label. axes : Axes | None, default=None Existing matplotlib Axes to plot on.

Reference Lines & Thresholds ^ vline : float | None, default=None Vertical reference line position (auto for DNA). hline : float | None, default=None Horizontal reference line position (auto for EdU). line_style : str, default=“–” Style for reference lines. line_color : str, default=“black” Color for reference lines. threshold : float | None, default=None Y-value threshold for blue/red coloring.

Styling & Colors show_title : bool, default=False Whether to show title. title : str | None, default=None Plot title. fig_size : tuple[float, float] | None, default=None Figure size in size_units. size_units : str, default=“cm” Units for figure size (“cm” or “inches”). tight_layout : bool, default=False Whether to use tight layout.

Save Options save : bool, default=False Whether to save the figure. path : Path | None, default=None Directory to save figure. file_format : str, default=“pdf” Format for saved figure. dpi : int, default=300 Resolution for saved figures.

tuple[Figure, Axes | list[Axes]] (Figure, Axes or list of Axes)

Examples

Basic cell cycle plot with auto-detection:

    >>> fig, ax = scatter_plot(df, "control")

Multiple conditions with threshold coloring:

    >>> fig, axes = scatter_plot(
    ...     df,
    ...     ["control", "treatment"],
    ...     y_feature="intensity_mean_p21_nucleus",
    ...     threshold=5000
    ... )

Custom features with log scales:

    >>> fig, ax = scatter_plot(
    ...     df,
    ...     "control",
    ...     x_feature="area_cell",
    ...     y_feature="intensity_mean_p21_nucleus",
    ...     x_scale="log",
    ...     y_scale="log"
    ... )