Deprecate offset_position="data".

anntzer · anntzer · commit a82cd8cc447a · 2020-02-15T13:13:10.000+01:00
The `offset_position` property of collections is currently set to "data"
only for hexbin(), but one can do away with it by just setting the
correct offsetTrans instead -- which this PR does.  The advantage of
doing so is that the correct offsetTrans only needs to be implemented
once, whereas support for `offset_position` needs to be implemented for
each renderer class separately (including at the C-level for the Agg
backend).

Note that the *offset_position* argument to `draw_path_collection` is
not pending removal because its removal would require coordination with
third-party backends; the plan is to just always set it to "screen"
after the deprecation period.

If there is demand for it, _VectorTransform could be made a public API.
diff --git a/doc/api/next_api_changes/deprecations.rst b/doc/api/next_api_changes/deprecations.rst
@@ -211,3 +211,12 @@ The *clear_temp* parameter and attribute of `.FileMovieWriter` is
 deprecated.  In the future, files placed in a temporary directory (using
 ``frame_prefix=None``, the default) will be cleared; files placed elsewhere
 will not.
+
+``offset_position`` property of `.Collection`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The ``offset_position`` property of `.Collection` is deprecated.  In the future,
+`.Collection`\s will always behave as if ``offset_position`` is set to "screen"
+(the default).
+
+Support for passing ``offset_position="data"`` to the ``draw_path_collection``
+of all renderer classes is deprecated.
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -4762,8 +4762,7 @@ def reduce_C_function(C: array) -> float
                 edgecolors=edgecolors,
                 linewidths=linewidths,
                 offsets=offsets,
-                transOffset=mtransforms.IdentityTransform(),
-                offset_position="data"
+                transOffset=mtransforms._VectorTransform(self.transData),
                 )
 
         # Set normalizer if bins is 'log'
diff --git a/lib/matplotlib/backend_bases.py b/lib/matplotlib/backend_bases.py
@@ -202,8 +202,10 @@ def draw_path_collection(self, gc, master_transform, paths, all_transforms,
         *linestyles* and *antialiaseds*. *offsets* is a list of
         offsets to apply to each of the paths.  The offsets in
         *offsets* are first transformed by *offsetTrans* before being
-        applied.  *offset_position* may be either "screen" or "data"
-        depending on the space that the offsets are in.
+        applied.
+
+        *offset_position* may be either "screen" or "data" depending on the
+        space that the offsets are in; "data" is deprecated.
 
         This provides a fallback implementation of
         :meth:`draw_path_collection` that makes multiple calls to
@@ -381,6 +383,11 @@ def _iter_collection(self, gc, master_transform, all_transforms,
         Naa = len(antialiaseds)
         Nurls = len(urls)
 
+        if offset_position == "data":
+            cbook.warn_deprecated(
+                "3.3", message="Support for offset_position='data' is "
+                "deprecated since %(since)s and will be removed %(removal)s.")
+
         if (Nfacecolors == 0 and Nedgecolors == 0) or Npaths == 0:
             return
         if Noffsets:
diff --git a/lib/matplotlib/backends/backend_agg.py b/lib/matplotlib/backends/backend_agg.py
@@ -108,7 +108,9 @@ def _update_methods(self):
         self.draw_gouraud_triangles = self._renderer.draw_gouraud_triangles
         self.draw_image = self._renderer.draw_image
         self.draw_markers = self._renderer.draw_markers
-        self.draw_path_collection = self._renderer.draw_path_collection
+        # This is its own method for the duration of the deprecation of
+        # offset_position = "data".
+        # self.draw_path_collection = self._renderer.draw_path_collection
         self.draw_quad_mesh = self._renderer.draw_quad_mesh
         self.copy_from_bbox = self._renderer.copy_from_bbox
         self.get_content_extents = self._renderer.get_content_extents
@@ -152,6 +154,19 @@ def draw_path(self, gc, path, transform, rgbFace=None):
                 raise OverflowError("Exceeded cell block limit (set "
                                     "'agg.path.chunksize' rcparam)")
 
+    def draw_path_collection(self, gc, master_transform, paths, all_transforms,
+                             offsets, offsetTrans, facecolors, edgecolors,
+                             linewidths, linestyles, antialiaseds, urls,
+                             offset_position):
+        if offset_position == "data":
+            cbook.warn_deprecated(
+                "3.3", message="Support for offset_position='data' is "
+                "deprecated since %(since)s and will be removed %(removal)s.")
+        return self._renderer.draw_path_collection(
+            gc, master_transform, paths, all_transforms, offsets, offsetTrans,
+            facecolors, edgecolors, linewidths, linestyles, antialiaseds, urls,
+            offset_position)
+
     def draw_mathtext(self, gc, x, y, s, prop, angle):
         """Draw mathtext using :mod:`matplotlib.mathtext`."""
         ox, oy, width, height, descent, font_image, used_characters = \
diff --git a/lib/matplotlib/collections.py b/lib/matplotlib/collections.py
@@ -41,28 +41,28 @@ class Collection(artist.Artist, cm.ScalarMappable):
 
     Keyword arguments and default values:
 
-        * *edgecolors*: None
-        * *facecolors*: None
-        * *linewidths*: None
-        * *capstyle*:   None
-        * *joinstyle*:  None
-        * *antialiaseds*: None
-        * *offsets*: None
-        * *transOffset*: transforms.IdentityTransform()
-        * *offset_position*: 'screen' (default) or 'data'
-        * *norm*: None (optional for
-          :class:`matplotlib.cm.ScalarMappable`)
-        * *cmap*: None (optional for
-          :class:`matplotlib.cm.ScalarMappable`)
-        * *hatch*: None
-        * *zorder*: 1
+    * *edgecolors*: None
+    * *facecolors*: None
+    * *linewidths*: None
+    * *capstyle*:   None
+    * *joinstyle*:  None
+    * *antialiaseds*: None
+    * *offsets*: None
+    * *transOffset*: transforms.IdentityTransform()
+    * *offset_position* (deprecated): 'screen' (default) or 'data' (deprecated)
+    * *norm*: None (optional for
+      :class:`matplotlib.cm.ScalarMappable`)
+    * *cmap*: None (optional for
+      :class:`matplotlib.cm.ScalarMappable`)
+    * *hatch*: None
+    * *zorder*: 1
 
     *offsets* and *transOffset* are used to translate the patch after
     rendering (default no offsets).  If offset_position is 'screen'
     (default) the offset is applied after the master transform has
     been applied, that is, the offsets are in screen coordinates.  If
-    offset_position is 'data', the offset is applied before the master
-    transform, i.e., the offsets are in data coordinates.
+    offset_position is 'data' (deprecated), the offset is applied before the
+    master transform, i.e., the offsets are in data coordinates.
 
     If any of *edgecolors*, *facecolors*, *linewidths*, *antialiaseds*
     are None, they default to their :data:`matplotlib.rcParams` patch
@@ -87,6 +87,7 @@ class Collection(artist.Artist, cm.ScalarMappable):
     # subclass-by-subclass basis.
     _edge_default = False
 
+    @cbook._delete_parameter("3.1", "offset_position")
     def __init__(self,
                  edgecolors=None,
                  facecolors=None,
@@ -132,7 +133,9 @@ def __init__(self,
         self.set_pickradius(pickradius)
         self.set_urls(urls)
         self.set_hatch(hatch)
-        self.set_offset_position(offset_position)
+        self._offset_position = "screen"
+        if offset_position != "screen":
+            self.set_offset_position(offset_position)  # emit deprecation.
         self.set_zorder(zorder)
 
         if capstyle:
@@ -407,7 +410,7 @@ def contains(self, mouseevent):
                self._picker is not True  # the bool, not just nonzero or 1
             else self._pickradius)
 
-        if self.axes and self.get_offset_position() == "data":
+        if self.axes:
             self.axes._unstale_viewLim()
 
         transform, transOffset, offsets, paths = self._prepare_points()
@@ -416,7 +419,7 @@ def contains(self, mouseevent):
             mouseevent.x, mouseevent.y, pickradius,
             transform.frozen(), paths, self.get_transforms(),
             offsets, transOffset, pickradius <= 0,
-            self.get_offset_position())
+            self._offset_position)
 
         return len(ind) > 0, dict(ind=ind)
 
@@ -497,6 +500,7 @@ def get_offsets(self):
         else:
             return self._uniform_offsets
 
+    @cbook.deprecated("3.3")
     def set_offset_position(self, offset_position):
         """
         Set how offsets are applied.  If *offset_position* is 'screen'
@@ -514,6 +518,7 @@ def set_offset_position(self, offset_position):
         self._offset_position = offset_position
         self.stale = True
 
+    @cbook.deprecated("3.3")
     def get_offset_position(self):
         """
         Returns how offsets are applied for the collection.  If
diff --git a/lib/matplotlib/tests/test_backend_bases.py b/lib/matplotlib/tests/test_backend_bases.py
@@ -25,11 +25,12 @@ def check(master_transform, paths, all_transforms,
             master_transform, paths, all_transforms))
         gc = rb.new_gc()
         ids = [path_id for xo, yo, path_id, gc0, rgbFace in
-               rb._iter_collection(gc, master_transform, all_transforms,
-                                   range(len(raw_paths)), offsets,
-                                   transforms.IdentityTransform(),
-                                   facecolors, edgecolors, [], [], [False],
-                                   [], 'data')]
+               rb._iter_collection(
+                   gc, master_transform, all_transforms,
+                   range(len(raw_paths)), offsets,
+                   transforms._VectorTransform(master_transform),
+                   facecolors, edgecolors, [], [], [False],
+                   [], 'screen')]
         uses = rb._iter_collection_uses_per_path(
             paths, all_transforms, offsets, facecolors, edgecolors)
         if raw_paths:
diff --git a/lib/matplotlib/transforms.py b/lib/matplotlib/transforms.py
@@ -2645,6 +2645,28 @@ def get_matrix(self):
         return self._mtx
 
 
+class _VectorTransform(Affine2DBase):
+    """
+    A transform wrapper that ignores the offset component of a base transform.
+    """
+
+    def __init__(self, transform, **kwargs):
+        super().__init__(**kwargs)
+        self._base_transform = transform
+
+    def __str__(self):
+        return ("{}(\n"
+                    "{})"
+                .format(type(self).__name__,
+                        _indent_str(self._base_transform)))
+
+    def get_matrix(self):
+        if self._invalid:
+            self._mtx = self._base_transform.get_matrix().copy()
+            self._mtx[:2, -1] = 0
+        return self._mtx
+
+
 class TransformedPath(TransformNode):
     """
     A `TransformedPath` caches a non-affine transformed copy of the

Original file line number	Diff line number	Diff line change
`@@ -4762,8 +4762,7 @@ def reduce_C_function(C: array) -> float`
`4762`	`4762`	`edgecolors=edgecolors,`
`4763`	`4763`	`linewidths=linewidths,`
`4764`	`4764`	`offsets=offsets,`
`4765`		`- transOffset=mtransforms.IdentityTransform(),`
`4766`		`- offset_position="data"`
	`4765`	`+ transOffset=mtransforms._VectorTransform(self.transData),`
`4767`	`4766`	`)`
`4768`	`4767`
`4769`	`4768`	`# Set normalizer if bins is 'log'`