ridgeplot._types module

Miscellaneous types, type aliases, type guards, and other related utilities used throughout the package.

ridgeplot._types.Color: TypeAlias = str | tuple[float, float, float]

A color can be represented by a tuple of (r, g, b) values or any valid CSS color string - including hex, rgb/a, hsl/a, hsv/a, and named CSS colors.

ridgeplot._types.ColorScale

The canonical form for a color scale is represented by a list of tuples of two elements:

  1. the first element (a scale value) is a float bounded to the interval [0, 1]

  2. the second element should be a valid Color representation.

For instance, the Viridis color scale can be represented as:

>>> viridis: ColorScale = [
  (0.0, 'rgb(68, 1, 84)'),
  (0.1111111111111111, 'rgb(72, 40, 120)'),
  (0.2222222222222222, 'rgb(62, 73, 137)'),
  (0.3333333333333333, 'rgb(49, 104, 142)'),
  (0.4444444444444444, 'rgb(38, 130, 142)'),
  (0.5555555555555556, 'rgb(31, 158, 137)'),
  (0.6666666666666666, 'rgb(53, 183, 121)'),
  (0.7777777777777777, 'rgb(110, 206, 88)'),
  (0.8888888888888888, 'rgb(181, 222, 43)'),
  (1.0, 'rgb(253, 231, 37)')
]
ridgeplot._types.NormalisationOption

A Literal type that represents the normalisation options available for the ridgeplot. See ridgeplot.ridgeplot.norm for more details.

alias of Literal[‘probability’, ‘percent’]

ridgeplot._types.CollectionL1

A TypeAlias for a 1-level-deep Collection.

Example

>>> c1 = [1, 2, 3]
ridgeplot._types.CollectionL2

A TypeAlias for a 2-level-deep Collection.

Example

>>> c2 = [[1, 2, 3], [4, 5, 6]]
ridgeplot._types.CollectionL3

A TypeAlias for a 3-level-deep Collection.

Example

>>> c3 = [
...     [[1, 2], [3, 4]],
...     [[5, 6], [7, 8]],
... ]
ridgeplot._types.is_collection_l2(obj)[source]

Type guard for CollectionL2.

Examples

>>> is_collection_l2("definitely not")
False
>>> is_collection_l2([1, 2, 3])
False
>>> is_collection_l2([[1, 2], [3, 4]])
True
>>> is_collection_l2([["a", "b"], ["c", "d"]])
True
>>> is_collection_l2([["a", "b"], "c"])
False
>>> is_collection_l2([[[1, 2], [3, 4]], [[5, 6], [7, 8]]])  # 3-level deep
True
ridgeplot._types.Float: TypeAlias = float | numpy.floating[typing_extensions.Any]

A TypeAlias for float types.

ridgeplot._types.Int: TypeAlias = int | numpy.integer[typing_extensions.Any]

A TypeAlias for a int types.

ridgeplot._types.Numeric: TypeAlias = int | numpy.integer[typing_extensions.Any] | float | numpy.floating[typing_extensions.Any]

A TypeAlias for numeric types.

class ridgeplot._types.NumericT

A TypeVar variable bound to Numeric types.

alias of TypeVar(‘NumericT’, bound=int | integer[Any] | float | floating[Any])

has_default()
ridgeplot._types._is_numeric(obj)[source]

Type guard for Numeric.

Examples

>>> _is_numeric(42)
True
>>> _is_numeric(12.3)
True
>>> _is_numeric(np.int64(17))
True
>>> _is_numeric(np.float64(3.14))
True
>>> _is_numeric("42")
False
>>> _is_numeric("12.3")
False
>>> _is_numeric([42])
False
>>> _is_numeric(None)
False
ridgeplot._types.XYCoordinate

A 2D \((x, y)\) coordinate, represented as a tuple of two Numeric values.

Example

>>> xy_coord = (1, 2)
ridgeplot._types.DensityTrace

A 2D line/trace represented as a collection of \((x, y)\) coordinates (i.e. XYCoordinates).

These are equivalent:

  • DensityTrace

  • CollectionL1[XYCoordinate]

  • Collection[tuple[Numeric, Numeric]]

By convention, the \(x\) values should be non-repeating and increasing. For instance, the following is a valid 2D line trace:

>>> density_trace = [(0, 0), (1, 1), (2, 2), (3, 1), (4, 0)]
../../_images/density_trace.webp
ridgeplot._types.DensitiesRow

A DensitiesRow represents a set of DensityTraces that are to be plotted on a given row of a ridgeplot.

These are equivalent:

  • DensitiesRow

  • CollectionL2[XYCoordinate]

  • Collection[Collection[Tuple[Numeric, Numeric]]]

Example

>>> densities_row = [
...     [(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
... ]
../../_images/densities_row.webp
ridgeplot._types.Densities

The Densities type represents the entire collection of traces that are to be plotted on a ridgeplot.

In a ridgeplot, several traces can be plotted on different rows. Each row is represented by a DensitiesRow object which, in turn, is a collection of DensityTraces. Therefore, the Densities type is a collection of DensitiesRows.

These are equivalent:

  • Densities

  • CollectionL1[DensitiesRow]

  • CollectionL3[XYCoordinate]

  • Collection[Collection[Collection[Tuple[Numeric, Numeric]]]]

Example

>>> 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
...     ],
... ]
../../_images/densities.webp
ridgeplot._types.ShallowDensities

Shallow type for Densities where each row of the ridgeplot contains only a single trace.

These are equivalent:

  • Densities

  • CollectionL1[DensityTrace]

  • CollectionL2[XYCoordinate]

  • Collection[Collection[Tuple[Numeric, Numeric]]]

Example

>>> shallow_densities = [
...     [(0, 0), (1, 1), (2, 0)], # Trace 1
...     [(1, 0), (2, 1), (3, 0)], # Trace 2
...     [(2, 0), (3, 1), (4, 0)], # Trace 3
... ]
../../_images/shallow_densities.webp
ridgeplot._types.is_xy_coord(obj)[source]

Type guard for XYCoordinate.

ridgeplot._types.is_density_trace(obj)[source]

Type guard for DensityTrace.

ridgeplot._types.is_shallow_densities(obj)[source]

Type guard for ShallowDensities.

Examples

>>> is_shallow_densities("definitely not")
False
>>> is_shallow_densities([["also"], ["not"]])
False
>>> deep_density = [
...     [
...         [(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)],
...     ],
... ]
>>> is_shallow_densities(deep_density)
False
>>> shallow_density = [[(0, 0), (1, 1)], [(2, 2), (3, 1)]]
>>> is_shallow_densities(shallow_density)
True
>>> shallow_samples = [[0, 1, 2], [2, 3, 4]]
>>> is_shallow_densities(shallow_samples)
False
ridgeplot._types.is_densities(obj)[source]

Type guard for Densities.

Examples

>>> is_densities("definitely not")
False
>>> is_densities([["also"], ["not"]])
False
>>> is_densities([[["still"], ["not"]], [["nope"]]])
False
>>> shallow_density = [[(0, 0), (1, 1)], [(2, 2), (3, 1)]]
>>> is_densities(shallow_density)
False
>>> deep_density = [
...     [                                             # 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
...     ],
... ]
>>> is_densities(deep_density)
True
ridgeplot._types.SamplesTrace

A SamplesTrace is a collection of numeric values representing a set of samples from which a DensityTrace can be estimated via KDE.

Example

>>> samples_trace = [0, 1, 1, 2, 2, 2, 3, 3, 4]
../../_images/samples_trace.webp
ridgeplot._types.SamplesRow

A SamplesRow represents a set of SamplesTraces that are to be plotted on a given row of a ridgeplot.

i.e. a SamplesRow is a collection of SamplesTraces and can be converted into a DensitiesRow by applying KDE to each trace.

Example

>>> samples_row = [
...     [0, 1, 1, 2, 2, 2, 3, 3, 4], # Trace 1
...     [1, 2, 2, 3, 3, 3, 4, 4, 5], # Trace 2
... ]
../../_images/samples_row.webp
ridgeplot._types.Samples

The Samples type represents the entire collection of samples that are to be plotted on a ridgeplot.

It is a collection of SamplesRow objects. Each row is represented by a SamplesRow type which, in turn, is a collection of SamplesTraces which can be converted into DensityTrace ‘s by applying a kernel density estimation algorithm.

Therefore, the Samples type can be converted into a Densities type by applying a kernel density estimation (KDE) algorithm to each trace.

See Densities for more details.

Example

>>> 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
...     ],
...     [                                # Row 2
...         [2, 3, 3, 4, 4, 4, 5, 5, 6], # Trace 3
...         [3, 4, 4, 5, 5, 5, 6, 6, 7], # Trace 4
...     ],
... ]
../../_images/samples.webp
ridgeplot._types.ShallowSamples

Shallow type for Samples where each row of the ridgeplot contains only a single trace.

Example

>>> shallow_samples = [
...     [0, 1, 1, 2, 2, 2, 3, 3, 4], # Trace 1
...     [1, 2, 2, 3, 3, 3, 4, 4, 5], # Trace 2
... ]
../../_images/shallow_samples.webp
ridgeplot._types.is_trace_samples(obj)[source]

Check if the given object is a SamplesTrace type.

ridgeplot._types.is_shallow_samples(obj)[source]

Type guard for ShallowSamples.

Examples

>>> is_shallow_samples("definitely not")
False
>>> is_shallow_samples([["also"], ["not"]])
False
>>> deep_samples = [
...     [
...         [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],
...     ],
... ]
>>> is_shallow_samples(deep_samples)
False
>>> shallow_samples = [[0, 1, 2], [2, 3, 4]]
>>> is_shallow_samples(shallow_samples)
True
>>> shallow_density = [[(0, 0), (1, 1)], [(2, 2), (3, 1)]]
>>> is_shallow_samples(shallow_density)
False
ridgeplot._types.TraceType

The type of trace to draw in a ridgeplot. See ridgeplot.ridgeplot.trace_type for more information.

alias of Literal[‘area’, ‘bar’]

ridgeplot._types.TraceTypesArray

A TraceTypesArray represents the types of traces in a ridgeplot.

Example

>>> trace_types_array: TraceTypesArray = [
...     ["area", "bar", "area"],
...     ["bar", "area"],
... ]
ridgeplot._types.ShallowTraceTypesArray

Shallow type for TraceTypesArray.

Example

>>> trace_types_array: ShallowTraceTypesArray = ["area", "bar", "area"]
ridgeplot._types.is_trace_type(obj)[source]

Type guard for TraceType.

Examples

>>> is_trace_type("area")
True
>>> is_trace_type("bar")
True
>>> is_trace_type("foo")
False
>>> is_trace_type(42)
False
ridgeplot._types.is_shallow_trace_types_array(obj)[source]

Type guard for ShallowTraceTypesArray.

Examples

>>> is_shallow_trace_types_array(["area", "bar", "area"])
True
>>> is_shallow_trace_types_array(["area", "bar", "foo"])
False
>>> is_shallow_trace_types_array([1, 2, 3])
False
ridgeplot._types.is_trace_types_array(obj)[source]

Type guard for TraceTypesArray.

Examples

>>> is_trace_types_array([["area", "bar"], ["area", "bar"]])
True
>>> is_trace_types_array([["area", "bar"], ["area", "foo"]])
False
>>> is_trace_types_array([["area", "bar"], ["area", 42]])
False
ridgeplot._types.LabelsArray

A LabelsArray represents the labels of traces in a ridgeplot.

Example

>>> labels_array: LabelsArray = [
...     ["trace 1", "trace 2", "trace 3"],
...     ["trace 4", "trace 5"],
... ]
ridgeplot._types.ShallowLabelsArray

Shallow type for LabelsArray.

Example

>>> labels_array: ShallowLabelsArray = ["trace 1", "trace 2", "trace 3"]
ridgeplot._types.SampleWeights: TypeAlias = collections.abc.Collection[int | numpy.integer[typing_extensions.Any] | float | numpy.floating[typing_extensions.Any]] | None

An array of KDE weights corresponding to each sample.

ridgeplot._types.SampleWeightsArray

A SampleWeightsArray represents the weights of the datapoints in a Samples array. The shape of the SampleWeightsArray array should match the shape of the corresponding Samples array.

ridgeplot._types.ShallowSampleWeightsArray

Shallow type for SampleWeightsArray.

ridgeplot._types.is_flat_str_collection(obj)[source]

Type guard for CollectionL1[str].

Note that this type-guard explicitly excludes the case where the object is a string itself (which can be considered a collection of string characters).

Examples

>>> is_flat_str_collection(["a", "b", "c"])
True
>>> is_flat_str_collection("abc")
False
>>> is_flat_str_collection(["a", "b", 1])
False
>>> is_flat_str_collection({"also", "a", "collection"})
True
>>> is_flat_str_collection((1, 2))
False
ridgeplot._types.is_flat_numeric_collection(obj)[source]

Type guard for CollectionL1[Numeric].

Examples

>>> is_flat_numeric_collection({1, 2, 3.14})
True
>>> is_flat_numeric_collection((1, np.nan, np.inf))
True
>>> is_flat_numeric_collection([3.14, np.float64(2.71), np.int64(42)])
True
>>> is_flat_numeric_collection([1, 2, "3"])
False
>>> is_flat_numeric_collection([1, 2, None])
False
>>> is_flat_numeric_collection("definitely not")
False
ridgeplot._types.nest_shallow_collection(shallow_collection)[source]

Convert a shallow collection type into a deep collection type.

This function should really only be used in the ridgeplot._ridgeplot module to normalise user input.

Examples

>>> nest_shallow_collection([1, "2", {"a": 3}])
[[1], ['2'], [{'a': 3}]]