bumplot 0.1.1__tar.gz → 0.3.0__tar.gz

bumplot-0.3.0/.github/workflows/doc.yaml

@@ -0,0 +1,32 @@
+name: Documentation
+on:
+  push:
+    branches:
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: 3.x
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install the project
+        run: uv sync --all-groups
+
+      - run: uv run zensical build --clean
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_branch: gh-pages
+          publish_dir: ./site

bumplot-0.3.0/.github/workflows/lint.yaml

@@ -0,0 +1,30 @@
+name: Check code formatting
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  check-formatting:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install the project
+        run: uv sync --all-groups
+
+      - name: Run Ruff formatter and linter
+        run: |
+          uv run ruff format --check .
+          uv run ruff check

{bumplot-0.1.1 → bumplot-0.3.0}/.github/workflows/pypi.yaml

@@ -17,7 +17,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           persist-credentials: false
       - name: Set up Python

{bumplot-0.1.1 → bumplot-0.3.0}/.github/workflows/tests.yaml

@@ -10,13 +10,12 @@ jobs:
     strategy:
       matrix:
         python-version:
-          - "3.11"
-          - "3.12"
-          - "3.13"
+          - "3.10"
+          - "3.15"
     env:
       UV_PYTHON: ${{ matrix.python-version }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Install uv
         uses: astral-sh/setup-uv@v5

{bumplot-0.1.1 → bumplot-0.3.0}/.github/workflows/type.yaml

@@ -1,9 +1,10 @@
-name: Check Static Typing
+name: Check static typing
 
 on:
+  push:
+    branches: [main]
   pull_request:
-    branches:
-      - main
+    branches: [main]
 
 jobs:
   check-formatting:
@@ -11,7 +12,9 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
 
       - name: Install uv
         uses: astral-sh/setup-uv@v5
@@ -21,5 +24,8 @@ jobs:
       - name: Install the project
         run: uv sync --all-groups
 
-      - name: Run tests
+      - name: ty
         run: uv run ty check
+
+      - name: pyrefly
+        run: uv run pyrefly check

{bumplot-0.1.1 → bumplot-0.3.0}/.gitignore

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

{bumplot-0.1.1 → bumplot-0.3.0}/PKG-INFO

@@ -1,17 +1,17 @@
 Metadata-Version: 2.4
 Name: bumplot
-Version: 0.1.1
+Version: 0.3.0
 Summary: Easily create and customize bump charts in Python
 Author-email: Joseph Barbier <joseph.barbierdarnal@gmail.com>
 License-Expression: MIT
+Project-URL: Documentation, https://y-sunflower.github.io/bumplot/
 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,bezier,curve
-Classifier: Programming Language :: Python :: 3
+Keywords: bezier,bump,bump charts,bump plot,curve,data,matplotlib,visualization
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Operating System :: OS Independent
-Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -21,20 +21,13 @@ Dynamic: license-file
 
 # `bumplot`: easily create and customize bump charts in Python
 
-<!-- Automatically generated, uses README.qmd to modify README.md -->
-
 <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
-**bump charts** using matplotlib and Bézier curves. It has high
-customization capabilities too!
+`bumplot` is a small Python package made to facilitate the creation of **bump charts** using matplotlib and Bézier curves. It has high customization capabilities too!
 
-Bump charts are useful when the focus is on comparing **relative
-rankings**—who is ahead of whom—rather than the exact magnitude of the
-differences.
+Bump charts are useful when the focus is on comparing **relative rankings**—who is ahead of whom—rather than the exact magnitude of the differences.
 
-Check out the [online
-documentation](https://y-sunflower.github.io/bumplot/)
+Check out the [online documentation](https://y-sunflower.github.io/bumplot/)
 
 <br> <br>
 
@@ -70,7 +63,7 @@ ax.spines[["top", "right", "left", "bottom"]].set_visible(False)
 ax.grid(alpha=0.4)
 ```
 
-![](README_files/figure-commonmark/cell-3-output-1.png)
+![A simple bump chart made with Python and bumplot](example.png)
 
 [See more examples](https://y-sunflower.github.io/bumplot/examples/)
 
@@ -78,14 +71,15 @@ ax.grid(alpha=0.4)
 
 ## Installation
 
-    pip install bumplot
+```sh
+pip install bumplot
+```
 
 <br><br>
 
 ## Features
 
-- Automatic ranking of your data (with support for both `pandas` and
-  `polars`)
+- 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.1/docs/README.qmd → bumplot-0.3.0/README.md

@@ -1,20 +1,3 @@
----
-format: gfm
-from: markdown-smart
-default-image-extension: ""
----
-
-<!-- Automatically generated, uses README.qmd to modify README.md -->
-
-```{python}
-# | include: false
-# | echo: false
-
-import matplotlib.pyplot as plt
-
-plt.rcParams["figure.dpi"] = 200
-```
-
 # `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"/>
@@ -25,14 +8,11 @@ Bump charts are useful when the focus is on comparing **relative rankings**—wh
 
 Check out the [online documentation](https://y-sunflower.github.io/bumplot/)
 
-
-
-<br>
-<br>
+<br> <br>
 
 ## Get started
 
-```{python}
+```python
 import matplotlib.pyplot as plt
 import pandas as pd
 
@@ -62,14 +42,15 @@ ax.spines[["top", "right", "left", "bottom"]].set_visible(False)
 ax.grid(alpha=0.4)
 ```
 
+![A simple bump chart made with Python and bumplot](example.png)
+
 [See more examples](https://y-sunflower.github.io/bumplot/examples/)
 
-<br>
-<br>
+<br> <br>
 
 ## Installation
 
-```
+```sh
 pip install bumplot
 ```
 

bumplot-0.3.0/bumplot/__init__.py

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

{bumplot-0.1.1 → bumplot-0.3.0}/bumplot/_utils.py

@@ -1,18 +1,11 @@
-import matplotlib.pyplot as plt
+from typing import Any
 
 import narwhals as nw
+from narwhals import DataFrame
 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]):
+def _ranked_df(df: IntoDataFrame, x: str, y_columns: list[str]) -> DataFrame[Any]:
     """
     Convert a dataframe to a ranked version of it.
     """
@@ -26,3 +19,12 @@ def _ranked_df(df: IntoDataFrame, x: str, y_columns: list[str]):
     )
 
     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.1.1 → bumplot-0.3.0}/bumplot/bezier.py

@@ -1,5 +1,5 @@
-from matplotlib.path import Path
 import numpy as np
+from matplotlib.path import Path
 
 
 def bezier_curve(
@@ -25,18 +25,24 @@ def bezier_curve(
         vertices: List of (x, y) vertices including control points for the Bézier segments.
         codes: Corresponding matplotlib Path codes for constructing the curve.
     """
-    vertices: list = []
-    codes: list = []
+    vertices = []
+    codes = []
 
-    vertices.append((x[0], y[0]))
-    codes.append(Path.MOVETO)
+    vertices.append((float(x[0]), float(y[0])))
+    codes.append(int(Path.MOVETO))
 
     for i in range(1, len(x)):
         x0, y0 = x[i - 1], y[i - 1]
         x1, y1 = x[i], y[i]
         dx = (x1 - x0) * force
 
-        vertices.extend([(x0 + dx, y0), (x1 - dx, y1), (x1, y1)])
-        codes.extend([Path.CURVE4, Path.CURVE4, Path.CURVE4])
+        vertices.extend(
+            [
+                (float(x0 + dx), float(y0)),
+                (float(x1 - dx), float(y1)),
+                (float(x1), float(y1)),
+            ]
+        )
+        codes.extend([int(Path.CURVE4)] * 3)
 
     return vertices, codes

bumplot-0.3.0/bumplot/main.py

@@ -0,0 +1,124 @@
+from collections.abc import Iterable
+from itertools import cycle
+from typing import Any
+
+import matplotlib.pyplot as plt
+import numpy as np
+from matplotlib import patches
+from matplotlib.axes import Axes
+from matplotlib.cbook import normalize_kwargs
+from matplotlib.collections import PathCollection
+from matplotlib.patches import PathPatch
+from matplotlib.path import Path
+from narwhals.typing import IntoDataFrame
+
+from ._utils import _ranked_df, _to_ordinal
+from .bezier import bezier_curve
+from .opts import BumpOpts, _get_plot_kwargs, _get_scatter_kwargs
+
+
+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] | None = None,
+    scatter_kwargs: dict[str, Any] | None = None,
+    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_kwargs = {} if plot_kwargs is None else plot_kwargs
+    scatter_kwargs = {} if scatter_kwargs is None else scatter_kwargs
+    _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 = _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)
+        path_kwargs: dict[str, Any] = {"edgecolor": color}
+        path_kwargs.update(normalize_kwargs(plot_kwargs, PathPatch))
+        path_kwargs.update(_get_plot_kwargs(bump_opts))
+        patch: PathPatch = patches.PathPatch(path=path, facecolor="none", **path_kwargs)
+        _plot_ax.add_patch(patch)
+
+        artist_scatter_kwargs: dict[str, Any] = {"facecolor": color}
+        artist_scatter_kwargs.update(normalize_kwargs(scatter_kwargs, PathCollection))
+        artist_scatter_kwargs.update(_get_scatter_kwargs(bump_opts))
+        scatter = _plot_ax.scatter(
+            x_values,
+            y_values,
+            label=name,
+            **artist_scatter_kwargs,
+        )
+        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.3.0/bumplot/opts.py

@@ -0,0 +1,190 @@
+from collections.abc import Mapping
+from typing import Any, TypedDict, cast
+
+
+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.
+    """
+    kwargs_mapping = cast(Mapping[str, Any], kwargs)
+    plot_kwargs: dict[str, Any] = {}
+    for bump_arg, mpl_arg in PLOT_MAPPINGS.items():
+        if bump_arg in kwargs_mapping:
+            plot_kwargs[mpl_arg] = kwargs_mapping[bump_arg]
+    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.
+    """
+    kwargs_mapping = cast(Mapping[str, Any], kwargs)
+    scatter_kwargs: dict[str, Any] = {}
+    for bump_arg, mpl_arg in SCATTER_MAPPINGS.items():
+        if bump_arg in kwargs_mapping:
+            scatter_kwargs[mpl_arg] = kwargs_mapping[bump_arg]
+    return scatter_kwargs