bumplot 0.1.0__py3-none-any.whl

bumplot/__init__.py

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

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/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/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

bumplot-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+bumplot/__init__.py,sha256=iAae8sD9-zkDT15T3hTBltnJnmC7InHXX8tnRlTnC6Y,71
+bumplot/_utils.py,sha256=bploOlyOu2GT1QoA0V0T1dOYRfA59fbyCieOBaJQkFc,789
+bumplot/bezier.py,sha256=-GiiZOu8lNH3yKBPBri5C3KInxm17nYB5guAFP8Qb8Q,1253
+bumplot/main.py,sha256=92T6xqJG6hh4QqIYXwW5jmjo1E4VvB78O6iWSahvFGM,3350
+bumplot-0.1.0.dist-info/licenses/LICENSE,sha256=K6JmhrEwtKtERXknPaQzAyliC-ZgMmSxwSjuwwsuCEw,1061
+bumplot-0.1.0.dist-info/METADATA,sha256=Xpf4U0RmuQmD_yR8IFHayKtjXDrrHtiunk822ZXJzGg,2380
+bumplot-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+bumplot-0.1.0.dist-info/top_level.txt,sha256=Uwy_9Tcw4jpd4cZNoBd1gTgSLj6Jm_vJQFIsASctRag,8
+bumplot-0.1.0.dist-info/RECORD,,

bumplot-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

bumplot-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+bumplot