ridgeplot.ridgeplot

ridgeplot.ridgeplot(samples=None, densities=None, trace_type=None, labels=None, kernel='gau', bandwidth='normal_reference', kde_points=500, nbins=None, sample_weights=None, norm=None, colorscale=None, colormode='fillgradient', opacity=None, line_color='black', line_width=None, spacing=0.5, show_yticklabels=True, xpad=0.05, coloralpha=<MISSING>, linewidth=<MISSING>)

Return an interactive ridgeline (Plotly) Figure.

Note

You must specify either samples or densities to this function, but not both. When specifying samples, the function will estimate the densities using either Kernel Density Estimation (KDE) or histogram binning. When specifying densities, the function will skip the density estimation step and use the provided densities directly. See the parameter descriptions below for more details.

Parameters:

• samples (Samples or ShallowSamples) – If samples data is specified, either Kernel Density Estimation (KDE) or histogram binning will be performed to estimate the underlying densities.

  See kernel, bandwidth, and kde_points for more details on the different KDE parameters. See nbins for more details on histogram binning. The sample_weights parameter can be used for both KDE and histogram binning.

  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 density estimation step will be performed over the sample values (\(S_t\)) for all traces. The resulting array will be a (4D) densities array of shape \((R, T_r, P_t, 2)\) (see densities below for more details).

• densities (Densities or ShallowDensities) – If a densities array is specified, the density estimation 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)

  See samples above for more details.

• trace_type (TraceTypesArray or ShallowTraceTypesArray or TraceType or None) – The type of trace to display. Choices are 'area' or 'bar'. If a single value is passed, it will be used for all traces. If a list of values is passed, it should have the same shape as the samples array. If not specified (default), the traces will be displayed as area plots (trace_type='area') unless histogram binning is used, in which case the traces will be displayed as bar plots (trace_type='bar').

  Added in version 0.3.0.

• labels (LabelsArray or ShallowLabelsArray or None) – A list of string labels for each trace. If not specified (default), the labels will be automatically generated as "Trace {n}", where n is the trace’s index. If instead a list of labels is specified, it should have the same shape as the samples 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 (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.

• nbins (int or None) – The number of bins to use when applying histogram binning. If not specified (default), KDE will be used instead of histogram binning.

  Added in version 0.3.0.

• sample_weights (SampleWeightsArray or ShallowSampleWeightsArray or SampleWeights or None) – An (optional) array of KDE weights corresponding to each sample. The weights should have the same shape as the samples array. If not specified (default), all samples will be weighted equally.

• norm (NormalisationOption or None) – The normalisation option to use when normalising the densities. If not specified (default), no normalisation will be applied and the densities will be used as is. The following normalisation options are available:

  • "probability" - normalise the densities by dividing each trace by its sum.

  • "percent" - same as "probability", but the normalised values are multiplied by 100.

  Added in version 0.2.0.

• colorscale (ColorScale or Collection[Color] or str or None) – A continuous color scale used to color the different traces in the ridgeline plot. It can be represented by a string name (e.g., "viridis"), a ColorScale object, or a list of valid Color objects. If a string name is provided, it must be one of the built-in color scales (see list_all_colorscale_names() and Plotly’s built-in color-scales). If a list of colors is provided, it must be a list of valid CSS colors (e.g., ["rgb(255, 0, 0)", "blue", "hsl(120, 100%, 50%)"]). The list will ultimately be converted into a ColorScale object, assuming the colors provided are evenly spaced. If not specified (default), the color scale will be inferred from current Plotly template.

• colormode ("fillgradient" or SolidColormode) – This argument controls the logic used for the coloring of each ridgeline trace.

  The "fillgradient" mode (default) will fill each trace with a gradient using the specified colorscale. The gradient normalisation is done using the minimum and maximum x-values over all densities.

  All other modes provide different methods for calculating interpolation values from the specified colorscale (i.e., a float value between 0 and 1) for each trace. The interpolated color will be used to color each trace with a solid color. The available modes are:

  • "row-index" - uses the row’s index. This is useful when the desired effect is to have the same color for all traces on the same row. e.g., if a ridgeplot has 3 rows of traces, then the color scale interpolation values will be [[0, ...], [0.5, ...], [1, ...]], respectively.

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

  • "trace-index-row-wise" - uses the row-wise trace index. This is similar to the "trace-index" mode, but the trace index is reset for each row. e.g., if a ridgeplot has a row with only one trace and another with two traces, then the color scale interpolation values will be [[0], [0, 1]], respectively.

  • "mean-minmax" - uses the min-max normalised (weighted) mean of each density to calculate the interpolation values. The normalisation min and max values are the absolute minimum and maximum x-values over all densities. This mode is useful when the desired effect is to have the color of each trace reflect the mean of the distribution, while also taking into account the distributions’ spread.

  • "mean-means" - similar to the "mean-minmax" mode, but where the normalisation min and max values are the minimum and maximum mean x-values over all densities. This mode is useful when the desired effect is to have the color of each trace reflect the mean of the distribution, but without taking into account the entire variability of the distributions.

  Changed in version 0.2.0: The default value changed from "mean-minmax" to "fillgradient".

• opacity (float or None) – If None (default), this argument will be ignored and the transparency values of the specified color-scale will remain untouched. Otherwise, if a float value is passed, it will be used to overwrite the opacity/transparency of the color-scale’s colors.

  Added in version 0.2.0: Replaces the deprecated coloralpha argument.

• line_color (Color or "fill-color") – The color of the traces’ lines. Any valid CSS color is allowed (default: "black"). If the value is set to “fill-color”, the line color will be the same as the fill color of the traces (see colormode). If colormode='fillgradient', the line color will be the mean color of the fill gradient (i.e., equivalent to the fill color when colormode='mean-minmax').

  Added in version 0.2.0.

• line_width (float or None) – The traces’ line width (in px). If not specified (default), area plots will have a line width of 1.5 px, and bar plots will have a line width of 0.5 px.

  Added in version 0.2.0: Replaces the deprecated linewidth argument.

  Changed in version 0.2.0: The default value changed from 1 to 1.5

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

• 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.

• coloralpha (float) –

  Deprecated since version 0.2.0: Use opacity instead.

• linewidth (float) –

  Deprecated since version 0.2.0: Use line_width instead.

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.