Adding a get_coordinates() method to Quadmesh collections #18472

greglucas · 2020-09-14T00:50:35Z

PR Summary

This returns the coordinates used to create the Quadmesh collection. These can be useful for knowing what vertices were used to generate the mesh returned from pcolormesh.

closes #18399

PR Checklist

Has pytest style unit tests (and pytest passes).
Is Flake 8 compliant (run flake8 on changed files to check).
New features are documented, with examples if plot related.
Documentation is sphinx and numpydoc compliant (the docs should build without error).
Conforms to Matplotlib style conventions (install flake8-docstrings and pydocstyle<4 and run flake8 --docstring-convention=all).
New features have an entry in doc/users/next_whats_new/ (follow instructions in README.rst there).
API changes documented in doc/api/next_api_changes/ (follow instructions in README.rst there).

jklymak

Seems simple enough

QuLogic · 2021-05-15T00:53:33Z

This is probably okay, but I'm unsure about the name. For pcolormesh, I'm not sure I consider the x/y coordinates the "data". I'm not sure we have anything else that works quite similarly, though, @timhoffm?

greglucas · 2021-05-15T01:25:51Z

See the linked issue for other ideas too. My initial idea was to call it get_coordinates(), but then saw Lines had get_xydata(), so then changed to that for consistency. I agree though it is a bit confusing and I think my preference would be get_coordinates(). I'll wait until others speak up with a preference one way or the other to change anything.

jklymak · 2021-05-15T15:23:41Z

Yeah, I didn't think about the name. get_xydata makes sense for Line2D but thats because x,y are the data whereas here x and y are the coordinates. These are called coordinates internally, so I'd suggest they are called this publicly as well. I guess the question is if we want to also allow set_coordinates?

Maybe need to change name...

greglucas · 2021-05-15T20:29:37Z

I really didn't want to go down the rabbit hole of adding set_coordinates() as well, and I think that may be even more confusing because the Quadmesh init() takes flattened coordinates as an argument:

matplotlib/lib/matplotlib/collections.py

Lines 1994 to 2001 in 6cf9219

    
           def __init__(self, meshWidth, meshHeight, coordinates, 
        
                        antialiased=True, shading='flat', **kwargs): 
        
               super().__init__(**kwargs) 
        
               self._meshWidth = meshWidth 
        
               self._meshHeight = meshHeight 
        
               # By converting to floats now, we can avoid that on every draw. 
        
               self._coordinates = np.asarray(coordinates, float).reshape( 
        
                   (meshHeight + 1, meshWidth + 1, 2))

which are promptly reshaped to (ny, nx, 2) to store internally, so which one of those versions do we support?

Digression...

Honestly, my real preference would be to deprecate the flattened version of Quadmesh altogether and only take the actual 3D mesh as input (or you could do xcoord, ycoord as well to make it more like pcolormesh). There really isn't a need to pass meshWidth and meshHeight into the constructor, you could easily just get that from the shape of the coordinates that were passed in. Now that I'm writing this out, I'm wondering if there would be buy-in from others on the idea of deprecating the flattened QuadMesh? I don't think too many people are creating QuadMesh's from the constructor, but rather it is usually a returned Class from pcolormesh and other higher-level plotting functions. So, a deprecation may not hit too many people actually and would hopefully benefit them by not forcing them to reshape/flatten.

timhoffm · 2021-05-15T22:42:09Z

I agree that flattened QuadMesh coordinates are awkward. It's the relation of 4 points that makes up a quadrilateral. Within the flattened data, we still imply a certain ordering in rows/columns. If we/the user gets that wrong, we'll end up with a total mess. Example (changing the order of points by reshape (4, 3) -> (3, 4)):

Show code

x = [0, 1, 2]
y = [2, 4, 6, 8]
z = np.arange(6).reshape(3, 2)
xx, yy = np.meshgrid(x, y)
fig, (ax1, ax2) = plt.subplots(1, 2)
ax1.pcolormesh(xx, yy, z, edgecolor='r')
ax2.pcolormesh(xx.reshape(3, 4), yy.reshape(3, 4), z.reshape(2, 3), edgecolor='r')

So, it seems better to make the relation explicit by a 2D shape.

There are multiple parts to this:

The new get_coordinates() (naming t.b.d.) here should directly return (ny, nx, 2).
QuadMesh.__init__ transition will take multiple steps. I'll can make a separate PR on this including the transition path from
__init__(self, meshWidth, meshHeight, coordinates, antialiased=True, shading='flat', **kwargs)
to
__init__(self, coordinates, *, antialiased=True, shading='flat', **kwargs)
set_array/ get_array() inherited from ScalarMappable
Multiple elements from Collection operate on the flattened data as well, e.g. edgecolors (get/set/kwarg) etc.

It will in particular be hard if not impossible to change everything in the fourth category. The 1D logic of ScalarMappable and Collection will always shine through in some places. However, that probably should not hold us up from changing 1., 2., and maybe 3. The alternative is having a consistently unusable API everywhere.

jklymak · 2021-05-16T19:30:08Z

lib/matplotlib/collections.py

+        Return the x and y vertices of the mesh.
+
+        The shape of the returned coordinates is
+        (*meshWidth* + 1, *meshHeight* + 1, 2).


Does the user know what meshWidth/Height are?

Maybe a bit more explanation?

Suggested change

(*meshWidth* + 1, *meshHeight* + 1, 2).

(*meshWidth* + 1, *meshHeight* + 1, 2), where *meshWidth* and *meshHeight* are the size of the

mesh, passed in when the Artist was initialized.

Hmm... Good point. Unfortunately, the initialized wording isn't entirely clear to me either because pcolormesh can auto-expand the coordinates for you (which is why I wanted this public in the first place). The docstring for QuadMesh gives some info on what meshWidth/meshHeight are, so maybe that is sufficient for now?
https://matplotlib.org/stable/api/collections_api.html#matplotlib.collections.QuadMesh

timhoffm · 2021-05-25T22:13:26Z

lib/matplotlib/collections.py

+        Return the x and y vertices of the mesh.
+
+        The shape of the returned coordinates is
+        (*meshWidth* + 1, *meshHeight* + 1, 2).


We're removing the names meshWidth/meshHeight from code and docs.

Some thing like this should do:

Suggested change

Return the x and y vertices of the mesh.

The shape of the returned coordinates is

(*meshWidth* + 1, *meshHeight* + 1, 2).

Return the vertex positions of the mesh as (M, N, 2) array.

M, N are the number of rows / columns in the mesh.

The last dimension specifies the components (x, y).

Sounds good. The only issue is that it may be confusing to use (M, N) here to refer to the vertices when other places use that notation to refer to the number of Polygons/Quads.

Yeah, technically this might be (M+1, N+1, 2) array. Would that be better?

More generally, I'm switch back and forward between the +/-1 interpretations, i.e. what is the canonical quantity for the number (M, N), the quadrilaterals or the vertices/coordinates?

Most of the previous documentation has had (M, N) as the number of quadrilaterals in the mesh, and to me that makes intuitive sense since that is the quantity we are most interested in. I'd vote for changing this to (M+1, N+1, 2) and explaining that here, but I also don't have a real strong preference.

I do - the data is MxN, the co-ordinates follow that. You could argue the coordinates are more important if they are twisting out some complicated shape, but 99.9% of the time this is tracking out a regular grid.

I changed the text to explicitly call out and distinguish the quads and vertices in the statement.

Return the vertices of the mesh as an (M+1, N+1, 2) array.

M, N are the number of quadrilaterals in the rows / columns of the mesh, corresponding to (M+1, N+1) vertices. The last dimension specifies the components (x, y).

This returns the coordinates used to create the Quadmesh collection.

timhoffm · 2021-05-26T22:45:37Z

Thanks @greglucas for keeping working on this and going through all the review cycles with us!

greglucas mentioned this pull request Sep 14, 2020

How to get Quadmesh coordinates #18399

Closed

jklymak previously approved these changes Apr 23, 2021

View reviewed changes

jklymak added the topic: collections and mappables label Apr 23, 2021

jklymak added this to the v3.5.0 milestone Apr 23, 2021

jklymak added the status: needs review label May 8, 2021

QuLogic added the status: needs comment/discussion needs consensus on next step label May 15, 2021

This was referenced May 15, 2021

Make QuadMesh arguments with defaults keyword_only #20237

Merged

Quadmesh.set_array validates dimensions #20215

Merged

greglucas force-pushed the quadmesh_get_xydata branch 2 times, most recently from b5c5b9b to fd9521e Compare May 16, 2021 02:13

jklymak approved these changes May 16, 2021

View reviewed changes

timhoffm reviewed May 25, 2021

View reviewed changes

greglucas force-pushed the quadmesh_get_xydata branch 2 times, most recently from 86c6e75 to f52bbc1 Compare May 26, 2021 02:23

greglucas changed the title ~~Adding a get_xydata() method to Quadmesh collections~~ Adding a get_coordinates() method to Quadmesh collections May 26, 2021

ENH: Adding a get_coordinates() method to Quadmesh

453abb1

This returns the coordinates used to create the Quadmesh collection.

greglucas force-pushed the quadmesh_get_xydata branch from f52bbc1 to 453abb1 Compare May 26, 2021 15:02

tacaswell approved these changes May 26, 2021

View reviewed changes

tacaswell merged commit 9091ba9 into matplotlib:master May 26, 2021

greglucas deleted the quadmesh_get_xydata branch May 26, 2021 17:25

greglucas removed status: needs comment/discussion needs consensus on next step status: needs review labels May 26, 2021

	(meshWidth + 1, meshHeight + 1, 2).
	(meshWidth + 1, meshHeight + 1, 2), where meshWidth and meshHeight are the size of the
	mesh, passed in when the Artist was initialized.

Uh oh!

Adding a get_coordinates() method to Quadmesh collections #18472

Adding a get_coordinates() method to Quadmesh collections #18472

Uh oh!

Conversation

greglucas commented Sep 14, 2020

PR Summary

PR Checklist

Uh oh!

jklymak left a comment

Choose a reason for hiding this comment

Uh oh!

QuLogic commented May 15, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

greglucas commented May 15, 2021

Uh oh!

jklymak commented May 15, 2021

Uh oh!

greglucas commented May 15, 2021

Digression...

Uh oh!

timhoffm commented May 15, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jklymak May 16, 2021

Choose a reason for hiding this comment

Uh oh!

greglucas May 16, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

timhoffm May 25, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

greglucas May 26, 2021

Choose a reason for hiding this comment

Uh oh!

timhoffm May 26, 2021

Choose a reason for hiding this comment

Uh oh!

greglucas May 26, 2021

Choose a reason for hiding this comment

Uh oh!

jklymak May 26, 2021

Choose a reason for hiding this comment

Uh oh!

greglucas May 26, 2021

Choose a reason for hiding this comment

Uh oh!

timhoffm commented May 26, 2021

Uh oh!

Uh oh!

QuLogic commented May 15, 2021 •

edited

Loading

timhoffm commented May 15, 2021 •

edited

Loading

greglucas May 16, 2021 •

edited

Loading

timhoffm May 25, 2021 •

edited

Loading