|
87 | 87 | angles : {'uv', 'xy'} or array-like, default: 'uv' |
88 | 88 | Method for determining the angle of the arrows. |
89 | 89 |
|
90 | | - - 'uv': Arrow direction in screen coordinates. Use this if the arrows |
91 | | - symbolize a quantity that is not based on *X*, *Y* data coordinates. |
| 90 | + - 'uv': Arrow directions are based on |
| 91 | + :ref:`display coordinates <coordinate-systems>`; i.e. a 45° angle will |
| 92 | + always show up as diagonal on the screen, irrespective of figure or Axes |
| 93 | + aspect ratio or Axes data ranges. This is useful when the arrows represent |
| 94 | + a quantity whose direction is not tied to the x and y data coordinates. |
92 | 95 |
|
93 | 96 | If *U* == *V* the orientation of the arrow on the plot is 45 degrees |
94 | 97 | counter-clockwise from the horizontal axis (positive to the right). |
95 | 98 |
|
96 | 99 | - 'xy': Arrow direction in data coordinates, i.e. the arrows point from |
97 | | - (x, y) to (x+u, y+v). Use this e.g. for plotting a gradient field. |
| 100 | + (x, y) to (x+u, y+v). This is ideal for vector fields or gradient plots |
| 101 | + where the arrows should directly represent movements or gradients in the |
| 102 | + x and y directions. |
98 | 103 |
|
99 | 104 | - Arbitrary angles may be specified explicitly as an array of values |
100 | 105 | in degrees, counter-clockwise from the horizontal axis. |
101 | 106 |
|
102 | 107 | In this case *U*, *V* is only used to determine the length of the |
103 | 108 | arrows. |
104 | 109 |
|
| 110 | + For example, ``angles=[30, 60, 90]`` will orient the arrows at 30, 60, and 90 |
| 111 | + degrees respectively, regardless of the *U* and *V* components. |
| 112 | +
|
105 | 113 | Note: inverting a data axis will correspondingly invert the |
106 | 114 | arrows only with ``angles='xy'``. |
107 | 115 |
|
|
114 | 122 | scale : float, optional |
115 | 123 | Scales the length of the arrow inversely. |
116 | 124 |
|
117 | | - Number of data units per arrow length unit, e.g., m/s per plot width; a |
118 | | - smaller scale parameter makes the arrow longer. Default is *None*. |
| 125 | + Number of data values represented by one unit of arrow length on the plot. |
| 126 | + For example, if the data represents velocity in meters per second (m/s), the |
| 127 | + scale parameter determines how many meters per second correspond to one unit of |
| 128 | + arrow length relative to the width of the plot. |
| 129 | + Smaller scale parameter makes the arrow longer. |
| 130 | +
|
| 131 | + By default, an autoscaling algorithm is used to scale the arrow length to a |
| 132 | + reasonable size, which is based on the average vector length and the number of |
| 133 | + vectors. |
| 134 | +
|
| 135 | + The arrow length unit is given by the *scale_units* parameter. |
| 136 | +
|
| 137 | +scale_units : {'width', 'height', 'dots', 'inches', 'x', 'y', 'xy'}, default: 'width' |
| 138 | +
|
| 139 | + The physical image unit, which is used for rendering the scaled arrow data *U*, *V*. |
| 140 | +
|
| 141 | + The rendered arrow length is given by |
| 142 | +
|
| 143 | + length in x direction = $\\frac{u}{\\mathrm{scale}} \\mathrm{scale_unit}$ |
| 144 | +
|
| 145 | + length in y direction = $\\frac{v}{\\mathrm{scale}} \\mathrm{scale_unit}$ |
| 146 | +
|
| 147 | + For example, ``(u, v) = (0.5, 0)`` with ``scale=10, scale_unit="width"`` results |
| 148 | + in a horizontal arrow with a length of *0.5 / 10 * "width"*, i.e. 0.05 times the |
| 149 | + Axes width. |
| 150 | +
|
| 151 | + Supported values are: |
| 152 | +
|
| 153 | + - 'width' or 'height': The arrow length is scaled relative to the width or height |
| 154 | + of the Axes. |
| 155 | + For example, ``scale_units='width', scale=1.0``, will result in an arrow length |
| 156 | + of width of the Axes. |
119 | 157 |
|
120 | | - If *None*, a simple autoscaling algorithm is used, based on the average |
121 | | - vector length and the number of vectors. The arrow length unit is given by |
122 | | - the *scale_units* parameter. |
| 158 | + - 'dots': The arrow length of the arrows is in measured in display dots (pixels). |
123 | 159 |
|
124 | | -scale_units : {'width', 'height', 'dots', 'inches', 'x', 'y', 'xy'}, optional |
125 | | - If the *scale* kwarg is *None*, the arrow length unit. Default is *None*. |
| 160 | + - 'inches': Arrow lengths are scaled based on the DPI (dots per inch) of the figure. |
| 161 | + This ensures that the arrows have a consistent physical size on the figure, |
| 162 | + in inches, regardless of data values or plot scaling. |
| 163 | + For example, ``(u, v) = (1, 0)`` with ``scale_units='inches', scale=2`` results |
| 164 | + in a 0.5 inch-long arrow. |
126 | 165 |
|
127 | | - e.g. *scale_units* is 'inches', *scale* is 2.0, and ``(u, v) = (1, 0)``, |
128 | | - then the vector will be 0.5 inches long. |
| 166 | + - 'x' or 'y': The arrow length is scaled relative to the x or y axis units. |
| 167 | + For example, ``(u, v) = (0, 1)`` with ``scale_units='x', scale=1`` results |
| 168 | + in a vertical arrow with the length of 1 x-axis unit. |
129 | 169 |
|
130 | | - If *scale_units* is 'width' or 'height', then the vector will be half the |
131 | | - width/height of the axes. |
| 170 | + - 'xy': Arrow length will be same as 'x' or 'y' units. |
| 171 | + This is useful for creating vectors in the x-y plane where u and v have |
| 172 | + the same units as x and y. To plot vectors in the x-y plane with u and v having |
| 173 | + the same units as x and y, use ``angles='xy', scale_units='xy', scale=1``. |
132 | 174 |
|
133 | | - If *scale_units* is 'x' then the vector will be 0.5 x-axis |
134 | | - units. To plot vectors in the x-y plane, with u and v having |
135 | | - the same units as x and y, use |
136 | | - ``angles='xy', scale_units='xy', scale=1``. |
| 175 | + Note: Setting *scale_units* without setting scale does not have any effect because |
| 176 | + the scale units only differ by a constant factor and that is rescaled through |
| 177 | + autoscaling. |
137 | 178 |
|
138 | 179 | units : {'width', 'height', 'dots', 'inches', 'x', 'y', 'xy'}, default: 'width' |
139 | 180 | Affects the arrow size (except for the length). In particular, the shaft |
|
0 commit comments