uvisbox.Modules.UncertaintyLobes.uncertainty_lobes
==================================================

.. py:module:: uvisbox.Modules.UncertaintyLobes.uncertainty_lobes

.. autoapi-nested-parse::

   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.





Module Contents
---------------

.. py:function:: uncertainty_lobes(positions, ensemble_vectors, percentile1=90, percentile2=50, scale=0.2, ax=None, show_median=True, workers=None, outer_lobe_edge_color='skyblue', outer_lobe_face_color='skyblue', inner_lobe_edge_color='skyblue', inner_lobe_face_color='skyblue', median_arrow_color='blue', outer_lobe_alpha=0.3, inner_lobe_alpha=1.0, median_arrow_alpha=1.0)

   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

   :param positions: Array of shape (n, 2) representing the positions of the lobe glyphs.
   :type positions: numpy.ndarray
   :param ensemble_vectors: Array of shape (n, m, 2) representing the ensemble vectors for each position.
   :type ensemble_vectors: numpy.ndarray
   :param percentile1: The first percentile for depth filtering (outer lobe). Range 0-100.
                       Higher values include more vectors (larger lobes).
                       Default: 90
   :type percentile1: float (0-100)
   :param percentile2: The second percentile for depth filtering (inner lobe). Range 0-100.
                       If None, only outer lobe is drawn.
                       Default: 50
   :type percentile2: float or None (0-100)
   :param scale: The scale factor for the glyphs (default: 0.2).
   :type scale: float
   :param ax: The axis to draw on. If None, a new figure and axis will be created.
   :type ax: matplotlib.Axes, optional
   :param show_median: Whether to show the median vector as an arrow (default: True).
   :type show_median: bool
   :param workers: 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
   :type workers: int, optional
   :param outer_lobe_edge_color: Matplotlib color for outer lobe edges. Default: ``'skyblue'``.
   :type outer_lobe_edge_color: color, optional
   :param outer_lobe_face_color: Matplotlib color for outer lobe faces. Default: ``'skyblue'``.
   :type outer_lobe_face_color: color, optional
   :param inner_lobe_edge_color: Matplotlib color for inner lobe edges. Default: ``'skyblue'``.
   :type inner_lobe_edge_color: color, optional
   :param inner_lobe_face_color: Matplotlib color for inner lobe faces. Default: ``'skyblue'``.
   :type inner_lobe_face_color: color, optional
   :param median_arrow_color: Matplotlib color for median arrows. Default: ``'blue'``.
   :type median_arrow_color: color, optional
   :param outer_lobe_alpha: Opacity for outer lobe wedges and their edges. Must be in ``[0, 1]``.
                            Default: ``0.3``.
   :type outer_lobe_alpha: float, optional
   :param inner_lobe_alpha: Opacity for inner lobe wedges and their edges. Must be in ``[0, 1]``.
                            Default: ``1.0``.
   :type inner_lobe_alpha: float, optional
   :param median_arrow_alpha: Opacity for median arrows. Must be in ``[0, 1]``. Default: ``1.0``.
   :type median_arrow_alpha: float, optional

   :returns: **ax** -- The axis with the drawn lobe glyphs.
   :rtype: matplotlib.Axes