kdiagram.plot.uncertainty.plot_polar_quiver

kdiagram.plot.uncertainty.plot_polar_quiver(df, r_col, theta_col, u_col, v_col, *, acov='default', color_col=None, theta_period=None, title=None, figsize=(8.0, 8.0), cmap='viridis', mask_angle=False, mask_radius=False, show_grid=True, grid_props=None, savefig=None, dpi=300, ax=None, **quiver_kws)[source]

Plot a polar quiver plot to visualize vector data.

This function draws arrows (vectors) on a polar grid. Each arrow’s origin, direction, and magnitude are determined by the data. This is highly effective for visualizing dynamic phenomena like forecast revisions, error vectors, or flow fields [1].

Parameters:
dfpd.DataFrame

The input DataFrame containing the vector data.

r_colstr

Name of the column for the radial position of the vector’s origin (tail).

theta_colstr

Name of the column for the angular position of the vector’s origin.

u_colstr

Name of the column for the radial component of the vector (the change in radius).

v_colstr

Name of the column for the tangential component of the vector (the change in angle).

acov{‘default’, ‘half_circle’, ‘quarter_circle’, ‘eighth_circle’},

default=’default’ Angular coverage of the plot:

  • 'default': full circle, \(2\pi\)

  • 'half_circle': \(\pi\)

  • 'quarter_circle': \(\pi/2\)

  • 'eighth_circle': \(\pi/4\)

(Value is case-insensitive; invalid values fall back to full circle with a warning.)

color_colstr, optional

Name of a column to use for coloring the arrows. If None, arrows are colored by their total vector magnitude.

theta_periodfloat, optional

The period of the cyclical data in theta_col. For example, if theta_col represents degrees in a circle, the period is 360. If provided, the angle is mapped to [0, 2*pi] based on this cycle.

titlestr, optional

The title for the plot. If None, a default is generated.

figsizetuple of (float, float), default=(8, 8)

Figure size in inches.

cmapstr, default=’viridis’

Matplotlib colormap for coloring the arrows.

show_gridbool, default=True

Toggle gridlines via the package helper set_axis_grid.

grid_propsdict, optional

Keyword arguments passed to set_axis_grid for grid customization.

mask_anglebool, default=False

If True, hide the angular tick labels (e.g., degrees).

mask_radiusbool, default=False

If True, hide the radial tick labels.

savefigstr, optional

If provided, save the figure to this path; otherwise the plot is shown interactively.

dpiint, default=300

Resolution for the saved figure.

**quiver_kwsdict, optional

Additional keyword arguments passed to the ax.quiver call (e.g., scale, width, headwidth).

Returns:
axmatplotlib.axes.Axes or None

The Matplotlib Axes object containing the plot, or None if the plot could not be generated.

Parameters:
Return type:

Axes | None

Notes

The plot visualizes a vector field on a polar coordinate system. For each data point \(i\), a vector is drawn footcite:p:Hunter2007.

  1. Vector Origin: The tail of the vector is positioned at the polar coordinates \((r_i, \theta_i)\) specified by r_col and theta_col.

  2. Vector Components: The vector itself is defined by its components in the radial and tangential directions:

    • \(u_i\) (from u_col) is the component in the radial direction (pointing away from the center).

    • \(v_i\) (from v_col) is the component in the tangential direction (perpendicular to the radial line).

  3. Visualization: Matplotlib’s polar quiver function places an arrow at each origin point \((r_i, \theta_i)\). The arrow’s length and orientation are determined by the vector \((u_i, v_i)\).

  4. Coloring: The color of each arrow can be determined by a separate metric from color_col. If not specified, it defaults to the vector’s Euclidean magnitude, \(M_i\).

    (1)\[M_i = \sqrt{u_i^2 + v_i^2}\]

References

Examples

>>> import numpy as np
>>> import pandas as pd
>>> from kdiagram.plot.uncertainty import plot_polar_quiver
>>>
>>> # Simulate forecast revisions for 50 spatial locations
>>> np.random.seed(0)
>>> n_points = 50
>>> locations = np.linspace(0, 360, n_points, endpoint=False)
>>> initial_forecast = 10 + 5 * np.sin(np.deg2rad(locations) * 3)
>>>
>>> # Simulate revisions (changes in value)
>>> radial_change = np.random.normal(0, 1.5, n_points)
>>> tangential_change = np.random.normal(0, 0.1, n_points)
>>>
>>> df_forecasts = pd.DataFrame({
...     'location_angle': locations,
...     'initial_value': initial_forecast,
...     'update_radial': radial_change,
...     'update_tangential': tangential_change,
... })
>>>
>>> # Generate the polar quiver plot
>>> ax = plot_polar_quiver(
...     df=df_forecasts,
...     r_col='initial_value',
...     theta_col='location_angle',
...     u_col='update_radial',
...     v_col='update_tangential',
...     theta_period=360,
...     title='Forecast Revisions for Spatial Locations',
...     cmap='coolwarm',
...     scale=25  # Adjusts arrow size for better visibility
... )