hbutils.collection.dimension

Dimension operations for multi-dimensional array structures.

This module provides utilities for working with nested list/tuple structures that represent multi-dimensional arrays (cubes). It includes functions for:

These operations are useful for manipulating nested data structures without requiring external dependencies like NumPy.

Example:

>>> from hbutils.collection.dimension import cube_shape, dimension_switch, swap_2d
>>> cube_shape([[1, 2, 3], [4, 5, 6]])
(2, 3)
>>> dimension_switch([[1, 2, 3], [4, 5, 6]], (1, 0))
[[1, 4], [2, 5], [3, 6]]
>>> swap_2d([[1, 2, 3], [4, 5, 6]])
[[1, 4], [2, 5], [3, 6]]

Note

These utilities operate on standard Python list/tuple structures and will return lists when building new arrays.

__all__

hbutils.collection.dimension.__all__ = ['cube_shape', 'dimension_switch', 'swap_2d']

Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

cube_shape

hbutils.collection.dimension.cube_shape(c: Any) → Tuple[int, ...][source]

Get the shape of a cube array (nested list/tuple structure).

This function analyzes a nested list or tuple structure and returns its shape as a tuple of dimensions. The structure must be a valid “cube” where all elements at the same nesting level have consistent shapes. If the input is not a list or tuple, an empty shape tuple is returned.

Parameters:

c (list or tuple or any) – The cube array to analyze (nested list/tuple structure).

Returns:

Shape of the cube as a tuple of dimension sizes.

Return type:

tuple

Raises:

ValueError – If the structure is not a valid cube (inconsistent shapes).

Examples::
>>> import numpy
>>> from hbutils.collection import cube_shape
>>> a = numpy.random.randint(-5, 15, (3, 5, 7, 9)).tolist()
>>> cube_shape(a)
(3, 5, 7, 9)

>>> # 2D example
>>> cube_shape([[1, 2, 3], [4, 5, 6]])
(2, 3)

>>> # Invalid cube (mismatched dimensions)
>>> cube_shape([[1, 2], [3, 4, 5]])
Traceback (most recent call last):
...
ValueError: ('Mismatching between (0,) and (1,), this is not a cube!', ((0,), (2,)), ((1,), (3,)))

dimension_switch

hbutils.collection.dimension.dimension_switch(c: Sequence[Any], dimensions: Sequence[int]) → List[Any][source]

Switch (transpose) the dimensions of a cube array according to a specified order.

This function rearranges the dimensions of a multi-dimensional nested structure according to the provided dimension order. It is similar to NumPy’s transpose operation but works with nested Python lists/tuples.

Parameters:

  • c (list or tuple) – Multi-dimensional array (nested list/tuple structure).

  • dimensions (tuple or list) – New order of dimensions as a tuple/list of indices (0 to N-1). Each index should appear exactly once.

Returns:

Array with switched dimensions.

Return type:

list

Raises:

ValueError – If dimensions parameter is invalid (missing indices, duplicates, or out of range).

Examples::
>>> import numpy
>>> from hbutils.collection import cube_shape, dimension_switch
>>> a = numpy.random.randint(-5, 15, (3, 5, 7, 9)).tolist()
>>> cube_shape(a)
(3, 5, 7, 9)
>>> b = dimension_switch(a, (3, 0, 2, 1))
>>> cube_shape(b)
(9, 3, 7, 5)

>>> # 2D transpose example
>>> arr = [[1, 2, 3], [4, 5, 6]]
>>> dimension_switch(arr, (1, 0))
[[1, 4], [2, 5], [3, 6]]

swap_2d

hbutils.collection.dimension.swap_2d(c: Sequence[Sequence[Any]]) → List[Any][source]

Swap the dimensions of a 2D array (transpose rows and columns).

This is a convenience function that transposes a 2D nested list/tuple structure by swapping its two dimensions. It is equivalent to calling dimension_switch() with (1, 0).

Parameters:

c (list or tuple) – 2D array (nested list/tuple structure).

Returns:

Transposed 2D array.

Return type:

list

Examples::
>>> from hbutils.collection import swap_2d
>>> swap_2d([
...     [9, 6, 4, 11, 5, -2, 1],
...     [0, 0, 11, 5, 8, -4, 9],
...     [0, 2, 13, 7, 0, 13, 0]
... ])
[[9, 0, 0],
 [6, 0, 2],
 [4, 11, 13],
 [11, 5, 7],
 [5, 8, 0],
 [-2, -4, 13],
 [1, 9, 0]]

>>> # Simple example
>>> swap_2d([[1, 2, 3], [4, 5, 6]])
[[1, 4], [2, 5], [3, 6]]