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=<object object>, show_yticklabels=True, xpad=0.05)[source]#
Return an interactive ridgeline (Plotly)
Figure
.Note
You must pass either
samples
ordensities
to this function, but not both. See descriptions below for more details.- Parameters:
samples (
Samples
orShallowSamples
, optional) –If
samples
data is specified, Kernel Density Estimation (KDE) will be computed. Seekernel
,bandwidth
, andkde_points
for more details and KDE configuration options. Thesamples
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 each trace \(t \in T\). After the KDE, the resulting array will be a (4D) :paramref:`densities array with shape \((R, T_r, P_t, 2)\) (see
densities
below for more details).densities (
Densities
orShallowDensities
, optional) –If
densities
arrays are specified instead, 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 thesamples
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)
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 ismin(std(x),IQR/1.34)
"silverman"
- .9 * A * nobs ** (-1/5.), where A ismin(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 datakern
: the kernel instance used
kde_points (
KDEPoints
) – This argument controls the points at which KDE is computed. If anint
value is passed (default=500), the densities will be evaluated atkde_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
orColorScale
) – Any valid Plotly color-scale or a str with a valid named color-scale. Useget_all_colorscale_names()
to see which names are available or check out Plotly’s built-in color-scales.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
orShallowLabelsArray
, 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.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.
New 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 theupdate_layout()
method).- Return type:
- Raises:
ValueError – If both
samples
anddensities
are specified, or if neither of them is specified. i.e. you may only specify one of them.