Improved documentation for quiver #28863

Kaustbh · 2024-09-22T19:42:06Z

PR summary

Issue #28209. This pull request improves the documentation for several key parameters in the quiver function of Matplotlib. The goal is to make it easier for users to understand how these parameters work and how they affect the behavior of quiver plots.

timhoffm

Please also fix the flake8 issues.

lib/matplotlib/quiver.py

timhoffm · 2024-09-27T20:22:06Z

@Kaustbh you've requested a review, but have not reacted to my previous comments. They still stand.

timhoffm

Not your fault, but I believe the scale and scale_units behavior and documentation is far from clear: How do they interact?

The behavior for both given is clear to me, just to be explained nicely.
If both are absent, we do the autoscaling.

But what happens when either one is not given.

If we want to touch the scale and scale_units docs, we need a better understanding. This would require digging into the code and trying out the different cases. I don't want to urge you into this. Fiddling this out would be very welcome, but I also understand if you just wanted to do a small doc PR and not start to reverse engineer our code.

timhoffm · 2024-09-29T21:48:48Z

lib/matplotlib/quiver.py

+    Number of data units per represented by one unit of arrow length on the plot.
+    For example, if the data represents velocity in meters per second (m/s), the
+    scale parameter determines how many meters per second correspond to one unit of
+    arrow length relative to the width of the plot.
+    Smaller scale parameter makes the arrow longer. Default is *None*.


I'm not an expert on the quiver logic. What I can say though from a quick look at the code is that

If scale is not not given, some autoscaling happens, so that we have "reasonable" arrow sizes. This should be mentioned. - I haven't determined exactly under which conditions (i.e. scale_units settings).

I also find the "units" framing and the physics example rather distracting. I think the relevant terms to connect here are "data values" U, V, (or "data length" if you will as sqrt(U2 +V2)), "scale_units" and scale. Basically this is done in the scale_units docs:

e.g. scale_units is 'inches', scale is 2.0, and (u, v) = (1, 0), then the vector will be 0.5 inches long.

could have more context, but basically, it feels that discussing the scale in the context of scale_units makes more sense.

timhoffm · 2024-09-29T21:50:03Z

lib/matplotlib/quiver.py

+    If the *scale* kwarg is *None*, the arrow length unit is automatically chosen based
+    on scale_units. Default is *None*.


This is a topic for the scale docs above.

Kaustbh · 2024-10-02T16:52:04Z

matplotlib/lib/matplotlib/quiver.py

Line 609 in 54d718e

def _make_verts(self, XY, U, V, angles):

The logic for scale and scale_units is implemented here, I will try to look into the code and fix the documentation.

Kaustbh · 2024-10-05T10:03:55Z

Hi, there are different formuals for calculating the scaling factor of arrow length based on the scale_units, should I include all the formulas for different scale_units in documentation?

timhoffm · 2024-10-07T10:38:49Z

You shouldn't necessarily document the formulas (as equation), but describe the logic; and for the logic, yes we need all cases - though you may group them together as e.g. "width" / "height" are analogous.

Kaustbh · 2024-10-10T11:33:38Z

scale : float, optional
    Scales the length of the arrow inversely.

    Number of data values represented by one unit of arrow length on the plot.
    For example, if the data represents velocity in meters per second (m/s), the
    scale parameter determines how many meters per second correspond to one unit of
    arrow length relative to the width of the plot.
    Smaller scale parameter makes the arrow longer.

    If *None*, a autoscaling algorithm is used, based on the average
    vector length and the number of vectors.
    The scaling factor is adjusted using the formula `*scale* = 1.8*amean*sn/self.span`, 
    where `amean` is the average arrow length, `sn` is the number of arrows, and `self.span`
    is the plots extent.
    The arrow length unit is given by the *scale_units* parameter.

scale_units : {'width', 'height', 'dots', 'inches', 'x', 'y', 'xy'}, optional
    If scale_units is None, the length of the arrows is determined directly by data values. 
    This means that the arrow length will correspond to the values in U and V without any 
    additional scaling based on figure dimensions or display units. 
    In this case, the arrow length is controlled purely by the scale parameter, and 
    no unit conversion is applied.

    - 'width' or 'height': The arrow length is scaled relative to the width or height
      of the axes. 
      For example, if *scale_units* is 'width' or 'height' and *scale* is 2.0, the
      vector will be half the width/height of the axes.
    
    - 'dots': The arrow length of the arrows is is measured in display dots (pixels).

    - 'inches': Arrow lengths are scaled based on the DPI (dots per inch) of the figure.
      This ensures that the arrows have a consistent physical size on the figure, in inches,
      regardless of data values or plot scaling.
      For example, if scale_units is 'inches', scale is 2.0, and `(u, v) = (1, 0)`, 
      then the vector will be 0.5 inches long.
    
    - 'x' or 'y': The arrow length is scaled relative to the x or y axis units.
      For example, if *scale_units* is 'x' and *scale* is 2.0, the vector will be 0.5
      x-axis units long.
    
    - 'xy': Arrow length is expressed in terms of the combined x and y data values.
      This is useful for creating vectors in the x-y plane where u and v have
      the same units as x and y. To plot vectors in the x-y plane with u and v having
      the same units as x and y, use ``angles='xy', scale_units='xy', scale=1``.

is it okay?

timhoffm · 2024-10-10T21:18:55Z

It would be simpler to review to put this into a commit, then I could annotate / suggest on individual parts.

If scale_units is None [...]

It's not immedately obvious from the code, but I looks like this is effectively the same as "width". Or am I missing something?

For example, if *scale_units* is 'width' or 'height' and *scale* is 2.0, the
vector will be half the width/height of the axes.

The vector depends on U, V data values which are not specified here. Does it help to specify the data length $l_{UV} = \sqrt{u^2 + v^2}$? I also suggest to use scale=1 if possible to simplify the calculation. Then you could say:

"For example, if scale_units is 'width' or 'height' and scale is 1, a data length $l_{UV}=0.5$ will result in an arrow length of width/height of the axes."

More generally, is this formula a good representation: $l_{arrow} = l_{UV} * \frac{\mathrm{scale\_unit}}{\mathrm{scale}}$?

In the above example we would get $l_{arrow} = 0.5 * \frac{\mathrm{Axes\ width}}{1} = 0.5 \mathrm{Axes\ width}$

The scaling factor is adjusted using the formula `*scale* = 1.8*amean*sn/self.span`, 
where `amean` is the average arrow length, `sn` is the number of arrows, and `self.span`
is the plots extent.

I suggest not to go into the details of the algorithm. The description is not accurate enough, e.g. sn is the number of arrows must be sn is the number of arrows in X-direction, but at least 10. But these details do not help the user. It should be sufficient to state that the arrows are autoscaled to a reasonable size. Knowledge of the algorithm does not make a difference, because you cannot tune any of the parameters. If the autoscaling does not yield a reasonable result, the user has to manually define a scale.

One important aspect to mention is that setting scale_units without setting scale does not have any effect because the scale units only differ by a constant factor and that is rescaled through autoscaling.

Kaustbh · 2024-10-12T18:47:37Z

Hi, is the length we are getting from length = a * (widthu_per_lenu / (self.scale * self.width)) is in pixels?

x_pos = 0
y_pos = 0
u = 1
v = 1
 
fig, ax = plt.subplots()
ax.quiver(x_pos, y_pos, u, v,
         scale = 5,scale_units='width')
 

ax.set_xlim(-5, 5)
ax.set_ylim(-7, 10)

plt.grid(True)
plt.show()

for the above code, I am getting the length as [37.71236166], and the plot I am getting is this,

the arrow in the plot has coordinates (0,0) -> (2,4.5), so how the length of arrow which we got is equal to the arrow length from plot?
am I doing something wrong? please guide me.

timhoffm · 2024-10-14T08:31:22Z

I believe this is in arrow-width units, i.e. the arrow is 37.7 times longer than wide, but t.b.c. i.e. try modifying quiver(..., width=...) and check that this scales length.

Kaustbh · 2024-10-18T08:13:11Z

Hi after reading the code and trying the different inputs I have made a commit, in this I have added a generalized formula for the different units, I also got that when scale_units is none it behaves like 'width'.

and for the case of 'inches' in the given example, I do not understand how the 0.5 inches are shown on the plot.

I'm sorry if there is any mistake in the :math: renderer. I was not able to render the documentation.

Please tell me if it is fine or need more changes.

timhoffm · 2024-10-18T10:01:36Z

lib/matplotlib/quiver.py

+scale_units : {'width', 'height', 'dots', 'inches', 'x', 'y', 'xy'}, optional
+    If scale_units is None, the length of the arrows is effectively same as when it
+    is set to 'width', meaning the arrow length will be relative to the width of
+    the axes.


From a user perspective, this is effectively

Suggested change

scale_units : {'width', 'height', 'dots', 'inches', 'x', 'y', 'xy'}, optional

If scale_units is None, the length of the arrows is effectivel 8000 y same as when it

is set to 'width', meaning the arrow length will be relative to the width of

the axes.

scale_units : {'width', 'height', 'dots', 'inches', 'x', 'y', 'xy'}, default: 'width'

(even though it's not obvious from the implementation, which could be a follow-up cleanup action)

timhoffm · 2024-10-18T10:03:55Z

lib/matplotlib/quiver.py

+    - 'width' or 'height': The arrow length is scaled relative to the width or height
+      of the axes. In this case, the arrow length will be relative to the width or
+      height of the axes.


Suggested change

- 'width' or 'height': The arrow length is scaled relative to the width or height

of the axes. In this case, the arrow length will be relative to the width or

height of the axes.

- 'width' or 'height': The arrow length is scaled relative to the width or height

of the Axes.

Both sentences say the same thing. Note that we capitalize "Axes" when refering to the logical construct and not just a plural of axis.

timhoffm · 2024-10-18T10:09:36Z

lib/matplotlib/quiver.py

+      "For example, if *scale_units* is 'width' or 'height' and *scale* is 1.0, will
+      result in an arrow length of width/height of the axes."


Suggested change

"For example, if *scale_units* is 'width' or 'height' and *scale* is 1.0, will

result in an arrow length of width/height of the axes."

"For example, ``scale_units='width', scale=1.0``, will result in an arrow length

of width of the Axes."

It's sufficient to choose one of width/height for an example. Also, I think stating all relevant parameters
as one code expression is slightly more readable.

lib/matplotlib/quiver.py

Kaustbh · 2024-10-18T17:22:50Z

is it correct for the case of 'x' or 'y'? , I have modified it like this,

- 'x' or 'y': The arrow length is scaled relative to the x or y axis units.
       For example, if *scale_units* is 'x' and *scale* is 1.0, the vector will be
       x-axis units long.
       The generalize formula is as follows:
            length in x direction = $\frac{u}{\mathrm{scale}}
            length in y direction = $\frac{v}{\mathrm{scale}}

timhoffm · 2024-10-21T16:15:54Z

is it correct for the case of 'x' or 'y'?

I'm unclear what "it" is. Anyway, #28863 (comment) cover 'x' and 'y' cases as well.

timhoffm

Minor formatting improvements. It's ready to go after addressing those.

lib/matplotlib/quiver.py

timhoffm · 2024-10-24T13:16:27Z

lib/matplotlib/quiver.py

-    units. To plot vectors in the x-y plane, with u and v having
-    the same units as x and y, use
-    ``angles='xy', scale_units='xy', scale=1``.
+    Note: setting scale_units without setting scale does not have any effect because


Suggested change

Note: setting scale_units without setting scale does not have any effect because

Note: Setting *scale_units* without setting scale does not have any effect because

lib/matplotlib/quiver.py

Kaustbh · 2024-10-25T18:33:46Z

Hi, are there any changes to be made?

timhoffm · 2024-10-26T00:26:40Z

Hi, are there any changes to be made?

Yes, but they were due to currently brittle handling of missing code references. I've made the relevant changes, so that you don't have to bother with this unrelated problem.

doc/missing-references.json

8000 timhoffm reviewed Sep 24, 2024

View reviewed changes

lib/matplotlib/quiver.py Outdated Show resolved Hide resolved

lib/matplotlib/quiver.py Outdated Show resolved Hide resolved

lib/matplotlib/quiver.py Outdated Show resolved Hide resolved

lib/matplotlib/quiver.py Outdated Show resolved Hide resolved

Kaustbh requested a review from timhoffm September 27, 2024 18:42

QuLogic removed the request for review from timhoffm September 28, 2024 00:05

Kaustbh force-pushed the issue1 branch from f851a7a to d902ee3 Compare September 28, 2024 06:02

Kaustbh requested a review from timhoffm September 28, 2024 06:03

timhoffm reviewed Sep 29, 2024

View reviewed changes

melissawm added the Documentation: API files in lib/ and doc/api label Oct 15, 2024

Kaustbh force-pushed the issue1 branch from d902ee3 to d3a5753 Compare October 18, 2024 07:53

github-actions bot removed the Documentation: API files in lib/ and doc/api label Oct 18, 2024

timhoffm reviewed Oct 18, 2024

View reviewed changes

Kaustbh force-pushed the issue1 branch from d3a5753 to cba81f9 Compare October 23, 2024 03:38

timhoffm reviewed Oct 24, 2024

View reviewed changes

improved documentation of quvier plot

804781d

Kaustbh force-pushed the issue1 branch from cba81f9 to 804781d Compare October 24, 2024 17:39

timhoffm reviewed Oct 25, 2024

View reviewed changes

lib/matplotlib/quiver.py Outdated Show resolved Hide resolved

lib/matplotlib/quiver.py Outdated Show resolved Hide resolved

Apply suggestions from code review

db0084e

timhoffm reviewed Oct 25, 2024

View reviewed changes

lib/matplotlib/quiver.py Outdated Show resolved Hide resolved

Fix typo

cf045b2

Fix missing references

479a41b

github-actions bot added the status: needs rebase label Oct 26, 2024

Merge branch 'main' into issue1

ebd11fb

github-actions bot removed the status: needs rebase label Oct 26, 2024

timhoffm reviewed Oct 26, 2024

View reviewed changes

doc/missing-references.json Outdated Show resolved Hide resolved

Update doc/missing-references.json

e3eba6c

timhoffm approved these changes Oct 26, 2024

View reviewed changes

timhoffm merged commit 64d984a into matplotlib:main Oct 26, 2024
41 of 42 checks passed

timhoffm added this to the v3.10.0 milestone Oct 26, 2024

QuLogic added the Documentation label Oct 26, 2024

timhoffm mentioned this pull request Oct 28, 2024

quiver angles parameter docstring nitpick #28840

Closed

1 task

		If the scale kwarg is None, the arrow length unit is automatically chosen based
		on scale_units. Default is None.

		"For example, if scale_units is 'width' or 'height' and scale is 1.0, will
		result in an arrow length of width/height of the axes."

	Note: setting scale_units without setting scale does not have any effect because
	Note: Setting scale_units without setting scale does not have any effect because

Uh oh!

Improved documentation for quiver #28863

Improved documentation for quiver #28863

Uh oh!

Conversation

PR summary

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!