Merge branch 'main' into add-gallery

Author: cvanelteren

docs/colorbars_legends.py

@@ -469,3 +469,44 @@
 ax = axs[1]
 ax.legend(hs2, loc="b", ncols=3, center=True, title="centered rows")
 axs.format(xlabel="xlabel", ylabel="ylabel", suptitle="Legend formatting demo")
+# %% [raw] raw_mimetype="text/restructuredtext"
+# .. _ug_guides_decouple:
+#
+# Decoupling legend content and location
+# --------------------------------------
+#
+# Sometimes you may want to generate a legend using handles from specific axes
+# but place it relative to other axes. In UltraPlot, you can achieve this by passing
+# both the `ax` and `ref` keywords to :func:`~ultraplot.figure.Figure.legend`
+# (or :func:`~ultraplot.figure.Figure.colorbar`). The `ax` keyword specifies the
+# axes used to generate the legend handles, while the `ref` keyword specifies the
+# reference axes used to determine the legend location.
+#
+# For example, to draw a legend based on the handles in the second row of subplots
+# but place it below the first row of subplots, you can use
+# ``fig.legend(ax=axs[1, :], ref=axs[0, :], loc='bottom')``. If ``ref`` is a list
+# of axes, UltraPlot intelligently infers the span (width or height) and anchors
+# the legend to the appropriate outer edge (e.g., the bottom-most axis for ``loc='bottom'``
+# or the right-most axis for ``loc='right'``).
+
+# %%
+import numpy as np
+
+import ultraplot as uplt
+
+fig, axs = uplt.subplots(nrows=2, ncols=2, refwidth=2, share=False)
+axs.format(abc="A.", suptitle="Decoupled legend location demo")
+
+# Plot data on all axes
+state = np.random.RandomState(51423)
+data = (state.rand(20, 4) - 0.5).cumsum(axis=0)
+for ax in axs:
+    ax.plot(data, cycle="mplotcolors", labels=list("abcd"))
+
+# Legend 1: Content from Row 2 (ax=axs[1, :]), Location below Row 1 (ref=axs[0, :])
+# This places a legend describing the bottom row data underneath the top row.
+fig.legend(ax=axs[1, :], ref=axs[0, :], loc="bottom", title="Data from Row 2")
+
+# Legend 2: Content from Row 1 (ax=axs[0, :]), Location below Row 2 (ref=axs[1, :])
+# This places a legend describing the top row data underneath the bottom row.
+fig.legend(ax=axs[0, :], ref=axs[1, :], loc="bottom", title="Data from Row 1")

docs/stats.py

@@ -79,9 +79,10 @@
 shadedata = np.percentile(data, (25, 75), axis=0)  # dark shading
 
 # %%
-import ultraplot as uplt
 import numpy as np
 
+import ultraplot as uplt
+
 # Loop through "vertical" and "horizontal" versions
 varray = [[1], [2], [3]]
 harray = [[1, 1], [2, 3], [2, 3]]
@@ -164,10 +165,11 @@
 # with the same keywords used for :ref:`on-the-fly error bars <ug_errorbars>`.
 
 # %%
-import ultraplot as uplt
 import numpy as np
 import pandas as pd
 
+import ultraplot as uplt
+
 # Sample data
 N = 500
 state = np.random.RandomState(51423)
@@ -221,9 +223,10 @@
 # will use the same algorithm for kernel density estimation as the `kde` commands.
 
 # %%
-import ultraplot as uplt
 import numpy as np
 
+import ultraplot as uplt
+
 # Sample data
 M, N = 300, 3
 state = np.random.RandomState(51423)
@@ -244,9 +247,10 @@
 )
 
 # %%
-import ultraplot as uplt
 import numpy as np
 
+import ultraplot as uplt
+
 # Sample data
 N = 500
 state = np.random.RandomState(51423)
@@ -284,3 +288,171 @@
     px = ax.panel("t", space=0)
     px.hist(x, bins, color=color, fill=True, ec="k")
     px.format(grid=False, ylocator=[], title=title, titleloc="l")
+
+
+# %% [raw] raw_mimetype="text/restructuredtext"
+# .. _ug_ridgeline:
+#
+# Ridgeline plots
+# ---------------
+#
+# Ridgeline plots (also known as joyplots) visualize distributions of multiple
+# datasets as stacked, overlapping density curves. They are useful for comparing
+# distributions across categories or over time. UltraPlot provides
+# :func:`~ultraplot.axes.PlotAxes.ridgeline` and :func:`~ultraplot.axes.PlotAxes.ridgelineh`
+# for creating vertical and horizontal ridgeline plots.
+#
+# Ridgeline plots support two display modes: smooth kernel density estimation (KDE)
+# by default, or histograms with the `hist` keyword. They also support two positioning
+# modes: categorical positioning with evenly-spaced ridges (traditional joyplots),
+# or continuous positioning where ridges are anchored to specific physical coordinates
+# (useful for scientific plots like depth profiles or time series).
+
+# %%
+import numpy as np
+
+import ultraplot as uplt
+
+# Sample data with different distributions
+state = np.random.RandomState(51423)
+data = [state.normal(i, 1, 500) for i in range(5)]
+labels = [f"Distribution {i+1}" for i in range(5)]
+
+# Create figure with two subplots
+fig, axs = uplt.subplots(ncols=2, figsize=(10, 5))
+axs.format(
+    abc="A.", abcloc="ul", grid=False, suptitle="Ridgeline plots: KDE vs Histogram"
+)
+
+# KDE ridgeline (default)
+axs[0].ridgeline(
+    data, labels=labels, overlap=0.6, cmap="viridis", alpha=0.7, linewidth=1.5
+)
+axs[0].format(title="Kernel Density Estimation", xlabel="Value")
+
+# Histogram ridgeline
+axs[1].ridgeline(
+    data,
+    labels=labels,
+    overlap=0.6,
+    cmap="plasma",
+    alpha=0.7,
+    hist=True,
+    bins=20,
+    linewidth=1.5,
+)
+axs[1].format(title="Histogram", xlabel="Value")
+
+# %%
+import numpy as np
+
+import ultraplot as uplt
+
+# Sample data
+state = np.random.RandomState(51423)
+data1 = [state.normal(i * 0.5, 1, 400) for i in range(6)]
+data2 = [state.normal(i, 0.8, 400) for i in range(4)]
+labels1 = [f"Group {i+1}" for i in range(6)]
+labels2 = ["Alpha", "Beta", "Gamma", "Delta"]
+
+# Create figure with vertical and horizontal orientations
+fig, axs = uplt.subplots(ncols=2, figsize=(10, 5))
+axs.format(abc="A.", abcloc="ul", grid=False, suptitle="Ridgeline plot orientations")
+
+# Vertical ridgeline (default - ridges are horizontal)
+axs[0].ridgeline(
+    data1, labels=labels1, overlap=0.7, cmap="coolwarm", alpha=0.8, linewidth=2
+)
+axs[0].format(title="Vertical (ridgeline)", xlabel="Value")
+
+# Horizontal ridgeline (ridges are vertical)
+axs[1].ridgelineh(
+    data2, labels=labels2, overlap=0.6, facecolor="skyblue", alpha=0.7, linewidth=1.5
+)
+axs[1].format(title="Horizontal (ridgelineh)", ylabel="Value")
+
+
+# %% [raw] raw_mimetype="text/restructuredtext"
+# .. _ug_ridgeline_continuous:
+#
+# Continuous positioning
+# ^^^^^^^^^^^^^^^^^^^^^^
+#
+# For scientific applications, ridgeline plots can use continuous (coordinate-based)
+# positioning where each ridge is anchored to a specific numerical coordinate along
+# the axis. This is useful for visualizing how distributions change with physical
+# variables like depth, time, altitude, or redshift. Use the `positions` parameter
+# to specify coordinates, and optionally the `height` parameter to control ridge height
+# in axis units.
+
+# %%
+import numpy as np
+
+import ultraplot as uplt
+
+# Simulate ocean temperature data at different depths
+state = np.random.RandomState(51423)
+depths = [0, 10, 25, 50, 100]  # meters
+mean_temps = [25, 22, 18, 12, 8]  # decreasing with depth
+data = [state.normal(temp, 2, 400) for temp in mean_temps]
+labels = ["Surface", "10m", "25m", "50m", "100m"]
+
+fig, ax = uplt.subplots(figsize=(8, 6))
+ax.ridgeline(
+    data,
+    labels=labels,
+    positions=depths,
+    height=8,  # height in axis units
+    cmap="coolwarm",
+    alpha=0.75,
+    linewidth=2,
+)
+ax.format(
+    title="Ocean Temperature Distribution by Depth",
+    xlabel="Temperature (°C)",
+    ylabel="Depth (m)",
+    yreverse=True,  # depth increases downward
+    grid=True,
+    gridcolor="gray5",
+    gridalpha=0.3,
+)
+
+# %%
+import numpy as np
+
+import ultraplot as uplt
+
+# Simulate climate data over time
+state = np.random.RandomState(51423)
+years = [1950, 1970, 1990, 2010, 2030]
+mean_temps = [14.0, 14.2, 14.5, 15.0, 15.5]  # warming trend
+data = [state.normal(temp, 0.8, 500) for temp in mean_temps]
+
+fig, axs = uplt.subplots(ncols=2, figsize=(11, 5))
+axs.format(abc="A.", abcloc="ul", suptitle="Categorical vs Continuous positioning")
+
+# Categorical positioning (default)
+axs[0].ridgeline(
+    data, labels=[str(y) for y in years], overlap=0.6, cmap="fire", alpha=0.7
+)
+axs[0].format(
+    title="Categorical (traditional joyplot)", xlabel="Temperature (°C)", grid=False
+)
+
+# Continuous positioning
+axs[1].ridgeline(
+    data,
+    labels=[str(y) for y in years],
+    positions=years,
+    height=15,  # height in year units
+    cmap="fire",
+    alpha=0.7,
+)
+axs[1].format(
+    title="Continuous (scientific)",
+    xlabel="Temperature (°C)",
+    ylabel="Year",
+    grid=True,
+    gridcolor="gray5",
+    gridalpha=0.3,
+)

ultraplot/axes/base.py

@@ -317,9 +317,9 @@
     The axes title. Can optionally be a sequence strings, in which case
     the title will be selected from the sequence according to `~Axes.number`.
 abc : bool or str or sequence, default: :rc:`abc`
-    The "a-b-c" subplot label style. Must contain the character ``a`` or ``A``,
+    The "a-b-c" subplot label style. Must contain the character `a` or `A`,
     for example ``'a.'``, or ``'A'``. If ``True`` then the default style of
-    ``'a'`` is used. The ``a`` or ``A`` is replaced with the alphabetic character
+    ``'a'`` is used. The `a` or ``A`` is replaced with the alphabetic character
     matching the `~Axes.number`. If `~Axes.number` is greater than 26, the
     characters loop around to a, ..., z, aa, ..., zz, aaa, ..., zzz, etc.
     Can also be a sequence of strings, in which case the "a-b-c" label will be selected sequentially from the list. For example `axs.format(abc = ["X", "Y"])` for a two-panel figure, and `axes[3:5].format(abc = ["X", "Y"])` for a two-panel subset of a larger figure.
@@ -341,8 +341,8 @@
     upper left inside axes    ``'upper left'``, ``'ul'``
     lower left inside axes    ``'lower left'``, ``'ll'``
     lower right inside axes   ``'lower right'``, ``'lr'``
-    left of y axis            ```'outer left'``, ``'ol'``
-    right of y axis           ```'outer right'``, ``'or'``
+    left of y axis            ``'outer left'``, ``'ol'``
+    right of y axis           ``'outer right'``, ``'or'``
     ========================  ============================
 
 abcborder, titleborder : bool, default: :rc:`abc.border` and :rc:`title.border`
@@ -370,16 +370,15 @@
 abctitlepad : float, default: :rc:`abc.titlepad`
     The horizontal padding between a-b-c labels and titles in the same location.
     %(units.pt)s
-ltitle, ctitle, rtitle, ultitle, uctitle, urtitle, lltitle, lctitle, lrtitle \\
-: str or sequence, optional
+ltitle, ctitle, rtitle, ultitle, uctitle, urtitle, lltitle, lctitle, lrtitle : str or sequence, optional \\
     Shorthands for the below keywords.
-lefttitle, centertitle, righttitle, upperlefttitle, uppercentertitle, upperrighttitle, \\
+    lefttitle, centertitle, righttitle, upperlefttitle, uppercentertitle, upperrighttitle : str or sequence, optional
 lowerlefttitle, lowercentertitle, lowerrighttitle : str or sequence, optional
     Additional titles in specific positions (see `title` for details). This works as
     an alternative to the ``ax.format(title='Title', titleloc=loc)`` workflow and
     permits adding more than one title-like label for a single axes.
-a, alpha, fc, facecolor, ec, edgecolor, lw, linewidth, ls, linestyle : default: \\
-:rc:`axes.alpha`, :rc:`axes.facecolor`, :rc:`axes.edgecolor`, :rc:`axes.linewidth`, '-'
+a, alpha, fc, facecolor, ec, edgecolor, lw, linewidth, ls, linestyle : default:
+    :rc:`axes.alpha` (default: 1.0), :rc:`axes.facecolor` (default: white), :rc:`axes.edgecolor` (default: black), :rc:`axes.linewidth` (default: 0.6), -
     Additional settings applied to the background patch, and their
     shorthands. Their defaults values are the ``'axes'`` properties.
 """
@@ -3646,7 +3645,7 @@ def colorbar(self, mappable, values=None, loc=None, location=None, **kwargs):
             width or height (default is :rcraw:`colorbar.length`). For inset
             colorbars, floats interpreted as em-widths and strings interpreted
             by `~ultraplot.utils.units` (default is :rcraw:`colorbar.insetlength`).
-        width : unit-spec, default: :rc:`colorbar.width` or :rc:`colorbar.insetwidth
+        width : unit-spec, default: :rc:`colorbar.width` or :rc:`colorbar.insetwidth`
             The colorbar width. For outer colorbars, floats are interpreted as inches
             (default is :rcraw:`colorbar.width`). For inset colorbars, floats are
             interpreted as em-widths (default is :rcraw:`colorbar.insetwidth`).

ultraplot/axes/geo.py

@@ -210,7 +210,7 @@
     must be passed to `~ultraplot.constructor.Proj` instead.
 color : color-spec, default: :rc:`meta.color`
     The color for the axes edge. Propagates to `labelcolor` unless specified
-    otherwise (similar to :func:`ultraplot.axes.CartesianAxes.format`).
+    otherwise (similar to :func:`~ultraplot.axes.CartesianAxes.format`).
 gridcolor : color-spec, default: :rc:`grid.color`
     The color for the gridline labels.
 labelcolor : color-spec, default: `color` or :rc:`grid.labelcolor`