Modules.ContourBoxplot package

Submodules

Modules.ContourBoxplot.contour_boxplot module

Modules.ContourBoxplot.contour_boxplot.contour_boxplot(ensemble_images, isovalue, boxplot_style=None, ax=None, workers=11)[source]

Create a contour boxplot visualization from an ensemble of scalar fields.

This function processes ensemble images by extracting binary contours at a given isovalue, computing their band depths, and visualizing the uncertainty using band envelopes.

Parameters:

ensemble_imagesnp.ndarray

3D or 4D array containing the ensemble scalar fields. Can be shape (n_ensemble, y_dim, x_dim) or will be rearranged to this format.

isovaluefloat

Threshold value for creating binary images. Pixels with values < isovalue are set to 1.

boxplot_styleBoxplotStyleConfig, optional

Configuration for the boxplot visualization including percentiles, and median/outlier styling. If None, uses default configuration. The percentile_colormap is used for the band sum visualization.

axmatplotlib.axes.Axes, optional

Matplotlib Axes object to plot on. If None, a new figure and axes will be created.

workersint, optional

Number of parallel workers for band depth computation. Default is 12.

Returns:

axmatplotlib.axes.Axes

The Axes object with the contour boxplot visualization.

Examples:

>>> # Basic usage with defaults
>>> ensemble = np.random.randn(50, 100, 100)  # 50 ensemble members
>>> ax = contour_boxplot(ensemble, isovalue=0.5)

>>> # Custom styling
>>> from uvisbox.Core.CommonInterface import BoxplotStyleConfig
>>> style = BoxplotStyleConfig(
...     percentiles=[25, 50, 75],
...     percentile_colormap='hot',
...     show_median=True,
...     show_outliers=True
... )
>>> ax = contour_boxplot(ensemble, isovalue=0.5, boxplot_style=style)

Modules.ContourBoxplot.contour_boxplot_mesh module

Modules.ContourBoxplot.contour_boxplot_mesh.contour_boxplot_mesh(summary_statistics)[source]

Process summary statistics to create mesh data for visualization.

This function aggregates percentile bands by overwriting values in descending percentile order, creating a single image that shows all bands with appropriate color values.

Parameters:

summary_statisticsdict

Dictionary from contour_boxplot_summary_statistics containing: - ‘median’: Binary image for median contour - ‘percentile_bands’: List of (percentile, band_image) tuples - ‘outliers’: List of outlier binary images

Returns:

dict

Dictionary containing: - ‘percentile_bands_image’: 2D array where each pixel value represents the percentile/100

it belongs to. Lower percentiles overwrite higher ones.

  • ‘median’: Binary image (unchanged from input)

  • ‘outliers’: List of binary images (unchanged from input)

Notes:

The aggregation works by: 1. Starting with highest percentile band (e.g., 90th) 2. Painting pixels with value 0.90 where band is non-zero 3. Overwriting with lower percentile bands (e.g., 75th → 0.75) 4. Continuing until lowest percentile This creates a layered visualization where inner bands overwrite outer bands.

Examples:

>>> stats = contour_boxplot_summary_statistics(ensemble, isovalue=0.5)
>>> mesh_data = contour_boxplot_mesh(stats)
>>> print(mesh_data['percentile_bands_image'].shape)
(100, 100)

Modules.ContourBoxplot.contour_boxplot_stats module

Modules.ContourBoxplot.contour_boxplot_stats.contour_boxplot_summary_statistics(ensemble_images, isovalue, boxplot_style=None, workers=11)[source]

Compute summary statistics for contour boxplot from ensemble scalar fields.

This function extracts binary contours at the given isovalue, computes their band depths, and generates percentile bands, median, and outlier information.

Parameters:

ensemble_imagesnp.ndarray

3D array of shape (n_ensemble, height, width) containing ensemble scalar fields.

isovaluefloat

Threshold value for creating binary images. Pixels with values < isovalue are set to 1 (inside), values >= isovalue are set to 0 (outside).

boxplot_styleBoxplotStyleConfig, optional

Configuration for percentiles and outlier detection. If None, uses default configuration.

workersint, optional

Number of parallel workers for band depth computation. Default is 11.

Returns:

dict

Dictionary containing: - ‘median’: Binary image (np.ndarray) representing the median contour sublevel set.

1 = inside contour (value < isovalue), 0 = outside contour (value >= isovalue).

  • ‘percentile_bands’: List of tuples (percentile, band_image) where band_image is a 2D array

    with values in [0, percentile/100]. percentile/100 means inside the band, 0 means outside the band.

  • ‘outliers’: List of binary images representing outlier contours (same format as median).

  • ‘sorted_contours’: 3D array (n_ensemble, height, width) of binary images sorted by depth.

  • ‘sorted_indices’: Array of indices showing the original order of sorted contours.

  • ‘depths’: Array of computed band depth values for each contour.

Examples:

>>> ensemble = np.random.randn(50, 100, 100)
>>> stats = contour_boxplot_summary_statistics(ensemble, isovalue=0.5)
>>> print(stats.keys())
dict_keys(['median', 'percentile_bands', 'outliers', 'sorted_contours', 'sorted_indices', 'depths'])

Modules.ContourBoxplot.contour_boxplot_vis module

Modules.ContourBoxplot.contour_boxplot_vis.visualize_contour_boxplot(mesh_data, boxplot_style=None, ax=None)[source]

Visualize contour boxplot using imshow for percentile bands and contour for median/outliers.

Parameters:

mesh_datadict

Dictionary from contour_boxplot_mesh containing: - ‘percentile_bands_image’: 2D array with aggregated percentile band values - ‘median’: Binary image for median contour - ‘outliers’: List of binary images for outlier contours

boxplot_styleBoxplotStyleConfig, optional

Configuration for visualization including colormap, median/outlier styling. If None, uses default configuration.

axmatplotlib.axes.Axes, optional

Matplotlib Axes object to plot on. If None, creates new figure and axes.

Returns:

axmatplotlib.axes.Axes

The Axes object with the contour boxplot visualization.

Notes:

  • Uses ax.imshow() to display the aggregated percentile bands with colormap

  • Uses ax.contour() at isovalue 0.5 to plot median and outlier contour lines

  • Colorbar shows percentile values from 0-100

  • Legend indicates median and outliers

Examples:

>>> stats = contour_boxplot_summary_statistics(ensemble, isovalue=0.5)
>>> mesh_data = contour_boxplot_mesh(stats)
>>> ax = visualize_contour_boxplot(mesh_data)

Module contents

ContourBoxplot Module

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

Modules.ContourBoxplot.contour_boxplot(ensemble_images, isovalue, boxplot_style=None, ax=None, workers=11)[source]

Create a contour boxplot visualization from an ensemble of scalar fields.

This function processes ensemble images by extracting binary contours at a given isovalue, computing their band depths, and visualizing the uncertainty using band envelopes.

Parameters:

ensemble_imagesnp.ndarray

3D or 4D array containing the ensemble scalar fields. Can be shape (n_ensemble, y_dim, x_dim) or will be rearranged to this format.

isovaluefloat

Threshold value for creating binary images. Pixels with values < isovalue are set to 1.

boxplot_styleBoxplotStyleConfig, optional

Configuration for the boxplot visualization including percentiles, and median/outlier styling. If None, uses default configuration. The percentile_colormap is used for the band sum visualization.

axmatplotlib.axes.Axes, optional

Matplotlib Axes object to plot on. If None, a new figure and axes will be created.

workersint, optional

Number of parallel workers for band depth computation. Default is 12.

Returns:

axmatplotlib.axes.Axes

The Axes object with the contour boxplot visualization.

Examples:

>>> # Basic usage with defaults
>>> ensemble = np.random.randn(50, 100, 100)  # 50 ensemble members
>>> ax = contour_boxplot(ensemble, isovalue=0.5)

>>> # Custom styling
>>> from uvisbox.Core.CommonInterface import BoxplotStyleConfig
>>> style = BoxplotStyleConfig(
...     percentiles=[25, 50, 75],
...     percentile_colormap='hot',
...     show_median=True,
...     show_outliers=True
... )
>>> ax = contour_boxplot(ensemble, isovalue=0.5, boxplot_style=style)
Modules.ContourBoxplot.contour_boxplot_mesh(summary_statistics)[source]

Process summary statistics to create mesh data for visualization.

This function aggregates percentile bands by overwriting values in descending percentile order, creating a single image that shows all bands with appropriate color values.

Parameters:

summary_statisticsdict

Dictionary from contour_boxplot_summary_statistics containing: - ‘median’: Binary image for median contour - ‘percentile_bands’: List of (percentile, band_image) tuples - ‘outliers’: List of outlier binary images

Returns:

dict

Dictionary containing: - ‘percentile_bands_image’: 2D array where each pixel value represents the percentile/100

it belongs to. Lower percentiles overwrite higher ones.

  • ‘median’: Binary image (unchanged from input)

  • ‘outliers’: List of binary images (unchanged from input)

Notes:

The aggregation works by: 1. Starting with highest percentile band (e.g., 90th) 2. Painting pixels with value 0.90 where band is non-zero 3. Overwriting with lower percentile bands (e.g., 75th → 0.75) 4. Continuing until lowest percentile This creates a layered visualization where inner bands overwrite outer bands.

Examples:

>>> stats = contour_boxplot_summary_statistics(ensemble, isovalue=0.5)
>>> mesh_data = contour_boxplot_mesh(stats)
>>> print(mesh_data['percentile_bands_image'].shape)
(100, 100)
Modules.ContourBoxplot.contour_boxplot_summary_statistics(ensemble_images, isovalue, boxplot_style=None, workers=11)[source]

Compute summary statistics for contour boxplot from ensemble scalar fields.

This function extracts binary contours at the given isovalue, computes their band depths, and generates percentile bands, median, and outlier information.

Parameters:

ensemble_imagesnp.ndarray

3D array of shape (n_ensemble, height, width) containing ensemble scalar fields.

isovaluefloat

Threshold value for creating binary images. Pixels with values < isovalue are set to 1 (inside), values >= isovalue are set to 0 (outside).

boxplot_styleBoxplotStyleConfig, optional

Configuration for percentiles and outlier detection. If None, uses default configuration.

workersint, optional

Number of parallel workers for band depth computation. Default is 11.

Returns:

dict

Dictionary containing: - ‘median’: Binary image (np.ndarray) representing the median contour sublevel set.

1 = inside contour (value < isovalue), 0 = outside contour (value >= isovalue).

  • ‘percentile_bands’: List of tuples (percentile, band_image) where band_image is a 2D array

    with values in [0, percentile/100]. percentile/100 means inside the band, 0 means outside the band.

  • ‘outliers’: List of binary images representing outlier contours (same format as median).

  • ‘sorted_contours’: 3D array (n_ensemble, height, width) of binary images sorted by depth.

  • ‘sorted_indices’: Array of indices showing the original order of sorted contours.

  • ‘depths’: Array of computed band depth values for each contour.

Examples:

>>> ensemble = np.random.randn(50, 100, 100)
>>> stats = contour_boxplot_summary_statistics(ensemble, isovalue=0.5)
>>> print(stats.keys())
dict_keys(['median', 'percentile_bands', 'outliers', 'sorted_contours', 'sorted_indices', 'depths'])
Modules.ContourBoxplot.visualize_contour_boxplot(mesh_data, boxplot_style=None, ax=None)[source]

Visualize contour boxplot using imshow for percentile bands and contour for median/outliers.

Parameters:

mesh_datadict

Dictionary from contour_boxplot_mesh containing: - ‘percentile_bands_image’: 2D array with aggregated percentile band values - ‘median’: Binary image for median contour - ‘outliers’: List of binary images for outlier contours

boxplot_styleBoxplotStyleConfig, optional

Configuration for visualization including colormap, median/outlier styling. If None, uses default configuration.

axmatplotlib.axes.Axes, optional

Matplotlib Axes object to plot on. If None, creates new figure and axes.

Returns:

axmatplotlib.axes.Axes

The Axes object with the contour boxplot visualization.

Notes:

  • Uses ax.imshow() to display the aggregated percentile bands with colormap

  • Uses ax.contour() at isovalue 0.5 to plot median and outlier contour lines

  • Colorbar shows percentile values from 0-100

  • Legend indicates median and outliers

Examples:

>>> stats = contour_boxplot_summary_statistics(ensemble, isovalue=0.5)
>>> mesh_data = contour_boxplot_mesh(stats)
>>> ax = visualize_contour_boxplot(mesh_data)