matplotlib · chahak13 · Feb 19, 2023 · Feb 26, 2023 · Feb 26, 2023 · Mar 14, 2023
diff --git a/ci/mypy-stubtest-allowlist.txt b/ci/mypy-stubtest-allowlist.txt
@@ -105,6 +105,10 @@ matplotlib.collections.Collection.set_linewidths
 matplotlib.collections.Collection.set_ls
 matplotlib.collections.Collection.set_lw
 matplotlib.collections.Collection.set_transOffset
+matplotlib.collections._CollectionWithSizes.get_markersize
+matplotlib.collections._CollectionWithSizes.get_s
+matplotlib.collections._CollectionWithSizes.set_markersize
+matplotlib.collections._CollectionWithSizes.set_s
 matplotlib.lines.Line2D.get_aa
 matplotlib.lines.Line2D.get_c
 matplotlib.lines.Line2D.get_ds

diff --git a/doc/users/next_whats_new/scatter_markersize.rst b/doc/users/next_whats_new/scatter_markersize.rst
@@ -0,0 +1,5 @@
+``markersize`` and ``markerscale`` added to scatter
+---------------------------------------------------
+``markersize`` is new alias for ``s`` in scatter that can be used to set the size of
+the markers. The marker sizes can now also be set using a linear scale using the
+``markerscale`` parameter.
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -4476,7 +4476,7 @@ def invalid_shape_exception(csize, xsize):
     @_docstring.interpd
     def scatter(self, x, y, s=None, c=None, marker=None, cmap=None, norm=None,
                 vmin=None, vmax=None, alpha=None, linewidths=None, *,
-                edgecolors=None, plotnonfinite=False, **kwargs):
+                edgecolors=None, plotnonfinite=False, markerscale=2, **kwargs):
         """
         A scatter plot of *y* vs. *x* with varying marker size and/or color.
 
@@ -4568,6 +4568,12 @@ def scatter(self, x, y, s=None, c=None, marker=None, cmap=None, norm=None,
             or ``nan``). If ``True`` the points are drawn with the *bad*
             colormap color (see `.Colormap.set_bad`).
 
+        markerscale : 1 or 2, optional, default: 2
+            Scaling factor used to set the size as points or points**2.
+            Default value is set as 2 to set the size values as points**2.
+
+            .. versionadded:: 3.9
+
         Returns
         -------
         `~matplotlib.collections.PathCollection`
@@ -4607,9 +4613,17 @@ def scatter(self, x, y, s=None, c=None, marker=None, cmap=None, norm=None,
         if x.size != y.size:
             raise ValueError("x and y must be the same size")
 
+        if s is not None and 'markersize' in kwargs:
+            raise ValueError(
+                "Only one of `s` or `markersize` should be passed. "
+                "Please refer to the docs for more details about usage.")
+
         if s is None:
-            s = (20 if mpl.rcParams['_internal.classic_mode'] else
-                 mpl.rcParams['lines.markersize'] ** 2.0)
+            if 'markersize' not in kwargs:
+                s = (20 if mpl.rcParams['_internal.classic_mode'] else
+                        mpl.rcParams['lines.markersize'] ** 2.0)
+            else:
+                s = kwargs.pop('markersize')
         s = np.ma.ravel(s)
         if (len(s) not in (1, x.size) or
                 (not np.issubdtype(s.dtype, np.floating) and
@@ -4696,6 +4710,7 @@ def scatter(self, x, y, s=None, c=None, marker=None, cmap=None, norm=None,
 
         collection = mcoll.PathCollection(
             (path,), scales,
+            markerscale=markerscale,
             facecolors=colors,
             edgecolors=edgecolors,
             linewidths=linewidths,

diff --git a/lib/matplotlib/axes/_axes.pyi b/lib/matplotlib/axes/_axes.pyi
@@ -411,6 +411,7 @@ class Axes(_AxesBase):
         *,
         edgecolors: Literal["face", "none"] | ColorType | Sequence[ColorType] | None = ...,
         plotnonfinite: bool = ...,
+        markerscale: int = ...,
         data=...,
         **kwargs
     ) -> PathCollection: ...

diff --git a/lib/matplotlib/collections.py b/lib/matplotlib/collections.py
@@ -930,6 +930,9 @@ def update_from(self, other):
         self.stale = True
 
 
+@_api.define_aliases({
+    "sizes": ["s", "markersize"]
+})
 class _CollectionWithSizes(Collection):
     """
     Base class for collections that have an array of sizes.
@@ -938,16 +941,35 @@ class _CollectionWithSizes(Collection):
 
     def get_sizes(self):
         """
-        Return the sizes ('areas') of the elements in the collection.
+        Return the sizes of the elements in the collection.
+
+        The sizes of the elements in the collection will be returned in
+        the last set scale of the markers, i.e. if the markerscale was
+        set to 1 then the sizes are set in points and if markerscale was
+        set to 2 then the sizes returned are such that the marker size is
+        in points**2.
 
         Returns
         -------
         array
-            The 'area' of each element.
+            The 'size' of each element.
         """
         return self._sizes
 
-    def set_sizes(self, sizes, dpi=72.0):
+    def get_markerscale(self):
+        """
+        Return the scale used for marker sizing.
+
+        .. versionadded:: 3.9
+
+        Returns
+        -------
+        int
+            The scale used to set the marker sizes.
+        """
+        return self._markerscale
+
+    def set_sizes(self, sizes, dpi=72.0, markerscale=2):
         """
         Set the sizes of each member of the collection.
 
@@ -958,22 +980,28 @@ def set_sizes(self, sizes, dpi=72.0):
             value is the 'area' of the element.
         dpi : float, default: 72
             The dpi of the canvas.
+        markerscale : 1 or 2, default: 2
+            Scaling factor used to set the size as points (1) or points**2 (2).
+
+            .. versionadded:: 3.9
         """
+        self._markerscale = markerscale
         if sizes is None:
             self._sizes = np.array([])
             self._transforms = np.empty((0, 3, 3))
         else:
             self._sizes = np.asarray(sizes)
             self._transforms = np.zeros((len(self._sizes), 3, 3))
-            scale = np.sqrt(self._sizes) * dpi / 72.0 * self._factor
+            s = np.sqrt(self._sizes) if self._markerscale == 2 else self._sizes
+            scale = s * dpi / 72.0 * self._factor
             self._transforms[:, 0, 0] = scale
             self._transforms[:, 1, 1] = scale
             self._transforms[:, 2, 2] = 1.0
         self.stale = True
 
     @artist.allow_rasterization
     def draw(self, renderer):
-        self.set_sizes(self._sizes, self.figure.dpi)
+        self.set_sizes(self._sizes, self.figure.dpi, self._markerscale)
         super().draw(renderer)
 
 
@@ -982,7 +1010,7 @@ class PathCollection(_CollectionWithSizes):
     A collection of `~.path.Path`\s, as created by e.g. `~.Axes.scatter`.
     """
 
-    def __init__(self, paths, sizes=None, **kwargs):
+    def __init__(self, paths, sizes=None, markerscale=2, **kwargs):
         """
         Parameters
         ----------
@@ -992,13 +1020,18 @@ def __init__(self, paths, sizes=None, **kwargs):
             The factor by which to scale each drawn `~.path.Path`. One unit
             squared in the Path's data space is scaled to be ``sizes**2``
             points when rendered.
+        markerscale : 1 or 2, default: 2
+            Scaling factor used to set the size as points (1) or points**2 (2).
+
+            .. versionadded:: 3.9
+
         **kwargs
             Forwarded to `.Collection`.
         """
 
         super().__init__(**kwargs)
         self.set_paths(paths)
-        self.set_sizes(sizes)
+        self.set_sizes(sizes, markerscale=markerscale)
         self.stale = True
 
     def set_paths(self, paths):

diff --git a/lib/matplotlib/collections.pyi b/lib/matplotlib/collections.pyi
@@ -70,11 +70,18 @@ class Collection(artist.Artist, cm.ScalarMappable):
 
 class _CollectionWithSizes(Collection):
     def get_sizes(self) -> np.ndarray: ...
-    def set_sizes(self, sizes: ArrayLike | None, dpi: float = ...) -> None: ...
+    def set_sizes(
+            self, sizes: ArrayLike | None, dpi: float = ..., markerscale: int = ...
+    ) -> None: ...
+    def get_markerscale(self) -> int: ...
 
 class PathCollection(_CollectionWithSizes):
     def __init__(
-        self, paths: Sequence[Path], sizes: ArrayLike | None = ..., **kwargs
+            self,
+            paths: Sequence[Path],
+            sizes: ArrayLike | None = ...,
+            markerscale: int = ...,
+            **kwargs
     ) -> None: ...
     def set_paths(self, paths: Sequence[Path]) -> None: ...
     def get_paths(self) -> Sequence[Path]: ...

diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -3587,6 +3587,7 @@ def scatter(
     *,
     edgecolors: Literal["face", "none"] | ColorType | Sequence[ColorType] | None = None,
     plotnonfinite: bool = False,
+    markerscale: int = 2,
     data=None,
     **kwargs,
 ) -> PathCollection:
@@ -3604,6 +3605,7 @@ def scatter(
         linewidths=linewidths,
         edgecolors=edgecolors,
         plotnonfinite=plotnonfinite,
+        markerscale=markerscale,
         **({"data": data} if data is not None else {}),
         **kwargs,
     )

diff --git a/lib/matplotlib/tests/test_collections.py b/lib/matplotlib/tests/test_collections.py
@@ -1216,3 +1216,25 @@ def test_striped_lines(fig_test, fig_ref, gapcolor):
     for x, gcol, ls in zip(x, itertools.cycle(gapcolor),
                            itertools.cycle(linestyles)):
         ax_ref.axvline(x, 0, 1, linestyle=ls, gapcolor=gcol, alpha=0.5)
+
+
+@check_figures_equal(extensions=["png"])
+def test_markerscale(fig_test, fig_ref):
+    ax_test = fig_test.add_subplot()
+    ax_ref = fig_ref.add_subplot()
+
+    x = np.arange(1, 6)**2
+
+    ax_test.scatter(x, x, s=x, markerscale=1)
+    ax_ref.scatter(x, x, s=x**2, markerscale=2)
+
+
+@check_figures_equal(extensions=["png"])
+def test_markersize_alias(fig_test, fig_ref):
+    ax_test = fig_test.add_subplot()
+    ax_ref = fig_ref.add_subplot()
+
+    x = np.arange(1, 6)**2
+
+    ax_test.scatter(x, x, s=x)
+    ax_ref.scatter(x, x, markersize=x)
diff --git a/lib/mpl_toolkits/mplot3d/art3d.py b/lib/mpl_toolkits/mplot3d/art3d.py
@@ -688,8 +688,8 @@ def set_3d_properties(self, zs, zdir):
         self._vzs = None
         self.stale = True
 
-    def set_sizes(self, sizes, dpi=72.0):
-        super().set_sizes(sizes, dpi)
+    def set_sizes(self, sizes, dpi=72.0, markerscale=2):
+        super().set_sizes(sizes, dpi=dpi, markerscale=markerscale)
         if not self._in_draw:
             self._sizes3d = sizes