diff --git a/docs/_static/charts/basic.html b/docs/_static/charts/basic.html
index 1c928f0c..8e43d4db 100644
--- a/docs/_static/charts/basic.html
+++ b/docs/_static/charts/basic.html
@@ -1 +1 @@
-
+
diff --git a/docs/_static/charts/basic.jpeg b/docs/_static/charts/basic.jpeg
index 6677fa0f..29ffc761 100644
Binary files a/docs/_static/charts/basic.jpeg and b/docs/_static/charts/basic.jpeg differ
diff --git a/docs/_static/charts/basic.webp b/docs/_static/charts/basic.webp
index 7e6b5716..7401abf1 100644
Binary files a/docs/_static/charts/basic.webp and b/docs/_static/charts/basic.webp differ
diff --git a/docs/_static/charts/lincoln_weather.html b/docs/_static/charts/lincoln_weather.html
index df7e513c..ab02afca 100644
--- a/docs/_static/charts/lincoln_weather.html
+++ b/docs/_static/charts/lincoln_weather.html
@@ -1 +1 @@
-
+
diff --git a/docs/_static/charts/lincoln_weather.jpeg b/docs/_static/charts/lincoln_weather.jpeg
index e38d85c2..a141b347 100644
Binary files a/docs/_static/charts/lincoln_weather.jpeg and b/docs/_static/charts/lincoln_weather.jpeg differ
diff --git a/docs/_static/charts/lincoln_weather.webp b/docs/_static/charts/lincoln_weather.webp
index 1d88188b..737feccc 100644
Binary files a/docs/_static/charts/lincoln_weather.webp and b/docs/_static/charts/lincoln_weather.webp differ
diff --git a/docs/_static/charts/lincoln_weather_red_blue.html b/docs/_static/charts/lincoln_weather_red_blue.html
index 44d98876..8949d609 100644
--- a/docs/_static/charts/lincoln_weather_red_blue.html
+++ b/docs/_static/charts/lincoln_weather_red_blue.html
@@ -1 +1 @@
-
+
diff --git a/docs/_static/charts/lincoln_weather_red_blue.jpeg b/docs/_static/charts/lincoln_weather_red_blue.jpeg
index 518efd1d..c474bd66 100644
Binary files a/docs/_static/charts/lincoln_weather_red_blue.jpeg and b/docs/_static/charts/lincoln_weather_red_blue.jpeg differ
diff --git a/docs/_static/charts/lincoln_weather_red_blue.webp b/docs/_static/charts/lincoln_weather_red_blue.webp
index 01245ce8..8f2f8dac 100644
Binary files a/docs/_static/charts/lincoln_weather_red_blue.webp and b/docs/_static/charts/lincoln_weather_red_blue.webp differ
diff --git a/docs/_static/charts/probly.html b/docs/_static/charts/probly.html
index e0f58a77..0381eed4 100644
--- a/docs/_static/charts/probly.html
+++ b/docs/_static/charts/probly.html
@@ -1 +1 @@
-
+
diff --git a/docs/_static/charts/probly.jpeg b/docs/_static/charts/probly.jpeg
index b9f57525..28ad0778 100644
Binary files a/docs/_static/charts/probly.jpeg and b/docs/_static/charts/probly.jpeg differ
diff --git a/docs/_static/charts/probly.webp b/docs/_static/charts/probly.webp
index b96aded4..6dbd688a 100644
Binary files a/docs/_static/charts/probly.webp and b/docs/_static/charts/probly.webp differ
diff --git a/docs/conf.py b/docs/conf.py
index 279c55c5..88abd329 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -258,21 +258,30 @@
# Type aliases
_TYPE_ALIASES_FULLY_QUALIFIED = {
- # ------- ._colormodes -------------------------
- "ridgeplot._color.interpolation.SolidColormode",
+ # ------- ._color.css_colors -------------------
+ "ridgeplot._color.css_colors.CssNamedColor",
+ # ------- ._color.interpolation ----------------
"ridgeplot._color.interpolation.ColorscaleInterpolants",
+ "ridgeplot._color.interpolation.SolidColormode",
# ------- ._figure_factory ---------------------
+ "ridgeplot._figure_factory.TraceType",
+ "ridgeplot._figure_factory.TraceTypesArray",
+ "ridgeplot._figure_factory.ShallowTraceTypesArray",
"ridgeplot._figure_factory.LabelsArray",
"ridgeplot._figure_factory.ShallowLabelsArray",
# ------- ._kde --------------------------------
"ridgeplot._kde.KDEPoints",
"ridgeplot._kde.KDEBandwidth",
+ "ridgeplot._kde.SampleWeights",
+ "ridgeplot._kde.SampleWeightsArray",
+ "ridgeplot._kde.ShallowSampleWeightsArray",
# ------- ._missing ----------------------------
"ridgeplot._missing.MISSING",
"ridgeplot._missing.MissingType",
# ------- ._types ------------------------------
"ridgeplot._types.Color",
"ridgeplot._types.ColorScale",
+ "ridgeplot._types.NormalisationOption",
"ridgeplot._types.CollectionL1",
"ridgeplot._types.CollectionL2",
"ridgeplot._types.CollectionL3",
diff --git a/docs/reference/changelog.md b/docs/reference/changelog.md
index 3f21d3ac..bc9a812b 100644
--- a/docs/reference/changelog.md
+++ b/docs/reference/changelog.md
@@ -5,7 +5,13 @@ This document outlines the list of changes to ridgeplot between each release. Fo
Unreleased changes
------------------
-- ...
+### Documentation
+
+- Small improvements to `ridgeplot()`'s docstring ({gh-pr}`284`)
+
+### Internal
+
+- Small improvements to type hints and annotations ({gh-pr}`284`)
---
diff --git a/src/ridgeplot/_color/interpolation.py b/src/ridgeplot/_color/interpolation.py
index 1980ec92..f3241711 100644
--- a/src/ridgeplot/_color/interpolation.py
+++ b/src/ridgeplot/_color/interpolation.py
@@ -1,7 +1,7 @@
from __future__ import annotations
from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any, Literal, Protocol
+from typing import TYPE_CHECKING, Literal, Protocol, TypedDict, overload
import plotly.graph_objs as go
@@ -63,14 +63,6 @@ def _interpolate_color(colorscale: ColorScale, p: float) -> str:
# --- Solid color modes
# ==============================================================
-SolidColormode = Literal[
- "row-index",
- "trace-index",
- "trace-index-row-wise",
- "mean-minmax",
- "mean-means",
-]
-"""See :paramref:`ridgeplot.ridgeplot.colormode` for more information."""
ColorscaleInterpolants = CollectionL2[float]
"""A :data:`ColorscaleInterpolants` contains the interpolants for a :data:`ColorScale`.
@@ -175,6 +167,15 @@ def _interpolate_mean_means(ctx: InterpolationContext) -> ColorscaleInterpolants
]
+SolidColormode = Literal[
+ "row-index",
+ "trace-index",
+ "trace-index-row-wise",
+ "mean-minmax",
+ "mean-means",
+]
+"""See :paramref:`ridgeplot.ridgeplot.colormode` for more information."""
+
SOLID_COLORMODE_MAPS: dict[SolidColormode, InterpolationFunc] = {
"row-index": _interpolate_row_index,
"trace-index": _interpolate_trace_index,
@@ -202,13 +203,18 @@ def _get_fill_color(p: float) -> str:
return ((_get_fill_color(p) for p in row) for row in interpolants)
+class SolidColorsDict(TypedDict):
+ line_color: Color
+ fillcolor: str
+
+
def _compute_solid_trace_colors(
colorscale: ColorScale,
colormode: SolidColormode,
line_color: Color | Literal["fill-color"],
opacity: float | None,
interpolation_ctx: InterpolationContext,
-) -> Generator[Generator[dict[str, Any]]]:
+) -> Generator[Generator[SolidColorsDict]]:
return (
(
dict(
@@ -276,12 +282,17 @@ def _slice_colorscale(
)
+class FillgradientColorsDict(TypedDict):
+ line_color: str
+ fillgradient: go.scatter.Fillgradient
+
+
def _compute_fillgradient_trace_colors(
colorscale: ColorScale,
line_color: Color | Literal["fill-color"],
opacity: float | None,
interpolation_ctx: InterpolationContext,
-) -> Generator[Generator[dict[str, Any]]]:
+) -> Generator[Generator[FillgradientColorsDict]]:
solid_line_colors: Generator[Generator[Color]]
if line_color == "fill-color":
solid_line_colors = _compute_solid_colors(
@@ -332,13 +343,33 @@ def _compute_fillgradient_trace_colors(
# ==============================================================
+@overload
+def compute_trace_colors(
+ colorscale: ColorScale | Collection[Color] | str | None,
+ colormode: Literal["fillgradient"],
+ line_color: Color | Literal["fill-color"],
+ opacity: float | None,
+ interpolation_ctx: InterpolationContext,
+) -> Generator[Generator[FillgradientColorsDict]]: ...
+
+
+@overload
+def compute_trace_colors(
+ colorscale: ColorScale | Collection[Color] | str | None,
+ colormode: SolidColormode,
+ line_color: Color | Literal["fill-color"],
+ opacity: float | None,
+ interpolation_ctx: InterpolationContext,
+) -> Generator[Generator[SolidColorsDict]]: ...
+
+
def compute_trace_colors(
colorscale: ColorScale | Collection[Color] | str | None,
colormode: Literal["fillgradient"] | SolidColormode,
line_color: Color | Literal["fill-color"],
opacity: float | None,
interpolation_ctx: InterpolationContext,
-) -> Generator[Generator[dict[str, Any]]]:
+) -> Generator[Generator[FillgradientColorsDict | SolidColorsDict]]:
colorscale = validate_and_coerce_colorscale(colorscale)
valid_colormodes = ("fillgradient", *SOLID_COLORMODE_MAPS)
diff --git a/src/ridgeplot/_ridgeplot.py b/src/ridgeplot/_ridgeplot.py
index eb4c2d63..de7b00c6 100644
--- a/src/ridgeplot/_ridgeplot.py
+++ b/src/ridgeplot/_ridgeplot.py
@@ -111,7 +111,7 @@ def ridgeplot(
Parameters
----------
- samples : Samples or ShallowSamples, optional
+ samples : Samples or ShallowSamples
If ``samples`` data is specified, Kernel Density Estimation (KDE) will
be computed. See :paramref:`kernel`, :paramref:`bandwidth`,
:paramref:`kde_points`, and :paramref:`sample_weights` for more details
@@ -130,7 +130,7 @@ def ridgeplot(
:paramref:`densities` array with shape :math:`(R, T_r, P_t, 2)`
(see below for more details).
- densities : Densities or ShallowDensities, optional
+ densities : Densities or ShallowDensities
If a ``densities`` array is specified, the KDE step will be skipped and
all associated arguments ignored. Each density array should have shape
:math:`(R, T_r, P_t, 2)` (4D). Just like the :paramref:`samples`
@@ -182,23 +182,25 @@ def ridgeplot(
set of samples. Optionally, you can also pass a custom 1D numerical
array, which will be used for all traces.
- sample_weights : SampleWeightsArray or ShallowSampleWeightsArray or SampleWeights, optional
+ sample_weights : SampleWeightsArray or ShallowSampleWeightsArray or SampleWeights or None
An (optional) array of KDE weights corresponding to each sample. The
- weights should be of the same shape as the samples array. If not
+ weights should have the same shape as the samples array. If not
specified (default), all samples will be weighted equally.
- colorscale : ColorScale or Collection[Color] or str
+ 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 :data:`~ridgeplot._colors.ColorScale` object, or a
- list of colors (see :data:`~ridgeplot._colors.Color`). If a string name
+ ``"viridis"``), a :data:`~ridgeplot._types.ColorScale` object, or a
+ list of valid :data:`~ridgeplot._colors.Color` objects. If a string name
is provided, it must be one of the built-in color scales (see
:func:`~ridgeplot.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 to a :data:`~ridgeplot._colors.ColorScale` object, assuming the
- colors are evenly spaced.
+ ultimately be converted into a :data:`~ridgeplot._colors.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
@@ -245,26 +247,25 @@ def ridgeplot(
The default value changed from ``"mean-minmax"`` to
``"fillgradient"``.
- opacity : float, optional
+ opacity : float or None
If None (default), this argument will be ignored and the transparency
- values of the specifies color-scale will remain untouched. Otherwise,
+ 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.
.. versionadded:: 0.2.0
Replaces the deprecated :paramref:`coloralpha` argument.
- 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.
+ 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.
- norm : NormalisationOption, optional
- The normalisation option to use when normalising the densities. The
- default is None, which means no normalisation will be applied and the
- densities will be used as is. The following normalisation options are
- available:
+ 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.
@@ -273,7 +274,7 @@ def ridgeplot(
.. versionadded:: 0.2.0
- line_color : Color or "fill-color", optional
+ 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
@@ -307,7 +308,7 @@ def ridgeplot(
units of the range between the minimum and maximum x-values from all
distributions.
- coloralpha : float, optional
+ coloralpha : float
.. deprecated:: 0.2.0
Use :paramref:`opacity` instead.
@@ -359,6 +360,11 @@ def ridgeplot(
opacity = coloralpha
if linewidth is not MISSING:
+ if line_width != 1.5:
+ raise ValueError(
+ "You may not specify both the 'linewidth' and 'line_width' arguments! "
+ "HINT: Use the new 'line_width' argument instead of the deprecated 'linewidth'."
+ )
warnings.warn(
"The 'linewidth' argument has been deprecated in favor of 'line_width'. "
"Support for the deprecated argument will be removed in a future version.",
diff --git a/tests/unit/color/test_interpolation.py b/tests/unit/color/test_interpolation.py
index 5a7ae793..3bddf200 100644
--- a/tests/unit/color/test_interpolation.py
+++ b/tests/unit/color/test_interpolation.py
@@ -215,7 +215,7 @@ def test_colormode_invalid() -> None:
):
compute_trace_colors(
colorscale="Viridis",
- colormode="INVALID", # type: ignore[arg-type]
+ colormode="INVALID", # type: ignore[call-overload]
line_color="black",
opacity=None,
interpolation_ctx=InterpolationContext.from_densities([[[(0, 0)]]]),
diff --git a/tests/unit/test_ridgeplot.py b/tests/unit/test_ridgeplot.py
index 9d0ab8b7..aa89c5d3 100644
--- a/tests/unit/test_ridgeplot.py
+++ b/tests/unit/test_ridgeplot.py
@@ -222,6 +222,14 @@ def test_deprecated_linewidth_is_not_missing() -> None:
ridgeplot(samples=[[1, 2, 3], [1, 2, 3]], linewidth=0.5)
+def test_deprecated_linewidth_and_line_width_together_raises() -> None:
+ with pytest.raises(
+ ValueError,
+ match="You may not specify both the 'linewidth' and 'line_width' arguments!",
+ ):
+ ridgeplot(samples=[[1, 2, 3], [1, 2, 3]], linewidth=0.4, line_width=0.6)
+
+
def test_ridgeplot_colorscale_default_deprecation_warning() -> None:
with pytest.warns(DeprecationWarning, match="colorscale='default' is deprecated"):
ridgeplot(samples=[[1, 2, 3], [1, 2, 3]], colorscale="default")