bumplot 0.1.1__tar.gz → 0.2.1__tar.gz

{bumplot-0.1.1 → 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.1 → bumplot-0.2.1}/.gitignore

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bumplot
-Version: 0.1.1
+Version: 0.2.1
 Summary: Easily create and customize bump charts in Python
 Author-email: Joseph Barbier <joseph.barbierdarnal@gmail.com>
 License-Expression: MIT
@@ -11,7 +11,7 @@ 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
 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

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.1 → 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.
@@ -26,3 +16,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.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.1 → bumplot-0.2.1}/bumplot.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bumplot
-Version: 0.1.1
+Version: 0.2.1
 Summary: Easily create and customize bump charts in Python
 Author-email: Joseph Barbier <joseph.barbierdarnal@gmail.com>
 License-Expression: MIT
@@ -11,7 +11,7 @@ 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
 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

{bumplot-0.1.1 → 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
@@ -17,6 +17,7 @@ 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

bumplot-0.2.1/docs/advanced-usage.md

@@ -0,0 +1,231 @@
+`bumplot` is designed to integrate seamlessly with matplotlib and allow you to control virtually everything.
+
+Here you will find examples that show how to use `bumplot` in more complex, but also more realistic, cases based on real data.
+
+These examples are also designed to be easy to reproduce: you should be able to simply copy and paste the code onto your computer.
+
+<br>
+<br>
+
+## Water sources in Africa
+
+```py
+# mkdocs: render
+import pandas as pd
+import matplotlib.pyplot as plt
+from pyfonts import set_default_font, load_google_font
+
+from bumplot import bumplot, opts_from_color
+
+url = "https://raw.githubusercontent.com/y-sunflower/bumplot/main/docs/data/water-africa.csv"
+df = pd.read_csv(url)
+
+font = load_google_font("Poppins")
+set_default_font(font)
+
+highlight = {
+    "Zambia": opts_from_color("#2a9d8f", zorder=2, line_width=3, marker_size=100),
+    "Tanzania": opts_from_color("#bb3e03", zorder=2, line_width=3, marker_size=100),
+}
+countries = [name for name in df.columns if not (name.startswith("decade"))]
+
+fig, ax = plt.subplots(figsize=(12, 5))
+_, bump_artists = bumplot(
+    x="decade",
+    y_columns=[(name, highlight.get(name, {})) for name in countries],
+    data=df,
+    curve_force=0.7,
+    ordinal_labels=True,
+    colors=["lightgray"]
+)
+ax.spines[["top", "right", "left", "bottom"]].set_visible(False)
+ax.margins(x=0.01)
+ax.tick_params(size=0)
+ax.tick_params(axis="x", labelsize=14, pad=10)
+ax.set_xticks(ax.get_xticks(), labels=[round(tick) for tick in ax.get_xticks()])
+
+font_bold = load_google_font("Poppins", weight="bold")
+for name, (_, scatter) in bump_artists.items():
+    _, last_y = scatter.get_offsets()[-1]
+    ax.text(
+        x=1,
+        y=last_y,
+        s=name,
+        size=11,
+        color=scatter.get_facecolor(),
+        va="center",
+        ha="left",
+        font=font_bold,
+        transform=ax.get_yaxis_transform(),
+    )
+
+fig.text(
+    x=0.5,
+    y=0.98,
+    s="# of water sources installations in africa".upper(),
+    size=18,
+    ha="center",
+    va="top",
+    font=font_bold,
+)
+fig.text(
+    x=0.5,
+    y=0.91,
+    s="Ranking of each country based on the total number of water source installations for each decade",
+    size=10,
+    ha="center",
+    va="top",
+    color="grey",
+    font=load_google_font("Poppins", italic=True),
+)
+fig.text(
+    x=0.12,
+    y=0,
+    s="Made with bumplot\nGraphic: Joseph Barbier",
+    va="top",
+    color="grey",
+    font=load_google_font("Poppins", italic=True),
+    size=10,
+)
+```
+
+<br>
+<br>
+
+## Global CO₂ Emissions Rankings
+
+```py
+# mkdocs: render
+import pandas as pd
+import matplotlib.pyplot as plt
+from pyfonts import set_default_font, load_google_font
+
+from bumplot import bumplot, opts_from_color
+
+url = "https://raw.githubusercontent.com/owid/co2-data/master/owid-co2-data.csv"
+df_raw = pd.read_csv(url)
+countries = [
+    "United States",
+    "China",
+    "India",
+    "Russia",
+    "Japan",
+    "Germany",
+    "Iran",
+    "South Korea",
+    "Saudi Arabia",
+    "Indonesia",
+]
+years = [1930, 1940, 1950, 1960, 1970, 1980, 1990, 2000, 2010, 2020]
+df = (
+    df_raw[df_raw["country"].isin(countries) & df_raw["year"].isin(years)][
+        ["year", "country", "co2"]
+    ]
+    .dropna()
+    .pivot(index="year", columns="country", values="co2")
+    .reset_index()
+)
+
+font = load_google_font("Inter")
+set_default_font(font)
+
+highlight = {
+    "China": opts_from_color(
+        "#ae2012",
+        marker_size=100,
+        marker_edgewidth=2,
+        zorder=10,
+    ),
+    "United States": opts_from_color(
+        "#005f73",
+        marker_size=100,
+        marker_edgewidth=2,
+        zorder=10,
+    ),
+}
+
+countries_to_plot = [col for col in df.columns if col != "year"]
+
+fig, ax = plt.subplots(figsize=(10, 7))
+_, bump_artists = bumplot(
+    x="year",
+    y_columns=[(name, highlight.get(name, {})) for name in countries_to_plot],
+    data=df,
+    curve_force=0.7,
+    ordinal_labels=True,
+    colors=["#D1D5DB"],
+    scatter_kwargs={
+        "edgecolor": "#D1D5DB",
+        "s": 40,
+        "linewidth": 1,
+        "facecolor": "#F3F4F6",
+    },
+    plot_kwargs={"linewidth": 1.5},
+)
+
+ax.spines[["top", "right", "left", "bottom"]].set_visible(False)
+ax.tick_params(axis="x", labelsize=11, pad=4, colors="#4a4e69")
+ax.tick_params(size=0)
+
+font_medium = load_google_font("Inter", weight="medium")
+for country in countries:
+    if country in bump_artists:
+        _, scatter = bump_artists[country]
+        _, last_y = scatter.get_offsets()[-1]
+
+        color = "#ae2012" if country == "China" else "#4a4e69"
+        weight = "bold" if country == "China" else "regular"
+        font_label = load_google_font("Inter", weight=weight)
+
+        ax.text(
+            x=1,
+            y=last_y,
+            s=country,
+            size=11,
+            color=color,
+            va="center",
+            ha="left",
+            font=font_label,
+            transform=ax.get_yaxis_transform(),
+        )
+
+font_bold = load_google_font("Inter", weight="bold")
+fig.text(
+    x=0.5,
+    y=0.97,
+    s="The Rise of China's CO₂ Emissions",
+    size=20,
+    ha="center",
+    va="top",
+    font=font_bold,
+    color="#111827",
+)
+fig.text(
+    x=0.5,
+    y=0.92,
+    s="Ranking of top 10 emitting countries, 1930–2020",
+    size=11,
+    ha="center",
+    va="top",
+    color="#4a4e69",
+)
+fig.text(
+    x=0.1,
+    y=0.04,
+    s="Source: Our World in Data · CO₂ emissions dataset",
+    va="bottom",
+    ha="left",
+    color="#4a4e69",
+    size=8,
+)
+fig.text(
+    x=0.9,
+    y=0.04,
+    s="Made with bumplot",
+    va="bottom",
+    ha="right",
+    color="#4a4e69",
+    font=font_bold,
+    size=8,
+)
+```

{bumplot-0.1.1 → bumplot-0.2.1}/docs/contributing.md

@@ -37,16 +37,18 @@ You can now make changes to the package and start coding!
 
 ### Run the test
 
+It's recommended to use [just](https://github.com/casey/just).
+
 - Test that everything works correctly by running:
 
 ```bash
-make test
+just test
 ```
 
 ### Preview documentation locally
 
 ```bash
-make preview
+just preview
 ```
 
 ## Push changes