uvisbox.Modules.FunctionalBoxplot.functional_boxplot
====================================================

.. py:module:: uvisbox.Modules.FunctionalBoxplot.functional_boxplot




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

.. py:function:: 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.

   :param data: 2D array of shape (N, D) where N is the number of curves and D is the number
                of points per curve.
   :type data: np.ndarray
   :param method: Method for computing band depth. Options are:
                  - 'fbd': functional band depth (default)
                  - 'mfbd': modified functional band depth
   :type method: str, optional
   :param boxplot_style: Configuration for the boxplot visualization including percentiles, colormap,
                         and median/outlier styling. If None, uses default configuration.
   :type boxplot_style: BoxplotStyleConfig, optional
   :param ax: Matplotlib axes to plot on. If None, creates a new figure.
   :type ax: matplotlib.axes.Axes, optional

   :returns: **ax** -- The matplotlib axes object with the plot.
   :rtype: matplotlib.axes.Axes

   :raises ValueError: If data is not 2D or if method is invalid.

   .. rubric:: 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

   .. rubric:: 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()