Modules.CurveBoxplot package

Submodules

Modules.CurveBoxplot.curve_boxplot module

Modules.CurveBoxplot.curve_boxplot.curve_boxplot(curves, boxplot_style=None, ax=None, workers=12)

Create a curve band depth plot with multiple percentile bands.

This function follows a 3-stage pipeline: statistics → mesh → visualization. It computes curve band depths, generates triangular meshes for percentile bands, and creates a visualization with median and outlier curves.

For 2D curves, uses matplotlib. For 3D curves, uses PyVista if available, otherwise falls back to matplotlib.

Parameters:

curvesnumpy.ndarray

3D array of shape (n_curves, n_steps, n_dims) containing curve data. Input data is not modified (computation happens on a copy).

boxplot_styleBoxplotStyleConfig, optional

Configuration for the boxplot visualization including percentiles, colors, and median/outlier styling. If None, uses default configuration.

axmatplotlib.axes.Axes or pyvista.Plotter, optional

Axes or plotter to plot on. Can be either: - matplotlib.axes.Axes for 2D or 3D matplotlib rendering - pyvista.Plotter for 3D PyVista rendering If None, creates appropriate visualization object automatically.

workersint, optional

Number of worker processes for parallel computation of band depths. Default is 12. Set to 1 or None to use sequential processing (useful for debugging).

Returns:

axmatplotlib.axes.Axes or pyvista.Plotter

The visualization object (matplotlib axes for 2D, PyVista plotter for 3D if available).

Notes:

• The function does not modify the input curves array

• Bands are plotted from largest to smallest percentile for proper layering

• The median curve is the curve with the highest depth value

• Outliers are curves beyond the largest percentile

• Curve depths are always computed internally

• For 3D curves, PyVista provides better interactivity than matplotlib

Examples:

>>> # Basic usage with defaults
>>> ax = curve_boxplot(curves)

>>> # Custom styling
>>> from uvisbox.Core.CommonInterface import BoxplotStyleConfig
>>> style = BoxplotStyleConfig(
...     percentiles=[10, 50, 90],
...     percentile_colors=['lightblue', 'blue', 'darkblue'],
...     show_median=True,
...     median_color='red',
...     show_outliers=True
... )
>>> ax = curve_boxplot(curves, boxplot_style=style)

>>> # 3D curves with PyVista
>>> import pyvista as pv
>>> plotter = pv.Plotter()
>>> curve_boxplot(curves_3d, ax=plotter)
>>> plotter.show()

>>> # Hide median and outliers
>>> style = BoxplotStyleConfig(show_median=False, show_outliers=False)
>>> ax = curve_boxplot(curves, boxplot_style=style)

Modules.CurveBoxplot.curve_boxplot_mesh module

Modules.CurveBoxplot.curve_boxplot_mesh.curve_boxplot_mesh(summary_stats)

Build triangular mesh for curve band depth visualization.

This function generates triangular meshes for each percentile band using the sorted curves from the summary statistics. For 2D curves, it uses ConvexHull and Delaunay triangulation with a center point. For 3D curves, it uses the ConvexHull faces directly.

Parameters:

summary_statsdict

Dictionary from curve_boxplot_summary_statistics() containing: - ‘sorted_curves’: curves sorted by depth (descending) - ‘percentiles’: list of percentile values - ‘n_dims’: dimensionality (2 or 3)

Returns:

mesh_datadict

Dictionary containing the following keys: - ‘percentile_meshes’: dict with keys like ‘50_percentile_mesh’ containing

tuples (points, triangles) where: * points: np.ndarray of shape (n_points, n_dims) * triangles: np.ndarray of shape (n_triangles, 3)

• ‘median_curve’: median curve from summary_stats

• ‘outliers’: outlier curves from summary_stats

• ‘n_dims’: dimensionality

Examples:

>>> import numpy as np
>>> from uvisbox.Modules.CurveBoxplot.curve_boxplot_stats import curve_boxplot_summary_statistics
>>> from uvisbox.Modules.CurveBoxplot.curve_boxplot_mesh import curve_boxplot_mesh
>>>
>>> # Generate synthetic curve data
>>> curves = np.random.randn(50, 100, 2).cumsum(axis=1)
>>>
>>> # Compute statistics
>>> stats = curve_boxplot_summary_statistics(curves)
>>>
>>> # Build mesh
>>> mesh_data = curve_boxplot_mesh(stats)
>>>
>>> # Access mesh for 50th percentile
>>> points, triangles = mesh_data['percentile_meshes']['50_percentile_mesh']
>>> print(f"Mesh has {points.shape[0]} points and {triangles.shape[0]} triangles")

Modules.CurveBoxplot.curve_boxplot_stats module

Modules.CurveBoxplot.curve_boxplot_stats.curve_boxplot_summary_statistics(curves, boxplot_style=None, workers=12)

Compute curve band depth summary statistics without visualization.

This function computes curve band depths, sorts curves, and identifies percentile bands and outliers based on the configuration.

Parameters:

curvesnumpy.ndarray

3D array of shape (n_curves, n_steps, n_dims) containing curve data. Input data is not modified (computation happens on a copy).

boxplot_styleBoxplotStyleConfig, optional

Configuration for the boxplot including percentiles and outlier settings. If None, uses default configuration.

workersint, optional

Number of worker processes for parallel computation of band depths. Default is 12. Set to 1 or None to use sequential processing (useful for debugging).

Returns:

statsdict

Dictionary containing the following keys: - ‘depths’: np.ndarray of shape (n_curves,) - band depths for each curve - ‘sorted_indices’: np.ndarray of shape (n_curves,) - original indices sorted by depth (descending) - ‘sorted_curves’: np.ndarray of shape (n_curves, n_steps, n_dims) - curves sorted by depth (descending) - ‘median_curve’: np.ndarray of shape (n_steps, n_dims) - curve with highest depth - ‘percentiles’: list of floats - percentile values from boxplot_style - ‘outliers’: np.ndarray of shape (n_outliers, n_steps, n_dims) - outlier curves beyond largest percentile - ‘n_dims’: int - dimensionality of curves (2 or 3)

Raises:

ValueError

If curves is not a 3D array or if n_dims is not 2 or 3.

Examples:

>>> import numpy as np
>>> from uvisbox.Modules.CurveBoxplot.curve_boxplot_stats import curve_boxplot_summary_statistics
>>> from uvisbox.Core.CommonInterface import BoxplotStyleConfig
>>>
>>> # Generate synthetic curve data (50 curves, 100 time steps, 2D)
>>> curves = np.random.randn(50, 100, 2).cumsum(axis=1)
>>>
>>> # Basic usage with default settings
>>> stats = curve_boxplot_summary_statistics(curves)
>>> print(f"Median curve shape: {stats['median_curve'].shape}")
>>> print(f"Number of outliers: {stats['outliers'].shape[0]}")
>>>
>>> # Custom percentiles
>>> style = BoxplotStyleConfig(percentiles=[10, 50, 90], show_outliers=True)
>>> stats = curve_boxplot_summary_statistics(curves, boxplot_style=style)

Modules.CurveBoxplot.curve_boxplot_vis module

Modules.CurveBoxplot.curve_boxplot_vis.visualize_curve_boxplot(mesh_data, boxplot_style=None, ax=None)

Visualize curve boxplot from mesh data.

This function creates a visualization of the curve boxplot using the mesh data output from the mesh pipeline. For 2D curves, it uses matplotlib. For 3D curves, it uses PyVista if available, otherwise falls back to matplotlib.

Parameters:

mesh_datadict

Dictionary containing mesh data with the following keys: - ‘percentile_meshes’: dict of percentile meshes - ‘median_curve’: median curve - ‘outliers’: outlier curves - ‘n_dims’: dimensionality (2 or 3)

boxplot_styleBoxplotStyleConfig, optional

Configuration for the boxplot visualization including percentiles, colors, and median/outlier styling. If None, uses default configuration.

axmatplotlib.axes.Axes or pyvista.Plotter, optional

Axes or plotter to use for visualization. Can be: - matplotlib.axes.Axes for 2D or 3D matplotlib rendering - pyvista.Plotter for 3D PyVista rendering - None: creates appropriate visualization object automatically

Returns:

axmatplotlib.axes.Axes or pyvista.Plotter

The visualization object (matplotlib axes for 2D, PyVista plotter for 3D).

Examples:

>>> import numpy as np
>>> from uvisbox.Modules.CurveBoxplot.curve_boxplot_stats import curve_boxplot_summary_statistics
>>> from uvisbox.Modules.CurveBoxplot.curve_boxplot_mesh import curve_boxplot_mesh
>>> from uvisbox.Modules.CurveBoxplot.curve_boxplot_vis import visualize_curve_boxplot
>>> from uvisbox.Core.CommonInterface import BoxplotStyleConfig
>>>
>>> # Generate synthetic curve data
>>> curves = np.random.randn(50, 100, 2).cumsum(axis=1)
>>>
>>> # Process through pipeline
>>> stats = curve_boxplot_summary_statistics(curves)
>>> mesh_data = curve_boxplot_mesh(stats)
>>>
>>> # Visualize
>>> ax = visualize_curve_boxplot(mesh_data)
>>>
>>> # Custom styling
>>> style = BoxplotStyleConfig(percentiles=[25, 50, 75], show_outliers=True)
>>> ax = visualize_curve_boxplot(mesh_data, boxplot_style=style)

Module contents

Curve_Boxplot Module

This module provides curve-based boxplot functionality for uncertainty visualization.

Modules.CurveBoxplot.curve_boxplot(curves, boxplot_style=None, ax=None, workers=12)

Create a curve band depth plot with multiple percentile bands.

This function follows a 3-stage pipeline: statistics → mesh → visualization. It computes curve band depths, generates triangular meshes for percentile bands, and creates a visualization with median and outlier curves.

For 2D curves, uses matplotlib. For 3D curves, uses PyVista if available, otherwise falls back to matplotlib.

Parameters:

curvesnumpy.ndarray

3D array of shape (n_curves, n_steps, n_dims) containing curve data. Input data is not modified (computation happens on a copy).

boxplot_styleBoxplotStyleConfig, optional

Configuration for the boxplot visualization including percentiles, colors, and median/outlier styling. If None, uses default configuration.

axmatplotlib.axes.Axes or pyvista.Plotter, optional

Axes or plotter to plot on. Can be either: - matplotlib.axes.Axes for 2D or 3D matplotlib rendering - pyvista.Plotter for 3D PyVista rendering If None, creates appropriate visualization object automatically.

workersint, optional

Number of worker processes for parallel computation of band depths. Default is 12. Set to 1 or None to use sequential processing (useful for debugging).

Returns:

axmatplotlib.axes.Axes or pyvista.Plotter

The visualization object (matplotlib axes for 2D, PyVista plotter for 3D if available).

Notes:

• The function does not modify the input curves array

• Bands are plotted from largest to smallest percentile for proper layering

• The median curve is the curve with the highest depth value

• Outliers are curves beyond the largest percentile

• Curve depths are always computed internally

• For 3D curves, PyVista provides better interactivity than matplotlib

Examples:

>>> # Basic usage with defaults
>>> ax = curve_boxplot(curves)

>>> # Custom styling
>>> from uvisbox.Core.CommonInterface import BoxplotStyleConfig
>>> style = BoxplotStyleConfig(
...     percentiles=[10, 50, 90],
...     percentile_colors=['lightblue', 'blue', 'darkblue'],
...     show_median=True,
...     median_color='red',
...     show_outliers=True
... )
>>> ax = curve_boxplot(curves, boxplot_style=style)

>>> # 3D curves with PyVista
>>> import pyvista as pv
>>> plotter = pv.Plotter()
>>> curve_boxplot(curves_3d, ax=plotter)
>>> plotter.show()

>>> # Hide median and outliers
>>> style = BoxplotStyleConfig(show_median=False, show_outliers=False)
>>> ax = curve_boxplot(curves, boxplot_style=style)

Modules.CurveBoxplot.curve_boxplot_mesh(summary_stats)

Build triangular mesh for curve band depth visualization.

This function generates triangular meshes for each percentile band using the sorted curves from the summary statistics. For 2D curves, it uses ConvexHull and Delaunay triangulation with a center point. For 3D curves, it uses the ConvexHull faces directly.

Parameters:

summary_statsdict

Dictionary from curve_boxplot_summary_statistics() containing: - ‘sorted_curves’: curves sorted by depth (descending) - ‘percentiles’: list of percentile values - ‘n_dims’: dimensionality (2 or 3)

Returns:

mesh_datadict

Dictionary containing the following keys: - ‘percentile_meshes’: dict with keys like ‘50_percentile_mesh’ containing

tuples (points, triangles) where: * points: np.ndarray of shape (n_points, n_dims) * triangles: np.ndarray of shape (n_triangles, 3)

• ‘median_curve’: median curve from summary_stats

• ‘outliers’: outlier curves from summary_stats

• ‘n_dims’: dimensionality

Examples:

>>> import numpy as np
>>> from uvisbox.Modules.CurveBoxplot.curve_boxplot_stats import curve_boxplot_summary_statistics
>>> from uvisbox.Modules.CurveBoxplot.curve_boxplot_mesh import curve_boxplot_mesh
>>>
>>> # Generate synthetic curve data
>>> curves = np.random.randn(50, 100, 2).cumsum(axis=1)
>>>
>>> # Compute statistics
>>> stats = curve_boxplot_summary_statistics(curves)
>>>
>>> # Build mesh
>>> mesh_data = curve_boxplot_mesh(stats)
>>>
>>> # Access mesh for 50th percentile
>>> points, triangles = mesh_data['percentile_meshes']['50_percentile_mesh']
>>> print(f"Mesh has {points.shape[0]} points and {triangles.shape[0]} triangles")

Modules.CurveBoxplot.curve_boxplot_summary_statistics(curves, boxplot_style=None, workers=12)

Compute curve band depth summary statistics without visualization.

This function computes curve band depths, sorts curves, and identifies percentile bands and outliers based on the configuration.

Parameters:

curvesnumpy.ndarray

3D array of shape (n_curves, n_steps, n_dims) containing curve data. Input data is not modified (computation happens on a copy).

boxplot_styleBoxplotStyleConfig, optional

Configuration for the boxplot including percentiles and outlier settings. If None, uses default configuration.

workersint, optional

Number of worker processes for parallel computation of band depths. Default is 12. Set to 1 or None to use sequential processing (useful for debugging).

Returns:

statsdict

Dictionary containing the following keys: - ‘depths’: np.ndarray of shape (n_curves,) - band depths for each curve - ‘sorted_indices’: np.ndarray of shape (n_curves,) - original indices sorted by depth (descending) - ‘sorted_curves’: np.ndarray of shape (n_curves, n_steps, n_dims) - curves sorted by depth (descending) - ‘median_curve’: np.ndarray of shape (n_steps, n_dims) - curve with highest depth - ‘percentiles’: list of floats - percentile values from boxplot_style - ‘outliers’: np.ndarray of shape (n_outliers, n_steps, n_dims) - outlier curves beyond largest percentile - ‘n_dims’: int - dimensionality of curves (2 or 3)

Raises:

ValueError

If curves is not a 3D array or if n_dims is not 2 or 3.

Examples:

>>> import numpy as np
>>> from uvisbox.Modules.CurveBoxplot.curve_boxplot_stats import curve_boxplot_summary_statistics
>>> from uvisbox.Core.CommonInterface import BoxplotStyleConfig
>>>
>>> # Generate synthetic curve data (50 curves, 100 time steps, 2D)
>>> curves = np.random.randn(50, 100, 2).cumsum(axis=1)
>>>
>>> # Basic usage with default settings
>>> stats = curve_boxplot_summary_statistics(curves)
>>> print(f"Median curve shape: {stats['median_curve'].shape}")
>>> print(f"Number of outliers: {stats['outliers'].shape[0]}")
>>>
>>> # Custom percentiles
>>> style = BoxplotStyleConfig(percentiles=[10, 50, 90], show_outliers=True)
>>> stats = curve_boxplot_summary_statistics(curves, boxplot_style=style)

Modules.CurveBoxplot.visualize_curve_boxplot(mesh_data, boxplot_style=None, ax=None)

Visualize curve boxplot from mesh data.

This function creates a visualization of the curve boxplot using the mesh data output from the mesh pipeline. For 2D curves, it uses matplotlib. For 3D curves, it uses PyVista if available, otherwise falls back to matplotlib.

Parameters:

mesh_datadict

Dictionary containing mesh data with the following keys: - ‘percentile_meshes’: dict of percentile meshes - ‘median_curve’: median curve - ‘outliers’: outlier curves - ‘n_dims’: dimensionality (2 or 3)

boxplot_styleBoxplotStyleConfig, optional

Configuration for the boxplot visualization including percentiles, colors, and median/outlier styling. If None, uses default configuration.

axmatplotlib.axes.Axes or pyvista.Plotter, optional

Axes or plotter to use for visualization. Can be: - matplotlib.axes.Axes for 2D or 3D matplotlib rendering - pyvista.Plotter for 3D PyVista rendering - None: creates appropriate visualization object automatically

Returns:

axmatplotlib.axes.Axes or pyvista.Plotter

The visualization object (matplotlib axes for 2D, PyVista plotter for 3D).

Examples:

>>> import numpy as np
>>> from uvisbox.Modules.CurveBoxplot.curve_boxplot_stats import curve_boxplot_summary_statistics
>>> from uvisbox.Modules.CurveBoxplot.curve_boxplot_mesh import curve_boxplot_mesh
>>> from uvisbox.Modules.CurveBoxplot.curve_boxplot_vis import visualize_curve_boxplot
>>> from uvisbox.Core.CommonInterface import BoxplotStyleConfig
>>>
>>> # Generate synthetic curve data
>>> curves = np.random.randn(50, 100, 2).cumsum(axis=1)
>>>
>>> # Process through pipeline
>>> stats = curve_boxplot_summary_statistics(curves)
>>> mesh_data = curve_boxplot_mesh(stats)
>>>
>>> # Visualize
>>> ax = visualize_curve_boxplot(mesh_data)
>>>
>>> # Custom styling
>>> style = BoxplotStyleConfig(percentiles=[25, 50, 75], show_outliers=True)
>>> ax = visualize_curve_boxplot(mesh_data, boxplot_style=style)