Feature Request: Add Ridgeline Plot Support

[cvanelteren]

Description

Add native support for ridgeline plots (also known as joyplots) to UltraPlot. Ridgeline plots are useful for visualizing distributions across multiple categories or time periods, where each distribution is plotted as a filled curve slightly overlapping the one below it.

Motivation

Ridgeline plots are increasingly popular for:

• Visualizing multiple distributions simultaneously
• Showing changes in distributions over time
• Comparing density distributions across categories
• Creating visually appealing data storytelling (famously used for Joy Division's "Unknown Pleasures" album cover)

Currently, creating ridgeline plots requires manual manipulation of multiple axes, making it difficult to achieve consistent styling and spacing.

Proposed API

import ultraplot as uplt
import numpy as np

# Simple interface
fig, ax = uplt.subplots()
data = [np.random.normal(i, 1, 1000) for i in range(5)]
ax.ridgeline(data, labels=['Group A', 'Group B', 'Group C', 'Group D', 'Group E'])

# Or with more control
fig, ax = uplt.subplots()
ax.ridgeline(
    data,
    labels=['Group A', 'Group B', 'Group C', 'Group D', 'Group E'],
    overlap=0.5,  # How much curves overlap (0-1)
    fill=True,
    alpha=0.7,
    colors='viridis',  # Use colormap
    bandwidth=0.3,  # KDE bandwidth
)

Desired Features

• Automatic spacing and overlap control
• Support for both KDE and histogram-based ridgelines
• Integration with UltraPlot's color cycle and styling
• Optional baseline coloring/shading
• Support for both vertical and horizontal orientations
• Ability to customize individual ridges

Related Work

• seaborn has rudimentary support via FacetGrid but it's cumbersome
• R's ggridges package is the gold standard
• matplotlib requires significant boilerplate code
• Potential base: https://github.com/leotac/joypy?tab=readme-ov-file

Additional Context

This would complement UltraPlot's existing distribution visualization tools (violin plots, box plots, etc.) and align with the library's goal of making complex visualizations simple.

[syrte]

Fantastic. This would be a great addition!!!
To ensure it covers scientific use cases, it would be great if the implementation can support two distinct positioning modes:

• Categorical Positioning: Ridges are spaced evenly based on discrete labels (the standard "joyplot" case).
• Continuous (Coordinate-based) Positioning: Ridges are anchored to specific numerical coordinates along a continuous Y-axis. This is essential when the vertical axis represents a physical variable, such as time, redshift, or distance.

In the continuous case, the user must be able to define the height of the ridges in the physical units of the subplot Y-axis. This distinguishes the density distribution (PDF) from the coordinate system of the plot.

Proposed API Examples

1. Categorical (Discrete labels)

import ultraplot as uplt
import numpy as np

fig, ax = uplt.subplots()
data = [np.random.normal(i, 1, 1000) for i in range(5)]
labels = ['Group A', 'Group B', 'Group C', 'Group D', 'Group E']

# Default behavior: even spacing based on labels
ax.ridgeline(data, labels=labels, overlap=0.5)

2. Continuous (Numerical Y-coordinates)

fig, ax = uplt.subplots()
# Data distributions at specific physical coordinates
y_coords = [0.1, 0.5, 1.2, 2.0, 3.5] 
data = [np.random.normal(0, 1, 1000) for _ in y_coords]

# 'positions' anchors ridges to the Y-axis values
# 'scale' defines the maximum height of a ridge in axes units
ax.ridgeline(
    data, 
    positions=y_coords, 
    scale=0.1,  # or other better name for this kwarg
    fill=True
)
ax.format(ylabel='Redshift (z)', ylim=(-0.5, 4.5))

[cvanelteren]

Thanks! Implemented on #451

[cvanelteren]

If you want you can review it @syrte