API Reference#

ridgeplot.ridgeplot(samples=None, densities=None, kernel='gau', bandwidth='normal_reference', kde_points=500, colorscale='plasma', colormode='mean-means', coloralpha=None, labels=None, linewidth=1.4, spacing=0.5, show_annotations=True, xpad=0.05)[source]#

Return a beautiful ridgeline plot Figure.

You have to specify either samples or densities, but not both. See samples and densities bellow for more information.

Parameters:

  • samples – If samples data is specified, Kernel Density Estimation (KDE) will be computed. See kernel, bandwidth, and kde_points for more details and KDE configuration options.

  • densities (Optional[Iterable[NestedNumericSequence]]) – If densities arrays are specified instead, the KDE step will be skipped and all associated arguments ignored. Each density array should have shape \((2, N)\), but \(N\) may vary with each array.

  • kernel (str) –

    The Kernel to be used during Kernel Density Estimation. The default is a Gaussian Kernel ("gau"). Choices are:

    • "biw" for biweight

    • "cos" for cosine

    • "epa" for Epanechnikov

    • "gau" for Gaussian.

    • "tri" for triangular

    • "triw" for triweight

    • "uni" for uniform

  • bandwidth –

    The bandwidth to use during Kernel Density Estimation. The default is normal_reference. Choices are:

    • "scott" - 1.059 * A * nobs ** (-1/5.), where A is min(std(x),IQR/1.34)

    • "silverman" - .9 * A * nobs ** (-1/5.), where A is min(std(x),IQR/1.34)

    • "normal_reference" - C * A * nobs ** (-1/5.), where C is calculated from the kernel. Equivalent (up to 2 dp) to the "scott" bandwidth for gaussian kernels. See bandwidths.py.

    • If a float is given, its value is used as the bandwidth.

    • If a callable is given, it’s return value is used. The callable should take exactly two parameters, i.e., fn(x, kern), and return a float, where:

      • x: the clipped input data

      • kern: the kernel instance used

  • kde_points – This argument controls the points at which KDE is computed. If an int value is passed (default), the densities will be evaluated at kde_points evenly spaced points between the min and max of each set of samples. However, you may also specify a custom range by instead passing an array of points. This array should be one-dimensional.

  • colorscale (Union[str, ColorScaleType]) – Any valid Plotly color-scale or a str with a valid named color-scale. Use get_all_colorscale_names() to see which names are available or check out Plotly’s built-in color-scales.

  • colormode (str) –

    This argument controls the logic for choosing the color filling of each ridgeline trace. Each option provides a different method for calculating the colorscale midpoint of each trace. The default is mode is "mean-means". Choices are:

    • "index" - uses the trace’s index. e.g. if 3 traces are specified, then the midpoints will be [0, 0.5, 1].

    • "mean-minmax" - uses the min-max normalized (weighted) mean of each density to calculate the midpoints. The normalization min and max values are the minimum and maximum x-values from all densities, respectively.

    • "mean-means" - uses the min-max normalized (weighted) mean of each density to calculate the midpoints. The normalization min and max values are the minimum and maximum mean values from all densities, respectively.

  • coloralpha (Optional[float]) – If None (default), this argument will be ignored and the transparency values of the specifies color-scale will remain untouched. Otherwise, if a float value is passed, it will be used to overwrite the transparency (alpha) of the color-scale’s colors.

  • labels – A list of string labels for each trace. The default value is None, which will result in auto-generated labels of form “Trace n”. If, instead, a list of labels is specified, it must be of the same size/length as the number of traces.

  • linewidth (float) – The traces’ line width (in px).

  • spacing (float) – The vertical spacing between density traces, which is defined in units of the highest distribution (i.e. the maximum y-value).

  • show_annotations (bool) – If True (default), it will show the label names as “y-tick-labels”.

  • xpad (float) – Specifies the extra padding to use on the x-axis. It is defined in units of the range between the minimum and maximum x-values from all distributions.

Returns:

A Plotly Figure with a ridgeline plot. You can further customize this figure to your liking (e.g. using the update_layout() method).

Return type:

plotly.graph_objects.Figure

Raises:

ValueError – If both samples and densities arguments are not None, or if neither samples nor densities are specified.

Color utilities#

ridgeplot.get_all_colorscale_names()[source]#

Get a tuple with all available colorscale names.

Data loading utilities#

ridgeplot.datasets.load_probly()[source]#

Load the probly dataset.

Internals#

Types#

protocol ridgeplot._types.SimpleSequence[source]#

A simple Sequence protocol that inherits from Collection and implements a __getitem__ method.

Classes that implement this protocol must have the following methods / attributes:

__getitem__(index)[source]#
ridgeplot._types.Numeric#

A TypeAlias for numeric types.

alias of Union[int, float, number]

ridgeplot._types.NumericT#

A TypeVar version of Numeric.

alias of TypeVar(‘NumericT’, bound=Union[int, float, number])

ridgeplot._types.NestedNumericSequence#

A TypeAlias for a sequence of sequences of numeric values.

Examples of valid types:

>>> [[1, 2], [3, 4]]
>>> ((1, 2), [3, 4])
>>> np.array([[1, 2], [3, 4]])
>>> np.array([[1, 2], [3, 4]], dtype=np.float32)

alias of Union[SimpleSequence[SimpleSequence[Union[int, float, number]]], ndarray]

ridgeplot._types.NestedNumericSequenceT#

Same as NestedNumericSequence, but with a NumericT type variable bound to Numeric instead the Numeric type alias.

alias of Union[SimpleSequence[SimpleSequence[NumericT]], ndarray]

ridgeplot._types.ColorScaleType#

A colorscale is an Iterable 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 (a color) is a string representation of a color parsable by Plotly

For instance, The Viridis colorscale would be defined as

>>> get_colorscale("viridis")
(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)'))

alias of Iterable[Tuple[float, str]]

Figure factory#

class ridgeplot._figure_factory.RidgePlotFigureFactory(densities, colorscale, coloralpha, colormode, labels, linewidth, spacing, show_annotations, xpad)[source]#

Refer to ridgeplot().

draw_base(x, y_shifted)[source]#

Draw the base for a density trace.

Adds an invisible trace at constant y that will serve as the fill-limit for the corresponding density trace.

draw_density_trace(x, y, label, color)[source]#

Draw a density trace.

Adds a density ‘trace’ to the Figure. The fill="tonexty" option fills the trace until the previously drawn trace (see draw_base()). This is why the base trace must be drawn first.

update_layout(y_ticks)[source]#

Update figure’s layout.

Kernel density estimation (KDE)#

ridgeplot._kde.evaluate_density(samples, points, kernel, bandwidth)[source]#

Evaluate a density function at a set of points.

For a given set of samples, computes the kernel densities at the given points. Both the original points and density arrays are returned.

Color utilities#

ridgeplot._colors.validate_colorscale(colorscale)[source]#

Validate the structure, scale values, and colors of colorscale.

Adapted from _plotly_utils.colors.validate_colorscale().

ridgeplot._colors.get_all_colorscale_names()[source]#

Get a tuple with all available colorscale names.

ridgeplot._colors.get_colorscale(name)[source]#

Get a colorscale by name.

Parameters:

name (str) – The colorscale name. This argument is case-insensitive. For instance, "YlOrRd" and "ylorrd" map to the same colorscale. Colorscale names ending in _r represent a reversed colorscale.

Raises:

ValueError – If an unknown name is provided

ridgeplot._colors.get_color(colorscale, midpoint)[source]#

Get a color from a colorscale at a given midpoint.

Given a colorscale, it interpolates the expected color at a given midpoint, on a scale from 0 to 1.

Other utilities#

ridgeplot._utils.get_xy_extrema(arrays)[source]#

Get the global x-y extrema (x_min, x_max, y_min, y_max) of a sequence of 2D array-like objects.

Parameters:

arrays (Iterable[NestedNumericSequenceT]) – A sequence of 2D array-like objects.

Returns:

A tuple of the form (x_min, x_max, y_min, y_max).

Return type:

Tuple[Numeric, Numeric, Numeric, Numeric]

Raises:

ValueError – If the arrays sequence is empty, or if one of the arrays is empty, or if one of the arrays is not 2D.

Examples

>>> get_xy_extrema([[[1, 2], [3, 4]], [[5, 6], [7, 8]]])
(1, 6, 3, 8)
class ridgeplot._utils.LazyMapping(loader)[source]#

A lazy mapping that loads its contents only when first needed.

Parameters:

loader – A callable that returns a mapping.

Examples

>>> from typing import Dict
>>>
>>> def my_io_loader() -> Dict[str, int]:
...     print("Loading...")
...     return {"a": 1, "b": 2}
...
>>> lazy_mapping = LazyMapping(my_io_loader)
>>> lazy_mapping
Loading...
{'a': 1, 'b': 2}