bumplot 0.1.0__tar.gz → 0.2.1__tar.gz

{bumplot-0.1.0 → bumplot-0.2.1}/.github/workflows/tests.yaml

@@ -10,8 +10,7 @@ jobs:
     strategy:
       matrix:
         python-version:
-          - "3.11"
-          - "3.12"
+          - "3.10"
           - "3.13"
     env:
       UV_PYTHON: ${{ matrix.python-version }}

{bumplot-0.1.0 → bumplot-0.2.1}/.gitignore

@@ -20,4 +20,5 @@ env/
 
 *.zip
 sandbox/
-scripts/release.sh
+release.sh
+.claude/

{bumplot-0.1.0 → bumplot-0.2.1}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) Year Name
+Copyright (c) 2025 Joseph Barbier
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{bumplot-0.1.0 → bumplot-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bumplot
-Version: 0.1.0
+Version: 0.2.1
 Summary: Easily create and customize bump charts in Python
 Author-email: Joseph Barbier <joseph.barbierdarnal@gmail.com>
 License-Expression: MIT
@@ -8,10 +8,10 @@ Project-URL: Homepage, https://y-sunflower.github.io/bumplot/
 Project-URL: Issues, https://github.com/y-sunflower/bumplot/issues
 Project-URL: Documentation, https://y-sunflower.github.io/bumplot/
 Project-URL: Repository, https://github.com/y-sunflower/bumplot
-Keywords: bump,bump plot,bump charts,matplotlib,data,visualization
+Keywords: bump,bump plot,bump charts,matplotlib,data,visualization,bezier,curve
 Classifier: Programming Language :: Python :: 3
 Classifier: Operating System :: OS Independent
-Classifier: Development Status :: 4 - Beta
+Classifier: Development Status :: 5 - Production/Stable
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -19,12 +19,10 @@ Requires-Dist: matplotlib>=3.9.4
 Requires-Dist: narwhals>=2.0.0
 Dynamic: license-file
 
-
+# `bumplot`: easily create and customize bump charts in Python
 
 <!-- Automatically generated, uses README.qmd to modify README.md -->
 
-# `bumplot`: easily create and customize bump charts in Python
-
 <img src="https://github.com/JosephBARBIERDARNAL/static/blob/main/python-libs/bumplot/image.png?raw=true" alt="bumplot logo" align="right" width="180px"/>
 
 `bumplot` is a small Python package made to facilitate the creation of
@@ -42,7 +40,7 @@ documentation](https://y-sunflower.github.io/bumplot/)
 
 ## Get started
 
-``` python
+```python
 import matplotlib.pyplot as plt
 import pandas as pd
 
@@ -56,13 +54,11 @@ data = pd.DataFrame(
         "C": [90, 20, 70, 40],
     }
 )
-x = "x"
-y_columns = ["A", "B", "C"]
 
 fig, ax = plt.subplots(figsize=(8, 4))
 bumplot(
-    x=x,
-    y_columns=y_columns,
+    x="x",
+    y_columns=["A", "B", "C"],
     data=data,
     curve_force=0.5,
     plot_kwargs={"lw": 4},
@@ -74,7 +70,7 @@ ax.spines[["top", "right", "left", "bottom"]].set_visible(False)
 ax.grid(alpha=0.4)
 ```
 
-![](README_files/figure-commonmark/cell-2-output-1.png)
+![](README_files/figure-commonmark/cell-3-output-1.png)
 
 [See more examples](https://y-sunflower.github.io/bumplot/examples/)
 
@@ -83,3 +79,13 @@ ax.grid(alpha=0.4)
 ## Installation
 
     pip install bumplot
+
+<br><br>
+
+## Features
+
+- Automatic ranking of your data (with support for both `pandas` and
+  `polars`)
+- Accept categorical data for x-axis
+- Infinite customization capabilities
+- Easy control of the curvature intensity

{bumplot-0.1.0 → bumplot-0.2.1}/README.md

@@ -1,9 +1,7 @@
-
+# `bumplot`: easily create and customize bump charts in Python
 
 <!-- Automatically generated, uses README.qmd to modify README.md -->
 
-# `bumplot`: easily create and customize bump charts in Python
-
 <img src="https://github.com/JosephBARBIERDARNAL/static/blob/main/python-libs/bumplot/image.png?raw=true" alt="bumplot logo" align="right" width="180px"/>
 
 `bumplot` is a small Python package made to facilitate the creation of
@@ -21,7 +19,7 @@ documentation](https://y-sunflower.github.io/bumplot/)
 
 ## Get started
 
-``` python
+```python
 import matplotlib.pyplot as plt
 import pandas as pd
 
@@ -35,13 +33,11 @@ data = pd.DataFrame(
         "C": [90, 20, 70, 40],
     }
 )
-x = "x"
-y_columns = ["A", "B", "C"]
 
 fig, ax = plt.subplots(figsize=(8, 4))
 bumplot(
-    x=x,
-    y_columns=y_columns,
+    x="x",
+    y_columns=["A", "B", "C"],
     data=data,
     curve_force=0.5,
     plot_kwargs={"lw": 4},
@@ -53,7 +49,7 @@ ax.spines[["top", "right", "left", "bottom"]].set_visible(False)
 ax.grid(alpha=0.4)
 ```
 
-![](README_files/figure-commonmark/cell-2-output-1.png)
+![](README_files/figure-commonmark/cell-3-output-1.png)
 
 [See more examples](https://y-sunflower.github.io/bumplot/examples/)
 
@@ -62,3 +58,13 @@ ax.grid(alpha=0.4)
 ## Installation
 
     pip install bumplot
+
+<br><br>
+
+## Features
+
+- Automatic ranking of your data (with support for both `pandas` and
+  `polars`)
+- Accept categorical data for x-axis
+- Infinite customization capabilities
+- Easy control of the curvature intensity

bumplot-0.2.1/bumplot/__init__.py

@@ -0,0 +1,5 @@
+from .main import bumplot
+from .opts import opts, opts_from_color
+
+__version__ = "0.2.1"
+__all__ = ["bumplot", "opts", "opts_from_color"]

{bumplot-0.1.0 → bumplot-0.2.1}/bumplot/_utils.py

@@ -1,17 +1,7 @@
-import matplotlib.pyplot as plt
-
 import narwhals as nw
 from narwhals.typing import IntoDataFrame
 
 
-def _get_first_n_colors(n=int) -> list[str]:
-    """
-    Get the first n colors from matplotlib rcParams.
-    """
-    colors: list[str] = plt.rcParams["axes.prop_cycle"].by_key()["color"][:n]
-    return colors
-
-
 def _ranked_df(df: IntoDataFrame, x: str, y_columns: list[str]):
     """
     Convert a dataframe to a ranked version of it.
@@ -20,9 +10,18 @@ def _ranked_df(df: IntoDataFrame, x: str, y_columns: list[str]):
 
     df_native_ranked = (
         df_native.unpivot(on=y_columns, index=x)
-        .with_columns(nw.col("value").rank("ordinal").over(x))
+        .with_columns(nw.col("value").rank("ordinal", descending=True).over(x))
         .pivot(on="variable", index=x, values="value")
         .select(nw.col(x), nw.col(y_columns))
     )
 
     return df_native_ranked
+
+
+def _to_ordinal(n: int) -> str:
+    """Convert number to ordinal string (1 -> '1st', 2 -> '2nd', etc.)"""
+    if 11 <= n % 100 <= 13:
+        suffix = "th"
+    else:
+        suffix = {1: "st", 2: "nd", 3: "rd"}.get(n % 10, "th")
+    return f"{n}{suffix}"

bumplot-0.2.1/bumplot/main.py

@@ -0,0 +1,131 @@
+from collections import ChainMap
+from itertools import cycle
+
+import matplotlib.pyplot as plt
+from matplotlib.axes import Axes
+from matplotlib.path import Path
+import matplotlib.patches as patches
+from matplotlib.cbook import normalize_kwargs
+from matplotlib.collections import PathCollection
+from matplotlib.patches import PathPatch
+
+import numpy as np
+
+from narwhals.typing import IntoDataFrame
+
+from .bezier import bezier_curve
+from ._utils import _ranked_df, _to_ordinal
+from .opts import BumpOpts, _get_plot_kwargs, _get_scatter_kwargs
+
+from typing import Any, Iterable, Tuple
+
+
+def bumplot(
+    x: str,
+    y_columns: Iterable[str | tuple[str, BumpOpts]],
+    data: IntoDataFrame,
+    curve_force: float = 1,
+    invert_y_axis: bool = True,
+    colors: Iterable[str] | None = None,
+    plot_kwargs: dict[str, Any] = {},
+    scatter_kwargs: dict[str, Any] = {},
+    ax: Axes | None = None,
+    ordinal_labels: bool = False,
+) -> Tuple[Axes, dict[str, Tuple[PathPatch, PathCollection]]]:
+    """
+    Creates bump plot, or bump chart, from multiple numerical
+    columns.
+
+    It requires the data to be in wide format (e.g., one column
+    per line you want to plot).
+
+    Args:
+        x: colname of the x-axis variable
+        y_columns: colnames of the y-axis variables and their plotting options.
+        data: A dataframe
+        curve_force: Smoothing factor controlling curve tightness. Higher
+            values increase curvature by moving control points further away
+            from the anchors.
+        invert_y_axis: Whether to invert y axis
+        colors: An optional list of colors
+        plot_kwargs: Additional arguments passed to `patches.PathPatch()`
+        scatter_kwargs: Additional arguments passed to `scatter()`
+        ax: The matplotlib Axes used. Default to `plt.gca()`
+        ordinal_labels: If True, converts y-axis labels to ordinal numbers (1st, 2nd, 3rd, etc.)
+    Returns:
+        The matplotlib Axes with the bump plot
+    """
+    _plot_ax: Axes = ax if ax is not None else plt.gca()
+    colors_iterable = (
+        colors
+        if colors is not None
+        else plt.rcParams["axes.prop_cycle"].by_key()["color"]
+    )
+
+    y_bumps: list[tuple[str, BumpOpts]] = [
+        (y, BumpOpts()) if isinstance(y, str) else y for y in y_columns
+    ]
+    ranked: IntoDataFrame = _ranked_df(data, x=x, y_columns=[y for y, _ in y_bumps])
+    x_values_raw: np.ndarray = np.ravel(ranked.select(x).to_numpy())
+
+    if np.issubdtype(x_values_raw.dtype, np.number):
+        x_values = x_values_raw
+        x_labels = x_values_raw
+    else:
+        uniques = list(dict.fromkeys(x_values_raw))  # preserves order
+        mapping = {val: i for i, val in enumerate(uniques)}
+        x_values = np.array([mapping[val] for val in x_values_raw], dtype=int)
+        x_labels = x_values_raw
+
+    artists = {}
+    for (name, bump_opts), color in zip(y_bumps, cycle(colors_iterable)):
+        y_values: np.ndarray = np.ravel(ranked.select(name).to_numpy())
+        vertices, codes = bezier_curve(
+            x=x_values,
+            y=y_values,
+            force=curve_force,
+        )
+
+        path: Path = Path(vertices=vertices, codes=codes)
+        patch: PathPatch = patches.PathPatch(
+            path=path,
+            facecolor="none",
+            **ChainMap(
+                _get_plot_kwargs(bump_opts),
+                normalize_kwargs(plot_kwargs, PathPatch),
+                {"edgecolor": color},
+            ),
+        )
+        _plot_ax.add_patch(patch)
+
+        scatter = _plot_ax.scatter(
+            x_values,
+            y_values,
+            label=name,
+            **ChainMap(
+                _get_scatter_kwargs(bump_opts),
+                normalize_kwargs(scatter_kwargs, PathCollection),
+                {"facecolor": color},
+            ),
+        )
+        artists[name] = (patch, scatter)
+
+    ticks: list[int] = list(range(1, len(y_bumps) + 1))
+
+    if invert_y_axis:
+        _plot_ax.invert_yaxis()
+    else:
+        ticks: list[int] = list(reversed(ticks))
+
+    _plot_ax.set_yticks(ticks=ticks)
+
+    labels = (
+        [_to_ordinal(tick) for tick in ticks]
+        if ordinal_labels
+        else [str(tick) for tick in ticks]
+    )
+    _plot_ax.set_yticklabels(labels)
+
+    _plot_ax.set_xticks(ticks=np.unique(x_values), labels=np.unique(x_labels))
+
+    return _plot_ax, artists

bumplot-0.2.1/bumplot/opts.py

@@ -0,0 +1,191 @@
+from typing import Any, TypedDict
+
+
+class BumpOpts(TypedDict, total=False):
+    """
+    Typed dictionary describing high-level styling options for a bump plot.
+
+    This type represents a user-facing, backend-agnostic set of visual options
+    that can be applied to both line (plot) and marker (scatter) artists.
+
+    All fields are optional. Keys are validated at runtime when constructed via
+    `opts()` to ensure only supported options are provided.
+
+    The options are later translated into Matplotlib-specific keyword arguments
+    via `_get_plot_kwargs()` and `_get_scatter_kwargs()`.
+
+    Notes
+    -----
+    - Keys prefixed with `line_` apply to line artists.
+    - Keys prefixed with `marker_` apply to scatter/marker artists.
+    - Some options (e.g. `clip_on` and `zorder`) apply to both.
+    """
+
+    line_alpha: float
+    line_color: str
+    line_style: str
+    line_width: float
+
+    marker: str
+    marker_size: float
+    marker_alpha: float
+    marker_facecolor: str
+    marker_edgecolor: str
+    marker_edgewidth: float
+
+    clip_on: bool
+    zorder: int
+
+
+PLOT_MAPPINGS: dict[str, str] = {
+    "line_alpha": "alpha",
+    "line_color": "edgecolor",
+    "line_style": "linestyle",
+    "line_width": "linewidth",
+    "clip_on": "clip_on",
+    "zorder": "zorder",
+}
+
+SCATTER_MAPPINGS: dict[str, str] = {
+    "marker": "marker",
+    "marker_alpha": "alpha",
+    "marker_edgecolor": "edgecolor",
+    "marker_edgewidth": "linewidth",
+    "marker_facecolor": "facecolor",
+    "marker_size": "s",
+    "clip_on": "clip_on",
+    "zorder": "zorder",
+}
+
+
+# TODO: For >=Python 3.11 (https://docs.python.org/3/library/typing.html#typing.Unpack)
+def opts(**kwargs: Any) -> BumpOpts:
+    """
+    Construct a validated `BumpOpts` mapping from keyword arguments.
+
+    This function enforces that all provided keyword arguments correspond to
+    supported `BumpOpts` fields. Any unexpected keys result in a `TypeError`.
+
+    Parameters
+    ----------
+    **kwargs: Unpack[BumpOpts]
+        Keyword arguments corresponding to fields defined on `BumpOpts`.
+
+    Returns
+    -------
+    BumpOpts
+        A typed dictionary containing the validated bump plot options.
+
+    Raises
+    ------
+    TypeError
+        If one or more unsupported keyword arguments are provided.
+
+    Notes
+    -----
+    This function exists to provide runtime validation for `BumpOpts`,
+    which is otherwise only enforced statically by type checkers.
+    """
+    unsupported_keys = kwargs.keys() - BumpOpts.__annotations__
+    if unsupported_keys:
+        unsupported_repr = ", ".join(map(repr, sorted(unsupported_keys)))
+        msg = f"BumpOpts got unexpected keyword argument(s): {unsupported_repr}"
+        raise TypeError(msg)
+
+    return BumpOpts(**kwargs)
+
+
+def opts_from_color(color, /, **kwargs: Any) -> BumpOpts:
+    """
+    Construct a `BumpOpts` mapping using a single color applied consistently
+    across line and marker components.
+
+    The provided color is applied to:
+    - `line_color`
+    - `marker_facecolor`
+    - `marker_edgecolor`
+
+    Any explicitly provided keyword arguments take precedence over the color-based
+    defaults.
+
+    Parameters
+    ----------
+    color
+        The color to apply to line and marker components.
+    **kwargs
+        Additional or overriding bump plot options (passed to `opts`).
+
+    Returns
+    -------
+    BumpOpts
+        A validated bump plot options mapping.
+
+    See Also
+    --------
+    opts: Performs keyword validation and construction.
+    """
+    overrides = ["line_color", "marker_facecolor", "marker_edgecolor"]
+    new_kwargs = {k: color for k in overrides} | kwargs
+    return opts(**new_kwargs)
+
+
+def _get_plot_kwargs(kwargs: BumpOpts, /) -> dict[str, Any]:
+    """
+    Extract Matplotlib `plot` keyword arguments from a `BumpOpts` mapping.
+
+    This function translates bump-plot-specific option names into the equivalent
+    Matplotlib `Axes.plot` keyword arguments using `bumplot.opts.PLOT_MAPPINGS`.
+
+    Parameters
+    ----------
+    kwargs: Unpack[BumpOpts]
+        A `BumpOpts` mapping containing zero or more plot-related options.
+
+    Returns
+    -------
+    dict[str, Any]
+        A dictionary of Matplotlib-compatible keyword arguments suitable for
+        `Axes.patches.PathPatch`.
+
+    Notes
+    -----
+    - Only keys present in both `kwargs` and `PLOT_MAPPINGS` are included.
+    """
+    plot_kwargs = {}
+    for bump_arg, mpl_arg in PLOT_MAPPINGS.items():
+        try:
+            plot_kwargs[mpl_arg] = kwargs[bump_arg]  # type: ignore[invalid-key]
+        except KeyError:
+            pass
+    return plot_kwargs
+
+
+def _get_scatter_kwargs(kwargs: BumpOpts, /) -> dict[str, Any]:
+    """
+    Extract Matplotlib `scatter` keyword arguments from a `BumpOpts` mapping.
+
+    This function translates bump-plot-specific option names into the equivalent
+    Matplotlib `Axes.scatter` keyword arguments using `bumplot.opts.SCATTER_MAPPINGS`.
+
+    Parameters
+    ----------
+    kwargs: Unpack[BumpOpts]
+        A `BumpOpts` mapping containing zero or more plot-related options.
+
+    Returns
+    -------
+    dict[str, Any]
+        A dictionary of Matplotlib-compatible keyword arguments suitable for
+        `Axes.scatter`.
+
+    Notes
+    -----
+    - Only keys present in both `kwargs` and `SCATTER_MAPPINGS` are included.
+    """
+    scatter_kwargs = {}
+    for bump_arg, mpl_arg in SCATTER_MAPPINGS.items():
+        try:
+            scatter_kwargs[mpl_arg] = kwargs[bump_arg]  # type: ignore[invalid-key]
+        except KeyError:
+            pass
+    return scatter_kwargs

{bumplot-0.1.0 → bumplot-0.2.1}/bumplot.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bumplot
-Version: 0.1.0
+Version: 0.2.1
 Summary: Easily create and customize bump charts in Python
 Author-email: Joseph Barbier <joseph.barbierdarnal@gmail.com>
 License-Expression: MIT
@@ -8,10 +8,10 @@ Project-URL: Homepage, https://y-sunflower.github.io/bumplot/
 Project-URL: Issues, https://github.com/y-sunflower/bumplot/issues
 Project-URL: Documentation, https://y-sunflower.github.io/bumplot/
 Project-URL: Repository, https://github.com/y-sunflower/bumplot
-Keywords: bump,bump plot,bump charts,matplotlib,data,visualization
+Keywords: bump,bump plot,bump charts,matplotlib,data,visualization,bezier,curve
 Classifier: Programming Language :: Python :: 3
 Classifier: Operating System :: OS Independent
-Classifier: Development Status :: 4 - Beta
+Classifier: Development Status :: 5 - Production/Stable
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -19,12 +19,10 @@ Requires-Dist: matplotlib>=3.9.4
 Requires-Dist: narwhals>=2.0.0
 Dynamic: license-file
 
-
+# `bumplot`: easily create and customize bump charts in Python
 
 <!-- Automatically generated, uses README.qmd to modify README.md -->
 
-# `bumplot`: easily create and customize bump charts in Python
-
 <img src="https://github.com/JosephBARBIERDARNAL/static/blob/main/python-libs/bumplot/image.png?raw=true" alt="bumplot logo" align="right" width="180px"/>
 
 `bumplot` is a small Python package made to facilitate the creation of
@@ -42,7 +40,7 @@ documentation](https://y-sunflower.github.io/bumplot/)
 
 ## Get started
 
-``` python
+```python
 import matplotlib.pyplot as plt
 import pandas as pd
 
@@ -56,13 +54,11 @@ data = pd.DataFrame(
         "C": [90, 20, 70, 40],
     }
 )
-x = "x"
-y_columns = ["A", "B", "C"]
 
 fig, ax = plt.subplots(figsize=(8, 4))
 bumplot(
-    x=x,
-    y_columns=y_columns,
+    x="x",
+    y_columns=["A", "B", "C"],
     data=data,
     curve_force=0.5,
     plot_kwargs={"lw": 4},
@@ -74,7 +70,7 @@ ax.spines[["top", "right", "left", "bottom"]].set_visible(False)
 ax.grid(alpha=0.4)
 ```
 
-![](README_files/figure-commonmark/cell-2-output-1.png)
+![](README_files/figure-commonmark/cell-3-output-1.png)
 
 [See more examples](https://y-sunflower.github.io/bumplot/examples/)
 
@@ -83,3 +79,13 @@ ax.grid(alpha=0.4)
 ## Installation
 
     pip install bumplot
+
+<br><br>
+
+## Features
+
+- Automatic ranking of your data (with support for both `pandas` and
+  `polars`)
+- Accept categorical data for x-axis
+- Infinite customization capabilities
+- Easy control of the curvature intensity

{bumplot-0.1.0 → bumplot-0.2.1}/bumplot.egg-info/SOURCES.txt

@@ -2,9 +2,9 @@
 .gitignore
 .pre-commit-config.yaml
 LICENSE
-Makefile
 README.md
 coverage-badge.svg
+justfile
 mkdocs.yaml
 pyproject.toml
 .github/workflows/doc.yaml
@@ -12,11 +12,12 @@ pyproject.toml
 .github/workflows/pypi.yaml
 .github/workflows/tests.yaml
 .github/workflows/type.yaml
-README_files/figure-commonmark/cell-2-output-1.png
+README_files/figure-commonmark/cell-3-output-1.png
 bumplot/__init__.py
 bumplot/_utils.py
 bumplot/bezier.py
 bumplot/main.py
+bumplot/opts.py
 bumplot.egg-info/PKG-INFO
 bumplot.egg-info/SOURCES.txt
 bumplot.egg-info/dependency_links.txt
@@ -24,12 +25,15 @@ bumplot.egg-info/requires.txt
 bumplot.egg-info/top_level.txt
 docs/.gitignore
 docs/README.qmd
+docs/advanced-usage.md
 docs/contributing.md
 docs/examples.md
 docs/index.md
+docs/data/water-africa.csv
 docs/reference/bezier.md
 docs/reference/bumplot.md
 docs/stylesheets/style.css
 overrides/partials/footer.html
 tests/__init__.py
-tests/test_main.py
+tests/test_main.py
+tests/test_opts.py