Modules.UncertaintyLobes package

Submodules

Modules.UncertaintyLobes.uncertainty_lobes module

Top-level API for uncertainty lobe visualization.

This module provides high-level functions that orchestrate the three-stage pipeline:

1. Compute statistics (vector depths, spreads, angular ranges)

2. Build mesh geometry (wedge vertices, triangles)

3. Render visualization (matplotlib)

For fine-grained control, use the individual stage functions directly:

• uncertainty_lobes_summary_statistics()

• uncertainty_lobes_mesh()

• visualize_uncertainty_lobes()

Based on: M. Jarema, I. Demir, J. Kehrer and R. Westermann, “Comparative visual analysis of vector field ensembles,” 2015 IEEE VAST, doi: 10.1109/VAST.2015.7347634.

This implementation uses vector depth and doesn’t fit ensemble to a Gaussian Mixture Model as in the original paper. In addition, this implementation doesn’t perform clustering of the vectors, instead it draws lobes for all vectors at each position.

Modules.UncertaintyLobes.uncertainty_lobes.uncertainty_lobes(positions, ensemble_vectors, percentile1=90, percentile2=50, scale=0.2, ax=None, show_median=True, workers=None)

Visualize uncertainty lobe glyphs.

This function orchestrates the three-stage pipeline:

1. Convert Cartesian → Polar, compute vector depths and spreads

2. Build wedge-shaped mesh (vertices, triangles)

3. Render with matplotlib

Draws uncertainty lobe glyphs representing directional uncertainty with dual-lobe visualization. Each glyph shows: - Outer lobe (percentile1, semi-transparent): larger angular and magnitude spread - Inner lobe (percentile2, opaque): smaller spread showing most probable region - Median arrow: most probable direction based on vector depth

Parameters:

positionsnumpy.ndarray

Array of shape (n, 2) representing the positions of the lobe glyphs.

ensemble_vectorsnumpy.ndarray

Array of shape (n, m, 2) representing the ensemble vectors for each position.

percentile1float (0-100)

The first percentile for depth filtering (outer lobe). Range 0-100. Higher values include more vectors (larger lobes). Default: 90

percentile2float or None (0-100)

The second percentile for depth filtering (inner lobe). Range 0-100. If None, only outer lobe is drawn. Default: 50

scalefloat

The scale factor for the glyphs (default: 0.2).

axmatplotlib.Axes, optional

The axis to draw on. If None, a new figure and axis will be created.

show_medianbool

Whether to show the median vector as an arrow (default: True).

workersint, optional

Number of worker processes for parallel vector depth computation. If None or <= 1, uses sequential computation. For ensemble size >= 30, parallelization can provide significant speedup. Default: None

Returns:

axmatplotlib.Axes

The axis with the drawn lobe glyphs.

Modules.UncertaintyLobes.uncertainty_lobes_stats module

Statistics computation for uncertainty lobes.

This module computes vector depth statistics for uncertainty lobe visualization:

• Convert Cartesian → Polar coordinates

• Compute vector depths

• Calculate spreads (min/max magnitude and angle)

Modules.UncertaintyLobes.uncertainty_lobes_stats.uncertainty_lobes_summary_statistics(ensemble_vectors, percentile1=90, percentile2=50, workers=None)

Compute vector depth statistics for uncertainty lobes.

Parameters:

ensemble_vectorsnumpy.ndarray

Shape (n, m, 2) - Cartesian ensemble vectors at n positions with m members

percentile1float (0-100)

First percentile for depth filtering (outer lobe). Higher values include more vectors. Default: 90

percentile2float or None (0-100)

Second percentile for depth filtering (inner lobe). If None, only one lobe is drawn. Default: 50

workersint, optional

Number of parallel workers for computation. Default is None (sequential). For ensemble size >= 30, parallelization can provide speedup.

Returns:

statsdict

{

‘ensemble_polar_vectors’: (n, m, 2) - polar coordinates [r, theta], ‘depths’: (n, m) - vector depths, ‘median_vectors’: (n, 2) - median vectors per position [r, theta], ‘outer_lobe_angles’: (n, 2) - angular spread for percentile1 [min_angle, max_angle], ‘inner_lobe_angles’: (n, 2) or None - angular spread for percentile2 (if provided), ‘median_angles’: (n,) - median angles (radians), ‘outer_lobe_radii’: (n,) - minimum magnitude for percentile1, ‘inner_lobe_radii’: (n,) - maximum magnitude for percentile2 (or 0 if None), ‘median_magnitudes’: (n,) - median vector magnitudes

}

Modules.UncertaintyLobes.uncertainty_lobes_vis module

Visualization rendering for uncertainty lobes.

This module renders uncertainty lobe meshes using matplotlib:

• Draw outer lobes (wedges)

• Draw inner lobes (wedges)

• Draw median direction arrows

Modules.UncertaintyLobes.uncertainty_lobes_vis.visualize_uncertainty_lobes(mesh, show_median=True, ax=None)

Render uncertainty lobe mesh with matplotlib.

Draws wedge-shaped glyphs representing directional uncertainty with: - Outer wedges (light blue, semi-transparent) - larger angular spread - Inner wedges (light blue, opaque) - smaller angular spread - Median arrows (blue) - showing the most probable direction

Parameters:

meshdict

From uncertainty_lobes_mesh() containing: - ‘wedges’: outer lobe wedge data - ‘inner_wedges’: inner lobe wedge data (optional) - ‘arrows’: median direction arrow data

show_medianbool

Whether to show median direction arrows (default: True)

axmatplotlib.Axes, optional

Existing axis to draw on. If None, creates new figure and axis.

Returns:

axmatplotlib.Axes

The axis with drawn lobe glyphs

Module contents

UncertaintyLobes Module

This module provides functionality for visualizing uncertainty lobes in vector field ensembles. It follows a three-stage visualization pipeline:

1. Compute statistics (vector depths, spreads, angular ranges)

2. Build mesh geometry (wedge vertices, triangles)

3. Render visualization (matplotlib)

Main functions:

• uncertainty_lobes(): High-level API for complete visualization

• uncertainty_lobes_summary_statistics(): Stage 1 - Statistics computation

• uncertainty_lobes_mesh(): Stage 2 - Mesh generation

• visualize_uncertainty_lobes(): Stage 3 - Visualization rendering

Modules.UncertaintyLobes.uncertainty_lobes(positions, ensemble_vectors, percentile1=90, percentile2=50, scale=0.2, ax=None, show_median=True, workers=None)

Visualize uncertainty lobe glyphs.

This function orchestrates the three-stage pipeline:

1. Convert Cartesian → Polar, compute vector depths and spreads

2. Build wedge-shaped mesh (vertices, triangles)

3. Render with matplotlib

Draws uncertainty lobe glyphs representing directional uncertainty with dual-lobe visualization. Each glyph shows: - Outer lobe (percentile1, semi-transparent): larger angular and magnitude spread - Inner lobe (percentile2, opaque): smaller spread showing most probable region - Median arrow: most probable direction based on vector depth

Parameters:

positionsnumpy.ndarray

Array of shape (n, 2) representing the positions of the lobe glyphs.

ensemble_vectorsnumpy.ndarray

Array of shape (n, m, 2) representing the ensemble vectors for each position.

percentile1float (0-100)

The first percentile for depth filtering (outer lobe). Range 0-100. Higher values include more vectors (larger lobes). Default: 90

percentile2float or None (0-100)

The second percentile for depth filtering (inner lobe). Range 0-100. If None, only outer lobe is drawn. Default: 50

scalefloat

The scale factor for the glyphs (default: 0.2).

axmatplotlib.Axes, optional

The axis to draw on. If None, a new figure and axis will be created.

show_medianbool

Whether to show the median vector as an arrow (default: True).

workersint, optional

Number of worker processes for parallel vector depth computation. If None or <= 1, uses sequential computation. For ensemble size >= 30, parallelization can provide significant speedup. Default: None

Returns:

axmatplotlib.Axes

The axis with the drawn lobe glyphs.

Modules.UncertaintyLobes.uncertainty_lobes_mesh(positions, stats, scale=0.2, arc_resolution=20)

Build uncertainty lobe mesh from statistics.

Creates wedge-shaped glyphs with: 1. Outer lobe (percentile1 - larger angular and magnitude spread) 2. Inner lobe (percentile2 - smaller spread, optional) 3. Median arrow direction

Parameters:

positionsnumpy.ndarray

Shape (n, 2) - lobe center positions

statsdict

From uncertainty_lobes_summary_statistics()

scalefloat

Glyph scale factor (default: 0.2)

arc_resolutionint

Number of points per wedge arc (default: 20)

Returns:

meshdict

{

‘wedges’: list of dicts - each containing ‘vertices’ and ‘triangles’ for outer lobe, ‘inner_wedges’: list of dicts - each containing ‘vertices’ and ‘triangles’ for inner lobe (if percentile2 != None), ‘arrows’: dict - {‘positions’: (n, 2), ‘directions’: (n, 2), ‘lengths’: (n,)}

}

Modules.UncertaintyLobes.uncertainty_lobes_summary_statistics(ensemble_vectors, percentile1=90, percentile2=50, workers=None)

Compute vector depth statistics for uncertainty lobes.

Parameters:

ensemble_vectorsnumpy.ndarray

Shape (n, m, 2) - Cartesian ensemble vectors at n positions with m members

percentile1float (0-100)

First percentile for depth filtering (outer lobe). Higher values include more vectors. Default: 90

percentile2float or None (0-100)

Second percentile for depth filtering (inner lobe). If None, only one lobe is drawn. Default: 50

workersint, optional

Number of parallel workers for computation. Default is None (sequential). For ensemble size >= 30, parallelization can provide speedup.

Returns:

statsdict

{

‘ensemble_polar_vectors’: (n, m, 2) - polar coordinates [r, theta], ‘depths’: (n, m) - vector depths, ‘median_vectors’: (n, 2) - median vectors per position [r, theta], ‘outer_lobe_angles’: (n, 2) - angular spread for percentile1 [min_angle, max_angle], ‘inner_lobe_angles’: (n, 2) or None - angular spread for percentile2 (if provided), ‘median_angles’: (n,) - median angles (radians), ‘outer_lobe_radii’: (n,) - minimum magnitude for percentile1, ‘inner_lobe_radii’: (n,) - maximum magnitude for percentile2 (or 0 if None), ‘median_magnitudes’: (n,) - median vector magnitudes

}

Modules.UncertaintyLobes.visualize_uncertainty_lobes(mesh, show_median=True, ax=None)

Render uncertainty lobe mesh with matplotlib.

Draws wedge-shaped glyphs representing directional uncertainty with: - Outer wedges (light blue, semi-transparent) - larger angular spread - Inner wedges (light blue, opaque) - smaller angular spread - Median arrows (blue) - showing the most probable direction

Parameters:

meshdict

From uncertainty_lobes_mesh() containing: - ‘wedges’: outer lobe wedge data - ‘inner_wedges’: inner lobe wedge data (optional) - ‘arrows’: median direction arrow data

show_medianbool

Whether to show median direction arrows (default: True)

axmatplotlib.Axes, optional

Existing axis to draw on. If None, creates new figure and axis.

Returns:

axmatplotlib.Axes

The axis with drawn lobe glyphs