bumplot 0.1.0__tar.gz

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

@@ -0,0 +1,41 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install the project
+        run: uv sync --all-groups
+
+      - name: Deploy MkDocs
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: PYTHONPATH=$(pwd) uv run mkdocs gh-deploy --force

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

@@ -0,0 +1,28 @@
+name: Check Code Formatting
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  check-formatting:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.13"
+
+      - name: Install Ruff
+        run: pip install ruff==0.9.10
+
+      - name: Run Ruff format check
+        run: ruff format --check .
+
+      - name: Run Ruff linting and auto-fix
+        run: ruff check --fix .

bumplot-0.1.0/.github/workflows/pypi.yaml

@@ -0,0 +1,98 @@
+# This is taken from
+# https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/#the-whole-ci-cd-workflow
+# but with the following differences
+# - removed the TestPyPI part
+# - instead of `on: push`, we have `tags` in there too
+
+name: Publish Python 🐍 distribution 📦 to PyPI
+
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+*"
+
+jobs:
+  build:
+    name: Build distribution 📦
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - name: Install pypa/build
+        run: python3 -m pip install build --user
+      - name: Build a binary wheel and a source tarball
+        run: python3 -m build
+      - name: Store the distribution packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-to-pypi:
+    name: >-
+      Publish Python 🐍 distribution 📦 to PyPI
+    if: startsWith(github.ref, 'refs/tags/') # only publish to PyPI on tag pushes
+    needs:
+      - build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pytest-cov
+    permissions:
+      id-token: write # IMPORTANT: mandatory for trusted publishing
+
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish distribution 📦 to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: >-
+      Sign the Python 🐍 distribution 📦 with Sigstore
+      and upload them to GitHub Release
+    needs:
+      - publish-to-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # IMPORTANT: mandatory for making GitHub Releases
+      id-token: write # IMPORTANT: mandatory for sigstore
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Sign the dists with Sigstore
+        uses: sigstore/gh-action-sigstore-python@v3.0.0
+        with:
+          inputs: >-
+            ./dist/*.tar.gz
+            ./dist/*.whl
+      - name: Create GitHub Release
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: >-
+          gh release create
+          "$GITHUB_REF_NAME"
+          --repo "$GITHUB_REPOSITORY"
+          --notes ""
+      - name: Upload artifact signatures to GitHub Release
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        # Upload to GitHub Release using the `gh` CLI.
+        # `dist/` contains the built packages, and the
+        # sigstore-produced signatures and certificates.
+        run: >-
+          gh release upload
+          "$GITHUB_REF_NAME" dist/**
+          --repo "$GITHUB_REPOSITORY"

bumplot-0.1.0/.github/workflows/tests.yaml

@@ -0,0 +1,30 @@
+name: Unit tests
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version:
+          - "3.11"
+          - "3.12"
+          - "3.13"
+    env:
+      UV_PYTHON: ${{ matrix.python-version }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install the project
+        run: uv sync --all-groups
+
+      - name: Run tests
+        run: uv run pytest

bumplot-0.1.0/.github/workflows/type.yaml

@@ -0,0 +1,25 @@
+name: Check Static Typing
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  check-formatting:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install the project
+        run: uv sync --all-groups
+
+      - name: Run tests
+        run: uv run ty check

bumplot-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+.env
+uv.lock
+
+.venv/
+venv/
+.env/
+env/
+
+.vscode/
+
+.DS_Store
+
+*cache*
+
+*.zip
+sandbox/
+scripts/release.sh

bumplot-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,21 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.11.7
+    hooks:
+      - id: ruff
+        types_or: [python, pyi]
+        args: [--fix]
+      - id: ruff-format
+        types_or: [python, pyi]
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-yaml
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-added-large-files
+  - repo: https://github.com/python-jsonschema/check-jsonschema
+    rev: 0.28.2
+    hooks:
+      - id: check-github-workflows
+        args: ["--verbose"]

bumplot-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Year Name
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bumplot-0.1.0/Makefile

@@ -0,0 +1,17 @@
+.PHONY: all
+
+readme:
+	quarto render docs/README.qmd --output-dir ..
+
+coverage:
+	uv run coverage run --source=bumplot -m pytest
+	uv run coverage report -m
+	uv run coverage xml
+	uv run genbadge coverage -i coverage.xml
+	rm coverage.xml
+
+preview:
+	uv run mkdocs serve
+
+test:
+	uv run pytest

bumplot-0.1.0/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: bumplot
+Version: 0.1.0
+Summary: Easily create and customize bump charts in Python
+Author-email: Joseph Barbier <joseph.barbierdarnal@gmail.com>
+License-Expression: MIT
+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
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 4 - Beta
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib>=3.9.4
+Requires-Dist: narwhals>=2.0.0
+Dynamic: license-file
+
+
+
+<!-- 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
+**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.
+
+Check out the [online
+documentation](https://y-sunflower.github.io/bumplot/)
+
+<br> <br>
+
+## Get started
+
+``` python
+import matplotlib.pyplot as plt
+import pandas as pd
+
+from bumplot import bumplot
+
+data = pd.DataFrame(
+    {
+        "x": [2020, 2021, 2022, 2023],
+        "A": [10, 50, 20, 80],
+        "B": [40, 30, 60, 10],
+        "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,
+    data=data,
+    curve_force=0.5,
+    plot_kwargs={"lw": 4},
+    scatter_kwargs={"s": 150, "ec": "black", "lw": 2},
+    colors=["#ffbe0b", "#ff006e", "#3a86ff"],
+)
+ax.legend()
+ax.spines[["top", "right", "left", "bottom"]].set_visible(False)
+ax.grid(alpha=0.4)
+```
+
+![](README_files/figure-commonmark/cell-2-output-1.png)
+
+[See more examples](https://y-sunflower.github.io/bumplot/examples/)
+
+<br> <br>
+
+## Installation
+
+    pip install bumplot

bumplot-0.1.0/README.md

@@ -0,0 +1,64 @@
+
+
+<!-- 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
+**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.
+
+Check out the [online
+documentation](https://y-sunflower.github.io/bumplot/)
+
+<br> <br>
+
+## Get started
+
+``` python
+import matplotlib.pyplot as plt
+import pandas as pd
+
+from bumplot import bumplot
+
+data = pd.DataFrame(
+    {
+        "x": [2020, 2021, 2022, 2023],
+        "A": [10, 50, 20, 80],
+        "B": [40, 30, 60, 10],
+        "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,
+    data=data,
+    curve_force=0.5,
+    plot_kwargs={"lw": 4},
+    scatter_kwargs={"s": 150, "ec": "black", "lw": 2},
+    colors=["#ffbe0b", "#ff006e", "#3a86ff"],
+)
+ax.legend()
+ax.spines[["top", "right", "left", "bottom"]].set_visible(False)
+ax.grid(alpha=0.4)
+```
+
+![](README_files/figure-commonmark/cell-2-output-1.png)
+
+[See more examples](https://y-sunflower.github.io/bumplot/examples/)
+
+<br> <br>
+
+## Installation
+
+    pip install bumplot

bumplot-0.1.0/bumplot/__init__.py

@@ -0,0 +1,4 @@
+from .main import bumplot
+
+__version__ = "0.1.0"
+__all__ = ["bumplot"]

bumplot-0.1.0/bumplot/_utils.py

@@ -0,0 +1,28 @@
+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.
+    """
+    df_native = nw.from_native(df).select(nw.col(x), nw.col(y_columns))
+
+    df_native_ranked = (
+        df_native.unpivot(on=y_columns, index=x)
+        .with_columns(nw.col("value").rank("ordinal").over(x))
+        .pivot(on="variable", index=x, values="value")
+        .select(nw.col(x), nw.col(y_columns))
+    )
+
+    return df_native_ranked

bumplot-0.1.0/bumplot/bezier.py

@@ -0,0 +1,42 @@
+from matplotlib.path import Path
+import numpy as np
+
+
+def bezier_curve(
+    x: np.ndarray,
+    y: np.ndarray,
+    force: float,
+) -> tuple[list[tuple[float, float]], list[int]]:
+    """
+    Generate vertices and path codes for a smooth cubic Bézier curve
+    passing through a sequence of points.
+
+    This function is used under the hood by [`bumplot()`](./bumplot.md),
+    but you can use it too.
+
+    Args:
+        x: X-coordinates of the points.
+        y: Y-coordinates of the points.
+        force: Smoothing factor controlling curve tightness. Higher values
+            increase curvature by moving control points further away
+            from the anchors.
+
+    Returns:
+        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.append((x[0], y[0]))
+    codes.append(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])
+
+    return vertices, codes

bumplot-0.1.0/bumplot/main.py

@@ -0,0 +1,104 @@
+import matplotlib.pyplot as plt
+from matplotlib.axes import Axes
+from matplotlib.path import Path
+import matplotlib.patches as patches
+from matplotlib.patches import PathPatch
+
+import numpy as np
+
+from narwhals.typing import IntoDataFrame
+
+from bumplot.bezier import bezier_curve
+from bumplot._utils import _get_first_n_colors, _ranked_df
+
+
+def bumplot(
+    x: str,
+    y_columns: list[str],
+    data: IntoDataFrame,
+    curve_force: float = 1,
+    invert_y_axis: bool = True,
+    colors: list | None = None,
+    plot_kwargs: dict | None = None,
+    scatter_kwargs: dict | None = None,
+    ax: Axes | None = None,
+) -> Axes:
+    """
+    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
+        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()`
+
+    Returns:
+        The matplotlib Axes with the bump plot
+    """
+    if ax is None:
+        ax: Axes = plt.gca()
+
+    default_plot_kwargs = {"facecolor": "none", "lw": 2}
+    if plot_kwargs is None:
+        plot_kwargs: dict = {}
+    default_plot_kwargs.update(plot_kwargs)
+
+    if scatter_kwargs is None:
+        scatter_kwargs: dict = {}
+
+    if colors is None:
+        colors: list[str] = _get_first_n_colors(n=len(y_columns))
+    else:
+        assert len(y_columns) <= len(colors), (
+            f"Not enough colors, expected <={len(y_columns)}, found {len(colors)}"
+        )
+
+    ranked: IntoDataFrame = _ranked_df(data, x=x, y_columns=y_columns)
+    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
+
+    for i, col in enumerate(y_columns):
+        y_values: np.ndarray = np.ravel(ranked.select(col).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,
+            edgecolor=colors[i],
+            **default_plot_kwargs,
+        )
+        ax.add_patch(patch)
+        ax.scatter(x_values, y_values, color=colors[i], label=col, **scatter_kwargs)
+
+    ticks: list[int] = list(range(1, len(y_columns) + 1))
+    if invert_y_axis:
+        ax.invert_yaxis()
+    else:
+        ticks: list[int] = list(reversed(ticks))
+    ax.set_yticks(ticks=ticks)
+    ax.set_xticks(ticks=np.unique(x_values), labels=np.unique(x_labels))
+
+    return ax