ridgeplot._utils module¶

Miscellaneous utilities and helper functions.

ridgeplot._utils.get_xy_extrema(densities)[source]¶

Get the global x-y extrema (x_min, x_max, y_min, y_max) over all DensityTraces in the Densities array.

Parameters:: densities – A Densities array.
Returns:: A tuple of the form (x_min, x_max, y_min, y_max).
Return type:: Tuple[Numeric, Numeric, Numeric, Numeric]

Examples

>>> get_xy_extrema(
...     [
...         [
...             [(0, 0), (1, 1), (2, 2), (3, 3)],
...             [(0, 0), (1, 1), (2, 2)],
...             [(0, 0), (1, 1), (2, 2), (3, 3), (4, 4)],
...         ],
...         [
...             [(-2, 2), (-1, 1), (0, 1)],
...             [(2, 2), (3, 1), (4, 1)],
...         ],
...     ]
... )
(-2, 4, 0, 4)

ridgeplot._utils.normalise_min_max(val, min_, max_)[source]¶

ridgeplot._utils.get_collection_array_shape(arr)[source]¶

Return the shape of a Collection array.

Parameters:: arr – The Collection array.
Returns:: The elements of the shape tuple give the lengths of the corresponding array dimensions. If the length of a dimension is variable, the corresponding element is a set of the variable lengths. Otherwise, (if the length of a dimension is fixed), the corresponding element is an int.
Return type:: Tuple[Union[int, Set[int]], ]

Examples

>>> get_collection_array_shape([])
(0,)

>>> get_collection_array_shape([1, 2, 3])
(3,)

>>> get_collection_array_shape([[1, 2, 3], [4, 5], [6], []])
(4, {0, 1, 2, 3})

>>> get_collection_array_shape(
...     [
...         [
...             [1, 2, 3], [4, 5]
...         ],
...         [
...             [6, 7, 8, 9],
...         ],
...     ]
... )
(2, {1, 2}, {2, 3, 4})

>>> get_collection_array_shape(
...     [
...         [
...             [1], [2, 3], [4, 5, 6],
...         ],
...         [
...             [7, 8, 9, 10, 11],
...         ],
...     ]
... )
(2, {1, 3}, {1, 2, 3, 5})

>>> get_collection_array_shape(
...     [
...         [
...             [(0, 0), (1, 1), (2, 2), (3, 3)],
...             [(0, 0), (1, 1), (2, 2)],
...             [(0, 0), (1, 1), (2, 2), (3, 3), (4, 4)],
...         ],
...         [
...             [(-2, 2), (-1, 1), (0, 1)],
...             [(2, 2), (3, 1), (4, 1)],
...         ],
...     ]
... )
(2, {2, 3}, {3, 4, 5}, 2)

>>> get_collection_array_shape(
...     [
...         [
...             ["a", "b", "c", "d"],
...             ["e", "f"],
...         ],
...         [
...             ["h", "i", "j", "k", "l"],
...             [],
...         ],
...     ]
... )
(2, 2, {0, 2, 4, 5})

>>> get_collection_array_shape("I'm not a collection")
Traceback (most recent call last):
...
TypeError: Expected a Collection. Got <class 'str'> instead.

ridgeplot._utils.ordered_dedup(seq)[source]¶

Return a list with the elements of seq in the order they first appear.

Parameters:: seq – A sequence.
Returns:: A list with the elements of seq in the order they first appear.
Return type:: list

Examples

>>> ordered_dedup([1, 2, 3, 1, 2, 3, 1, 2, 3])
[1, 2, 3]

>>> ordered_dedup([1, 2, 3, 4, 5, 6])
[1, 2, 3, 4, 5, 6]

>>> ordered_dedup([1, 1, 1, 1, 1, 1, 1, 1, 1])
[1]

>>> ordered_dedup([1, 2, 3, 3, 2, 1])
[1, 2, 3]

>>> ordered_dedup([3, 1, 2, 4, 2, 4, 5])
[3, 1, 2, 4, 5]

ridgeplot._utils.normalise_row_attrs(attrs, l2_target)[source]¶

Validate and normalise the attributes over a CollectionL2 array such that the number of attributes matches the number of traces in each row.

Parameters:

attrs – The attributes collection to normalise.
l2_target – The densities or samples array to normalise the attributes over.

Returns:

The normalised attributes collection.

Return type:

CollectionL2

Raises:

ValueError – If the number of traces does not match the number of attributes for a row.

Examples

>>> densities = [
...     [                                             # Row 1
...         [(0, 0), (1, 1), (2, 0)],                 # Trace 1
...         [(1, 0), (2, 1), (3, 2), (4, 1)],         # Trace 2
...         [(3, 0), (4, 1), (5, 2), (6, 1), (7, 0)], # Trace 3
...     ],
...     [                                             # Row 2
...         [(-2, 0), (-1, 1), (0, 0)],               # Trace 4
...         [(0, 0), (1, 1), (2, 1), (3, 0)],         # Trace 5
...     ],
... ]
>>> normalise_row_attrs([["A"], ["B"]], densities)
[['A', 'A', 'A'], ['B', 'B']]
>>> normalise_row_attrs([["A"], ["B", "C"]], densities)
[['A', 'A', 'A'], ['B', 'C']]
>>> normalise_row_attrs([["A", "D", "A"], ["B", "B"]], densities)
[['A', 'D', 'A'], ['B', 'B']]
>>> normalise_row_attrs([["A", "B"], ["C"]], densities)
Traceback (most recent call last):
...
ValueError: Mismatch between number of traces (3) and number of attrs (2) for row 0.

>>> samples = [
...     [                                # Row 1
...         [0, 1, 1, 2, 2, 2, 3, 3, 4], # Trace 1
...         [1, 2, 2, 3, 3, 3, 4, 4, 5], # Trace 2
...         [3, 4, 4, 5, 5, 5, 6, 6, 7], # Trace 3
...     ],
...     [                                # Row 2
...         [2, 3, 3, 4, 4, 4, 5, 5, 6], # Trace 4
...         [3, 4, 4, 5, 5, 5, 6, 6, 7], # Trace 5
...     ],
... ]
>>> normalise_row_attrs([["A"], ["B"]], samples)
[['A', 'A', 'A'], ['B', 'B']]
>>> normalise_row_attrs([["A"], ["B", "C", "X"]], samples)
Traceback (most recent call last):
...
ValueError: Mismatch between number of traces (2) and number of attrs (3) for row 1.

ridgeplot._utils.normalise_densities(densities, norm)[source]¶

Normalise a densities array.

Parameters:

densities – The densities array to normalise.
norm – The normalisation option. Can be either ‘percent’ or ‘probability’.

Returns:

The normalised densities array.

Return type:

Densities

Raises:

ValueError – If the normalisation option is invalid.

Examples

>>> densities = [
...     [
...         [(0, 0), (1, 1), (2, 0)],  # Trace 1
...         [(1, 0), (2, 2), (3, 0)],  # Trace 2
...         [(2, 1), (3, 2), (4, 1)],  # Trace 3
...     ],
...     [
...         [(0, 4), (1, 4), (2, 8)],  # Trace 4
...         [(1, 4), (2, 4), (3, 2)],  # Trace 5
...     ],
... ]
>>> normalise_densities(densities, "probability")  
[[[(0, 0.0), (1, 1.0), (2, 0.0)],
  [(1, 0.0), (2, 1.0), (3, 0.0)],
  [(2, 0.25), (3, 0.5), (4, 0.25)]],
 [[(0, 0.25), (1, 0.25), (2, 0.5)], [(1, 0.4), (2, 0.4), (3, 0.2)]]]
>>> normalise_densities(densities, "percent")  
[[[(0, 0.0), (1, 100.0), (2, 0.0)],
  [(1, 0.0), (2, 100.0), (3, 0.0)],
  [(2, 25.0), (3, 50.0), (4, 25.0)]],
 [[(0, 25.0), (1, 25.0), (2, 50.0)], [(1, 40.0), (2, 40.0), (3, 20.0)]]]
>>> normalise_densities(densities, "invalid")
Traceback (most recent call last):
...
ValueError: Invalid normalisation option 'invalid', expected 'percent' or 'probability'