ridgeplot.ridgeplot

ridgeplot.ridgeplot(samples=None, densities=None, kernel='gau', bandwidth='normal_reference', kde_points=500, colorscale='plasma', colormode='mean-minmax', coloralpha=None, labels=None, linewidth=1.0, spacing=0.5, show_annotations=<MISSING>, show_yticklabels=True, xpad=0.05)

Return an interactive ridgeline (Plotly) Figure.

Note

You must pass either samples or densities to this function, but not both. See descriptions below for more details.

Parameters:

• samples (Samples or ShallowSamples, optional) – 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. The samples argument should be an array of shape \((R, T_r, S_t)\). Note that we support irregular (ragged) arrays, where:

  • \(R\) is the number of rows in the plot

  • \(T_r\) is the number of traces per row, where each row \(r \in R\) can have a different number of traces.

  • \(S_t\) is the number of samples per trace, where each trace \(t \in T_r\) can also have a different number of samples.

  The KDE will be performed over the sample values (\(S_t\)) for all traces. After the KDE, the resulting array will be a (4D) densities array with shape \((R, T_r, P_t, 2)\) (see below for more details).

• densities (Densities or ShallowDensities, optional) – If a densities array is specified, the KDE step will be skipped and all associated arguments ignored. Each density array should have shape \((R, T_r, P_t, 2)\) (4D). Just like the samples argument, we also support irregular (ragged) densities arrays, where:

  • \(R\) is the number of rows in the plot

  • \(T_r\) is the number of traces per row, where each row \(r \in R\) can have a different number of traces.

  • \(P_t\) is the number of points per trace, where each trace \(t \in T_r\) can also have a different number of points.

  • \(2\) is the number of coordinates per point (x and y)

• 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 (KDEBandwidth) – 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 (KDEPoints) – This argument controls the points at which KDE is computed. If an int value is passed (default=500), the densities will be evaluated at kde_points evenly spaced points between the min and max of each set of samples. Optionally, you can also pass a custom 1D numerical array, which will be used for all traces.

• colorscale (str or ColorScale) – Any valid Plotly color-scale or a str with a valid named color-scale. Use list_all_colorscale_names() to see which names are available or check out Plotly’s built-in color-scales.

• colormode (Colormode) – 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:

  • "row-index" - uses the row’s index. e.g. if the ridgeplot has 3 rows of traces, then the midpoints will be [[0, ...], [0.5, ...], [1, ...]].

  • "trace-index" - uses the trace’s index. e.g. if the ridgeplot has a total of 3 traces (across all rows), then the midpoints will be 0, 0.5, and 1, respectively.

  • "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 (float, optional) – 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 (LabelsArray or ShallowLabelsArray, optional) – 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) – Whether to show the tick labels on the y-axis. The default is True.

  Deprecated since version 0.1.21: Use show_yticklabels instead.

• show_yticklabels (bool) – Whether to show the tick labels on the y-axis. The default is True.

  Added in version 0.1.21: Replaces the deprecated show_annotations argument.

• 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 are specified, or if neither of them is specified. i.e. you may only specify one of them.