gsplot.scatter#

scatter(target, x, y, *, series=None, label=None, c=None, marker='o', s=1, alpha=1, config=None, props=None)#

Plot publication-ready points on one or more explicit Axes.

Parameters:

  • target (Axes | _AxesBase | Sequence[Axes | _AxesBase] | Mapping[Any, Axes | _AxesBase] | ndarray[tuple[int, ...], dtype[Any]]) – One Axes or a deterministic same-Figure collection of Axes.

  • x (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | Mapping[object, Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]]) – One finite one-dimensional pair broadcast to every target, or two exact-key mappings containing one pair per target.

  • y (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | Mapping[object, Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]]) – One finite one-dimensional pair broadcast to every target, or two exact-key mappings containing one pair per target.

  • series (Any) – Optional deterministic publication identity from 0 through 9.

  • label (Any) – Concise point controls. Scalars broadcast; exact-key mappings provide per-target colors and markers.

  • c (Any) – Concise point controls. Scalars broadcast; exact-key mappings provide per-target colors and markers.

  • marker (Any) – Concise point controls. Scalars broadcast; exact-key mappings provide per-target colors and markers.

  • s (Any) – Concise point controls. Scalars broadcast; exact-key mappings provide per-target colors and markers.

  • alpha (Any) – Concise point controls. Scalars broadcast; exact-key mappings provide per-target colors and markers.

  • config (Config | None) – Optional immutable configuration for omitted values.

  • props (Mapping[str, object] | None) – Optional closed advanced property mapping. It cannot duplicate a separately supplied direct field.

Returns:

Native Matplotlib collections in normalized target order.

Return type:

matplotlib.collections.PathCollection or tuple of PathCollection

Raises:

DataError – If targets, data, series, or style values fail atomic preflight.

Notes

The target Axes cycle supplies color when both series and c are omitted. Long Matplotlib spellings and the names in SCATTER_ADVANCED_OPTIONS remain accepted through 1.x.

Examples

>>> import gsplot as gs
>>> figure, ax = gs.subplots()
>>> points = gs.scatter(ax, [0, 1], [1, 2], series=1, label="sample")
>>> points.axes is ax
True
>>> figure.clear()