Core.BandDepths package

Submodules

Core.BandDepths.contour_banddepth module

Core.BandDepths.contour_banddepth.choose2(x)

Helper function to compute x choose 2

Parameters:

xint

number of elements

Returns:

[]int

x choose 2

Core.BandDepths.contour_banddepth.contour_banddepth(data, combination=None, allow_portion=False, eps=0)

Calculates the band depth of binary contour data using pairwise combinations. R. T. Whitaker, M. Mirzargar and R. M. Kirby, “Contour Boxplots: A Method for Characterizing Uncertainty in Feature Sets from Simulation Ensembles,” in IEEE Transactions on Visualization and Computer Graphics, vol. 19, no. 12, pp. 2713-2722, Dec. 2013, doi: 10.1109/TVCG.2013.143

Parameters:

datanp.ndarray

Input data representing binary contours. Should be convertible to a boolean NumPy array.

combinationlist of tuples, optional

List of index pairs (xdx, ydx) specifying which images to combine for band depth calculation. If None, combinations are generated automatically.

allow_portionbool, default False

If True, uses a portion-based subset calculation for depth; otherwise, uses epsilon-based subset.

epsfloat, default 0

Epsilon tolerance for subset checks when allow_portion is False.

Returns:

depthsnp.ndarray

Array of band depth values for each image in the input data.

raises ValueError::

If the input data cannot be converted to a boolean array.

Notes

• The function expects binary contour data, where each image is represented as a boolean array.

• Depth is computed by evaluating how each image fits within the intersection and union of pairs of images.

• Helper functions _portion_subset and _epsilon_subset are used for subset checks.

Core.BandDepths.contour_banddepth.get_combinations(n)

returns (n_combination, 2) as list of pair of indices for n elements, get all 2-subsets

Parameters:

nint

number of elements

Returns:

combinationsnp.ndarray

array of shape (n_choose_2, 2)

Core.BandDepths.curve_banddepth module

Core.BandDepths.curve_banddepth.curve_banddepths(curves, indices=None)

Calculate band depth for curves based on how often each curve’s points lie within convex hulls formed by bands of other curves. M. Mirzargar, R. T. Whitaker and R. M. Kirby, “Curve Boxplot: Generalization of Boxplot for Ensembles of Curves,” in IEEE Transactions on Visualization and Computer Graphics, vol. 20, no. 12, pp. 2654-2663, 31 Dec. 2014, doi: 10.1109/TVCG.2014.2346455.

Parameters:

curvesnumpy.ndarray

3D array of shape (n_curves, n_steps, n_dims) containing curve data

indiceslist of lists

Each inner list contains indices of curves that form a band indices can be created by itertools.combinations(range(n_curves), k) for some k recommended caching for indices

Returns:

numpy.ndarray

1D array of normalized depth scores for each curve

Core.BandDepths.curve_banddepth.point_in_hull(point, hull_or_vertices, eps=1e-06)

Check if a point is inside a convex hull.

Parameters:

pointarray-like

The coordinates of the point to check. Should be a 1D array or list of length equal to the dimension of the hull.

hull_or_verticesscipy.spatial.ConvexHull or array-like

Either a SciPy ConvexHull object, or an array/list of vertices that define the convex hull. If vertices are provided, a ConvexHull object will be constructed internally.

epsfloat, optional

Tolerance for numerical precision when checking if the point is inside the hull. Default is 1e-6.

Returns:

bool

True if the point is inside the convex hull (within the specified tolerance), False otherwise.

raises ValueError:

If hull_or_vertices is not a ConvexHull object, ndarray, or list of vertices.

Notes

• The function uses the hull’s half-space equations to determine if the point is inside.

• Points on the boundary (within eps tolerance) are considered inside.

Core.BandDepths.functional_banddepth module

Core.BandDepths.functional_banddepth.calculate_band(sorted_curves, percentile)

Core.BandDepths.functional_banddepth.fdb(data, dtype=<class 'numpy.float64'>)

Compute the functional band depth of the input data. The band is assumed to be formed by 2-subsets This implements Sun, Y., Genton, M.G. and Nychka, D.W. (2012), Exact fast computation of band depth for large functional datasets: How quickly can one million curves be ranked?. Stat, 1: 68-74. https://doi.org/10.1002/sta4.8 Data is a 2D array of shape (N, D)

Parameters:

datanp.ndarray

2D array of shape (N, D) where N is the number of samples and D is the number of features

dtypedata-type, optional

Desired data-type for the computation (default is np.float64)

Returns:

band_depthsnp.ndarray

1D array of band depths of shape (N,)

Core.BandDepths.functional_banddepth.functional_banddepth(data, dtype=<class 'numpy.float64'>)

Compute the functional band depth of the input data. The band is assumed to be formed by 2-subsets This implements Sun, Y., Genton, M.G. and Nychka, D.W. (2012), Exact fast computation of band depth for large functional datasets: How quickly can one million curves be ranked?. Stat, 1: 68-74. https://doi.org/10.1002/sta4.8 Data is a 2D array of shape (N, D)

Parameters:

datanp.ndarray

2D array of shape (N, D) where N is the number of samples and D is the number of features

dtypedata-type, optional

Desired data-type for the computation (default is np.float64)

Returns:

band_depthsnp.ndarray

1D array of band depths of shape (N,)

Core.BandDepths.functional_banddepth.mdb(data, dtype=<class 'numpy.float64'>)

Compute the modified functional band depth of the input data The band is assumed to be formed by 2-subsets This implements Sun, Y., Genton, M.G. and Nychka, D.W. (2012), Exact fast computation of band depth for large functional datasets: How quickly can one million curves be ranked?. Stat, 1: 68-74. https://doi.org/10.1002/sta4.8 Data is a 2D array of shape (N, D) Parameters: ———– data : np.ndarray

2D array of shape (N, D) where N is the number of samples and D is the number of features

dtypedata-type, optional

Desired data-type for the computation (default is np.float64)

Returns:

band_depthsnp.ndarray

1D array of band depths of shape (N,)

Core.BandDepths.functional_banddepth.modified_functional_banddepth(data, dtype=<class 'numpy.float64'>)

Compute the modified functional band depth of the input data The band is assumed to be formed by 2-subsets This implements Sun, Y., Genton, M.G. and Nychka, D.W. (2012), Exact fast computation of band depth for large functional datasets: How quickly can one million curves be ranked?. Stat, 1: 68-74. https://doi.org/10.1002/sta4.8 Data is a 2D array of shape (N, D) Parameters: ———– data : np.ndarray

2D array of shape (N, D) where N is the number of samples and D is the number of features

dtypedata-type, optional

Desired data-type for the computation (default is np.float64)

Returns:

band_depthsnp.ndarray

1D array of band depths of shape (N,)

Core.BandDepths.vector_depths module

Core.BandDepths.vector_depths.angular_spread(vectors)

Calculate the angular spread and magnitude spread of a set of vectors.

Parameters:

vectors (numpy.ndarray) – Array of shape (n, 2) representing 2D Cartesian vectors.

Returns:

• angular_spread_deg (float) – The angular spread in degrees.

• magnitude_spread (float) – The magnitude spread.

• min_idx (int) – Index of the vector with the minimum angle.

• max_idx (int) – Index of the vector with the maximum angle.

Core.BandDepths.vector_depths.calculate_spread_2D(vectors, depths, percentil)

Calculate the spread in 2D polar coordinates. Parameters: ———–

vectorsnumpy.ndarray

Array of shape (n, 2) in polar coordinates (magnitude, angle)

depthsnumpy.ndarray

Array of shape (n,) representing the depth of each vector

percentilfloat

The percentile for depth filtering

Returns:

tuple

Indices of vectors with min/max magnitude, angle among those with depth > 1.0-percentil

Core.BandDepths.vector_depths.calculate_spread_3D(vectors, depths, percentil)

Calculate the spread in 3D spherical coordinates.

Parameters:

vectorsnumpy.ndarray

Array of shape (n, 3) in spherical coordinates (magnitude, theta, phi)

depthsnumpy.ndarray

Array of shape (n,) representing the depth of each vector

percentilfloat

The percentile for depth filtering

Returns:

tuple

Indices of vectors with min/max magnitude, theta, phi among those with depth > 1.0-percentil

Core.BandDepths.vector_depths.cartesian_to_polar(vectors)

Convert 2D Cartesian vectors to polar coordinates (magnitude, angle).

Parameters:

vectorsnumpy.ndarray

Array of shape (n, 2) representing 2D Cartesian vectors.

Returns:

polar_coordsnumpy.ndarray

Array of shape (n, 2) with columns [magnitude, angle in radians].

Core.BandDepths.vector_depths.cartesian_to_spherical(vectors)

Convert 3D Cartesian vectors to spherical coordinates (magnitude, theta, phi).

Parameters:

vectorsnumpy.ndarray

Array of shape (n, 3) representing 3D Cartesian vectors.

Returns:

spherical_coordsnumpy.ndarray

Array of shape (n, 3) with columns [magnitude, theta, phi].

Core.BandDepths.vector_depths.compute_vector_depths_2D(vectors)

Compute the depth of each vector in the ensemble. The vector depth calculation is based on T. A. J. Ouermi, J. Li, Z. Morrow, B. Van Bloemen Waanders and C. R. Johnson, “Glyph-Based Uncertainty Visualization and Analysis of Time-Varying Vector Fields,” 2024 IEEE Workshop on Uncertainty Visualization: Applications, Techniques, Software, and Decision Frameworks, St Pete Beach, FL, USA, 2024, pp. 73-77, doi: 10.1109/UncertaintyVisualization63963.2024.00014.

Parameters:

vectorsnumpy.ndarray

Array of shape (n, 2) representing 2D Cartesian vectors.

Returns:

depthsnumpy.ndarray

Array of shape (n,) with the depth of each vector.

Core.BandDepths.vector_depths.compute_vector_depths_3D(vectors)

Compute the depth of each vector in the ensemble in 3D. Assumes vectors are in spherical coordinates (magnitude, theta, phi). The vector depth calculation is based on T. A. J. Ouermi, J. Li, Z. Morrow, B. Van Bloemen Waanders and C. R. Johnson, “Glyph-Based Uncertainty Visualization and Analysis of Time-Varying Vector Fields,” 2024 IEEE Workshop on Uncertainty Visualization: Applications, Techniques, Software, and Decision Frameworks, St Pete Beach, FL, USA, 2024, pp. 73-77, doi: 10.1109/UncertaintyVisualization63963.2024.00014.

Parameters:

vectorsnumpy.ndarray

Array of shape (n, 3) representing 3D spherical coordinates.

Returns:

depthsnumpy.ndarray

Array of shape (n,) with the depth of each vector.

Core.BandDepths.vector_depths.magnitude_spread(vectors)

Calculate the magnitude spread of a set of vectors. :param vectors: Array of shape (n, 2) representing 2D Cartesian vectors. :type vectors: numpy.ndarray

Returns:

• magnitude_spread (float) – The magnitude spread.

• min_mag_idx (int) – Index of the vector with the minimum magnitude.

• max_mag_idx (int) – Index of the vector with the maximum magnitude.

Module contents

Core BandDepths Module

This module contains core statistical methods for band depth calculations. These are fundamental algorithms used across the UVisBox package.