@jklymak , I don't think plt.vector needs to support arrays for the following two reasons

• plt.arrow does not
• plt.quiver exists for this purpose

Indeed plt.quiver provides this functionality, so why do we need vector? It's easy enough to pass a single x, y, u, v to quiver.

Indeed plt.quiver provides this functionality, so why do we need vector? It's easy enough to pass a single x, y, u, v to quiver.

I tried this out a bit and quiver is unfortunately not good substitute. Trying to replicate vector requires two extra kwargs and still doesn't replicate it. It also doesn't follow the color cycle

import matplotlib.pyplot as plt
import numpy as np

fig, ax = plt.subplots()

x = .5
y = .5
dx = 1
dy=10
ax.vector(dx, dy, x ,y, label='vector')
shift = .05
ax.quiver(x+shift,y+shift, dx, dy, angles='xy', scale=np.linalg.norm([dx,dy]), label='quiver')
plt.legend(loc=2)
plt.show()

gives

Ok then, there is probably a need for vector to accept more than one set of data

We've discussed this method in the dev call: https://hackmd.io/jd_7FjxNQ4y7XgNknvmvGQ#vector-API

Basic ideas:

• vector() is a replacement for arrow() and thus try to follow its API where possible.
• vector() is a method wrapper for creating a FancyArrowPatch.

Summary:

• we want vector(x, y, dx, dy, **kwargs); all kwargs are passed through to FancyArrowPatch. The non-kwarg parameters match arrow().
• vector should only accept and draw one arrow. Accepting more causes some issues either way. You get either return type instability or always have to return a list of FancyArrowPatches, which is awkward for the common case that you only draw one. Note also that PatchCollection does not work with FancyArrowPatch (and this is not easily fixable).
• There's been a hot discussion whether vector should follow the color cycle or not (and if so the line or the patch color cycle) (and if not should there be an additional `rcParams['vector.color'] to make it configurable.

Long story short, the color topic needs more investigation, we haven't reached a decision yet.

As a user, I would be very frustrated if plt.vector did not follow the color cycle. I feel like this is a sensible default and can always be overridden through the "color", "ec", and/or "fc" kwargs. I guess I am missing the counterargument.

There's been a hot discussion whether vector should follow the color cycle

I second @kmdalton that it should follow a color cycle. I find methods that don't to be extremely frustrating.

or not (and if so the line or the patch color cycle)
Long story short, the color topic needs more investigation, we haven't reached a decision yet.

Probably not best discussed here but I've always wished that there was one global color cycle. It's disconcerting that scatter, plot and hist each have their own color cycle. That aside, I would advocate for the plot color cycle.

If we are only making one arrow at a time, then I'm not convinced adding a new method is worth it just for the autolim and colorcycle behaviour. The colorcycle is dubious; I don't understand why we would want single arrows cycling their colors by default (groups of many arrows, sure). Similarly if I'm just adding one arrow at a time I typically have other data that I have plotted and that data set the limits for me.

If we are only making one arrow at a time, then I'm not convinced adding a new method is worth it just for the autolim and colorcycle behaviour. The colorcycle is dubious; I don't understand why we would want single arrows cycling their colors by default (groups of many arrows, sure). Similarly if I'm just adding one arrow at a time I typically have other data that I have plotted and that data set the limits for me.

Here's a plot I made last week using plt.arrow to demonstrate complex addition for my students.

I had to manually specify colors, limits, and otherwise override the broken default kwargs in plt.arrow. The whole process was frustrating and time-consuming. As you've noted, @jklymak , plt.arrow doesn't use FancyArrowPatch so the result isn't very aesthetically appealing either.
With the version of vector in this PR, you can already do this sort of plot in just a few lines with mostly default params.

import matplotlib.pyplot as plt
import numpy as np

F1, F2 = np.random.random(2) + 1j*np.random.random(2)

fig, ax = plt.subplots()

dx,dy,x,y= np.real(F1),np.imag(F1),0., 0.
ax.vector(dx, dy, x, y, label='F1')

dx,dy,x,y= np.real(F2),np.imag(F2),np.real(F1),np.imag(F1)
ax.vector(dx, dy, x, y, label='F2')

dx,dy,x,y= np.real(F1+F2),np.imag(F1+F2),0., 0.
ax.vector(dx, dy, x, y, label='F1+F2')

plt.xlabel(r"$\mathbb{Re}$", size=16)
plt.ylabel(r"$\mathbb{Im}$", size=16)
plt.grid(ls='-.')
plt.legend()
plt.show()

The relevant comparison is not plt.arrow which we all agree is broken, but plt.annotate.

I find your diagramming use case very specialized that you could easily write a little annotate wrapper for. I don't feel it justifies a whole new api element. But I'm just one vote. If others on the dev team think this is a good way to go, I'm not going to block it (unless it lacks unit support)

I'm still not clear what the right way forward is. Let's maybe take one step back from what vector should do

Basic ideas:

• vector() is a replacement for arrow() and thus try to follow its API where possible.
• vector() is a method wrapper for creating a FancyArrowPatch.

to what is needed:

1. Current users of arrow() need an alternative, that is reasonably simple to switch to.
2. It should be possible to create a single FancyArrowPatch arrow using a function.
3. There is a desire to be able to draw a set of arrows at once.

Discussion

RE 3: is out of scope here. Likely this wants a collection-type Artist, which we currently don't have for arrows (it was mentioned in the dev call that PatchCollection does not work with FancyArrowPatch, and that's not easily fixable). So let's save that for later.

RE 2: "To create an arrow, create an annotation without text." is too convoluted. Semantically, a data arrow and an annotation are different things (and they may have different behaviors, e.g. concerning color-cycling). We need a dedicated function. Whether that'd be vector or fancy_arrow.

RE 1: I'm pulling back a bit on the need to follow the arrow() API, as long as everything is still possible and it's reasonably simple to switch to the new API.

We've discussed this extensively again in the dev call today: https://hackmd.io/jd_7FjxNQ4y7XgNknvmvGQ#Arrow

Conculsions:

• Definitly not doing multiple here. This can be done with quiver in a reasonable way but definitly needs to be better documented.
• Change signature to def vector(self, start, *, delta=None, end=None)
  • require exactly 1 of delta or * end*
• should also add the start, end, delta setter/getters to FancyArrowPatch
• color cycle: yes and line cycle
• legend: yes
  we at least check and document what these do or do not get picked up by plt.legend(['a', 'b', 'c'])

Sorry to miss the discussion - however, what was the argument for vector, other than to replace arrow? For multiple arrows we have quiver; for single arrows we have annotate. Our API problems are usually caused by too many similar ways to achieve the same thing (see pcolor,pcolorfast, pcolormesh), so I still don't understand why we want to add something that is basically just annotate with no option for accompanying text.

for single arrows we have annotate.

As discussed above "To create an arrow, create an annotation without text." is awkward and not intuitive/discoverable. Moreover, they are conceptually different. Annotations are decorations, while we came to the conclusion that vector arrows should be considered as data. This implies that vector arrows take part in color cycling and can be added to the legend.

This will be the only place in the library where "data" is only allowed to be represented by one set of values per method call.

We don't have a suitable artist for multiple FancyArrowPatch (it doesn't work with PatchCollection because it needs special draw-time logic: an positioned in data space but it's shape must be drawn in screen space. 🤷 There's always the option to extend vector() later, but let's start small for now.

A common complaint about Matplotlib is that there are too many ways to do the same thing, and the proposal here is to add another way to do something already accessible via annotate. I think such an addition should have a compelling case, and hew to the existing API as closely as possible for the sake of consistency.

A common complaint about Matplotlib is that there are too many ways to do the same thing, and the proposal here is to add another way to do something already accessible via annotate

Um so I don't think they're two ways to do the same thing, I think they're two different things (annotating and encoding¹) that may generate the same visual element (an arrow). Kinda like how plot and vlines can both create vertical lines, or vlines+scatter = stem, or matshow is shifted imshow. And I think a lot of the confusion for users is also not so much in the multiple ways to do things, it's that we could be much clearer about which way matches their use case and therefore as part of the implementation has the defaults (eta: baked in semantic assumptions) they expect for their visualization task.

For example, this new vector method would get an entry in plot types and maybe we should add a new section there and move all the annotation type plotting methods - spans, fills, annotate-there.

proposal here is to add another way to do something already accessible via annotate.

@story645 has clearly laid out the arguments why vector is different from annotate and why we need it in addition. Please answer specific to these arguments if you think the are invalid.

hew to the existing API as closely as possible for the sake of consistency.

This is generally a good idea. We‘ve started from there in the API discussion rounds. However we realized that a) the current arrow API has deficits and b) changed behavior is desirable (e.g. color cycling). Because of b) vector is not a 100% compatible drop in replacement anyway. Then, taking a slightly larger step and improve the API can be reasonable. Overall, we can choose to prioritize either compatibility or improving the API and functionality. In our discussions there has been a consensus to go with le latter in this case.

a dev can block a PR if they really think it's wrong or misguided, and even that can be cleared by other devs, usually after a discussion.

To my understanding this discussion happened at the weekly meeting and a consensus was reached as presented in #22435 (comment). Is this not the case?

As a broader point: It's difficult to work on PRs like this if there isn't clarity about what constitutes a consensus. As an experienced contributor I find that I can stick with it, but were I newer then the uncertainty as to whether or not there has been a conclusion of if this feature will make it in in any form would be very difficult to deal with.

I've just pushed an update that I think matches the spec as laid out in #22435 (comment) with the small exception that I only added a delta setter/getter as set_position already gives the ability to change the start and end (although with naming of posA, and posB).

Happy to add tests once there is clarity that this is direction this PR should take.

With current implementation this example code:

import matplotlib.pyplot as plt
import numpy as np

F1, F2 = np.random.random(2) + 1j*np.random.random(2)

fig, ax = plt.subplots()

dx,dy,x,y= np.real(F1),np.imag(F1),0., 0.
ax.vector((x,y), delta=(dx, dy), label='F1')

dx,dy,x,y= np.real(F2),np.imag(F2),np.real(F1),np.imag(F1)
ax.vector((x,y), delta = (dx, dy), label='F2')

dx,dy,x,y= np.real(F1+F2),np.imag(F1+F2),0., 0.
ax.vector((x,y), delta=(dx, dy), label='F3')

plt.xlabel(r"$\mathbb{Re}$", size=16)
plt.ylabel(r"$\mathbb{Im}$", size=16)
plt.grid(ls='-.')
plt.legend()
plt.show()

gives:

To my understanding this discussion happened at the weekly meeting and a consensus was reached as presented in #22435 (comment). Is this not the case?

Historic note: We had at least two weekly meetings on the topic and positions have changed throughout and between the meetings (the topic is compicated and we have to balance different aspects). #22435 (comment) was the consensus of the last meeting. I don't remember exactly, but I think @jklymak has not been part of that meeting.

As a broader point: It's difficult to work on PRs like this if there isn't clarity about what constitutes a consensus. As an experienced contributor I find that I can stick with it, but were I newer then the uncertainty as to whether or not there has been a conclusion of if this feature will make it in in any form would be very difficult to deal with.

I definitively agree. This topic turned out to be more complex than we initially thought. We had a first decision on the API, which then was labelled "good first issue". Only after the PR came in and all details were mapped out, we partially realized that the initial decision wasn't quite right, which resulted in the following controversial discussion.
The general appoach of labelling "good first issue" was right because at that time, we thought it's all decided and the PR is only doing. We may be more careful with that label on anything that needs non-trivial API decisions in the future, even if we think they are set.

Please answer specific to these arguments if you think the are invalid.

Those arguments are based on "encoding" of the method for use case, which is completely subjective, and boil down to "I don't think of adding arrows that join data as annotating". I think we should guard against the API being expanded just to fit different mental models of how to add information to a plot. Expanding the API should add new non-niche actual functionality that is not otherwise available, or it should be significantly more convenient for a significant proportion of our users.

What's more, I don't agree that adding arrows, one at a time, is not annotating the plot, regardless of the intention. By this logic we should also allow plot_data_with_text(x, y, string) that plots a string at x, y to represent the data at that point. Is it a valid thing to do? Sure! Is it functionally any different than text(x, y, string) or annotate(string, (x,y))? No. You could add autolim behaviour, have the text color cycle through the color cycle, and make it show up in the legend. But it's still exactly the same thing, and I doubt we would allow it as new API.

What I am arguing against is having the same object put on the plot by different APIs. If you need the autolim behaviour (which is the most useful in my opinion), that could be added to annotate. I'm skeptical about the color cycling, but again, could be added to annotate, as could allowing the arrow patch be part of the legend. That leaves us with the slight awkwardness that annotate has a default argument of text, and the xy, and xytext not being great names for specifying where an arrow goes.

However, plotting one vector at a time and cycling through a colorcycle and adding the vectors to a plot is extremely niche. I have never seen a plot like that outside of a physics or math text book, and even then the vectors are typically the same color, and labeled in-situ rather in a legend. I don't mind, at all, Matplotlib being used for diagraming vectors this way, but I don't think it merits a new API when it can relatively easily be achieved via annotate.

If you cannot remember that annotate is a great way to draw individual arrows, adding a helper method to your helper library is surely a nice way to work around awkwardness in the API if you don't like the defaults and you do something often enough.

If you need the autolim behaviour (which is the most useful in my opinion), that could be added to annotate. I'm skeptical about the color cycling, but again, could be added to annotate, as could allowing the arrow patch be part of the legend. That leaves us with the slight awkwardness that annotate has a default argument of text, and the xy, and xytext not being great names for specifying where an arrow goes.

This is essentially a suggestion to grow the annotate implementation so that it supports the behavior expected of a visualization function instead of the proposal here of factoring this behavior into a well scoped vector function. Annotate is plenty complex because of the coordinate labeling logic and signature related to it, and the arrows mostly seem to be a by product of how matlab does it.

ETA: The point @timhoffm and I are trying to make, which you seem to support here, is that visualizing data as arrows has different requirements than drawing arrows for labeling; therefore one way to make this easier on the user (ETA: and maintainer) is to encode these different needs and expectations in different functions.

I think this need‘s a live discussion to resolve. Unfortunately, I currently cannot commit to a dev call. You may discuss this without me. I support @story645‘s position. (Or we’ll have to defer this a bit- 3.8 is still somewhat away.)

Again, I don't think this meets my criteria of what should be added to the API. If no one else is concerned about the cruft, you should feel free to move forward.

I apologize for not making it to the calls these days (a bit overwhelmed with work), but I generally with @jklymak's points:

If you need the autolim behaviour (which is the most useful in my opinion), that could be added to annotate. I'm skeptical about the color cycling, but again, could be added to annotate, as could allowing the arrow patch be part of the legend. [...] However, plotting one vector at a time and cycling through a colorcycle and adding the vectors to a plot is extremely niche.

I just performed the following poll to n=1 matplotlib user: "In matplotlib there are functions which auto-advance the color (e.g. plot()) and functions which don't (e.g. text()). There is currently a proposal to add a function for drawing arrows (which is currently possible but a bit complicated); do you expect that this function should auto-advance the color or not?" (This question is specifically formulated so that the pollee doesn't need to know advanced concepts like "color cycle" other than as "what plot() does", and also assumes that the pollee doesn't know about the already existing arrow() method -- I believe both assumptions are true for the vast majority of matplotlib users. I also don't think the formulation is particularly biased.)

I got the response "no the arrows should obviously all be black, why would you want them of various colors?" (followed by a rather salient "Usually if you have two line plots which are the same color it's impossible to tell which is which, whereas usually arrows are self-evident given where they point to and thus don't need different colors". Naturally I realize that there are exceptions, but that was the intuition of the user I polled.). Naturally that's n=1 but I could easily poll more people and would suggest that others do the same. Perhaps my intuition is completely off, but I would bet that the vast majority of users would respond "the arrows should all be black".

Note that my point is not really "we should not add vector()"; it's more "it should be more like annotate".

Edit: Current polling status: 3 users against color-cycling, 0 in favor of it.

As a side point, if we are going to make the "it can be added to legends" feature a selling point for vector(), then it should get a proper legend handler so that the legend entry is also an arrow; having the legend entry be a rectangle of solid color looks quite sloppy to me.

We didn't discuss it on the call so nothing missed. I'm currently too burnt out from stuff happening at home to intentionally add a contentious discussion.

if we are going to make the "it can be added to legends" feature a selling point for vector() then it should get a proper legend handler so that the legend entry is also an arrow

💯 and also I think this is another reason for factoring all this stuff into vector, b/c labeling-annotations generally serve the same "identify/add context to" role as legends and therefore probably don't need this logic either. (ETA: With the assumption that vector returns a FancyArrowPatch while annotate returns an text.Annotatation object, so the handler would I think be for FancyArrowPatch)

I think it should participate in the color cycle for the sake of consistency, but also a "help us design new API" banner at the top of the docs/as poll in the sidebar could be a fun little user engagement project.

it should participate in the color cycle for the sake of consistency

Text doesn't participate in the color cycle, so consistency isn't everything. Yes, I realize that arrows can be "data" rather than "annotations", but (in agreement @jklymak's point above, I believe) I believe that if you poll a few users and ask them a method that draws arrows should participate in the color cycle or not (which is essentially asking "is it more like text() or more like plot()", without getting into abstract concepts like data vs. annotations) they would say "no" (i.e. they see it as annotations).

Re: color cycle participation (semi-OT):

Aside from fundamental considerations, part of the argument for color-cycling was "it's easy to opt out by giving an explicit color; you cannot opt-in". Possibly we should make it easier to opt in; e.g. supporting color='next' or color='from_cycle' or similar. This needs careful consideration though, because cyclers are more complex than only color.

Looked it up and a major reason for opting into color_cycle is that's what arrow did #22390 (comment) and this is supposed to be the replacement 😓

but also @kmdalton and @ianhi what do you all think since you use these in your work?

ETA: on the legend patch - I think a FancyArrowPatchHandler can be created separate from this PR/as a follow up, and that the regular patch handling is good enough.

I'm a bit behind on this thread, but to answer @story645, I would prefer that vector

• Follow the color cycle
• Work with plt.legend

My use case often looks like what @ianhi shared in his last post.

It would be nice to see prior work - a published example of this type of plot and/or another library that does this.

There are countless examples in Bernhard Rupp's textbook, but I will not post them here because I do not have the copyright. Here are some fairly typical examples online. Most often authors use color coded arrows which are annotated with text. When I make these sorts of plots for lectures, I prefer to use legends to cut down on clutter. Frequently we use circles to represent a set of complex numbers with a particular amplitude and offset.

An example from Rupp is at https://www.ruppweb.org/Xray/tutorial/vectordiag.htm. Here is a journal article https://journals.iucr.org/d/issues/2003/11/00/ba5050/ba5050.pdf that makes liberal use of these. Note that these are called vector diagrams or Argand diagrams and they all, almost uniformly, have a bunch of labelling, arc circles etc. They also tend to key two or three colors with semantic meaning. They also never seem to have quantitative information on the axes.

Hello, friends! What are the action items here? Should we add this for discussion at the community meeting?

I think the last thing I considered blocking was #22435 (comment) and #22435 (comment) which imply that a live discussion is needed to finalize the api. After that there will need to be (1) tests, (2) a custom legend patch as a follow up PR

FWIW I think Kevin and I got a bit disheartened/overwhelmed by the level of back and forth. So in the mean time we have made and are using mpl-arrow. Though I still believe that long term this has a place in the core library (e.g. we had to use some private methods to get it work correctly).

n.b. I appreciate that it's difficult to get API "right" and thus understand the necessity of the back and forth, but nonetheless found it disheartening.