Modules.FunctionalBoxplot package

Submodules

Modules.FunctionalBoxplot.functional_boxplot module

Modules.FunctionalBoxplot.functional_boxplot.functional_boxplot(data, method='fbd', vmin=0, vmax=1, boxplot_style=None, ax=None)

Create a functional band depth boxplot with multiple percentile bands.

This function computes functional band depths, plots bands in descending percentile order (largest to smallest for proper layering), and highlights the median curve.

Parameters:

datanp.ndarray

2D array of shape (N, D) where N is the number of curves and D is the number of points per curve.

methodstr, optional

Method for computing band depth. Options are: - ‘fbd’: functional band depth (default) - ‘mfbd’: modified functional band depth

boxplot_styleBoxplotStyleConfig, optional

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

axmatplotlib.axes.Axes, optional

Matplotlib axes to plot on. If None, creates a new figure.

Returns:

axmatplotlib.axes.Axes

The matplotlib axes object with the plot.

Raises:

ValueError

If data is not 2D or if method is invalid.

Notes:

• Input data is not modified (computation happens on a copy)

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

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

• Outliers are curves beyond the largest percentile

• Curve depths are always computed internally

Examples:

>>> import numpy as np
>>> from uvisbox.Modules.FunctionalBoxplot import functional_boxplot
>>> from uvisbox.Core.CommonInterface import BoxplotStyleConfig
>>>
>>> # Generate synthetic functional data
>>> t = np.linspace(0, 1, 100)
>>> data = np.array([np.sin(2*np.pi*t) + 0.2*np.random.randn(100) for _ in range(50)])
>>>
>>> # Basic usage with default settings
>>> ax = functional_boxplot(data)
>>>
>>> # Custom styling
>>> style = BoxplotStyleConfig(
...     percentiles=[10, 50, 90],
...     percentile_colormap='plasma',
...     show_median=True,
...     show_outliers=True
... )
>>> ax = functional_boxplot(data, boxplot_style=style)
>>>
>>> # Plot on existing axes
>>> import matplotlib.pyplot as plt
>>> fig, ax = plt.subplots(figsize=(12, 6))
>>> functional_boxplot(data, ax=ax)
>>> plt.show()

Modules.FunctionalBoxplot.functional_boxplot_mesh module

Modules.FunctionalBoxplot.functional_boxplot_mesh.functional_boxplot_mesh(summary_stats)

Identity function that ensures consistent data processing pipeline.

This function passes through the summary statistics unchanged, maintaining compatibility with the standard data processing pipeline (stats -> mesh -> vis).

Parameters:

summary_statsdict

Dictionary of summary statistics from functional_boxplot_summary_statistics() function. Expected to contain keys like ‘depths’, ‘median’, ‘percentile_bands’, ‘outliers’, ‘sorted_curves’, and ‘sorted_indices’.

Returns:

summary_statsdict

The same dictionary passed as input, unchanged.

Examples:

>>> from uvisbox.Modules.FunctionalBoxplot.functional_boxplot_stats import functional_boxplot_summary_statistics
>>> from uvisbox.Modules.FunctionalBoxplot.functional_boxplot_mesh import functional_boxplot_mesh
>>>
>>> # Generate data and compute statistics
>>> import numpy as np
>>> data = np.random.randn(100, 50)
>>> stats = functional_boxplot_summary_statistics(data)
>>>
>>> # Pass through mesh stage (identity operation)
>>> mesh_data = functional_boxplot_mesh(stats)
>>>
>>> # mesh_data is identical to stats
>>> assert mesh_data is stats

Modules.FunctionalBoxplot.functional_boxplot_stats module

Modules.FunctionalBoxplot.functional_boxplot_stats.functional_boxplot_band_depths(data, method='fbd')

Compute band depths for a set of functional curves.

Parameters:

curvesnp.ndarray

2D array of shape (N, D) where N is the number of curves and D is the number of points per curve.

methodstr, optional

Method for computing band depth. Options are: - ‘fbd’: Functional band depth (default) - ‘mfbd’: Modified functional band depth

Modules.FunctionalBoxplot.functional_boxplot_stats.functional_boxplot_get_band(data, percentile, method='fbd')

Compute the band envelope for a given percentile using functional band depth.

Parameters:

datanp.ndarray

2D array of shape (N, D) where N is the number of curves and D is the number of points per curve.

percentilefloat

Percentile value (0-100) for the band envelope.

methodstr, optional

Method for computing band depth. Options are: - ‘fbd’: functional band depth (default) - ‘mfbd’: modified functional band depth

Returns:

bottom_curvenp.ndarray

1D array representing the bottom envelope of the band.

top_curvenp.ndarray

1D array representing the top envelope of the band.

Examples:

>>> data = np.random.randn(100, 50)  # 100 curves, 50 points each
>>> bottom, top = functional_boxplot_get_band(data, 50, method='fbd')  # 50th percentile band

Modules.FunctionalBoxplot.functional_boxplot_stats.functional_boxplot_summary_statistics(data, method='fbd', boxplot_style=None)

Compute functional boxplot summary statistics without visualization.

This function computes the same statistics as functional_boxplot but returns them as numpy arrays in a dictionary instead of creating a plot.

Parameters:

datanp.ndarray

2D array of shape (N, D) where N is the number of curves and D is the number of points per curve.

methodstr, optional

Method for computing band depth. Options are: - ‘fbd’: functional band depth (default) - ‘mfbd’: modified functional band depth

boxplot_styleBoxplotStyleConfig, optional

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

Returns:

statsdict

Dictionary containing the following keys: - ‘depths’: np.ndarray of shape (N,) - band depths for each curve - ‘median’: np.ndarray of shape (D,) - median curve (highest depth) - ‘percentile_bands’: dict - percentile bands with keys like ‘25_percentile_band’

containing tuples (bottom_curve, top_curve) of shape (D,) each

• ‘outliers’: np.ndarray of shape (n_outliers, D) - outlier curves beyond largest percentile

• ‘sorted_curves’: np.ndarray of shape (N, D) - curves sorted by depth (descending)

• ‘sorted_indices’: np.ndarray of shape (N,) - original indices sorted by depth

Raises:

ValueError

If data is not 2D or if method is invalid.

Examples:

>>> import numpy as np
>>> from uvisbox.Modules.FunctionalBoxplot.functional_boxplot_stats import functional_boxplot_summary_statistics
>>> from uvisbox.Core.CommonInterface import BoxplotStyleConfig
>>>
>>> # Generate synthetic functional data
>>> t = np.linspace(0, 1, 100)
>>> data = np.array([np.sin(2*np.pi*t) + 0.2*np.random.randn(100) for _ in range(50)])
>>>
>>> # Basic usage with default settings
>>> stats = functional_boxplot_summary_statistics(data)
>>> print(f"Median curve shape: {stats['median'].shape}")
>>> print(f"Number of outliers: {stats['outliers'].shape[0]}")
>>> print(f"Available percentile bands: {list(stats['percentile_bands'].keys())}")
>>>
>>> # Access specific percentile band
>>> bottom_25, top_25 = stats['percentile_bands']['25_percentile_band']
>>> print(f"25th percentile band shapes: {bottom_25.shape}, {top_25.shape}")
>>>
>>> # Custom percentiles
>>> style = BoxplotStyleConfig(percentiles=[10, 50, 90], show_outliers=True)
>>> stats = functional_boxplot_summary_statistics(data, boxplot_style=style)

Modules.FunctionalBoxplot.functional_boxplot_vis module

Modules.FunctionalBoxplot.functional_boxplot_vis.plot_band(bottom_curve, top_curve, vmin=0, vmax=1, ax=None, color='red', alpha=1.0, scale=1.0)

Plot a functional band envelope between bottom and top curves.

This function creates a filled area between the curves using matplotlib’s fill_between.

Parameters:

bottom_curvenp.ndarray

1D array representing the bottom boundary of the band.

top_curvenp.ndarray

1D array representing the top boundary of the band.

axmatplotlib.axes.Axes, optional

Matplotlib axes to plot on. If None, creates new figure with axes.

colorstr or tuple, optional

Color for the band. Default is ‘red’. Can be any matplotlib color specification (named color, hex, RGB tuple, etc.).

alphafloat, optional

Transparency of the band (0=transparent, 1=opaque). Default is 1.0.

scalefloat, optional

Scale factor for the curves. Default is 1.0.

Returns:

axmatplotlib.axes.Axes

The matplotlib axes object used for plotting.

Raises:

ValueError

If bottom_curve and top_curve have different shapes.

Examples:

>>> import numpy as np
>>> import matplotlib.pyplot as plt
>>> from uvisbox.Modules.FunctionalBoxplot import plot_band
>>> from uvisbox.Modules.FunctionalBoxplot.functional_boxplot_stats import functional_boxplot_get_band
>>>
>>> # Generate synthetic data
>>> data = np.random.randn(100, 50).cumsum(axis=1)
>>>
>>> # Get 50th percentile band
>>> bottom, top = functional_boxplot_get_band(data, 50, method='fbd')
>>>
>>> # Plot the band
>>> fig, ax = plt.subplots()
>>> plot_band(bottom, top, ax=ax, color='blue', alpha=0.5)
>>> plt.show()

Modules.FunctionalBoxplot.functional_boxplot_vis.visualize_functional_boxplot(mesh_data, vmin=0, vmax=1, boxplot_style=None, ax=None)

Visualize functional boxplot from mesh data (summary statistics).

This function creates a matplotlib visualization of the functional boxplot using the summary statistics output from the stats/mesh pipeline.

Parameters:

mesh_datadict

Dictionary containing summary statistics with the following keys: - ‘percentile_bands’: dict of percentile bands - ‘median’: median curve - ‘outliers’: outlier curves - ‘sorted_curves’: all curves sorted by depth

boxplot_styleBoxplotStyleConfig, optional

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

axmatplotlib.axes.Axes, optional

Matplotlib axes to plot on. If None, creates a new figure.

Returns:

axmatplotlib.axes.Axes

The matplotlib axes object with the plot.

Examples:

>>> import numpy as np
>>> from uvisbox.Modules.FunctionalBoxplot.functional_boxplot_stats import functional_boxplot_summary_statistics
>>> from uvisbox.Modules.FunctionalBoxplot.functional_boxplot_mesh import functional_boxplot_mesh
>>> from uvisbox.Modules.FunctionalBoxplot.functional_boxplot_vis import visualize_functional_boxplot
>>> from uvisbox.Core.CommonInterface import BoxplotStyleConfig
>>>
>>> # Generate synthetic functional data
>>> t = np.linspace(0, 1, 100)
>>> data = np.array([np.sin(2*np.pi*t) + 0.2*np.random.randn(100) for _ in range(50)])
>>>
>>> # Process through pipeline
>>> stats = functional_boxplot_summary_statistics(data)
>>> mesh_data = functional_boxplot_mesh(stats)
>>>
>>> # Visualize
>>> ax = visualize_functional_boxplot(mesh_data)
>>>
>>> # Custom styling
>>> style = BoxplotStyleConfig(percentiles=[25, 50, 75, 90], show_outliers=True)
>>> ax = visualize_functional_boxplot(mesh_data, boxplot_style=style)

Module contents

FunctionalBoxplot Module

This module provides functional boxplot functionality for uncertainty visualization.

Modules.FunctionalBoxplot.functional_boxplot(data, method='fbd', vmin=0, vmax=1, boxplot_style=None, ax=None)

Create a functional band depth boxplot with multiple percentile bands.

This function computes functional band depths, plots bands in descending percentile order (largest to smallest for proper layering), and highlights the median curve.

Parameters:

datanp.ndarray

2D array of shape (N, D) where N is the number of curves and D is the number of points per curve.

methodstr, optional

Method for computing band depth. Options are: - ‘fbd’: functional band depth (default) - ‘mfbd’: modified functional band depth

boxplot_styleBoxplotStyleConfig, optional

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

axmatplotlib.axes.Axes, optional

Matplotlib axes to plot on. If None, creates a new figure.

Returns:

axmatplotlib.axes.Axes

The matplotlib axes object with the plot.

Raises:

ValueError

If data is not 2D or if method is invalid.

Notes:

• Input data is not modified (computation happens on a copy)

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

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

• Outliers are curves beyond the largest percentile

• Curve depths are always computed internally

Examples:

>>> import numpy as np
>>> from uvisbox.Modules.FunctionalBoxplot import functional_boxplot
>>> from uvisbox.Core.CommonInterface import BoxplotStyleConfig
>>>
>>> # Generate synthetic functional data
>>> t = np.linspace(0, 1, 100)
>>> data = np.array([np.sin(2*np.pi*t) + 0.2*np.random.randn(100) for _ in range(50)])
>>>
>>> # Basic usage with default settings
>>> ax = functional_boxplot(data)
>>>
>>> # Custom styling
>>> style = BoxplotStyleConfig(
...     percentiles=[10, 50, 90],
...     percentile_colormap='plasma',
...     show_median=True,
...     show_outliers=True
... )
>>> ax = functional_boxplot(data, boxplot_style=style)
>>>
>>> # Plot on existing axes
>>> import matplotlib.pyplot as plt
>>> fig, ax = plt.subplots(figsize=(12, 6))
>>> functional_boxplot(data, ax=ax)
>>> plt.show()

Modules.FunctionalBoxplot.functional_boxplot_mesh(summary_stats)

Identity function that ensures consistent data processing pipeline.

This function passes through the summary statistics unchanged, maintaining compatibility with the standard data processing pipeline (stats -> mesh -> vis).

Parameters:

summary_statsdict

Dictionary of summary statistics from functional_boxplot_summary_statistics() function. Expected to contain keys like ‘depths’, ‘median’, ‘percentile_bands’, ‘outliers’, ‘sorted_curves’, and ‘sorted_indices’.

Returns:

summary_statsdict

The same dictionary passed as input, unchanged.

Examples:

>>> from uvisbox.Modules.FunctionalBoxplot.functional_boxplot_stats import functional_boxplot_summary_statistics
>>> from uvisbox.Modules.FunctionalBoxplot.functional_boxplot_mesh import functional_boxplot_mesh
>>>
>>> # Generate data and compute statistics
>>> import numpy as np
>>> data = np.random.randn(100, 50)
>>> stats = functional_boxplot_summary_statistics(data)
>>>
>>> # Pass through mesh stage (identity operation)
>>> mesh_data = functional_boxplot_mesh(stats)
>>>
>>> # mesh_data is identical to stats
>>> assert mesh_data is stats

Modules.FunctionalBoxplot.functional_boxplot_summary_statistics(data, method='fbd', boxplot_style=None)

Compute functional boxplot summary statistics without visualization.

This function computes the same statistics as functional_boxplot but returns them as numpy arrays in a dictionary instead of creating a plot.

Parameters:

datanp.ndarray

2D array of shape (N, D) where N is the number of curves and D is the number of points per curve.

methodstr, optional

Method for computing band depth. Options are: - ‘fbd’: functional band depth (default) - ‘mfbd’: modified functional band depth

boxplot_styleBoxplotStyleConfig, optional

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

Returns:

statsdict

Dictionary containing the following keys: - ‘depths’: np.ndarray of shape (N,) - band depths for each curve - ‘median’: np.ndarray of shape (D,) - median curve (highest depth) - ‘percentile_bands’: dict - percentile bands with keys like ‘25_percentile_band’

containing tuples (bottom_curve, top_curve) of shape (D,) each

• ‘outliers’: np.ndarray of shape (n_outliers, D) - outlier curves beyond largest percentile

• ‘sorted_curves’: np.ndarray of shape (N, D) - curves sorted by depth (descending)

• ‘sorted_indices’: np.ndarray of shape (N,) - original indices sorted by depth

Raises:

ValueError

If data is not 2D or if method is invalid.

Examples:

>>> import numpy as np
>>> from uvisbox.Modules.FunctionalBoxplot.functional_boxplot_stats import functional_boxplot_summary_statistics
>>> from uvisbox.Core.CommonInterface import BoxplotStyleConfig
>>>
>>> # Generate synthetic functional data
>>> t = np.linspace(0, 1, 100)
>>> data = np.array([np.sin(2*np.pi*t) + 0.2*np.random.randn(100) for _ in range(50)])
>>>
>>> # Basic usage with default settings
>>> stats = functional_boxplot_summary_statistics(data)
>>> print(f"Median curve shape: {stats['median'].shape}")
>>> print(f"Number of outliers: {stats['outliers'].shape[0]}")
>>> print(f"Available percentile bands: {list(stats['percentile_bands'].keys())}")
>>>
>>> # Access specific percentile band
>>> bottom_25, top_25 = stats['percentile_bands']['25_percentile_band']
>>> print(f"25th percentile band shapes: {bottom_25.shape}, {top_25.shape}")
>>>
>>> # Custom percentiles
>>> style = BoxplotStyleConfig(percentiles=[10, 50, 90], show_outliers=True)
>>> stats = functional_boxplot_summary_statistics(data, boxplot_style=style)

Modules.FunctionalBoxplot.visualize_functional_boxplot(mesh_data, vmin=0, vmax=1, boxplot_style=None, ax=None)

Visualize functional boxplot from mesh data (summary statistics).

This function creates a matplotlib visualization of the functional boxplot using the summary statistics output from the stats/mesh pipeline.

Parameters:

mesh_datadict

Dictionary containing summary statistics with the following keys: - ‘percentile_bands’: dict of percentile bands - ‘median’: median curve - ‘outliers’: outlier curves - ‘sorted_curves’: all curves sorted by depth

boxplot_styleBoxplotStyleConfig, optional

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

axmatplotlib.axes.Axes, optional

Matplotlib axes to plot on. If None, creates a new figure.

Returns:

axmatplotlib.axes.Axes

The matplotlib axes object with the plot.

Examples:

>>> import numpy as np
>>> from uvisbox.Modules.FunctionalBoxplot.functional_boxplot_stats import functional_boxplot_summary_statistics
>>> from uvisbox.Modules.FunctionalBoxplot.functional_boxplot_mesh import functional_boxplot_mesh
>>> from uvisbox.Modules.FunctionalBoxplot.functional_boxplot_vis import visualize_functional_boxplot
>>> from uvisbox.Core.CommonInterface import BoxplotStyleConfig
>>>
>>> # Generate synthetic functional data
>>> t = np.linspace(0, 1, 100)
>>> data = np.array([np.sin(2*np.pi*t) + 0.2*np.random.randn(100) for _ in range(50)])
>>>
>>> # Process through pipeline
>>> stats = functional_boxplot_summary_statistics(data)
>>> mesh_data = functional_boxplot_mesh(stats)
>>>
>>> # Visualize
>>> ax = visualize_functional_boxplot(mesh_data)
>>>
>>> # Custom styling
>>> style = BoxplotStyleConfig(percentiles=[25, 50, 75, 90], show_outliers=True)
>>> ax = visualize_functional_boxplot(mesh_data, boxplot_style=style)