Functions

The public functions exported from reglscatterpy.

---

scatterplot

The public scatterplot() entry point.

By default this renders through reglscatterpy's own anywidget, which drives the very same compiled widget the R package ships (legend, lasso, tooltips, sync, PNG/SVG/PDF export) - so a plot is pixel-identical across R and Python. It works in Jupyter, JupyterLab, VS Code, Colab and (via shinywidgets) Shiny for Python, and embeds into self-contained HTML.

Pass backend="jscatter" to render through jupyter-scatter <https://github.com/flekschas/jupyter-scatter>_ instead (the JS author's binding) - lighter, but without the package's own legend / sync / export UI.

The signature mirrors the R reglScatterplot() so the two feel like one tool.

scatterplot

scatterplot(
    data: Any = None,
    *,
    color: Any = _UNSET,
    size: Any = _UNSET,
    cmap: Any = _UNSET,
    palette: Any = _UNSET,
    components: Any = _UNSET,
    ncols: Optional[int] = None,
    save: Optional[str] = None,
    na_color: str = "lightgray",
    groups: Any = None,
    add_outline: bool = False,
    outline_width: Sequence[float] = (0.3, 0.05),
    outline_color: Sequence = ("black", "white"),
    sort_order: bool = True,
    random_state: Optional[int] = None,
    max_points: Any = "auto",
    subsample: str = "density",
    basis: Optional[Union[str, int]] = None,
    x: Optional[Union[str, int]] = None,
    y: Optional[Union[str, int]] = None,
    color_by: ColorSpec = None,
    group_by: ColorSpec = None,
    layer: Optional[str] = None,
    use_raw: Optional[bool] = None,
    dims: Optional[tuple] = None,
    table: Optional[str] = None,
    point_size: Optional[float] = None,
    opacity: Optional[float] = None,
    alpha: Optional[float] = None,
    point_color: Optional[str] = None,
    size_by: Any = None,
    opacity_by: Any = None,
    tooltip_by: Any = None,
    pixel_ratio: Optional[float] = None,
    categorical_palette: str = "scanpy",
    continuous_palette: str = "viridis",
    custom_palette: Optional[Sequence[str]] = None,
    custom_colors: Optional[dict] = None,
    vmin: Any = None,
    vmax: Any = None,
    center_zero: bool = False,
    title: Optional[str] = None,
    xlab: Optional[str] = None,
    ylab: Optional[str] = None,
    legend_title: Optional[str] = None,
    show_axes: bool = True,
    show_tooltip: bool = True,
    background_color: Optional[str] = None,
    axis_color: str = "#333333",
    legend_bg: str = "#ffffff",
    legend_text: str = "#000000",
    legend_opacity: Optional[float] = None,
    legend_blur: Optional[float] = None,
    toolbar: str = "left",
    zoom_on_selection: bool = False,
    legend_position: str = "top-right",
    draggable_legend: bool = True,
    legend_counts: bool = True,
    enable_download: bool = False,
    font_size: int = 12,
    legend_font_size: int = 12,
    auto_fit: bool = False,
    range_padding: float = 0.15,
    xrange: Optional[Sequence[float]] = None,
    yrange: Optional[Sequence[float]] = None,
    filter_by: Any = None,
    point_labels: Optional[Sequence] = None,
    plot_id: Optional[str] = None,
    width: Optional[int] = 700,
    height: int = 500,
    backend: str = "regl",
    interactive: bool = True,
    theme: Optional[str] = None,
    progressive: bool = False,
    progressive_opts: Optional[dict] = None,
    _fast: bool = False,
    _detail_on_zoom: bool = False,
    _performance_mode: Optional[bool] = None,
    _color_categories=None,
    _pd_data: Any = None,
    _size_values: Any = _UNSET,
    _opacity_values: Any = _UNSET,
    _tooltip_cols: Any = _UNSET,
    _filter_df: Any = _UNSET,
    show: bool = True,
    **backend_kwargs: Any
)

Interactive WebGL scatterplot from single-cell / tabular data.

Parameters:

Name	Type	Description	Default
data	Any	AnnData, MuData, SpatialData, pandas DataFrame or numpy array. See :func:reglscatterpy._extract.extract.	None
basis	Optional[Union[str, int]]	Embedding selector for single-cell objects (an obsm key, e.g. "umap"/"X_umap"/"pca"; short names are auto-prefixed and matched case-insensitively). Preferred over x for embeddings. Pass a list (e.g. ["umap", "tsne"]) for a linked multi-panel grid, one panel per embedding. A list for basis AND color_by renders their cross-product (one panel per basis×colour), capped at 16 panels.	None
alpha	Optional[float]	Global point opacity (0–1), a scanpy alias for opacity applied to every panel. For PER-POINT opacity use opacity_by; alpha is a single number and does not create panels.	None
x	Optional[Union[str, int]]	For single-cell objects, x is an alias for basis (same meaning). For DataFrame / array inputs, x/y are the column names / indices of the coordinates. basis is not valid for tables/arrays.	None
y	Optional[Union[str, int]]	For single-cell objects, x is an alias for basis (same meaning). For DataFrame / array inputs, x/y are the column names / indices of the coordinates. basis is not valid for tables/arrays.	None
color_by	ColorSpec	Pass a single name to colour by one obs column / feature, or a list of names (genes and/or obs columns) to render a linked multi-panel grid — one panel per value (a raw per-point colour vector must be a numpy array / pandas Series, not a list of strings).	None
color_by	ColorSpec	obs column, a feature in var_names, or a raw vector ("modality:feature" for MuData).	None
group_by	ColorSpec	obs column, a feature in var_names, or a raw vector ("modality:feature" for MuData).	None
point_color	Optional[str]	A fixed hex colour overriding color_by.	None
pixel_ratio	Optional[float]	Device-pixel-ratio for the WebGL backing store (defaults to a crisp max(devicePixelRatio, 2) in-widget).	None
categorical_palette	str	"scanpy" (the default) picks scanpy's size-aware colours (vega_20 / zeileis_28 / godsnot_102), matching sc.pl.umap. Or a ColorBrewer qualitative name ("Set1", "Dark2" ...). Read the rendered map back with w.colors ({category: hex}).	'scanpy'
continuous_palette	str	A viridis-family name ("viridis", "magma" ...).	'viridis'
custom_colors	Optional[dict]	Explicit per-level mapping (dict) or ordered list of colours.	None
custom_palette	Optional[dict]	Explicit per-level mapping (dict) or ordered list of colours.	None
filter_by	Any	Numeric columns shown as interactive range-filter sliders. Give a dict / DataFrame, or just obs / column name(s) (a str or list of str) to pull them from adata.obs automatically, or True for every numeric obs column.	None
max_points	Any	Cap on points actually drawn (huge data stays interactive). "auto" (default) caps at 500k via a density-preserving subsample; None draws every point (ABC-Atlas style, smooth to ~4M); an int sets a custom cap. The plot is captioned "X of Y shown" and an automatic cap warns once.	'auto'
subsample	str	"density" (default, atlas-safe: keeps rare cells) or "random".	'density'
add_outline	bool	Draw a scanpy-style outline (a dark ring + a background-coloured gap) around every point, to make clusters pop. outline_width=(outline, gap) are fractions of the point radius and outline_color=(outline, gap) set the two colours (the gap defaults to the background). Rendered in a single shader pass — no extra points, no performance cost — but the ring is only visible with reasonably large points (use it for small/medium plots, not 20M-cell atlases where points are ~1px).	False
interactive	bool	True (the default) returns the live, kernel-linked widget — needed for w.selection / subset / annotate / linked compose and for reading interactions back into Python. Set interactive=False for a self-contained static snapshot (an iframe that renders anywhere, e.g. a server without the Jupyter widgets frontend, but with no kernel link).	True
theme	Optional[str]	Card theme for the live widget: "light" (default — a white figure card, matching the static export), "dark", or "auto"/"system" (follow the notebook: dark card only when the host theme is dark). None uses the global default from :func:reglscatterpy.set_theme. An explicit background_color / axis_color always overrides the theme. Has no effect on a static/exported plot (it stays portably light).	None
progressive	bool	For datasets beyond ~4M: show a density-sketch overview and re-render all cells inside the viewport as you zoom in (detail-on-zoom, no preprocessing). Always uses the live widget.	False
progressive_opts	Optional[dict]	Tuning dict for progressive: detail_max_points (max points per zoomed-in viewport; default max_points/500k) and overscan (fraction of margin fetched around the view; default 0.6).	None
backend	str	"regl" (default) renders the package's own widget; "jscatter" uses jupyter-scatter.	'regl'
show	bool	When True (default) returns the displayable widget.	True

Returns:

Type	Description
The widget object (displays inline in notebooks).

Notes

Argument names follow scanpy where possible — color, size, cmap, palette, components (1-based), ncols, layer, vmin/vmax, save — and the original names (color_by, point_size, continuous_palette, categorical_palette, dims …) keep working.

---

compose

compose(
    plots: Sequence, cols: Optional[int] = None, sync="auto"
)

Lay out scatterplot widgets in a linked grid.

Parameters:

Name	Type	Description	Default
plots	Sequence	A list of widgets returned by :func:scatterplot.	required
cols	Optional[int]	Number of columns (defaults to a near-square grid).	None
sync		"auto" (default) links pan/zoom, lasso selection and filters across panels only when they share the same data object — panels from different AnnData files stay independent (linking by cell index would be meaningless). True / False force linking on / off.	'auto'

Returns:

Type	Description
A ``GridBox`` (subclass) of the plots. When linked it exposes the group's
``selection`` / ``filtered`` / ``subset`` / ``composition`` / ``annotate`` /
``diff_expression`` / ``diff_expression_by`` (all proxied to a shared panel);
either way ``grid.panels`` gives the per-panel widgets (e.g.
``grid.panels[0].filtered``).

---

save_html

save_html(widget, path, title='reglscatterpy plot')

Write a plot (or a compose() grid) to a standalone, offline HTML file (like R's saveWidget).

---

save_notebook_html

save_notebook_html(
    notebook,
    out_path=None,
    execute=False,
    kernel_name="python3",
    timeout=600,
)

Convert a whole notebook to a self-contained HTML report.

Unlike plain jupyter nbconvert --to html (which leaves reglscatterpy plots blank), this bakes every plot in as an interactive, kernel-free figure, sharing one copy of the bundle across all plots.

Parameters:

Name	Type	Description	Default
notebook		Path to the .ipynb.	required
out_path		Destination .html (defaults to the notebook name with .html).	None
execute		Re-run the notebook before exporting. Default False — it uses the notebook's existing outputs, so a heavy notebook is not re-run. This works when the notebook was run with :func:record_html (recommended). Pass True to re-run a notebook that wasn't recorded.	False
kernel_name		Passed to the execute step when execute=True.	'python3'
timeout		Passed to the execute step when execute=True.	'python3'

Returns:

Type	Description
str	The path written.

---

record_html

record_html(enable=True)

Bake a static, offline copy of every plot into its cell output.

Call once near the top of a notebook::

import reglscatterpy as rs
rs.record_html()

From then on each scatterplot(...) displays a self-contained interactive plot that is stored in the notebook output — so reopening the notebook or running jupyter nbconvert --to html shows the plots with no re-execution. Recorded plots are one-way (no w.selection round-trip); call rs.record_html(False) to return to the live, kernel-linked widget.

---

set_theme

set_theme(value: str) -> str

Set the default theme for all subsequent plots. Returns the value set.

---

get_theme

get_theme() -> str

The current default theme ("light", "dark" or "auto").

---

extract

extract(
    data: Any,
    *,
    x: Optional[Union[str, int]] = None,
    y: Optional[Union[str, int]] = None,
    color_by: ColorSpec = None,
    group_by: ColorSpec = None,
    layer: Optional[str] = None,
    dims: Optional[tuple] = None,
    table: Optional[str] = None,
    use_raw: Optional[bool] = None
) -> PlotData

Normalise any supported input into :class:PlotData.

---

PlotData dataclass

Normalised, render-agnostic plot inputs.